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)
This commit is contained in:
Dru Lavigne 2013-10-09 19:08:10 +00:00
parent 4fc9a02f19
commit 55bc696609
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=42918

View file

@ -1315,132 +1315,87 @@ The deinstallation will free 229 kB
<secondary>upgrading</secondary> <secondary>upgrading</secondary>
</indexterm> </indexterm>
<para>First, list outdated ports that have a newer version <para>Over time, newer versions of software become available
available in the Ports Collection with the &man.pkg.version.1; in the Ports Collection. This section describes how to
command:</para> determine which software can be upgraded and how to perform
the upgrade.</para>
<screen>&prompt.root; <userinput>pkg_version -v</userinput></screen> <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>
<sect3 id="ports-file-updating"> <screen>&prompt.root; <userinput>pkg_version -l "&lt;"</userinput></screen>
<title>Read <filename>/usr/ports/UPDATING</filename></title>
<para>Once you have updated your Ports Collection, before <important>
attempting a port upgrade, you should check <para>Before
<filename>/usr/ports/UPDATING</filename>. This file 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 describes various issues and additional steps users may
encounter and need to perform when updating a port, encounter and need to perform when updating a port,
including such things as file format changes, changes in including such things as file format changes, changes in
locations of configuration files, or other such locations of configuration files, or any
incompatibilities with previous versions.</para> 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>If <filename>UPDATING</filename> contradicts something <para>To perform the actual upgrade, use either
you read here, <filename>UPDATING</filename> takes <application>Portmaster</application> or
precedence.</para> <application>Portupgrade</application>.</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>
<sect3 id="portmaster"> <sect3 id="portmaster">
<title>Upgrading Ports Using <title>Upgrading Ports Using
<application>portmaster</application></title> <application>Portmaster</application></title>
<indexterm> <indexterm>
<primary>portmaster</primary> <primary>portmaster</primary>
</indexterm> </indexterm>
<para><filename <para>The <filename
role="package">ports-mgmt/portmaster</filename> is another role="package">ports-mgmt/portmaster</filename>
utility for upgrading installed ports. package or port is the recommended tool for upgrading installed ports
<application>portmaster</application> was designed to as it is designed to
use the tools found in the <quote>base</quote> system use the tools installed with &os;
without depending upon other ports. It uses the information without depending upon other ports. It uses the information
in <filename class="directory">/var/db/pkg/</filename> to in <filename class="directory">/var/db/pkg/</filename> to
determine which ports to upgrade. To install the determine which ports to upgrade. To install this utility
port:</para> 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> &prompt.root; <userinput>make install clean</userinput></screen>
<para><application>Portmaster</application> groups ports into <para><application>Portmaster</application> defines
four categories:</para> four categories of ports:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Root ports: no dependencies and is not depended on <para>Root port: has no dependencies and is not a dependency of
by other ports</para> any other ports.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Trunk ports: no dependencies, but other ports depend <para>Trunk port: has no dependencies, but other ports depend
upon it</para> upon it.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Branch ports: have dependencies and are depended <para>Branch port: has dependencies and other ports depend
upon by other ports</para> upon it.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Leaf ports: have dependencies but are not depended <para>Leaf port: has dependencies but no other ports depend
upon by other ports</para> upon it.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>To list all installed software and search for updates, <para>To list these categories and search for updates:</para>
use <option>-L</option>:</para>
<screen>&prompt.root; <userinput>portmaster -L</userinput> <screen>&prompt.root; <userinput>portmaster -L</userinput>
===>>> Root ports (No dependencies, not depended on) ===>>> Root ports (No dependencies, not depended on)
@ -1464,39 +1419,98 @@ The deinstallation will free 229 kB
===>>> 137 total installed ports ===>>> 137 total installed ports
===>>> 83 have new versions available</screen> ===>>> 83 have new versions available</screen>
<para>All the installed ports can be upgraded using this <para>This command is used to upgrade all outdated ports:</para>
command:</para>
<screen>&prompt.root; <userinput>portmaster -a</userinput></screen> <screen>&prompt.root; <userinput>portmaster -a</userinput></screen>
<note> <note>
<para>By default, <application>portmaster</application> will <para>By default, <application>Portmaster</application> will
make a backup package before deleting the existing port. make a backup package before deleting the existing port.
If the installation of the new version is successful, 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 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 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 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> </note>
<para>If you encounter errors during the upgrade process, use <para>If errors are encountered during the upgrade process, add
<option>-f</option> to upgrade/rebuild all ports:</para> <option>-f</option> to upgrade and rebuild all ports:</para>
<screen>&prompt.root; <userinput>portmaster -af</userinput></screen> <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 to install new ports on the system, upgrading all
dependencies before building and installing the new 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> <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> </sect3>
</sect2> </sect2>
<sect2 id="ports-disk-space"> <sect2 id="ports-disk-space">
<title>Ports and Disk Space</title> <title>Ports and Disk Space</title>
@ -1507,33 +1521,41 @@ The deinstallation will free 229 kB
</indexterm> </indexterm>
<para>Using the Ports Collection will use up disk space over <para>Using the Ports Collection will use up disk space over
time. After building and installing a port, <command>make time. After building and installing a port, running <command>make
<maketarget>clean</maketarget></command> will clean up the <maketarget>clean</maketarget></command> within the ports skeleton will clean up the
temporary <filename class="directory">work</filename> 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> <screen>&prompt.root; <userinput>portsclean -C</userinput></screen>
<para>A lot of out-dated source distribution files will collect <para>In addition, a lot of out-dated source distribution files will collect
in <filename class="directory">distfiles</filename> over time. in <filename class="directory">/usr/ports/distfiles</filename> over time.
The following command will delete all the distfiles that are If <application>Portupgrade</application> is installed, this
command will delete all the distfiles that are
no longer referenced by any ports:</para> no longer referenced by any ports:</para>
<screen>&prompt.root; <userinput>portsclean -D</userinput></screen> <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> currently installed on the system:</para>
<screen>&prompt.root; <userinput>portsclean -DD</userinput></screen> <screen>&prompt.root; <userinput>portsclean -DD</userinput></screen>
<note> <para>If <application>Portmaster</application> is installed, use:</para>
<para>The <command>portsclean</command> utility is part of the
<filename role="package">ports-mgmt/portupgrade</filename>
suite.</para>
</note>
<para><filename <screen>&prompt.root; <userinput>portmaster --clean-distfiles</userinput></screen>
role="package">ports-mgmt/pkg_cutleaves</filename> automates
<para>By default, this command is interactive and will prompt
the user to confirm if a distfile should be deleted.</para>
<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 the task of removing installed ports that are no longer
needed.</para> needed.</para>
</sect2> </sect2>
@ -1594,26 +1616,25 @@ The deinstallation will free 229 kB
<sect1 id="ports-broken"> <sect1 id="ports-broken">
<title>Dealing with Broken Ports</title> <title>Dealing with Broken Ports</title>
<para>When coming across a port that does not build or <para>When a port does not build or
install:</para> install, try the following:</para>
<orderedlist> <orderedlist>
<listitem> <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 the <ulink url="&url.base;/support.html#gnats">Problem
Report database</ulink>. If so, the proposed fix may Report database</ulink>. If so, implementing the proposed fix may
work.</para> fix the issue.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Ask the maintainer of the port for help. Type <para>Ask the maintainer of the port for help. Type
<command>make <maketarget>maintainer</maketarget></command> <command>make <maketarget>maintainer</maketarget></command>
or read the <filename>Makefile</filename> to find the in the ports skeleton or read the port's <filename>Makefile</filename> to find the
maintainer's email address. Remember to include the name maintainer's email address. Remember to include the
and version of the port (send the <literal>&dollar;FreeBSD:</literal> line from the port's
<literal>&dollar;FreeBSD:</literal> line from the <filename>Makefile</filename> and the output leading up to
<filename>Makefile</filename>) and the output leading up to the error in the email to the maintainer.</para>
the error when you email the maintainer.</para>
<note> <note>
<para>Some ports are not maintained by an individual but <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 list</ulink>. Many, but not all, of these addresses look
like <email like <email
role="nolink">freebsd-listname@FreeBSD.org</email>. role="nolink">freebsd-listname@FreeBSD.org</email>.
Please take this into account when phrasing your Take this into account when sending an email.</para>
questions.</para>
<para>In particular, ports shown as maintained by <para>In particular, ports shown as maintained by
<email role="nolink">ports@FreeBSD.org</email> are <email role="nolink">ports@FreeBSD.org</email> are
actually not maintained by anyone. Fixes and support, if not maintained by a specific individual. Instead, any fixes and support
any, come from the general community who subscribe to that come from the general community who subscribe to that
mailing list. More volunteers are always needed!</para> mailing list. More volunteers are always needed!</para>
</note> </note>
<para>If you do not get a response, use &man.send-pr.1; to <para>If there is no response to the email, use &man.send-pr.1; to
submit a bug report (see <ulink submit a bug report using the instructions in <ulink
url="&url.articles.problem-reports;/article.html">Writing url="&url.articles.problem-reports;/article.html">Writing
&os; Problem Reports</ulink>).</para> &os; Problem Reports</ulink>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Fix it! The <ulink <para>Fix it! The <ulink
url="&url.books.porters-handbook;/index.html">Porter's url="&url.books.porters-handbook;/index.html">Porter's
Handbook</ulink> includes detailed information on the 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> occasional broken port or even submit your own!</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Use &man.pkg.add.1; to instead install the <para>Install the package instead of the port using the instructions in
package.</para> <xref
linkend="packages-using"/> or <xref
linkend="pkgng-intro"/>.</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</sect1> </sect1>