Index: chapter.xml =================================================================== --- chapter.xml +++ chapter.xml @@ -70,8 +70,8 @@ Unpack the software from its distribution format. This - is typically a tarball compressed with &man.compress.1;, - &man.gzip.1;, or &man.bzip2.1;. + is typically a tarball compressed with a program such as + &man.compress.1;, &man.gzip.1;, &man.bzip2.1; or &man.xz.1;. @@ -400,11 +406,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, managing package with + pkg might be sufficient. + + However, for those sites building from source or using + their own repositories, a separate + port management tool will be needed. + 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. @@ -414,17 +426,31 @@ pkg &os; includes a bootstrap utility which can be used to - download and install pkg, along - with its manual pages. + download and install pkg + and its manual pages. This utility is designed to work + with versions of &os; starting with + 10.X. + + Not all &os; versions and architectures + support this bootstrap process. The current list is at + . + + To bootstrap the system, run: &prompt.root; /usr/sbin/pkg - For earlier &os; versions, + If the bootstrap fails, pkg must instead be installed from the Ports Collection or as a binary package. + + The error message may resemble: +pkg: http://pkg.FreeBSD.org/FreeBSD:[osversion]:[arch]/latest/packagesite.txz: Not Found +Unable to update repository FreeBSD + + To install the port, run: &prompt.root; cd /usr/ports/ports-mgmt/pkg @@ -432,7 +458,7 @@ &prompt.root; make install clean When upgrading an existing system that originally used the - older package system, the database must be converted to the + older pkg_* tools, the database must be converted to the new format, so that the new tools are aware of the already installed packages. Once pkg has been installed, the @@ -456,13 +482,13 @@ The package database conversion may emit errors as the contents are converted to the new version. Generally, these errors can be safely ignored. However, a list of - third-party software that was not successfully converted + software that was not successfully converted will be listed after pkg2ng has finished and these applications must be manually reinstalled. - To ensure that the &os; Ports Collection registers - new software with pkg, and not + To ensure that the Ports Collection registers + new software with pkg instead of the traditional packages format, &os; versions earlier than 10.X require this line in /etc/make.conf: @@ -469,10 +495,12 @@ 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 + linkend="ports-poudriere"/>. Additional pkg configuration options are described in &man.pkg.conf.5;. @@ -589,7 +617,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 @@ -1152,7 +1189,8 @@ ports-mgmt/portmaster is a very small utility for upgrading installed ports. - It is designed to use the tools installed with &os; + 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 +1363,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 +1382,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 +1433,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 +1534,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 +1542,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 +1568,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 +1600,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 +1624,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,14 +1674,14 @@ 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. + role="nolink">freebsd-listname@FreeBSD.org. + Please take this into account when sending an email. - In particular, ports shown as maintained by + In particular, ports maintained by ports@FreeBSD.org are not maintained by a specific individual. Instead, any fixes and support come from the general community who subscribe