svn commit: r42903 - head/en_US.ISO8859-1/books/handbook/ports

Dru Lavigne dru at FreeBSD.org
Tue Oct 8 19:48:28 UTC 2013


Author: dru
Date: Tue Oct  8 19:48:28 2013
New Revision: 42903
URL: http://svnweb.freebsd.org/changeset/doc/42903

Log:
  This patch does the following to the first half of 5.6. Using the Ports Collection:
  - as per discussion with portmgr, removes csup warnings and how-tos
  - as per discussion on IRC, remove Method 3 as sysinstall is being phased out
  - adds some text and word-smithing to make unclear instructions a bit clearer
  - some tag cleanup
  - updated lsof listing
  - some text shuffling to improve flow
  
  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	Tue Oct  8 17:39:20 2013	(r42902)
+++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml	Tue Oct  8 19:48:28 2013	(r42903)
@@ -888,41 +888,22 @@ Deinstalling ca_root_nss-3.15.1_1... don
   <sect1 id="ports-using">
     <title>Using the Ports Collection</title>
 
-    <para>This section provides basic instructions on using the Ports
-      Collection to install or remove software.  The detailed
-      description of available <command>make</command> targets and
-      environment variables is available in &man.ports.7;.</para>
-
-    <warning>
-      <para>As of mid 2012, the &os; Ports Project has migrated
-	revision control systems from CVS to Subversion.  The
-	preferred method for obtaining and maintaining the ports tree
-	is <application>Portsnap</application>.  Users requiring local
-	customization of ports (that is, maintaining additional local
-	patches) will probably prefer to use Subversion directly.  The
-	<application>CVSup</application> service was phased out
-	as of February 28, 2013.</para>
-    </warning>
-
-    <sect2 id="ports-tree">
-      <title>Obtaining the Ports Collection</title>
-
       <para>The Ports Collection is a set of
 	<filename>Makefiles</filename>, patches, and description files
-	stored in <filename>/usr/ports</filename>.  This set of files
-	is used to compile and install applications on &os;.  The
-	instructions below show several methods of obtaining the Ports
-	Collection if it was not installed during initial &os;
-	setup.</para>
+	stored in <filename class="directory">/usr/ports</filename>.  This set of files
+	is used to compile and install applications on &os;.  Before
+	an application can be compiled using a port, the Ports
+	Collection must first be installed.  If it was not installed during the installatio of &os;,
+	use one of the following methods to install it:</para>
 
       <procedure>
 	<title>Portsnap Method</title>
 
 	<para><application>Portsnap</application> is a fast and
-	  user-friendly tool for retrieving the Ports Collection, the
-	  preferred choice for most users.  See
-	  <link linkend="updating-upgrading-portsnap">Using
-	    Portsnap</link> for a detailed description of
+	  user-friendly tool for retrieving the Ports Collection and is the
+	  recommended choice for most users.  See
+	  <xref linkend="updating-upgrading-portsnap"/>
+	  for a detailed description of
 	  <application>Portsnap</application>.</para>
 
 	<step>
@@ -946,7 +927,7 @@ Deinstalling ca_root_nss-3.15.1_1... don
 	    <application>Portsnap</application> has been completed as
 	    shown above,
 	    <filename class="directory">/usr/ports</filename> can be
-	    updated with:</para>
+	    updated as needed by running:</para>
 
 	  <screen>&prompt.root; <userinput>portsnap fetch</userinput>
 &prompt.root; <userinput>portsnap update</userinput></screen>
@@ -956,8 +937,8 @@ Deinstalling ca_root_nss-3.15.1_1... don
       <procedure>
 	<title>Subversion Method</title>
 
-	<para>If more control over the ports tree is needed (for
-	  example, for maintaining local changes),
+	<para>If more control over the ports tree is needed or if
+	  local changes need to be maintained,
 	  <application>Subversion</application> can be used to
 	  obtain the Ports Collection.  Refer to <ulink
 	    url="&url.articles.committers-guide;/subversion-primer.html">the
@@ -988,22 +969,17 @@ Deinstalling ca_root_nss-3.15.1_1... don
 	</step>
 
 	<step>
-	  <para>Check out a copy of the ports tree.  Use a specific
+	  <para>Check out a copy of the ports tree.  For better performance,
+	    replace <replaceable>svn0.us-east.FreeBSD.org</replaceable> with a
 	    <ulink
 	      url="&url.books.handbook;/svn-mirrors.html">Subversion
-	      mirror</ulink> close to your geographic location instead
-	    of <replaceable>svn0.us-east.FreeBSD.org</replaceable> in the
-	    command below for better performance.  Committers should
-	    read the <ulink
-	      url="&url.articles.committers-guide;/subversion-primer.html">Subversion
-	      Primer</ulink> first to be sure the correct protocol is
-	    chosen.</para>
+	      mirror</ulink> close to your geographic location:</para>
 
 	  <screen>&prompt.root; <userinput>svn checkout https://<replaceable>svn0.us-east.FreeBSD.org</replaceable>/ports/head /usr/ports</userinput></screen>
 	</step>
 
 	<step>
-	  <para>To update
+	  <para>As needed, update
 	    <filename class="directory">/usr/ports</filename> after
 	    the initial <application>Subversion</application>
 	    checkout:</para>
@@ -1012,411 +988,259 @@ Deinstalling ca_root_nss-3.15.1_1... don
 	</step>
       </procedure>
 
-      <procedure>
-	<title>Sysinstall Method</title>
-
-	<para>This method involves using
-	  <application>sysinstall</application> to install the Ports
-	  Collection from the installation media.  Note that the old
-	  copy of Ports Collection from the date of the release will
-	  be installed.  If you have Internet access, you should
-	  always use one of the methods mentioned above.</para>
-
-	<step>
-	  <para>As <username>root</username>, run
-	    <command>sysinstall</command> as shown below:</para>
-
-	  <screen>&prompt.root; <userinput>sysinstall</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Scroll down and select
-	    <guimenuitem>Configure</guimenuitem>, press
-	    <keycap>Enter</keycap>.</para>
-	</step>
-
-	<step>
-	  <para>Scroll down and select
-	    <guimenuitem>Distributions</guimenuitem>, press
-	    <keycap>Enter</keycap>.</para>
-	</step>
-
-	<step>
-	  <para>Scroll down to <guimenuitem>ports</guimenuitem>, press
-	    <keycap>Space</keycap>.</para>
-	</step>
-
-	<step>
-	  <para>Scroll up to <guimenuitem>Exit</guimenuitem>, press
-	    <keycap>Enter</keycap>.</para>
-	</step>
-
-	<step>
-	  <para>Select your desired installation media, such as CDROM,
-	    FTP, and so on.</para>
-	</step>
-
-	<step>
-	  <para>Scroll up to <guimenuitem>Exit</guimenuitem> and press
-	    <keycap>Enter</keycap>.</para>
-	</step>
-
-	<step>
-	  <para>Press <keycap>X</keycap> to exit
-	    <application>sysinstall</application>.</para>
-	</step>
-      </procedure>
-    </sect2>
-
-    <sect2 id="cvsup-migration">
-      <title>Migrating from
-	<application>CVSup</application>/<application>csup</application>
-	to <application>portsnap</application></title>
-
-      <warning>
-	<para>By February 28, 2013, the ports tree will no longer be
-	  exported to <application>CVS</application> and therefore
-	  <application>CVSup</application> and
-	  <application>csup</application> will no longer provide
-	  updates for the ports tree.</para>
-      </warning>
-
-      <procedure>
-	<title>Migration to Portsnap</title>
-
-	<para>The migration will require about 1 GB of disk space
-	  on <filename class="directory">/usr</filename>, plus
-	  <application>Portsnap</application> requires about
-	  150 MB disk space on <filename
-	    class="directory">/var</filename>.</para>
-
-	<step>
-	  <para>Disable any automated ports updates you may use, such
-	    as a &man.cron.8; job calling
-	    <application>CVSup</application> or
-	    <application>csup</application>.</para>
-	</step>
-
-	<step>
-	  <para>Move the existing ports tree to a temporary
-	    location:</para>
-
-	  <screen>&prompt.root; <userinput>mv /usr/ports /usr/ports.old</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Fetch the new ports tree with
-	    <application>Portsnap</application> and extract it to
-	    <filename class="directory">/usr/ports</filename>:</para>
-
-	  <screen>&prompt.root; <userinput>portsnap fetch extract</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Move distfiles and saved packages to the new ports
-	    tree:</para>
-
-	  <screen>&prompt.root; <userinput>mv /usr/ports.old/distfiles /usr/ports</userinput>
-&prompt.root; <userinput>mv /usr/ports.old/packages /usr/ports</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Delete the old ports tree:</para>
-
-	  <screen>&prompt.root; <userinput>rm -rf /usr/ports.old</userinput></screen>
-	</step>
-
-	<step>
-	  <para>If <application>CVSup</application> was used before,
-	    it can now be uninstalled:</para>
-
-	  <screen>&prompt.root; <userinput>pkg_delete -r -v cvsup-without-gui-\*</userinput></screen>
-
-	  <para>Users of <application>pkgng</application> can use the
-	    following command:</para>
-
-	  <screen>&prompt.root; <userinput>pkg delete cvsup-without-gui</userinput></screen>
-	</step>
-      </procedure>
-
-      <para>See <link linkend="updating-upgrading-portsnap">Using
-	  Portsnap</link> for a detailed description of
-	<application>Portsnap</application> and how to update the
-	ports tree with <application>Portsnap</application>.</para>
-    </sect2>
-
-    <sect2 id="ports-skeleton">
-      <title>Installing Ports</title>
-
-      <indexterm>
-	<primary>ports</primary>
-	<secondary>installing</secondary>
-      </indexterm>
-
-      <para>A port skeleton is a set of files that tell &os; system
-	how to compile and install a program.  Each port skeleton
-	includes:</para>
+      <para>The Ports Collection installs a series of directories
+	representing software categories with each category having
+	a subdirectory for each application.  Each subdirectory, also
+	referred to as a ports skeleton, contains a set of files that tell &os;
+	how to compile and install that program.  Each port skeleton
+	includes these files and directories:</para>
 
       <itemizedlist>
 	<listitem>
-	  <para><filename>Makefile</filename>:  The
-	    <filename>Makefile</filename> contains statements that
+	  <para><filename>Makefile</filename>: contains statements that
 	    specify how the application should be compiled and where
 	    its components should be installed.</para>
 	</listitem>
 
 	<listitem>
-	  <para><filename>distinfo</filename>:  This file contains
-	    information about the files that must be downloaded to
-	    build the port, and their checksums (using
-	    &man.sha256.1;), to verify that files have not been
-	    corrupted during the download.</para>
+	  <para><filename>distinfo</filename>: contains the names
+	    and checksums of the files that must be downloaded to
+	    build the port.</para>
 	</listitem>
 
 	<listitem>
-	  <para><filename>files/</filename>:  This directory contains
+	  <para><filename>files/</filename>: this directory contains
 	    any patches needed for the program to compile and install
 	    on &os;.  This directory may also contain other files used
 	    to build the port.</para>
 	</listitem>
 
 	<listitem>
-	  <para><filename>pkg-descr</filename>: This file provides a
+	  <para><filename>pkg-descr</filename>: provides a
 	    more detailed description of the program.</para>
 	</listitem>
 
 	<listitem>
-	  <para><filename>pkg-plist</filename>:  This is a list
+	  <para><filename>pkg-plist</filename>:  a list
 	    of all the files that will be installed by the port.  It
-	    also tells the ports system what files to remove upon
+	    also tells the ports system which files to remove upon
 	    deinstallation.</para>
 	</listitem>
       </itemizedlist>
 
-      <para>Some ports include other files, such as
-	<filename>pkg-message</filename>.  The ports system uses these
-	files to handle special situations.  If you want more details
+      <para>Some ports include
+	<filename>pkg-message</filename> or other
+	files to handle special situations.  For more details
 	on these files, and on ports in general, refer to the
 	<ulink url="&url.books.porters-handbook;/index.html">&os;
 	  Porter's Handbook</ulink>.</para>
 
       <para>The port does not include the actual source code, also
-	known as a <quote>distfile</quote>. Source code is distributed
-	in whatever manner the software author desires.  The two
-	methods for installing a &os; port are described below.</para>
+	known as a <filename>distfile</filename>.  The extract portion
+	of building a port will automatically save the downloaded
+	source to <filename
+	  class="directory">/usr/ports/distfiles</filename>.</para>
 
-      <note>
-	<para>You must be logged in as <username>root</username> to
-	  install ports.</para>
-      </note>
+      <sect2 id="ports-skeleton">
+      <title>Installing Ports</title>
+
+      <indexterm>
+	<primary>ports</primary>
+	<secondary>installing</secondary>
+      </indexterm>
+
+      <para>This section provides basic instructions on using the Ports
+	Collection to install or remove software.  The detailed
+	description of available <command>make</command> targets and
+	environment variables is available in &man.ports.7;.</para>
 
       <warning>
-	<para>Before compiling any port, be sure to have an
-	  up-to-date Ports Collection and check <ulink
-	    url="http://vuxml.freebsd.org/"></ulink> for security
-	  issues related to your port.  If <filename
+	<para>Before compiling any port, be sure to update the
+	  Ports Collection as described in the previous section.
+	  Since the installation of any third-party software can
+	  introduce security vulnerabilities, it is recommended to
+	  first check <ulink
+	    url="http://vuxml.freebsd.org/"></ulink> for known security
+	  issues related to the port.  Alternately, if <filename
 	    role="package">ports-mgmt/portaudit</filename> is
 	  installed, run <command>portaudit -F</command> before
-	  installing a new port, to fetch the current vulnerabilities
-	  database.  A security audit and an update of the database
-	  will be performed during the daily security system check.
-	  For more information read the &man.portaudit.1; and
-	  &man.periodic.8; manual pages.</para>
+	  installing a new port.  This command can be configured to
+	  automatically perform a security audit and an update of the vulnerability database
+	  during the daily security system check.
+	  For more information, refer to the manual page for <application>portaudit</application> and
+	  &man.periodic.8;.</para>
       </warning>
 
       <para>Using the Ports Collection assumes a working Internet
-	connection.  Otherwise, manually obtain and place a copy of
-	the distfile into
-	<filename>/usr/ports/distfiles</filename>.</para>
+	connection.  It also requires
+	superuser privilege.</para>
 
-      <para>To begin, change to the directory of the port to
-	be installed:</para>
-
-      <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput></screen>
-
-      <para>To compile, or <quote>build</quote>, the port, type
-	<command>make</command> at the prompt.  You should see
-	messages similar to the ones in this example:</para>
-
-      <screen>&prompt.root; <userinput>make</userinput>
->> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
+      <para>Some third-party DVD products such as the &os;
+	Toolkit from <ulink url="http://www.freebsdmall.com/">freebsdmall.com
+	  </ulink> contain distfiles which can be used to install ports
+	without an Internet connection.
+	Mount the DVD on
+	<filename class="directory">/cdrom</filename>.  If you use a different mount
+	point, set the <makevar>CD_MOUNTPTS</makevar> make variable.  The
+	needed distfiles will be automatically used if they are
+	present on the disk.  However, the licenses of a few ports do not allow their inclusion
+	  on the DVD.  This could be because a registration form
+	  needs to be filled out before downloading or redistribution
+	  is not allowed.  In order to install a port not included
+	  on the DVD, a connection to the
+	  Internet will still be required.</para>
+
+      <para>To compile and install the port, change to the directory of the port to
+	be installed, then type
+	<command>make install</command> at the prompt.  Messages will
+	indicate the progress:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
+&prompt.root; <userinput>make install</userinput>
+>> lsof_4.88D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
 >> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
-===>  Extracting for lsof-4.57
+===>  Extracting for lsof-4.88
 ...
 [extraction output snipped]
 ...
->> Checksum OK for lsof_4.57D.freebsd.tar.gz.
-===>  Patching for lsof-4.57
-===>  Applying FreeBSD patches for lsof-4.57
-===>  Configuring for lsof-4.57
+>> Checksum OK for lsof_4.88D.freebsd.tar.gz.
+===>  Patching for lsof-4.88.d,8
+===>  Applying FreeBSD patches for lsof-4.88.d,8
+===>  Configuring for lsof-4.88.d,8
 ...
 [configure output snipped]
 ...
-===>  Building for lsof-4.57
+===>  Building for lsof-4.88.d,8
 ...
 [compilation output snipped]
 ...
-&prompt.root;</screen>
-
-      <para>Once the compile is complete, you are returned to the
-	prompt.  The next step is to install the port using
-	<command>make <maketarget>install</maketarget></command>:</para>
 
-      <screen>&prompt.root; <userinput>make install</userinput>
-===>  Installing for lsof-4.57
+===>  Installing for lsof-4.88.d,8
 ...
 [installation output snipped]
 ...
 ===>   Generating temporary packing list
-===>   Compressing manual pages for lsof-4.57
-===>   Registering installation for lsof-4.57
+===>   Compressing manual pages for lsof-4.88.d,8
+===>   Registering installation for lsof-4.88.d,8
 ===>  SECURITY NOTE:
       This port has installed the following binaries which execute with
       increased privileges.
+/usr/local/sbin/lsof
 &prompt.root;</screen>
 
-      <para>Once you are returned to the prompt, you should be able
-	to run the installed application.  Since
+      <para>Since
 	<command>lsof</command> is a program that runs with increased
-	privileges, a security warning is shown.  During the building
-	and installation of ports, take heed of any other warnings
-	that may appear.</para>
+	privileges, a security warning is displayed as it is installed.
+	Once the installation is complete, the prompt will be
+	returned.</para>
 
-      <para>It is a good idea to delete the working subdirectory,
+	  <para>Some shells keep a cache of the commands that are
+	  available in the directories listed in the
+	  <envar>PATH</envar> environment variable, to speed up lookup
+	  operations for the executable file of these commands.  Users
+	  of the <command>tcsh</command> shell should
+	  type <command>rehash</command> so that a newly installed
+	  command can be used without specifying its full path.  Use
+	  <command>hash -r</command> instead for the
+	  <command>sh</command> shell.  Refer to the documentation for
+	  the shell for more information.</para>
+
+      <para>During installation, a working subdirectory is created
 	which contains all the temporary files used during
-	compilation.  Doing so saves disk space and minimizes the
+	compilation.  Removing this directory saves disk space and minimizes the
 	chance of problems later when upgrading to the newer version
-	of the port.</para>
+	of the port:</para>
 
       <screen>&prompt.root; <userinput>make clean</userinput>
-===>  Cleaning for lsof-4.57
+===>  Cleaning for lsof-88.d,8
 &prompt.root;</screen>
 
       <note>
-	<para>You can save two extra steps by just running
+	<para>To save this extra step, instead use
 	  <command>make
-	    <maketarget>install clean</maketarget></command>
-	  instead of <command>make</command>,
-	  <command>make <maketarget>install</maketarget></command>
-	  and <command>make <maketarget>clean</maketarget></command>
-	  as three separate steps.</para>
+	    <maketarget>install clean</maketarget></command> when
+	  compiling the port.</para>
       </note>
+      
+      <sect3>
+	<title>Customizing Ports Installation</title>
 
-      <note>
-	<para>Using only
-	  <command>make <maketarget>install</maketarget></command>
-	  means there will potentially be many
-	  waiting periods between user interaction as the default
-	  behaviour is to prompt the user for options.  To avoid this
-	  when there are many dependencies, first run <command>make
+	<para>Some ports provide build options which can be used to
+	  enable or disable application components,
+	  provide security options, or allow for other customizations.
+	  Examples include
+	  <filename role="package">www/firefox</filename>,
+	  <filename role="package">security/gpgme</filename>, and
+	  <filename role="package">mail/sylpheed-claws</filename>.
+	  If the port has configurable options, it may pause
+	  several times for
+	  user interaction as the default
+	  behavior is to prompt the user to select options from a menu.
+ 	  To avoid this,
+	  run <command>make
 	    <maketarget>config-recursive</maketarget></command> to do
-	  the configuration in one batch.  Then run <command>make
+	  this configuration in one batch.  Then, run <command>make
 	    <maketarget>install [clean]</maketarget></command>
-	  afterwards.</para>
-      </note>
+	  to compile and install the port.</para>
 
       <tip>
 	<para>When using <maketarget>config-recursive</maketarget>,
 	  the list of ports to configure are gathered by the
-	  <maketarget>all-depends-list</maketarget> &man.make.1;
-	  target.  It is often recommended to run <command>make
+	  <maketarget>all-depends-list</maketarget>
+	  target.  It is recommended to run <command>make
 	    <maketarget>config-recursive</maketarget></command>
 	  until all dependent ports options have been defined, and
-	  ports options &man.dialog.1; screens no longer
-	  appear, to be certain all ports options have been
-	  configured as intended.</para>
+	  ports options screens no longer
+	  appear, to be certain that all dependency options have been
+	  configured.</para>
       </tip>
 
-      <note>
-	<para>Some shells keep a cache of the commands that are
-	  available in the directories listed in the
-	  <envar>PATH</envar> environment variable, to speed up lookup
-	  operations for the executable file of these commands.  If
-	  you are using <command>tcsh</command>, you might have to
-	  type <command>rehash</command> so that a newly installed
-	  command can be used without specifying its full path.  Use
-	  <command>hash -r</command> instead for the
-	  <command>sh</command> shell.  Refer to the documentation for
-	  the shell for more information.</para>
-      </note>
-
-      <para>Some third-party DVD products such as the &os;
-	Toolkit from the <ulink url="http://www.freebsdmall.com/">&os;
-	  Mall</ulink> contain distfiles.  They can be used with the
-	Ports Collection.  Mount the DVD on
-	<filename>/cdrom</filename>.  If you use a different mount
-	point, set <makevar>CD_MOUNTPTS</makevar> make variable.  The
-	needed distfiles will be automatically used if they are
-	present on the disk.</para>
-
-      <note>
-	<para>The licenses of a few ports do not allow their inclusion
-	  on the DVD.  This could be because a registration form
-	  needs to be filled out before downloading or redistribution
-	  is not allowed.  If you wish to install a port not included
-	  on the DVD, you will need to be connected to the
-	  Internet.</para>
-      </note>
+      <para>There are several ways to revisit a port's build options menu
+	  in order to add, remove, or change these options after a
+	  port has been built.  One method is to
+	  <command>cd</command> into the directory containing the
+	  port and type
+	  <command>make <maketarget>config</maketarget></command>.
+	  Another option is to use
+	  <command>make <maketarget>showconfig</maketarget></command>.
+	  Another option is to execute
+	  <command>make <maketarget>rmconfig</maketarget></command>
+	  which will remove all selected options and allow you to
+	  start over.  All of these options, and others, are explained
+	  in great detail in &man.ports.7;.</para>
 
       <para>The ports system uses &man.fetch.1; to download the
-	files, which honors various environment variables, including
+	source files, which supports various environment variables.  The
 	<envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and
-	<envar>FTP_PASSWORD</envar>.  You may need to set one or more
-	of these if you are behind a firewall, or need to use an
+	<envar>FTP_PASSWORD</envar> variables may need to be set if the &os; system
+	is behind a firewall or
 	FTP/HTTP proxy.  See &man.fetch.3; for the complete
-	list.</para>
+	list of supported variables.</para>
 
-      <para>For users which cannot be connected all the time, the
-	<command>make <maketarget>fetch</maketarget></command> option
-	is provided.  Run this command within
-	<filename>/usr/ports</filename> and the required files will
-	be downloaded.  This command also works in the
-	lower level categories, such as
-	<filename>/usr/ports/net</filename>.  Note that if a port
-	depends on libraries or other ports, this will
+      <para>For users who cannot be connected to the Internet all the time,
+	<command>make <maketarget>fetch</maketarget></command> can  be run
+	within
+	<filename class="directory">/usr/ports</filename>, to fetch all distfiles, or within
+	a category, such as
+	<filename class="directory">/usr/ports/net</filename>, or within the
+	specific port skeleton.  Note that if a port has any dependencies,
+	running this command in a category or ports skeleton will
 	<emphasis>not</emphasis> fetch the distfiles of ports
-	from another category.  Use
+	from another category.  Instead, use
 	<command>make
 	  <maketarget>fetch-recursive</maketarget></command>
-	to fetch
+	to also fetch the distfiles for
 	all the dependencies of a port.</para>
 
-      <note>
-	<para>You can build all the ports in a category or as a
-	  whole by running <command>make</command> in the top level
-	  directory.  This is dangerous, however, as some ports cannot
-	  co-exist.  In other cases, some ports can install two
-	  different files with the same filename.</para>
-      </note>
-
-      <para>In some rare cases, users may need to acquire the
-	tarballs from a site other than the default
-	<makevar>MASTER_SITES</makevar>.  You can override the
-	<makevar>MASTER_SITES</makevar> option with the following
-	command:</para>
+      <para>In rare cases, such as when an organization has a local
+	distfiles repository, the
+	<makevar>MASTER_SITES</makevar> variable can be used to override the
+	download locations specified in the <filename>Makefile</filename>.
+	When using, specify the alternate location:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput>
 &prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \
-ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen>
-
-      <para>In this example, <makevar>MASTER_SITES</makevar> is
-	changed to <hostid
-	  role="fqdn">ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</hostid>.</para>
-
-      <note>
-	<para>Some ports provide build options which can be used to
-	  enable/disable parts of the application which are unneeded,
-	  provide security options, or allow for other customizations.
-	  Examples include
-	  <filename role="package">www/firefox</filename>,
-	  <filename role="package">security/gpgme</filename>, and
-	  <filename role="package">mail/sylpheed-claws</filename>.  A
-	  menu will be displayed at the beginning of a port
-	  compile when compile options are available.</para>
-      </note>
-
-      <sect3>
-	<title>Overriding the Default Ports Directories</title>
+<replaceable>ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/</replaceable> fetch</userinput></screen>
 
 	<para>The <makevar>WRKDIRPREFIX</makevar> and
 	  <makevar>PREFIX</makevar> variables can override the default
@@ -1425,44 +1249,24 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/
 	<screen>&prompt.root; <userinput>make WRKDIRPREFIX=/usr/home/example/ports install</userinput></screen>
 
 	<para>will compile the port in
-	  <filename>/usr/home/example/ports</filename> and install
-	  everything under <filename>/usr/local</filename>.</para>
+	  <filename class="directory">/usr/home/example/ports</filename> and install
+	  everything under <filename class="directory">/usr/local</filename>.</para>
 
 	<screen>&prompt.root; <userinput>make PREFIX=/usr/home/example/local install</userinput></screen>
 
-	<para>will compile the port in <filename>/usr/ports</filename>
+	<para>will compile the port in <filename class="directory">/usr/ports</filename>
 	  and install it in
-	  <filename>/usr/home/example/local</filename>.</para>
-
-	<para>And</para>
+	  <filename class="directory">/usr/home/example/local</filename>.  And:</para>
 
 	<screen>&prompt.root; <userinput>make WRKDIRPREFIX=../ports PREFIX=../local install</userinput></screen>
 
 	<para>will combine the two.</para>
 
-	<para>Alternatively, these can be set as environmental
+	<para>These can also be set as environmental
 	  variables.  Refer to the manual page for your shell
 	  for instructions on how to set an environmental
 	  variable.</para>
-      </sect3>
-
-      <sect3>
-	<title>Reconfiguring Ports</title>
 
-	<para>Certain ports provide an ncurses-based menu containing
-	  build options.  There are several ways to revisit this menu
-	  in order to add, remove, or change these options after a
-	  port has been built.  One method is to
-	  <command>cd</command> into the directory containing the
-	  port and type
-	  <command>make <maketarget>config</maketarget></command>.
-	  Another option is to use
-	  <command>make <maketarget>showconfig</maketarget></command>.
-	  Another option is to execute
-	  <command>make <maketarget>rmconfig</maketarget></command>
-	  which will remove all selected options and allow you to
-	  start over.  All of these options, and others, are explained
-	  in great detail in the manual page for &man.ports.7;.</para>
       </sect3>
     </sect2>
 
@@ -1474,10 +1278,34 @@ ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/
 	<secondary>removing</secondary>
       </indexterm>
 
-      <para>Installed ports and packages are uninstalled using
-	the &man.pkg.delete.1; command:</para>
-
-      <screen>&prompt.root; <userinput>pkg_delete lsof-4.57</userinput></screen>
+      <para>Installed ports can be uninstalled using
+	&man.pkg.delete.1;.  Alternately, if the &os; system has been
+	configured to use <application>pkg</application>, a port can be
+	uninstalled using <command>pkg delete</command>.  Examples
+	for using these commands can be found in <xref
+	  linkend="packages-using"/> and <xref
+	  linkend="pkgng-intro"/></para>
+
+      <para>Alternately, <command>make deinstall</command> can be
+	run in the port's directory:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput>
+<userinput>make deinstall</userinput>
+===>  Deinstalling for sysutils/lsof
+===>   Deinstalling
+Deinstallation has been requested for the following 1 packages:
+
+	lsof-4.88.d,8
+
+The deinstallation will free 229 kB
+[1/1] Deleting lsof-4.88.d,8... done</screen>
+
+      <para>It is recommended to read the messages as the port is
+	uninstalled.  If the port has any applications that depend
+	upon it, this information will be displayed but the
+	uninstallation will proceed.  In such cases, it may be better
+	to reinstall the application in order to prevent broken
+	dependencies.</para>
     </sect2>
 
     <sect2 id="ports-upgrading">


More information about the svn-doc-all mailing list