Index: chapter.xml =================================================================== --- chapter.xml +++ chapter.xml @@ -71,7 +71,7 @@ Unpack the software from its distribution format. This is typically a tarball compressed with &man.compress.1;, - &man.gzip.1;, or &man.bzip2.1;. + &man.gzip.1;, &man.bzip2.1; &man.xz.1;, or similar program. @@ -257,7 +259,8 @@ To search the binary package - repository for an application: + repository for a particular application, for instance, + Subversion: &prompt.root; pkg search subversion git-subversion-1.9.2 @@ -400,11 +403,17 @@ offering many features that make dealing with binary packages faster and easier. + For sites wishing to only use prebuilt binary packages + from the &os; mirrors, pkg may be + a sufficient management tool. + + However, for those sites building from source and/or using + their own repositories, a different tool will be needed, termed + a port management tool. + pkg is not a replacement for - port management tools like - ports-mgmt/portmaster or - ports-mgmt/portupgrade. These tools can be - used to install third-party software from both binary packages + such tools. Those tools can be + used to install software from both binary packages and the Ports Collection, while pkg installs only binary packages. @@ -415,13 +424,21 @@ &os; includes a bootstrap utility which can be used to download and install pkg, along - with its manual pages. + with its manual pages. This utility is designed to work + with versions of &os; starting with + 10.X. + + Not all combinations of &os; version and architecture + support this bootstrap process. The current list is at + . + + To bootstrap the system, run: &prompt.root; /usr/sbin/pkg - For earlier &os; versions, + If that does not work, pkg must instead be installed from the Ports Collection or as a binary package. @@ -469,8 +486,10 @@ WITH_PKGNG= yes - By default pkg uses the &os; - package mirrors. For information about building a custom + By default pkg uses the + binary packages on the &os; + package mirrors (the "repository"). + For information about building a custom package repository, see @@ -589,7 +608,7 @@ Auditing Installed Packages - Occasionally, software vulnerabilities may be discovered + Software vulnerabilities are regularly discovered in third-party applications. To address this, pkg includes a built-in auditing mechanism. To determine if there are any known @@ -714,9 +733,14 @@ Using the Ports Collection The Ports Collection is a set of - Makefiles, patches, and description files - stored in /usr/ports. This set of files is - used to compile and install applications on &os;. Before an + Makefiles, patches, and description files. + Each set of these files is used to compile and install an individual + application on &os;, and is termed a port. + + By default these files are stored under + /usr/ports. + + 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 &os;, use one of the following methods to @@ -810,11 +834,12 @@ - The Ports Collection installs a series of directories + The Ports Collection installs directories representing software categories with each category having - a subdirectory for each application. Each subdirectory, also - referred to as a ports skeleton, contains a set of files that - tell &os; how to compile and install that program. Each port + a subdirectory for each application. That directory + contains a set of files that + tell &os; how to compile and install that program, + referred to as a ports skeleton. Each port skeleton includes these files and directories: @@ -1152,8 +1177,8 @@ ports-mgmt/portmaster is a very small utility for upgrading installed ports. - It is designed to use the tools installed with &os; - without depending on other ports or databases. + It is designed to use the tools installed with the &os; + base system without depending on other ports or databases. To install this utility as a port: @@ -1325,15 +1350,15 @@ &prompt.root; portsclean -C - In addition, a lot of out-dated source distribution files - will collect in /usr/ports/distfiles over - time. If Portupgrade is installed, - this command will delete all the distfiles that are no longer + In addition, outdated source distribution files + accumulate in /usr/ports/distfiles over + time. To use Portupgrade to + delete all the distfiles that are no longer referenced by any ports: &prompt.root; portsclean -D - To use Portupgrade to remove + Portupgrade can remove all distfiles not referenced by any port currently installed on the system: @@ -1344,11 +1369,11 @@ &prompt.root; portmaster --clean-distfiles - By default, this command is interactive and will prompt + By default, this command is interactive and prompts the user to confirm if a distfile should be deleted. - In addition to these commands, the - ports-mgmt/pkg_cutleaves package or port + In addition to these commands, + ports-mgmt/pkg_cutleaves automates the task of removing installed ports that are no longer needed. @@ -1395,7 +1420,7 @@ The number of processor cores detected is used to define how many builds should run in parallel. Supply enough virtual memory, either with RAM or swap space. If - virtual memory runs out, compiling jails will stop and be torn + virtual memory runs out, the compilation jails will stop and be torn down, resulting in weird error messages. @@ -1496,7 +1521,7 @@ &prompt.root; poudriere bulk -j 10amd64 -p local -z workstation -f 10amd64-local-workstation-pkglist - While running, pressing Ctrlt displays the current state of the build. Poudriere also builds files in @@ -1504,7 +1529,7 @@ that can be used with a web server to display build information. - Packages are now available for + After completion, the new packages are now available for installation from the poudriere repository. @@ -1530,10 +1555,10 @@ } Usually it is easiest to serve a poudriere repository to - the client machines via HTTP. Setup a webserver to serve up + the client machines via HTTP. Set up a webserver to serve up the package directory, usually something like: - /usr/local/poudriere/data/packages/10amd64. - Where 10amd64 is the name of the + /usr/local/poudriere/data/packages/10amd64, + where 10amd64 is the name of the build. If the URL to the package repository is: @@ -1562,7 +1587,7 @@ Most applications install at least one default configuration file in /usr/local/etc. - In the case where an application has a large number of + In cases where an application has a large number of configuration files, a subdirectory will be created to hold them. Often, sample configuration files are installed which end with a suffix such as .sample. The @@ -1586,6 +1611,14 @@ script in /usr/local/etc/rc.d. See Starting Services for more information. + + + By design, applications do not run their startup + script upon installation, nor do they run their stop + script upon deinstallation or upgrade. This decision + is left to the individual system administrator. + + @@ -1628,12 +1661,12 @@ Some ports are not maintained by an individual but - instead by a mailing list. Many, but not all, of these addresses look like freebsd-listname@FreeBSD.org. - Take this into account when sending an email. + Please take this into account when sending an email. In particular, ports shown as maintained by ports@FreeBSD.org are not