Date: Fri, 4 Oct 2013 18:43:31 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42829 - head/en_US.ISO8859-1/books/handbook/ports Message-ID: <201310041843.r94IhV3x074595@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Fri Oct 4 18:43:31 2013 New Revision: 42829 URL: http://svnweb.freebsd.org/changeset/doc/42829 Log: This patch does the following: - general tightening and clarification of content - the section 3s were changed to section 2s to prevent this chapter from going too deep into headings and to be more consistent with the previous section; I will make igor happy with a white-space change after the rest of the changes to chapter 5 are complete - listings were updated to latest version of pkgng Approved by: gjb (mentor) 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 Fri Oct 4 17:54:01 2013 (r42828) +++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Fri Oct 4 18:43:31 2013 (r42829) @@ -568,40 +568,37 @@ docbook = <title>Using <application>pkgng</application> for Binary Package Management</title> - <para><application>pkgng</application> is an improved replacement + <para><application>pkgng</application> is the next generation replacement for the traditional &os; package management tools, offering many features that make dealing with binary packages faster and - easier. The first release of <application>pkgng</application> - was in August, 2012.</para> + easier.</para> <para><application>pkgng</application> is not a replacement for port management tools like <filename role="package">ports-mgmt/portmaster</filename> or <filename - role="package">ports-mgmt/portupgrade</filename>. While - <filename role="package">ports-mgmt/portmaster</filename> and - <filename role="package">ports-mgmt/portupgrade</filename> can + role="package">ports-mgmt/portupgrade</filename>. These + tools can be used to install third-party software from both binary packages and the - Ports Collection, <application>pkgng</application> installs + Ports Collection, while <application>pkgng</application> installs only binary packages.</para> <sect2 id="pkgng-initial-setup"> <title>Getting Started with <application>pkgng</application></title> - <para>&os; 9.1 and later includes a "bootstrap" - utility for <application>pkgng</application>. The bootstrap - utility will download and install - <application>pkgng</application>.</para> + <para>&os; 9.1 and later includes a bootstrap + utility which can be used to download and install + <application>pkgng</application>, along with its manual pages.</para> <para>To bootstrap the system, run:</para> <screen>&prompt.root; <userinput>/usr/sbin/pkg</userinput></screen> <para>For earlier &os; versions, - <application>pkgng</application> must be installed from the - Ports Collection, or as a binary package.</para> + <application>pkgng</application> must instead be installed from the + Ports Collection or as a binary package.</para> - <para>To install the <application>pkgng</application> port, + <para>To install the port, run:</para> <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/pkg</userinput> @@ -612,220 +609,181 @@ docbook = <screen>&prompt.root; <userinput>pkg_add -r pkg</userinput></screen> - <para>Existing &os; installations require conversion of the - <application>pkg_install</application> package database to the - new format. To convert the package database, run:</para> + <para>Once <application>pkgng</application> is installed, the package database + must be converted from the traditional format to the + new format by running this command:</para> <screen>&prompt.root; <userinput>pkg2ng</userinput></screen> <para>This step is not required for new installations that do - not have third-party software installed.</para> + not yet have any third-party software installed.</para> <important> <para>This step is not reversible. Once the package database has been converted to the <application>pkgng</application> - format, the <application>pkg_install</application> tools + format, the traditional <literal>pkg_*</literal> tools should not be used.</para> </important> <note> <para>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 + errors can be safely ignored. However, a list of third-party software that was not successfully converted will be listed - after <command>pkg2ng</command> has finished. These must be - fixed by hand.</para> + after <command>pkg2ng</command> has finished and these applications must be + manually reinstalled.</para> </note> - <para>To ensure the &os; Ports Collection registers new + <para>To ensure that the &os; Ports Collection registers new software with <application>pkgng</application>, and not - <application>pkg_install</application>, &os; versions earlier + the traditional packages format, &os; versions earlier than 10.<replaceable>X</replaceable> require this line in <filename>/etc/make.conf</filename>:</para> <programlisting>WITH_PKGNG= yes</programlisting> - </sect2> - - <sect2 id="pkgng-pkg-conf"> - <title>Configuring the <application>pkgng</application> - Environment</title> <para>The <application>pkgng</application> package management system uses a package repository for most operations. The default package repository location is defined in - <filename>/usr/local/etc/pkg.conf</filename> or the + <filename>/usr/local/etc/pkg.conf</filename> or by the <envar>PACKAGESITE</envar> environment variable, which overrides the configuration file.</para> <para>Additional <application>pkgng</application> configuration options are described in pkg.conf(5).</para> - </sect2> - - <sect2 id="pkgng-basic-usage"> - <title>Basic <application>pkgng</application> Operations</title> <para>Usage information for <application>pkgng</application> is - available in the pkg(8) manual page, or by running + available in pkg(8) or by running <command>pkg</command> without additional arguments.</para> <para>Each <application>pkgng</application> command argument is documented in a command-specific manual page. To read the manual page for <command>pkg install</command>, for example, - run either:</para> + run either of these commands:</para> <screen>&prompt.root; <userinput>pkg help install</userinput></screen> <screen>&prompt.root; <userinput>man pkg-install</userinput></screen> - <sect3 id="pkgng-pkg-info"> - <title>Obtaining Information About Installed Packages with - <application>pkgng</application></title> - - <para>Information about the packages installed on a system can - be viewed by running <command>pkg info</command>. Similar - to &man.pkg.info.1;, the package version and - description for all packages will be listed.</para> + <para>The rest of this section demonstrates common binary package management + tasks which can be performed using <application>pkgng</application>. Each + demonstrated command provides many switches to customize its + use. Refer to a command's help or man page for details and + more examples.</para> + </sect2> - <para>Information about a specific package is available by - running:</para> + <sect2 id="pkgng-pkg-info"> + <title>Obtaining Information About Installed Packages</title> - <screen>&prompt.root; <userinput>pkg info <replaceable>packagename</replaceable></userinput></screen> + <para>Information about the packages installed on a system can + be viewed by running <command>pkg info</command> which, when run without any switches, will + list the package version for either all installed packages or the specified package.</para> <para>For example, to see which version of - <application>pkgng</application> is installed on the system, + <application>pkgng</application> is installed, run:</para> <screen>&prompt.root; <userinput>pkg info pkg</userinput> -pkg-1.0.2 New generation package manager</screen> - </sect3> +pkg-1.1.4_1</screen> + </sect2> - <sect3 id="pkgng-installing-deinstalling"> - <title>Installing and Removing Packages with - <application>pkgng</application></title> + <sect2 id="pkgng-installing-deinstalling"> + <title>Installing and Removing Packages</title> - <para>In general, most &os; users will install binary packages - by running:</para> + <para>To install a binary package + use the following command, where + <replaceable>packagename</replaceable> is the name of the + package to install:</para> <screen>&prompt.root; <userinput>pkg install <replaceable>packagename</replaceable></userinput></screen> - <para><command>pkg install</command> uses repository data, as - mentioned in <xref linkend="pkgng-pkg-conf"/>. Conversely, - pkg-add(8) does not use repository data, nor does it use the - defined <envar>PACKAGESITE</envar>, so dependencies may not - be properly tracked, and missing dependencies will not be - fetched from a remote source. This section covers usage of - <command>pkg install</command>. For information on usage of - <command>pkg add</command>, see pkg-add(8).</para> - - <para>Additional binary packages can be installed with - <command>pkg install</command>. For example, to install + <para>This command uses repository data to determine which + version of the software to install and if it has any + uninstalled dependencies. For example, to install <application>curl</application>:</para> <screen>&prompt.root; <userinput>pkg install curl</userinput> Updating repository catalogue -Repository catalogue is up-to-date, no need to fetch fresh copy -The following packages will be installed: +/usr/local/tmp/All/curl-7.31.0_1.txz 100% of 1181 kB 1380 kBps 00m01s - Installing ca_root_nss: 3.13.5 - Installing curl: 7.24.0 +/usr/local/tmp/All/ca_root_nss-3.15.1_1.txz 100% of 288 kB 1700 kBps 00m00s -The installation will require 4 MB more space +Updating repository catalogue +The following 2 packages will be installed: + + Installing ca_root_nss: 3.15.1_1 + Installing curl: 7.31.0_1 + +The installation will require 3 MB more space -1 MB to be downloaded +0 B to be downloaded Proceed with installing packages [y/N]: <userinput>y</userinput> -ca_root_nss-3.13.5.txz 100% 255KB 255.1KB/s 255.1KB/s 00:00 -curl-7.24.0.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00 Checking integrity... done -Installing ca_root_nss-3.13.5... done -Installing curl-7.24.0... done</screen> +[1/2] Installing ca_root_nss-3.15.5_1... done +[2/2] Installing curl-7.31.0_1... done +Cleaning up cache files...Done</screen> <para>The new package and any additional packages that were installed as dependencies can be seen in the installed packages list:</para> <screen>&prompt.root; <userinput>pkg info</userinput> -ca_root_nss-3.13.5 The root certificate bundle from the Mozilla Project -curl-7.24.0 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers -pkg-1.0.2 New generation package manager</screen> +ca_root_nss-3.15.5_1 The root certificate bundle from the Mozilla Project +curl-7.31.0_1 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers +pkg-1.1.4_6 New generation package manager</screen> <para>Packages that are no longer needed can be removed with - <command>pkg delete</command>. For example, if it turns out - that <application>curl</application> is not needed after - all:</para> + <command>pkg delete</command>. For example:</para> <screen>&prompt.root; <userinput>pkg delete curl</userinput> The following packages will be deleted: - curl-7.24.0_1 + curl-7.31.0_1 The deletion will free 3 MB Proceed with deleting packages [y/N]: <userinput>y</userinput> -Deleting curl-7.24.0_1... done</screen> - </sect3> +[1/1] Deleting curl-7.31.0_1... done</screen> + </sect2> - <sect3 id="pkgng-upgrading"> - <title>Upgrading Installed Packages with - <application>pkgng</application></title> + <sect2 id="pkgng-upgrading"> + <title>Upgrading Installed Packages</title> <para>Packages that are outdated can be found with <command>pkg version</command>. If a local ports tree does not exist, pkg-version(8) will use the remote - repository catalogue, otherwise the local ports tree will + repository catalogue. Otherwise, the local ports tree will be used to identify package versions.</para> - <para>Packages can be upgraded to newer versions with - <application>pkgng</application>. Suppose a new version of - <application>curl</application> has been released. The - local package can be upgraded to the new version:</para> - - <screen>&prompt.root; <userinput>pkg upgrade</userinput> -Updating repository catalogue -repo.txz 100% 297KB 296.5KB/s 296.5KB/s 00:00 -The following packages will be upgraded: - - Upgrading curl: 7.24.0 -> 7.24.0_1 - -1 MB to be downloaded - -Proceed with upgrading packages [y/N]: <userinput>y</userinput> -curl-7.24.0_1.txz 100% 1108KB 1.1MB/s 1.1MB/s 00:00 -Checking integrity... done -Upgrading curl from 7.24.0 to 7.24.0_1... done</screen> - </sect3> + <para>Installed packages can be upgraded to their latest versions + by typing <command>pkg upgrade</command>. This command + will compare the installed versions with those available + in the repository catalogue. When finished, it will list + the applications that have newer versions. Type + <userinput>y</userinput> to proceed with the upgrade or + <userinput>n</userinput> to cancel the upgrade.</para> + </sect2> - <sect3 id="pkgng-auditing"> - <title>Auditing Installed Packages with - <application>pkgng</application></title> + <sect2 id="pkgng-auditing"> + <title>Auditing Installed Packages</title> <para>Occasionally, software vulnerabilities may be discovered - in software within the Ports Collection. - <application>pkgng</application> includes built-in auditing, - similar to the <filename - role="package">ports-mgmt/portaudit</filename> package. - To audit the software installed on the system, run:</para> + in third-party applications. To address this, + <application>pkgng</application> includes a built-in auditing mechanism. + To determine if there are any known vulnerabilities for the software installed on the system, run:</para> <screen>&prompt.root; <userinput>pkg audit -F</userinput></screen> - </sect3> </sect2> - <sect2 id="pkgng-advanced-usage"> - <title>Advanced <application>pkgng</application> - Operations</title> - - <sect3 id="pkgng-autoremove"> - <title>Automatically Removing Leaf Dependencies with - <application>pkgng</application></title> - - <para>Removing a package may leave behind unnecessary - dependencies, like <filename - role="package">security/ca_root_nss</filename> in the - example above. Such packages are still installed, but - nothing depends on them any more. Unneeded packages that + <sect2 id="pkgng-autoremove"> + <title>Automatically Removing Leaf Dependencies</title> + + <para>Removing a package may leave behind + dependencies which are no longer required. Unneeded packages that were installed as dependencies can be automatically detected - and removed:</para> + and removed using:</para> <screen>&prompt.root; <userinput>pkg autoremove</userinput> Packages to be autoremoved: @@ -834,35 +792,31 @@ Packages to be autoremoved: The autoremoval will free 723 kB Proceed with autoremoval of packages [y/N]: <userinput>y</userinput> -Deinstalling ca_root_nss-3.13.5... done</screen> - </sect3> +Deinstalling ca_root_nss-3.15.1_1... done</screen> + </sect2> - <sect3 id="pkgng-backup"> - <title>Backing Up the <application>pkgng</application> Package + <sect2 id="pkgng-backup"> + <title>Backing Up the Package Database</title> <para>Unlike the traditional package management system, <application>pkgng</application> includes its own package - database backup mechanism. To manually back up the package - database contents, run:</para> + database backup mechanism. To manually back up the contents of the package + database, run the following command, replacing + <replaceable>pkgng.db</replaceable> with a suitable file + name:</para> <screen>&prompt.root; <userinput>pkg backup -d <replaceable>pkgng.db</replaceable></userinput></screen> - <note> - <para>Replace the file name - <replaceable>pkgng.db</replaceable> to a suitable file - name.</para> - </note> - <para>Additionally, <application>pkgng</application> includes - a &man.periodic.8; script to automatically back up the - package database daily if + a &man.periodic.8; script to automatically perform a daily back up of the + package database. This functionality is enabled if <literal>daily_backup_pkgng_enable</literal> is set to <literal>YES</literal> in &man.periodic.conf.5;.</para> <tip> - <para>To prevent the <application>pkg_install</application> - periodic script from also backing up the package database, + <para>To disable the + periodic script from backing up the package database, set <literal>daily_backup_pkgdb_enable</literal> to <literal>NO</literal> in &man.periodic.conf.5;.</para> </tip> @@ -871,53 +825,38 @@ Deinstalling ca_root_nss-3.13.5... done< backup, run:</para> <screen>&prompt.root; <userinput>pkg backup -r <replaceable>/path/to/pkgng.db</replaceable></userinput></screen> - </sect3> + </sect2> - <sect3 id="pkgng-clean"> - <title>Removing Stale <application>pkgng</application> + <sect2 id="pkgng-clean"> + <title>Removing Stale Packages</title> <para>By default, <application>pkgng</application> stores - binary packages in a cache directory as defined by + binary packages in a cache directory defined by <envar>PKG_CACHEDIR</envar> in pkg.conf(5). When upgrading packages with <command>pkg upgrade</command>, old versions of the upgraded packages are not automatically removed.</para> - <para>To remove the outdated binary packages, run:</para> + <para>To remove these outdated binary packages, run:</para> <screen>&prompt.root; <userinput>pkg clean</userinput></screen> - </sect3> + </sect2> - <sect3 id="pkgng-set"> - <title>Modifying <application>pkgng</application> Package + <sect2 id="pkgng-set"> + <title>Modifying Package Metadata</title> - <para>Historically, software within the &os; Ports - Collection can undergo major version number changes. Unlike - <application>pkg_install</application>, + <para>Software within the &os; Ports + Collection can undergo major version number changes. To address this, <application>pkgng</application> has a built-in command to - update package origins. For example, if <filename - role="package">lang/php5</filename> was originally at - version <literal>5.3</literal>, but has been renamed to - <filename role="package">lang/php53</filename> for the - inclusion of version <literal>5.4</literal>, - <application>pkg_install</application> would require the use - of additional software such as <filename - role="package">ports-mgmt/portmaster</filename> to update - the package database, reflecting from which port the - installation originated.</para> + update package origins. This can be useful, for example, if <filename + role="package">lang/php5</filename> is renamed to + <filename role="package">lang/php53</filename> so that <filename + role="package">lang/php5</filename> can now represent + version <literal>5.4</literal>.</para> - <para>Unlike the <filename - role="package">ports-mgmt/portmaster</filename> and - <filename role="package">ports-mgmt/portupgrade</filename> - ports, the order in which the new and old versions are - listed differ. For <application>pkgng</application>, the - syntax is:</para> - - <screen>&prompt.root; <userinput>pkg set -o <replaceable>category/oldport</replaceable>:<replaceable>category/newport</replaceable></userinput></screen> - - <para>For example, to change the package origin for the above + <para>To change the package origin for the above example, run:</para> <screen>&prompt.root; <userinput>pkg set -o lang/php5:lang/php53</userinput></screen> @@ -936,14 +875,13 @@ Deinstalling ca_root_nss-3.13.5... done< <screen>&prompt.root; <userinput>pkg set -o graphics/libglut:graphics/freeglut</userinput></screen> <note> - <para>When changing package origins, in most cases it is + <para>When changing package origins, it is important to reinstall packages that are dependent on the - package that has had the origin changed. To force a + package with the modified origin. To force a reinstallation of dependent packages, run:</para> <screen>&prompt.root; <userinput>pkg install -Rf <replaceable>graphics/freeglut</replaceable></userinput></screen> </note> - </sect3> </sect2> </sect1>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201310041843.r94IhV3x074595>