git: 132ff9d795 - main - Merge 1d19a09bf0 -> f725439f65, lost during asciidoctor conversion.
Ryusuke SUZUKI
ryusuke at FreeBSD.org
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,
}
....
More information about the dev-commits-doc-all
mailing list