From owner-svn-doc-all@freebsd.org Tue Jan 10 22:49:39 2017 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 98187CAA975; Tue, 10 Jan 2017 22:49:39 +0000 (UTC) (envelope-from linimon@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 751B610BE; Tue, 10 Jan 2017 22:49:39 +0000 (UTC) (envelope-from linimon@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v0AMnc68024274; Tue, 10 Jan 2017 22:49:38 GMT (envelope-from linimon@FreeBSD.org) Received: (from linimon@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v0AMncJk024273; Tue, 10 Jan 2017 22:49:38 GMT (envelope-from linimon@FreeBSD.org) Message-Id: <201701102249.v0AMncJk024273@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: linimon set sender to linimon@FreeBSD.org using -f From: Mark Linimon Date: Tue, 10 Jan 2017 22:49:38 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r49827 - head/en_US.ISO8859-1/books/handbook/ports X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 10 Jan 2017 22:49:39 -0000 Author: linimon Date: Tue Jan 10 22:49:38 2017 New Revision: 49827 URL: https://svnweb.freebsd.org/changeset/doc/49827 Log: Clarify wording in the ports section of the Handbook. The presentation assumes more knowledge on the part of a new user to FreeBSD than it should. Some of the text, while correct, is still too easy to misunderstand. The overall sense of the text does not change. Add note about ports not running their startup scripts upon installation as being by design. Submitted by: linimon Reviewed by: wblock Approved by: wblock (mentor) Differential Revision: https://reviews.freebsd.org/D8838 Modified: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Tue Jan 10 18:44:22 2017 (r49826) +++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Tue Jan 10 22:49:38 2017 (r49827) @@ -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 @@ Info: Lists information about open fil 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 @@ Info: Lists information about open fil 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 @@ Info: Lists information about open fil 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 @@ Proceed with deleting packages [y/N]: 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 @@ The deinstallation will free 229 kB 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 @@ The deinstallation will free 229 kB &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 @@ The deinstallation will free 229 kB &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 @@ The deinstallation will free 229 kB 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 @@ ports-mgmt/pkg &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 @@ ports-mgmt/pkg 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 @@ ports-mgmt/pkg } 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 @@ ports-mgmt/pkg 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 @@ ports-mgmt/pkg 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 @@ ports-mgmt/pkg 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