[Bug 287662] Handbook updates wrt 'kmods' - proposals

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=287662

            Bug ID: 287662
           Summary: Handbook updates wrt 'kmods' - proposals
           Product: Documentation
           Version: Latest
          Hardware: Any
                OS: Any
            Status: New
          Severity: Affects Some People
          Priority: ---
         Component: Books & Articles
          Assignee: doc@FreeBSD.org
          Reporter: erichanskrs@gmail.com

Further documentation and guidance about the 'kmods' seem to be in need; it is
absent in the Handbook. Below are some of my notes regarding the introduction
and usage of the FreeBSD-kmods repository.

- A finicky issue about installation and upgrading
- 'kmods' introduction - suggested items, possibly as basis for the Handbook or
elsewhere
- Proposal for the Handbook


=== Finicky first: installation and upgrading hurdles with pkg(8) 2.1.2
Various problems with pkg v.2.1.2 inability to handle multiple enabled
repositories correctly have appeared in various FreeBSD mailing lists, PRs and
the FreeBSD forums, as well as in external sources.

These problems have had a notable impact when users are trying to use
'FreeBSD-kmods' to get the desired packages tailored to a specific minor
release version. This is now occurring with 14.3-RELEASE where both the
'FreeBSD' and 'FreeBD-kmods' repository are enabled by default. This also seems
to occur in poudriere bulk builds that use these defaults from 14.3-RELEASE.
Various solutions/work-arounds have been suggested and confirmed; in my view:
temporary work-arounds.

ports-mgmt/pkg: update to 2.2.0 - 2025-06-18 06:43:32 has been released.
I hope that solves the problems related to multiple repos.


=== Intro and explanation
Suggested possible items:
(excluding remarks for the dev branch -CURRENT and pkgbase related items)

- Intro of the 'kmods' repos (Quarterly & Latest) for -RELEASE and -STABLE for
the 14 branch as of stable/14, ca. from 14.3-R onwards 
- 'FreeBSD' & 'FreeBSD-kmods' are per default set to use Quarterly (on amd64).
- The std 'FreeBSD' repo is a more general repository that is being maintained
for supported -RELEASE versions. This contains the bulk of available packages.
- The 'FreeBSD-kmods' repo, however, is intended for packages containing kernel
modules that are specific for a targeted minor -RELEASE version such as
14.2-RELEASE and 14.3-RELEASE. At the moment of introduction there are packages
related to the graphics and wireless stack in the 'FreeBSD-kmods' repos.
- The 'FreeBSD-kmods' repo contains considerably less packages than the general
std. "FreeBSD" repos of the Latest and Quarterly branch.
- The 'FreeBSD-kmods' repo facilitates current trends in development and
support for new drivers that require quick adaptation and development, such as
for modern graphics and wireless hardware. Currently this requires changes
during the lifetime of major version's -STABLE branch that cannot wait for
introduction to be delayed until the next major version release. The -STABLE
branch is the basis for -RELEASE versions.

Separate 'FreeBSD-kmods' repositories for either the Quarterly or the Latest
branch are maintained for the -STABLE development branch. 


=== Handbook proposal
Proposed text wrt to:
https://docs.freebsd.org/en/books/handbook/ports/#quarterly-latest-branch
===

A release version can have the recently introduced 'FreeBSD-kmods' repository
as default enabled, in addition to the usual 'FreeBSD' repository.

When no local configuration setting has been created, such as
/usr/local/etc/pkg/repos/FreeBSD.conf, run the following commands to switch
pkg(8) from Quarterly to Latest: 

# mkdir -p /usr/local/etc/pkg/repos
# echo 'FreeBSD: { url: "pkg+https://pkg.FreeBSD.org/${ABI}/latest" }' >
/usr/local/etc/pkg/repos/FreeBSD.conf
# echo 'FreeBSD: { url:
"pkg+https://pkg.FreeBSD.org/${ABI}/kmods_latest_${VERSION_MINOR}"," }' >>
/usr/local/etc/pkg/repos/FreeBSD.conf

Then run this command to update the local package repositories catalogues for
the Latest branch:

# pkg update -f

==
Optionally: separate part for 14.2-RELEASE that does not have the kmods as
default (unless a patch changes that)
Notes: for the 13 branch kmods is NA; if so desired change to using editor
instructions
==
To enable the FreeBSD-kmods repository when only the default FreeBSD repository
for the Quarterly branch is defined, run the following commands: 

# mkdir -p /usr/local/etc/pkg/repos
# echo 'FreeBSD-kmods: {' > /usr/local/etc/pkg/repos/FreeBSD.conf
# echo '    url:
"pkg+https://pkg.FreeBSD.org/${ABI}/kmods_quarterly_${VERSION_MINOR}",' >>
/usr/local/etc/pkg/repos/FreeBSD.conf
# echo '    signature_type: "fingerprints",' >>
/usr/local/etc/pkg/repos/FreeBSD.conf
# echo '    fingerprints: "/usr/share/keys/pkg",' >>
/usr/local/etc/pkg/repos/FreeBSD.conf
# echo '    mirror_type: "srv",' >> /usr/local/etc/pkg/repos/FreeBSD.conf
# echo '    enabled: yes' >> /usr/local/etc/pkg/repos/FreeBSD.conf
# echo '}' >> /usr/local/etc/pkg/repos/FreeBSD.conf

Then run this command to update the local package repositories catalogues for
the Latest branch:

# pkg update -f

You can also switch to the Latest repository. Below are instructions when, as
per default, [i]only[/i] the FreeBSD repository using Quarterly is defined; run
the following commands to enable both repositories using the Latest branch:

# mkdir -p /usr/local/etc/pkg/repos
# echo 'FreeBSD: { url: "pkg+http://pkg.FreeBSD.org/${ABI}/latest" }' >
/usr/local/etc/pkg/repos/FreeBSD.conf
# echo 'FreeBSD-kmods: {' >> /usr/local/etc/pkg/repos/FreeBSD.conf
# echo '    url:
"pkg+https://pkg.FreeBSD.org/${ABI}/kmods_latest_${VERSION_MINOR}",' >>
/usr/local/etc/pkg/repos/FreeBSD.conf
# echo '    signature_type: "fingerprints",' >>
/usr/local/etc/pkg/repos/FreeBSD.conf
# echo '    fingerprints: "/usr/share/keys/pkg",' >>
/usr/local/etc/pkg/repos/FreeBSD.conf
# echo '    mirror_type: "srv",' >> /usr/local/etc/pkg/repos/FreeBSD.conf
# echo '    enabled: yes' >> /usr/local/etc/pkg/repos/FreeBSD.conf
# echo '}' >> /usr/local/etc/pkg/repos/FreeBSD.conf

Then run this command to update the local package repositories catalogues for
the Latest branch:

# pkg update -f

When you switch between Latest and Quarterly, the following can be easily
overlooked.

- Warning
When using 'FreeBSD-kmods', the referred remote repositories for 'FreeBSD' and
the 'FreeBSD-kmods' must be 'compatible':
When using Latest, the following lines must be present:
   url: "pkg+https://pkg.FreeBSD.org/${ABI}/latest"
   url: "pkg+https://pkg.FreeBSD.org/${ABI}/kmods_latest_${VERSION_MINOR}"

When using Quarterly, the following lines must be present:
   url: "pkg+https://pkg.FreeBSD.org/${ABI}/quarterly"
   url: "pkg+https://pkg.FreeBSD.org/${ABI}/kmods_quarterly_${VERSION_MINOR}"

-- 
You are receiving this mail because:
You are the assignee for the bug.