git: 132ff9d795 - main - Merge 1d19a09bf0 -> f725439f65, lost during asciidoctor conversion.

Sat Apr 17 04:41:34 UTC 2021

The branch main has been updated by ryusuke:

URL: https://cgit.FreeBSD.org/doc/commit/?id=132ff9d79530ae03e2cf0ade5dd02e5758bd80d1

commit 132ff9d79530ae03e2cf0ade5dd02e5758bd80d1
Author:     Ryusuke SUZUKI <ryusuke at FreeBSD.org>
AuthorDate: 2021-04-17 04:41:09 +0000
Commit:     Ryusuke SUZUKI <ryusuke at FreeBSD.org>
CommitDate: 2021-04-17 04:41:09 +0000

    Merge 1d19a09bf0 -> f725439f65, lost during asciidoctor conversion.
---
 .../content/en/books/handbook/ports/_index.adoc    | 44 ++++++++++++++++------
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/documentation/content/en/books/handbook/ports/_index.adoc b/documentation/content/en/books/handbook/ports/_index.adoc
index 7df5c7c6d4..8130484319 100644
--- a/documentation/content/en/books/handbook/ports/_index.adoc
+++ b/documentation/content/en/books/handbook/ports/_index.adoc
@@ -567,10 +567,18 @@ When changing package origins, it is important to reinstall packages that are de
 [[ports-using]]
 == Using the Ports Collection
 
-The Ports Collection is a set of [.filename]#Makefiles#, patches, and description files. Each set of these files is used to compile and install an individual application on FreeBSD, and is called a _port_.
+The Ports Collection is a set of [.filename]##Makefile##s, patches, and description files. Each set of these files is used to compile and install an individual application on FreeBSD, and is called a _port_.
 
 By default, the Ports Collection itself is stored as a subdirectory of [.filename]#/usr/ports#.
 
+[WARNING]
+====
+
+Before installing and using the Ports Collection, please be aware that it is generally ill-advised to use the Ports Collection in conjunction with the binary packages provided via pkg to install software.
+pkg, by default, tracks quarterly branch-releases of the ports tree and not HEAD. Dependencies could be different for a port in HEAD compared to its counterpart in a quarterly branch release and this could result in conflicts between dependencies installed by pkg and those from the Ports Collection.
+If the Ports Collection and pkg must be used in conjunction, then be sure that your Ports Collection and pkg are on the same branch release of the ports tree.
+====
+
 Before an application can be compiled using a port, the Ports Collection must first be installed. If it was not installed during the installation of FreeBSD, use one of the following methods to install it:
 
 [[ports-using-portsnap-method]]
@@ -578,7 +586,7 @@ Before an application can be compiled using a port, the Ports Collection must fi
 ****
 *Procedure: Portsnap Method*
 
-The base system of FreeBSD includes Portsnap. This is a fast and user-friendly tool for retrieving the Ports Collection and is the recommended choice for most users. This utility connects to a FreeBSD site, verifies the secure key, and downloads a new copy of the Ports Collection. The key is used to verify the integrity of all downloaded files.
+The base system of FreeBSD includes Portsnap. This is a fast and user-friendly tool for retrieving the Ports Collection and is the recommended choice for most users not running FreeBSD-CURRENT. This utility connects to a FreeBSD site, verifies the secure key, and downloads a new copy of the Ports Collection. The key is used to verify the integrity of all downloaded files.
 
 . To download a compressed snapshot of the Ports Collection into [.filename]#/var/db/portsnap#:
 +
@@ -615,7 +623,7 @@ When using `fetch`, the `extract` or the `update` operation may be run consecuti
 ****
 *Procedure: Git Method*
 
-If more control over the ports tree is needed or if local changes need to be maintained, Git can be used to obtain the Ports Collection. Refer to link:{committers-guide}#git-primer[the Git Primer] for a detailed description of Git.
+If more control over the ports tree is needed or if local changes need to be maintained, or if running FreeBSD-CURRENT, Git can be used to obtain the Ports Collection. Refer to link:{committers-guide}#git-primer[the Git Primer] for a detailed description of Git.
 
 . Git must be installed before it can be used to check out the ports tree. If a copy of the ports tree is already present, install Git like this:
 +
@@ -632,19 +640,33 @@ If the ports tree is not available, or pkg is being used to manage packages, Git
 # pkg install git
 ....
 +
-. Check out a copy of the ports tree:
+. Check out a copy of the HEAD branch of the ports tree:
 +
 [source,shell]
 ....
 # git clone https://git.FreeBSD.org/ports.git /usr/ports
 ....
 +
+. Or, check out a copy of a quarterly branch:
++
+[source,shell]
+....
+# git clone https://git.FreeBSD.org/ports.git -b 2020Q3 /usr/ports
+....
++
 . As needed, update [.filename]#/usr/ports# after the initial Git checkout:
 +
 [source,shell]
 ....
 # git -C /usr/ports pull
 ....
++
+. As needed, switch [.filename]#/usr/ports# to a different quarterly branch:
++
+[source,shell]
+....
+# git -C /usr/ports switch 2020Q4
+....
 ****
 
 The Ports Collection contains directories for software categories. Inside each category are subdirectories for individual applications. Each application subdirectory contains a set of files that tells FreeBSD how to compile and install that program, called a _ports skeleton_. Each port skeleton includes these files and directories:
@@ -1056,9 +1078,9 @@ Scanning //usr/share/certs/trusted for certificates...
 
 On a single computer, poudriere can build ports with multiple configurations, in multiple jails, and from different port trees. Custom configurations for these combinations are called _sets_. See the CUSTOMIZATION section of man:poudriere[8] for details after package:ports-mgmt/poudriere[] or package:ports-mgmt/poudriere-devel[] is installed.
 
-The basic configuration shown here puts a single jail-, port-, and set-specific [.filename]#make.conf# in [.filename]#/usr/local/etc/poudriere.d#. The filename in this example is created by combining the jail name, port name, and set name: [.filename]#10amd64-local-workstation-make.conf#. The system [.filename]#make.conf# and this new file are combined at build time to create the [.filename]#make.conf# used by the build jail.
+The basic configuration shown here puts a single jail-, port-, and set-specific [.filename]#make.conf# in [.filename]#/usr/local/etc/poudriere.d#. The filename in this example is created by combining the jail name, port name, and set name: [.filename]#11amd64-local-workstation-make.conf#. The system [.filename]#make.conf# and this new file are combined at build time to create the [.filename]#make.conf# used by the build jail.
 
-Packages to be built are entered in [.filename]#10amd64-local-workstation-pkglist#:
+Packages to be built are entered in [.filename]#11amd64-local-workstation-pkglist#:
 
 [.programlisting]
 ....
@@ -1072,14 +1094,14 @@ Options and dependencies for the specified ports are configured:
 
 [source,shell]
 ....
-# poudriere options -j 10amd64 -p local -z workstation -f 10amd64-local-workstation-pkglist
+# poudriere options -j 11amd64 -p local -z workstation -f 11amd64-local-workstation-pkglist
 ....
 
 Finally, packages are built and a package repository is created:
 
 [source,shell]
 ....
-# poudriere bulk -j 10amd64 -p local -z workstation -f 10amd64-local-workstation-pkglist
+# poudriere bulk -j 11amd64 -p local -z workstation -f 11amd64-local-workstation-pkglist
 ....
 
 While running, pressing kbd:[Ctrl+t] displays the current state of the build. Poudriere also builds files in [.filename]#/poudriere/logs/bulk/jailname# that can be used with a web server to display build information.
@@ -1099,14 +1121,14 @@ FreeBSD: {
 }
 ....
 
-Usually it is easiest to serve a poudriere repository to the client machines via HTTP. Set up a webserver to serve up the package directory, for instance: [.filename]#/usr/local/poudriere/data/packages/10amd64#, where [.filename]#10amd64# is the name of the build.
+Usually it is easiest to serve a poudriere repository to the client machines via HTTP. Set up a webserver to serve up the package directory, for instance: [.filename]#/usr/local/poudriere/data/packages/11amd64#, where [.filename]#11amd64# is the name of the build.
 
-If the URL to the package repository is: `http://pkg.example.com/10amd64`, then the repository configuration file in [.filename]#/usr/local/etc/pkg/repos/custom.conf# would look like:
+If the URL to the package repository is: `http://pkg.example.com/11amd64`, then the repository configuration file in [.filename]#/usr/local/etc/pkg/repos/custom.conf# would look like:
 
 [.programlisting]
 ....
 custom: {
-	url: "http://pkg.example.com/10amd64",
+	url: "http://pkg.example.com/11amd64",
 	enabled: yes,
 }
 ....
