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
parent
4fc9a02f19
commit
55bc696609
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=42918
1 changed files with 161 additions and 139 deletions
|
|
@ -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>
|
||||
<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>
|
||||
|
||||
<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">
|
||||
<title>Read <filename>/usr/ports/UPDATING</filename></title>
|
||||
<screen>&prompt.root; <userinput>pkg_version -l "<"</userinput></screen>
|
||||
|
||||
<para>Once you have updated your Ports Collection, before
|
||||
attempting a port upgrade, you should check
|
||||
<filename>/usr/ports/UPDATING</filename>. This file
|
||||
<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>
|
||||
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>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>
|
||||
<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>
|
||||
|
||||
<para><filename
|
||||
role="package">ports-mgmt/pkg_cutleaves</filename> automates
|
||||
<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>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@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@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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue