svn commit: r42918 - head/en_US.ISO8859-1/books/handbook/ports
Dru Lavigne
dru at FreeBSD.org
Wed Oct 9 19:08:11 UTC 2013
Author: dru
Date: Wed Oct 9 19:08:10 2013
New Revision: 42918
URL: http://svnweb.freebsd.org/changeset/doc/42918
Log:
This patch does the following:
- adds missing introductory explanations and clarifies some
sections
- puts portmaster before portupgrade
- adds instructions for both portmaster/portupgrade where needed
- moves 5.6.3.1 into an Important box
This will be followed by a subsequent white space fix.
Approved by: bcr (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 Wed Oct 9 17:23:32 2013 (r42917)
+++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Wed Oct 9 19:08:10 2013 (r42918)
@@ -1315,132 +1315,87 @@ The deinstallation will free 229 kB
<secondary>upgrading</secondary>
</indexterm>
- <para>First, list outdated ports that have a newer version
- available in the Ports Collection with the &man.pkg.version.1;
- command:</para>
-
- <screen>&prompt.root; <userinput>pkg_version -v</userinput></screen>
-
- <sect3 id="ports-file-updating">
- <title>Read <filename>/usr/ports/UPDATING</filename></title>
-
- <para>Once you have updated your Ports Collection, before
- attempting a port upgrade, you should check
- <filename>/usr/ports/UPDATING</filename>. This file
+ <para>Over time, newer versions of software become available
+ in the Ports Collection. This section describes how to
+ determine which software can be upgraded and how to perform
+ the upgrade.</para>
+
+ <para>To determine if newer versions of installed ports are
+ available, ensure that the latest version of the ports tree
+ is installed, using the updating command described in either
+ Procedure 5.1 or Procedure 5.2. Then, run this command to
+ get a listing of the ports which are older than the currently
+ available version:</para>
+
+ <screen>&prompt.root; <userinput>pkg_version -l "<"</userinput></screen>
+
+ <important>
+ <para>Before
+ attempting an upgrade, read
+ <filename>/usr/ports/UPDATING</filename> from the top of
+ the file to the date closest to the last time ports were
+ upgraded or the system was installed. This file
describes various issues and additional steps users may
encounter and need to perform when updating a port,
including such things as file format changes, changes in
- locations of configuration files, or other such
- incompatibilities with previous versions.</para>
-
- <para>If <filename>UPDATING</filename> contradicts something
- you read here, <filename>UPDATING</filename> takes
- precedence.</para>
- </sect3>
-
- <sect3 id="portupgrade">
- <title>Upgrading Ports Using Portupgrade</title>
-
- <indexterm>
- <primary>portupgrade</primary>
- </indexterm>
-
- <para>The <application>portupgrade</application> utility is
- designed to easily upgrade installed ports. It is available
- from the <filename
- role="package">ports-mgmt/portupgrade</filename> port.
- Install it like any other port, using
- <command>make <maketarget>install
- clean</maketarget></command>:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portupgrade</userinput>
-&prompt.root; <userinput>make install clean</userinput></screen>
-
- <para>Scan the list of installed ports using
- <command>pkgdb -F</command> and fix all the inconsistencies
- it reports. It is a good idea to do this regularly, before
- every upgrade.</para>
-
- <para>Use <command>portupgrade -a</command> to upgrade all the
- outdated ports installed on the system. Include
- <option>-i</option> to be asked for confirmation of every
- individual upgrade.</para>
-
- <screen>&prompt.root; <userinput>portupgrade -ai</userinput></screen>
-
- <para>To upgrade only a specified application instead of all
- available ports, use <command>portupgrade
- <replaceable>pkgname</replaceable></command>. Include
- <option>-R</option> to first upgrade all the ports required
- by the given application.</para>
-
- <screen>&prompt.root; <userinput>portupgrade -R firefox</userinput></screen>
-
- <para>To use packages instead of ports, include the
- <option>-P</option> flag. With this option,
- <application>portupgrade</application> searches the local
- directories listed in <envar>PKG_PATH</envar>, then fetches
- packages from a remote site if not found locally. If
- packages can not be found locally or fetched remotely,
- <application>portupgrade</application> will use ports. To
- avoid using ports, specify <option>-PP</option>.</para>
-
- <screen>&prompt.root; <userinput>portupgrade -PP gnome2</userinput></screen>
-
- <para>To just fetch distfiles (or packages, if
- <option>-P</option> is specified) without building or
- installing anything, use <option>-F</option>. For further
- information see &man.portupgrade.1;.</para>
- </sect3>
+ locations of configuration files, or any
+ incompatibilities with previous versions. Make note of
+ any instructions which match any of the ports that need
+ upgrading and follow these instructions when performing
+ the upgrade.</para>
+ </important>
+
+ <para>To perform the actual upgrade, use either
+ <application>Portmaster</application> or
+ <application>Portupgrade</application>.</para>
<sect3 id="portmaster">
<title>Upgrading Ports Using
- <application>portmaster</application></title>
+ <application>Portmaster</application></title>
<indexterm>
<primary>portmaster</primary>
</indexterm>
- <para><filename
- role="package">ports-mgmt/portmaster</filename> is another
- utility for upgrading installed ports.
- <application>portmaster</application> was designed to
- use the tools found in the <quote>base</quote> system
+ <para>The <filename
+ role="package">ports-mgmt/portmaster</filename>
+ package or port is the recommended tool for upgrading installed ports
+ as it is designed to
+ use the tools installed with &os;
without depending upon other ports. It uses the information
in <filename class="directory">/var/db/pkg/</filename> to
- determine which ports to upgrade. To install the
- port:</para>
+ determine which ports to upgrade. To install this utility
+ as a port:</para>
- <screen>&prompt.root; <userinput>cd <filename class="directory">/usr/ports/ports-mgmt/portmaster</filename></userinput>
+ <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portmaster</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
- <para><application>Portmaster</application> groups ports into
- four categories:</para>
+ <para><application>Portmaster</application> defines
+ four categories of ports:</para>
<itemizedlist>
<listitem>
- <para>Root ports: no dependencies and is not depended on
- by other ports</para>
+ <para>Root port: has no dependencies and is not a dependency of
+ any other ports.</para>
</listitem>
<listitem>
- <para>Trunk ports: no dependencies, but other ports depend
- upon it</para>
+ <para>Trunk port: has no dependencies, but other ports depend
+ upon it.</para>
</listitem>
<listitem>
- <para>Branch ports: have dependencies and are depended
- upon by other ports</para>
+ <para>Branch port: has dependencies and other ports depend
+ upon it.</para>
</listitem>
<listitem>
- <para>Leaf ports: have dependencies but are not depended
- upon by other ports</para>
+ <para>Leaf port: has dependencies but no other ports depend
+ upon it.</para>
</listitem>
</itemizedlist>
- <para>To list all installed software and search for updates,
- use <option>-L</option>:</para>
+ <para>To list these categories and search for updates:</para>
<screen>&prompt.root; <userinput>portmaster -L</userinput>
===>>> Root ports (No dependencies, not depended on)
@@ -1464,39 +1419,98 @@ The deinstallation will free 229 kB
===>>> 137 total installed ports
===>>> 83 have new versions available</screen>
- <para>All the installed ports can be upgraded using this
- command:</para>
+ <para>This command is used to upgrade all outdated ports:</para>
<screen>&prompt.root; <userinput>portmaster -a</userinput></screen>
<note>
- <para>By default, <application>portmaster</application> will
+ <para>By default, <application>Portmaster</application> will
make a backup package before deleting the existing port.
If the installation of the new version is successful,
- <application>portmaster</application> will delete the
+ <application>Portmaster</application> will delete the
backup. Using <option>-b</option> will instruct
- <application>portmaster</application> not to automatically
+ <application>Portmaster</application> not to automatically
delete the backup. Adding <option>-i</option> will start
- <application>portmaster</application> in interactive mode,
+ <application>Portmaster</application> in interactive mode,
prompting for confirmation before upgrading each
- port.</para>
+ port. Many other options are available. Read through
+ the manual page for portmaster(8) for details regarding
+ their usage.</para>
</note>
- <para>If you encounter errors during the upgrade process, use
- <option>-f</option> to upgrade/rebuild all ports:</para>
+ <para>If errors are encountered during the upgrade process, add
+ <option>-f</option> to upgrade and rebuild all ports:</para>
<screen>&prompt.root; <userinput>portmaster -af</userinput></screen>
- <para>You can also use <application>portmaster</application>
+ <para><application>Portmaster</application> can also be used
to install new ports on the system, upgrading all
dependencies before building and installing the new
- port:</para>
+ port. To use this function, specify the location of the
+ port in the Ports Collection:</para>
<screen>&prompt.root; <userinput>portmaster <replaceable>shells/bash</replaceable></userinput></screen>
+ </sect3>
- <para>Refer to &man.portmaster.8; for more information.</para>
+ <sect3 id="portupgrade">
+ <title>Upgrading Ports Using Portupgrade</title>
+
+ <indexterm>
+ <primary>portupgrade</primary>
+ </indexterm>
+
+ <para>Another utility that can be used to upgrade ports is
+ <application>Portupgrade</application>, which is
+ available
+ as the <filename
+ role="package">ports-mgmt/portupgrade</filename> package or port.
+ This utility installs a suite of applications which can be
+ used to manage ports. However, it is dependent upon Ruby.
+ To install the port:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portupgrade</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+ <para>Before performing an upgrade using this utility, it is
+ recommended to scan the list of installed ports using
+ <command>pkgdb -F</command> and to fix all the inconsistencies
+ it reports.</para>
+
+ <para>To upgrade all the
+ outdated ports installed on the system, use <command>portupgrade -a</command>. Alternately, include
+ <option>-i</option> to be asked for confirmation of every
+ individual upgrade:</para>
+
+ <screen>&prompt.root; <userinput>portupgrade -ai</userinput></screen>
+
+ <para>To upgrade only a specified application instead of all
+ available ports, use <command>portupgrade
+ <replaceable>pkgname</replaceable></command>. It is very important to include
+ <option>-R</option> to first upgrade all the ports required
+ by the given application:</para>
+
+ <screen>&prompt.root; <userinput>portupgrade -R firefox</userinput></screen>
+
+ <para>If
+ <option>-P</option> is included,
+ <application>Portupgrade</application> searches for available packages in the local
+ directories listed in <envar>PKG_PATH</envar>. If none are available locally, it then fetches
+ packages from a remote site. If
+ packages can not be found locally or fetched remotely,
+ <application>Portupgrade</application> will use ports. To
+ avoid using ports entirely, specify <option>-PP</option>.
+ This last set of options tells <application>Portupgrade</application>
+ to abort if no packages are available:</para>
+
+ <screen>&prompt.root; <userinput>portupgrade -PP gnome2</userinput></screen>
+
+ <para>To just fetch the port distfiles, or packages, if
+ <option>-P</option> is specified, without building or
+ installing anything, use <option>-F</option>. For further
+ information on all of the available switches, refer to the
+ manual page for <command>portupgrade</command>.</para>
</sect3>
- </sect2>
+ </sect2>
<sect2 id="ports-disk-space">
<title>Ports and Disk Space</title>
@@ -1507,33 +1521,41 @@ The deinstallation will free 229 kB
</indexterm>
<para>Using the Ports Collection will use up disk space over
- time. After building and installing a port, <command>make
- <maketarget>clean</maketarget></command> will clean up the
+ time. After building and installing a port, running <command>make
+ <maketarget>clean</maketarget></command> within the ports skeleton will clean up the
temporary <filename class="directory">work</filename>
- directory. To sweep the whole Ports Collection:</para>
+ directory. If <application>Portmaster</application> is used
+ to install a port, it will automatically remove this directory
+ unless <option>-K</option> is specified. If
+ <application>Portupgrade</application> is installed, this command
+ will remove all <filename class="directory">work</filename>
+ directories found within the local copy of the Ports
+ Collection:</para>
<screen>&prompt.root; <userinput>portsclean -C</userinput></screen>
- <para>A lot of out-dated source distribution files will collect
- in <filename class="directory">distfiles</filename> over time.
- The following command will delete all the distfiles that are
+ <para>In addition, a lot of out-dated source distribution files will collect
+ in <filename class="directory">/usr/ports/distfiles</filename> over time.
+ If <application>Portupgrade</application> is installed, this
+ command will delete all the distfiles that are
no longer referenced by any ports:</para>
<screen>&prompt.root; <userinput>portsclean -D</userinput></screen>
- <para>To remove all distfiles not referenced by any port
+ <para>To use <application>Portupgrade</application> to remove all distfiles not referenced by any port
currently installed on the system:</para>
<screen>&prompt.root; <userinput>portsclean -DD</userinput></screen>
- <note>
- <para>The <command>portsclean</command> utility is part of the
- <filename role="package">ports-mgmt/portupgrade</filename>
- suite.</para>
- </note>
+ <para>If <application>Portmaster</application> is installed, use:</para>
+
+ <screen>&prompt.root; <userinput>portmaster --clean-distfiles</userinput></screen>
+
+ <para>By default, this command is interactive and will prompt
+ the user to confirm if a distfile should be deleted.</para>
- <para><filename
- role="package">ports-mgmt/pkg_cutleaves</filename> automates
+ <para>In addition to these commands, the <filename
+ role="package">ports-mgmt/pkg_cutleaves</filename> package or port automates
the task of removing installed ports that are no longer
needed.</para>
</sect2>
@@ -1594,26 +1616,25 @@ The deinstallation will free 229 kB
<sect1 id="ports-broken">
<title>Dealing with Broken Ports</title>
- <para>When coming across a port that does not build or
- install:</para>
+ <para>When a port does not build or
+ install, try the following:</para>
<orderedlist>
<listitem>
- <para>Find out if there is a fix pending for the port in
+ <para>Search to see if there is a fix pending for the port in
the <ulink url="&url.base;/support.html#gnats">Problem
- Report database</ulink>. If so, the proposed fix may
- work.</para>
+ Report database</ulink>. If so, implementing the proposed fix may
+ fix the issue.</para>
</listitem>
<listitem>
<para>Ask the maintainer of the port for help. Type
<command>make <maketarget>maintainer</maketarget></command>
- or read the <filename>Makefile</filename> to find the
- maintainer's email address. Remember to include the name
- and version of the port (send the
- <literal>$FreeBSD:</literal> line from the
- <filename>Makefile</filename>) and the output leading up to
- the error when you email the maintainer.</para>
+ in the ports skeleton or read the port's <filename>Makefile</filename> to find the
+ maintainer's email address. Remember to include the
+ <literal>$FreeBSD:</literal> line from the port's
+ <filename>Makefile</filename> and the output leading up to
+ the error in the email to the maintainer.</para>
<note>
<para>Some ports are not maintained by an individual but
@@ -1622,33 +1643,34 @@ The deinstallation will free 229 kB
list</ulink>. Many, but not all, of these addresses look
like <email
role="nolink">freebsd-listname at FreeBSD.org</email>.
- Please take this into account when phrasing your
- questions.</para>
+ Take this into account when sending an email.</para>
<para>In particular, ports shown as maintained by
<email role="nolink">ports at FreeBSD.org</email> are
- actually not maintained by anyone. Fixes and support, if
- any, come from the general community who subscribe to that
+ not maintained by a specific individual. Instead, any fixes and support
+ come from the general community who subscribe to that
mailing list. More volunteers are always needed!</para>
</note>
- <para>If you do not get a response, use &man.send-pr.1; to
- submit a bug report (see <ulink
+ <para>If there is no response to the email, use &man.send-pr.1; to
+ submit a bug report using the instructions in <ulink
url="&url.articles.problem-reports;/article.html">Writing
- &os; Problem Reports</ulink>).</para>
+ &os; Problem Reports</ulink>.</para>
</listitem>
<listitem>
<para>Fix it! The <ulink
url="&url.books.porters-handbook;/index.html">Porter's
Handbook</ulink> includes detailed information on the
- <quote>Ports</quote> infrastructure so that you can fix the
+ ports infrastructure so that you can fix the
occasional broken port or even submit your own!</para>
</listitem>
<listitem>
- <para>Use &man.pkg.add.1; to instead install the
- package.</para>
+ <para>Install the package instead of the port using the instructions in
+ <xref
+ linkend="packages-using"/> or <xref
+ linkend="pkgng-intro"/>.</para>
</listitem>
</orderedlist>
</sect1>
More information about the svn-doc-all
mailing list