Date: Wed, 9 Oct 2013 19:08:11 +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: r42918 - head/en_US.ISO8859-1/books/handbook/ports Message-ID: <201310091908.r99J8B14066064@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201310091908.r99J8B14066064>