Index: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/handbook/ports/chapter.xml +++ head/en_US.ISO8859-1/books/handbook/ports/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 +400,18 @@ offering many features that make dealing with binary packages faster and easier. - 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 + For sites wishing to only use prebuilt binary packages + from the &os; mirrors, managing packages with + pkg can be sufficient. + + However, for those sites building from source or using + their own repositories, a separate + port management tool will be needed. + + Since pkg only works with + binary packages, it + is not a replacement for 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,25 +421,36 @@ 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 + . + For other cases, + pkg must instead be installed + from the Ports Collection or as a binary package. + + To bootstrap the system, run: &prompt.root; /usr/sbin/pkg - For earlier &os; versions, - pkg must instead be installed - from the Ports Collection or as a binary package. + You must have a working Internet connection for the + bootstrap process to suceed. - To install the port, run: + Otherwise, to install the port, run: &prompt.root; cd /usr/ports/ports-mgmt/pkg &prompt.root; make &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,23 +474,25 @@ 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 - will be listed after pkg2ng has finished - and these applications must be manually reinstalled. + software that was not successfully converted + is shown after pkg2ng finishes. + These applications must be manually reinstalled. - To ensure that the &os; Ports Collection registers - new software with pkg, and not - the traditional packages format, &os; versions earlier than + To ensure that the Ports Collection registers + new software with pkg instead of + the traditional packages database, &os; versions earlier than 10.X require this line in /etc/make.conf: WITH_PKGNG= yes - By default pkg uses the &os; - package mirrors. For information about building a custom - package repository, see + By default, pkg uses the + binary packages from the &os; + package mirrors (the repository). + For information about building a custom + package repository, see + . Additional pkg configuration options are described in &man.pkg.conf.5;. @@ -589,7 +609,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 +1172,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 +1346,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 +1365,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. @@ -1393,9 +1414,9 @@ other configuration values are adequate. The number of processor cores detected is used to define how - many builds should run in parallel. Supply enough virtual + many builds will 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 +1517,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 +1525,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,11 +1551,11 @@ } Usually it is easiest to serve a poudriere repository to - the client machines via HTTP. Setup a webserver to serve up - the package directory, usually something like: - /usr/local/poudriere/data/packages/10amd64. - Where 10amd64 is the name of the - build. + the client machines via HTTP. Set up a webserver to serve up + the package directory, for instance: + /usr/local/poudriere/data/packages/10amd64, + where 10amd64 + is the name of the build. If the URL to the package repository is: http://pkg.example.com/10amd64, then the @@ -1562,7 +1583,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 +1607,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 +1657,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