git: 132ff9d795 - main - Merge 1d19a09bf0 -> f725439f65, lost during asciidoctor conversion.
Ryusuke SUZUKI <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
The branch main has been updated by ryusuke: URL: https://cgit.FreeBSD.org/doc/commit/?id=132ff9d79530ae03e2cf0ade5dd02e5758bd80d1 commit 132ff9d79530ae03e2cf0ade5dd02e5758bd80d1 Author: Ryusuke SUZUKI <[email protected]> AuthorDate: 2021-04-17 04:41:09 +0000 Commit: Ryusuke SUZUKI <[email protected]> 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, } .... _______________________________________________ [email protected] mailing list https://lists.freebsd.org/mailman/listinfo/dev-commits-doc-all To unsubscribe, send any mail to "[email protected]"