Changeset 122996 for trunk/doc-new


Ignore:
Timestamp:
Aug 3, 2014, 12:54:13 PM (4 years ago)
Author:
cal@…
Message:

guide: Refactor the complete "using" section, add undocumented stuff, remove outdated information (e.g., rpm packaging), add standard modeline (except the tcl stuff), reformat.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc-new/guide/xml/using.xml

    r122549 r122996  
    11<?xml version="1.0" encoding="UTF-8"?>
     2<!-- -*- coding: utf-8; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- vim:fenc=utf-8:et:sw=4:ts=4:sts=4:tw=120
     3-->
    24<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    35"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
     
    68]>
    79<chapter id="using">
    8   <title>Using MacPorts</title>
    9 
    10   <para>This chapter describes using the <command>port</command> command, port
    11   variants, common tasks and port binaries<!--, and setting up an rsync
    12   replication server-->.</para>
    13 
    14   <section id="using.port">
    15     <title>The port Command</title>
    16 
    17     <para>The MacPorts <command>port</command> command is the main utility
    18     used to interact with MacPorts. It is used to update
    19     <filename>Portfile</filename>s and the MacPorts infrastructure, and
    20     install and manage ports.</para>
    21 
    22     <section id="using.port.help">
    23       <title>help</title>
    24 
    25       <para>The <option>help</option> action shows some brief information about
    26       the specified action, or if no action is specified, shows basic usage
    27       information for the <command>port</command> command in general.</para>
    28 
    29       <programlisting><prompt>%%</prompt> <userinput>port help selfupdate</userinput></programlisting>
    30       <screen>Usage: selfupdate --nosync
    31 
    32 Upgrade MacPorts itself and run the sync target</screen>
    33     </section>
    34 
    35     <section id="using.port.selfupdate">
    36       <title>selfupdate</title>
    37 
    38       <para>The <option>selfupdate</option> action should be used regularly to
    39       <option>sync</option> the local ports tree with the global MacPorts
    40       ports repository so you will have the latest port versions. It also
    41       checks for new revisions of the MacPorts infrastructure, called MacPorts
    42       base, and upgrades it when necessary.</para>
    43 
    44       <note>
    45         <para>Selfupdate is only tested on OS X. If you are running MacPorts on
    46           another platform, <option>selfupdate</option> may not work correctly.
    47           In this case, you should use the <link
    48             linkend="using.port.sync">sync</link> action to update the ports
    49           tree; to update MacPorts base you must manually install a newer
    50           version from source.</para>
    51       </note>
    52 
    53       <programlisting><prompt>%%</prompt> <userinput>sudo port selfupdate</userinput></programlisting>
    54 
    55       <screen>
    56 --->  Updating MacPorts base sources using rsync
    57 MacPorts base version &macports-version; installed,
    58 MacPorts base version &macports-version; downloaded.
    59 --->  Updating the ports tree
    60 --->  MacPorts base is already the latest version
    61 </screen>
    62 
    63       <para>As always, you can use the debug flag for verbose output. This is
    64         useful to debug problems with <option>selfupdate</option>.</para>
    65 
    66       <programlisting><prompt>%%</prompt> <userinput>sudo port -d selfupdate</userinput></programlisting>
    67 
    68       <para>If <option>selfupdate</option> detects that a newer version of
    69       MacPorts base is available, it automatically updates the installed copy
    70       of MacPorts base to the latest released version. In that case, you will
    71       see this message:</para>
    72 
    73       <screen>
    74 --->  Updating MacPorts base sources using rsync
    75 MacPorts base version &macports-prev-version; installed,
    76 MacPorts base version &macports-version; downloaded.
    77 --->  Updating the ports tree
    78 --->  MacPorts base is outdated, installing new version &macports-version;
    79 Installing new MacPorts release in /opt/local as root:admin; permissions 755
    80 </screen>
    81 
    82       <para>If the <option>selfupdate</option> procedure fails you'll see
    83       a message like this:</para>
    84 
    85       <screen>Error installing new MacPorts base: command execution failed</screen>
    86 
    87       <para>Re-run <option>selfupdate</option> with the <option>-d</option>
    88       flag to see all output generated by the build system. The output may give
    89       you an idea why the build failed. If it doesn't, please <link
    90         linkend="project.tickets">file a ticket</link> and attach the output
    91       generated by <command>sudo port -d selfupdate</command>.</para>
    92     </section>
    93 
    94     <section id="using.port.sync">
    95       <title>sync</title>
    96 
    97       <para>The <option>sync</option> action performs a subset of
    98       <option>selfupdate</option> actions. It synchronizes the ports tree, as
    99       does <option>selfupdate</option>, but it does not check for upgrades to
    100       MacPorts base. On OS X, unless there is a special reason not to do
    101       so, you should run <link
    102       linkend="using.port.selfupdate">selfupdate</link>.</para>
    103 
    104       <note>
    105         <para>For platforms other than OS X, <option>sync</option> is the
    106         only way to get port updates because <option>selfupdate</option> is
    107         supported only on OS X.</para>
    108       </note>
    109     </section>
    110 
    111     <section id="using.port.list">
    112       <title>list</title>
    113 
    114       <para>The <option>list</option> action lists the currently available version of
    115       the specified ports, or if no ports are specified, displays a list of all available
    116       ports. The list of available ports is very long, so use <link
    117       linkend="using.port.search">search</link> if you know a port's name or
    118       part of it.</para>
    119 
    120       <programlisting><prompt>%%</prompt> <userinput>port list</userinput></programlisting>
    121     </section>
    122 
    123     <section id="using.port.search">
    124       <title>search</title>
    125 
    126       <para>The <option>search</option> action allows finding ports
    127       by partial matches of the name or description. Other fields can be matched
    128       against, and matched in different ways, by using options. Run <userinput>port help search</userinput>
    129       for details.</para>
    130 
    131       <programlisting><prompt>%%</prompt> <userinput>port search rrd</userinput></programlisting>
    132 
    133       <screen>php5-rrdtool @1.0 (php, net, devel)
    134     PHP 5 glue for rrdtool
    135 
    136 rrdtool @1.4.4 (net)
     10    <title>Using MacPorts</title>
     11
     12    <para>This chapter describes using the <command>port</command> command, port variants, common tasks and port
     13    binaries.</para>
     14
     15    <section id="using.port">
     16        <title>The port Command</title>
     17
     18        <para>The MacPorts <command>port</command> command is the main utility used to interact with MacPorts. It is
     19            used to update <filename>Portfile</filename>s and the MacPorts infrastructure, and install and manage
     20            ports.</para>
     21
     22        <section id="using.port.help">
     23            <title>port help</title>
     24
     25            <para>The <option>help</option> action shows some brief information about the specified action, or if no
     26                action is specified, shows basic usage information for the <command>port</command> command in
     27                general.</para>
     28
     29            <programlisting><prompt>$</prompt> <userinput>port help selfupdate</userinput></programlisting>
     30
     31            <screen>
     32Usage: selfupdate --nosync
     33
     34Upgrade MacPorts itself and run the sync target
     35
     36--nosync   Do not run the sync target, i.e. do not update the ports tree.
     37           Only checks for (and installs, if available) new versions of
     38           MacPorts.</screen>
     39        </section>
     40
     41        <section id="using.port.selfupdate">
     42            <title>port selfupdate</title>
     43
     44            <para>The <option>selfupdate</option> action should be used regularly to update the local ports tree with
     45                the global MacPorts ports repository so you will have the latest versions of software packages
     46                available. It also checks for new releases of MacPorts itself, and upgrades it when necessary.</para>
     47
     48            <programlisting><prompt>$</prompt> <userinput>sudo port selfupdate</userinput></programlisting>
     49
     50            <screen>
     51<!--        -->---&gt; Updating MacPorts base sources using rsync
     52<!--        -->MacPorts base version &macports-version; installed,
     53<!--        -->MacPorts base version &macports-version; downloaded.
     54<!--        -->---&gt; Updating the ports tree
     55<!--        -->---&gt; MacPorts base is already the latest version</screen>
     56
     57            <para>If <option>selfupdate</option> detects that a newer version of MacPorts is available, it automatically
     58                updates the installed copy of MacPorts base to the latest released version. In that case, you will see
     59                this message:</para>
     60
     61            <screen>
     62<!--        -->---&gt; Updating MacPorts base sources using rsync
     63<!--        -->MacPorts base version &macports-prev-version; installed,
     64<!--        -->MacPorts base version &macports-version; downloaded.
     65<!--        -->---&gt; Updating the ports tree
     66<!--        -->---&gt; MacPorts base is outdated, installing new version &macports-version;
     67<!--        -->Installing new MacPorts release in /opt/local as root:admin; permissions 755</screen>
     68
     69            <para>If the <option>selfupdate</option> procedure fails you'll see a message like this:</para>
     70
     71            <screen>Error installing new MacPorts base: command execution failed</screen>
     72
     73            <para>As always, you can use the debug flag <option>-d</option> to enable verbose output. If your
     74                <option>selfupdate</option> failed, re-run it with debug output enabled to see all output generated by
     75                the build system.</para>
     76
     77            <programlisting><prompt>$</prompt> <userinput>sudo port -d selfupdate</userinput></programlisting>
     78
     79            <para>The output may give you an idea why the build failed. Look for the first occurances of
     80                <quote>error</quote>. If you cannot figure out what's wrong yourself, feel free to ask on the
     81                <email>macports-users@lists.macosforge.org</email> mailing list and attach the output generated by
     82                <command>sudo port -d selfupdate</command>.</para>
     83
     84            <para><option>selfupdate</option> accepts a single switch:</para>
     85
     86            <variablelist>
     87                <varlistentry>
     88                    <term><option>--nosync</option></term>
     89                    <listitem>
     90                        <para>Only update MacPorts itself, do not update the tree of <filename>Portfile</filename>s.</para>
     91                    </listitem>
     92                </varlistentry>
     93            </variablelist>
     94        </section>
     95
     96        <section id="using.port.sync">
     97            <title>port sync</title>
     98
     99            <para>The <option>sync</option> action performs a subset of <option>selfupdate</option>. It synchronizes the
     100                ports tree, as does <option>selfupdate</option>, but it does not check for MacPorts upgrades. On OS X,
     101                unless there is a special reason not to do so, you should alawys run <link
     102                    linkend="using.port.selfupdate">selfupdate</link>.</para>
     103
     104            <para><option>sync</option> does not accept any switches.</para>
     105        </section>
     106
     107        <section id="using.port.list">
     108            <title>port list</title>
     109
     110            <para>The <option>list</option> action lists the currently available version of the specified ports, or if
     111                no ports are specified, displays a list of all available ports. The list of available ports is very
     112                long, so use <link linkend="using.port.search">search</link> if you are looking for a specific
     113                port.</para>
     114
     115            <programlisting><prompt>$</prompt> <userinput>port list</userinput></programlisting>
     116
     117            <note>
     118                <para><command>port list</command> always lists the most recent version available in MacPorts, which is
     119                    not necessarily the version you have installed. For this reason, <command>port list
     120                        installed</command> likely produces unexpected output. In most cases where you would
     121                    <option>list</option>, using <option>installed</option> or <option>echo</option> is the better
     122                    choice instead. Both <command>port installed</command> and <command>port echo installed</command>
     123                    would produce the output you might expect from the command, <command>port list installed</command>
     124                    will not (and, to make matters worse, will be slow).</para>
     125
     126                <para>You will hardly need <command>port list</command> at all to work with MacPorts. When searching,
     127                    <command>port search</command> is the better choice and when trying to list ports, <command>port
     128                        installed</command> and <command>port echo</command> are much more useful.</para>
     129            </note>
     130        </section>
     131
     132        <section id="using.port.search">
     133            <title>port search</title>
     134
     135            <para>The <option>search</option> action allows finding ports by partial matches of the name or description.
     136                Other fields can be matched against, and matched in different ways, by using options. <command>port
     137                    search</command> is the tool of choice if you are looking for a specific software in MacPorts. We
     138                recommend you read up on some of its flags to improve your efficiency when searching for ports. Run
     139                <command>port help search</command> for an exhaustive list of possible switches.</para>
     140
     141            <para>Suppose you are looking for PHP in MacPorts. You might start with <command>port search php</command>
     142                and notice your query produces a lot of output. In fact, at the time of writing this, this search
     143                produces 661 matches. By default, <command>port search</command> searches both name and description of
     144                a port. While we're looking for PHP, we can reduce the number of hits by using the
     145                <option>--name</option> flag. Furthermore, we only want ports whose name starts with <quote>php</quote>,
     146                so we add the <option>--glob</option> flag (actually, we could leave it out because it is the default)
     147                and modify the search term to <userinput>php*</userinput>:</para>
     148
     149            <programlisting><prompt>$ </prompt><userinput>port search --name --glob 'php*'</userinput></programlisting>
     150
     151            <para>Furthermore, we can enable compact output by using the <option>--line</option> switch. This causes only
     152                a single line to be printed for each match:</para>
     153
     154            <programlisting><prompt>$ </prompt><userinput>port search --name --line --glob 'php*'</userinput></programlisting>
     155
     156            <para>Among a large number of PHP modules you will find the main PHP ports, which are named
     157                php<varname>&lt;version&gt;</varname>. Choose one to install.</para>
     158
     159            <para>If you know regex and know about the format of the PHP versions, you can further reduce the output of
     160                <command>port search</command>:</para>
     161
     162            <programlisting><prompt>$ </prompt><userinput>port search --name --line --regex '^php\d*$'</userinput></programlisting>
     163
     164            <screen><!--
     165            -->php     5.5       lang www    PHP: Hypertext Preprocessor
     166<!--        -->php4    4.4.9     lang www    PHP: Hypertext Preprocessor
     167<!--        -->php5    5.3.28    lang www    PHP: Hypertext Preprocessor
     168<!--        -->php52   5.2.17    lang www    PHP: Hypertext Preprocessor
     169<!--        -->php53   5.3.28    lang www    PHP: Hypertext Preprocessor
     170<!--        -->php54   5.4.31    lang www    PHP: Hypertext Preprocessor
     171<!--        -->php55   5.5.15    lang www    PHP: Hypertext Preprocessor
     172<!--        -->php56   5.6.0RC2  lang www    PHP: Hypertext Preprocessor</screen>
     173
     174            <para>Let us look at another example that is less complicated. Assuming you are looking for
     175                <userinput>rrdtool</userinput>, a popular system to store and graph time-series data, the simple search
     176                approach works well:</para>
     177
     178            <programlisting><prompt>$ </prompt><userinput>port search rrd</userinput></programlisting>
     179
     180            <screen>
     181cacti @0.8.8b (net)
     182    Cacti is a complete RRDtool network graphing solution.
     183
     184jrrd @1.0.4 (java)
     185    Java interface to RRDTool
     186
     187netmrg @0.20 (net)
     188    An RRDtool frontend for network monitoring, reporting, and graphing that generates day/week/month
     189    MRTG style graphs.
     190
     191network-weathermap @0.97c (net)
     192    Weathermap is a network visualisation tool, to take graphs you already have and display an
     193    overview of your network as a map. It supports RRD, MRTG (RRD and old log-format), and
     194    tab-delimited text files. Other sources are via plugins or external scripts.
     195
     196php-rrd @1.1.3 (php, net, devel)
     197    PHP rrdtool extension
     198
     199php5-rrd @1.1.3 (php, net, devel)
     200    PHP rrdtool extension
     201
     202php5-rrdtool @1.0.5 (php, net, devel)
     203    this port is only a stub and has been made obsolete by php5-rrd
     204
     205php53-rrd @1.1.3 (php, net, devel)
     206    PHP rrdtool extension
     207
     208php54-rrd @1.1.3 (php, net, devel)
     209    PHP rrdtool extension
     210
     211php55-rrd @1.1.3 (php, net, devel)
     212    PHP rrdtool extension
     213
     214rrdtool @1.4.7_5 (net)
    137215    Round Robin Database
    138216
    139 Found 2 ports.</screen>
    140     </section>
    141 
    142     <section id="using.port.info">
    143       <title>info</title>
    144 
    145       <para>The <option>info</option> action is used to get information about
    146       a port: description, maintainer, etc.</para>
    147 
    148       <programlisting><prompt>%%</prompt> <userinput>port info flowd</userinput></programlisting>
    149 
    150       <screen>flowd @0.9 (net)
     217Found 11 ports.</screen>
     218
     219            <para>The possible switches to <option>search</option> and their meaning are:</para>
     220
     221            <variablelist>
     222                <varlistentry>
     223                    <term><option>--case-sensitive</option></term>
     224                    <listitem>
     225                        <para>Match the search string in a case-sensitive manner.</para>
     226                    </listitem>
     227                </varlistentry>
     228
     229                <varlistentry>
     230                    <term><option>--exact</option></term>
     231                    <listitem>
     232                        <para>Match the literal search string exactly.</para>
     233                    </listitem>
     234                </varlistentry>
     235
     236                <varlistentry>
     237                    <term><option>--glob</option></term>
     238                    <listitem>
     239                        <para>Treat the given search string as glob search string (i.e., expand wildcards
     240                            <option>*</option>, <option>?</option>, and <option>[<varname>chars</varname>]</option>).
     241                            This is the default behavior.</para>
     242                    </listitem>
     243                </varlistentry>
     244
     245                <varlistentry>
     246                    <term><option>--regex</option></term>
     247                    <listitem>
     248                        <para>Treat the given search string as regular expression.</para>
     249                    </listitem>
     250                </varlistentry>
     251
     252                <varlistentry>
     253                    <term><option>--<varname>&lt;field&gt;</varname></option></term>
     254                    <listitem>
     255                        <para>Test the search string against <varname>&lt;field&gt;</varname>. Can be specified multiple
     256                            times to test against multiple fields. The default is <option>--name --description</option>.
     257                            Possible values for <varname>&lt;field&gt;</varname> are</para>
     258
     259                        <variablelist>
     260                            <varlistentry>
     261                                <term><option>--category</option>, <option>--categories</option></term>
     262                                <listitem>
     263                                    <para>Search for ports in a given category.</para>
     264                                </listitem>
     265                            </varlistentry>
     266
     267                            <varlistentry>
     268                                <term>
     269                                    <option>--depends</option>,
     270                                    <option>--depends_build</option>,
     271                                    <option>--depends_extract</option>,
     272                                    <option>--depends_fetch</option>,
     273                                    <option>--depends_lib</option>,
     274                                    <option>--depends_run</option></term>
     275                                <listitem>
     276                                    <para>Search for ports that depend on the port given as search string. The
     277                                        <option>--depends</option> is an alias for all other <option>--depends_</option>
     278                                        options combined. Note that only dependencies specified in default variants will
     279                                        be found.</para>
     280                                </listitem>
     281                            </varlistentry>
     282
     283                            <varlistentry>
     284                                <term><option>--description</option>, <option>--long_description</option></term>
     285                                <listitem>
     286                                    <para>Test the search string against ports' descriptions.</para>
     287                                </listitem>
     288                            </varlistentry>
     289
     290                            <varlistentry>
     291                                <term><option>--homepage</option></term>
     292                                <listitem>
     293                                    <para>Test the search string against the homepage field of all ports.</para>
     294                                </listitem>
     295                            </varlistentry>
     296
     297                            <varlistentry>
     298                                <term><option>--maintainer</option>, <option>--maintainer</option></term>
     299                                <listitem>
     300                                    <para>Search for ports maintained by a specific maintainer.</para>
     301                                </listitem>
     302                            </varlistentry>
     303
     304                            <varlistentry>
     305                                <term><option>--name</option></term>
     306                                <listitem>
     307                                    <para>Search only ports' names.</para>
     308                                </listitem>
     309                            </varlistentry>
     310
     311                            <varlistentry>
     312                                <term><option>--portdir</option></term>
     313                                <listitem>
     314                                    <para>Test the search string against the path of the directory that contains the port.</para>
     315                                </listitem>
     316                            </varlistentry>
     317
     318                            <varlistentry>
     319                                <term><option>--variant</option>, <option>--variants</option></term>
     320                                <listitem>
     321                                    <para>Search for variant names.</para>
     322                                </listitem>
     323                            </varlistentry>
     324                        </variablelist>
     325                    </listitem>
     326                </varlistentry>
     327            </variablelist>
     328        </section>
     329
     330        <section id="using.port.info">
     331            <title>port info</title>
     332
     333            <para>The <option>info</option> action is used to get information about a port: name, version, description,
     334                variants, homepage, dependencies, license, and maintainers.</para>
     335
     336            <programlisting><prompt>$ </prompt><userinput>port info yubico-pam</userinput></programlisting>
     337
     338            <screen>
     339yubico-pam @2.16 (security)
    151340Variants:             universal
    152341
    153 Description:          flowd is a small, fast and secure NetFlow collector.
    154 Homepage:             http://www.mindrot.org/flowd.html
    155 
     342Description:          The Yubico PAM module provides an easy way to integrate the YubiKey into your
     343                      existing user authentication infrastructure. The module can be configured to
     344                      validate YubiKeys against Yubico's YubiCloud infrastructure, a custom YubiKey
     345                      validation server or it can be used for offline authentication with newer
     346                      YubiKeys supporting a challenge-response protocol.
     347Homepage:             https://github.com/Yubico/yubico-pam
     348
     349Build Dependencies:   pkgconfig, autoconf, automake, libtool
     350Library Dependencies: ykpers, yubico-c-client
    156351Platforms:            darwin
    157 License:              unknown
    158 Maintainers:          nomaintainer@macports.org</screen>
    159     </section>
    160 
    161     <section id="using.port.deps">
    162       <title>deps</title>
    163 
    164       <para>The <option>deps</option> action shows you the dependencies of a
    165       port; dependencies are explicitly declared in
    166       <filename>Portfile</filename>s.</para>
    167 
    168       <programlisting><prompt>%%</prompt> <userinput>port deps apache2</userinput></programlisting>
    169 
    170       <screen>Full Name: apache2 @2.2.17_0+preforkmpm
    171 Library Dependencies: apr, apr-util, expat, openssl, pcre</screen>
    172     </section>
    173 
    174     <section id="using.port.variants">
    175       <title>variants</title>
    176 
    177       <para>The <option>variants</option> action allows you to check what
    178       variations of a port are available before you install it. Variants are a
    179       way for port authors to provide options that may be invoked at install
    180       time. See <link linkend="using.variants.invoking">Invoking Port
    181       Variants</link> below to install ports that have variants.</para>
    182 
    183       <programlisting><prompt>%%</prompt> <userinput>port variants nmap</userinput></programlisting>
    184 
    185       <screen>nmap has the variants:
    186    no_pcre: build without pcre support
    187    no_ssl: build without ssl support
     352License:              BSD
     353Maintainers:          cal@macports.org</screen>
     354        </section>
     355
     356        <section id="using.port.deps">
     357            <title>port deps</title>
     358
     359            <para>The <option>deps</option> action lists the dependencies of a port. Dependencies are the packages are
     360                required by a port at runtime (library and runtime dependencies) or required to install it (build,
     361                fetch, and extract dependencies).</para>
     362
     363            <programlisting><prompt>$ </prompt><userinput>port deps apache2</userinput></programlisting>
     364
     365            <screen>Full Name: apache2 @2.2.27_0+preforkmpm
     366<!--        -->Library Dependencies: apr, apr-util, expat, openssl, pcre, perl5, zlib</screen>
     367
     368            <para>Note that the list of dependencies might depend on the variants you chose. For example, choosing the
     369                <option>+openldap</option> variant of <option>apache2</option> adds a dependency on
     370                <option>openldap</option>:</para>
     371
     372            <programlisting><prompt>$ </prompt><userinput>port deps apache2 +openldap</userinput></programlisting>
     373
     374            <screen>Full Name: apache2 @2.2.27_0+openldap+preforkmpm
     375<!--        -->Library Dependencies: apr, apr-util, expat, openssl, pcre, perl5, zlib, openldap</screen>
     376
     377            <para><option>deps</option> accepts two switches:</para>
     378
     379            <variablelist>
     380                <varlistentry>
     381                    <term><option>--index</option></term>
     382                    <listitem>
     383                        <para>Do not read the <filename>Portfile</filename> to determine dependencies. Instead, rely on
     384                            the information cached in the port index. Note that (despite specifying them), this option
     385                            will ignore any effects of variants. It is, however, much faster.</para>
     386                    </listitem>
     387                </varlistentry>
     388
     389                <varlistentry>
     390                    <term><option>--no-build</option></term>
     391                    <listitem>
     392                        <para>Exclude dependencies only required at build time, i.e. fetch, extract, and build
     393                            dependencies.</para>
     394                    </listitem>
     395                </varlistentry>
     396            </variablelist>
     397
     398        </section>
     399
     400        <section id="using.port.variants">
     401            <title>port variants</title>
     402
     403            <para>The <option>variants</option> action allows you to check what variations of a port are available
     404                before you install it. Variants are a way for port authors to provide options you can use to customize
     405                your build at install time. See <link linkend="using.variants.invoking">Invoking Port Variants</link>
     406                below to install ports that have variants.</para>
     407
     408            <programlisting><prompt>$ </prompt><userinput>port variants apache2</userinput></programlisting>
     409
     410            <screen>
     411apache2 has the variants:
     412   eventmpm: Use event MPM (experimental)
     413     * conflicts with preforkmpm workermpm
     414   openldap: Enable LDAP support through OpenLDAP
     415[+]preforkmpm: Use prefork MPM
     416     * conflicts with eventmpm workermpm
    188417   universal: Build for multiple architectures
    189    zenmap: build zenmap in addition to nmap</screen>
    190     </section>
    191 
    192     <section id="using.port.install">
    193       <title>install</title>
    194 
    195       <para>The action <option>install</option> is used to install a port. See
    196       <link linkend="using.variants.invoking">Invoking Port Variants</link>
    197       below to install ports that have variants.</para>
    198 
    199       <programlisting><prompt>%%</prompt> <userinput>sudo port install nmap</userinput></programlisting>
    200 
    201       <note>
    202         <para>You may break up a port's installation into smaller steps for
    203         troubleshooting by passing <command>port</command> a prior
    204         installation phase such as fetch, configure, build, or destroot. See
    205         section <link linkend="reference.phases">Port Phases</link> for a
    206         complete list of phases.</para>
    207       </note>
    208     </section>
    209 
    210     <section id="using.port.clean">
    211       <title>clean</title>
    212 
    213       <para>The action <option>clean</option> deletes all intermediate files
    214       that MacPorts creates while building a port. A <userinput>port
    215       clean</userinput> is also often necessary to remove corrupted tarballs
    216       after a failed <userinput>fetch</userinput> phase.</para>
    217 
    218       <programlisting><prompt>%%</prompt> <userinput>sudo port clean --all vile</userinput></programlisting>
    219 
    220       <note>
    221         <para>You may also clean files selectively by using options
    222         <option>--dist</option>, <option>--archive</option>, or
    223         <option>--work</option>.</para>
    224       </note>
    225     </section>
    226 
    227     <section id="using.port.uninstall">
    228       <title>uninstall</title>
    229 
    230       <para>The <option>uninstall</option> action will remove an installed
    231       port.</para>
    232 
    233       <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall vile</userinput></programlisting>
    234 
    235       <note>
    236         <para>To also recursively uninstall the ports that the given port depends on,
    237         use the <option>&#x2011;&#x2011;follow&#x2011;dependencies</option> flag. This will not uninstall
    238         dependencies that are marked as requested or that have other dependents.</para>
    239         <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall --follow-dependencies vile</userinput></programlisting>
    240 
    241         <para>To recursively uninstall all ports that depend on the given port before uninstalling
    242         the port itself, use the <option>&#x2011;&#x2011;follow&#x2011;dependents</option> flag.</para>
    243         <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall --follow-dependents ncurses</userinput></programlisting>
    244 
    245         <para>If a port is a dependency of another installed port,
    246         uninstall will not remove it unless you remove the dependent port(s)
    247         first. To override this behavior, use the <option>-f</option> (force)
    248         switch. This will obviously break the dependents. Don't force uninstall ports
    249         unless you know what you are doing.</para>
    250 
    251         <programlisting><prompt>%%</prompt> <userinput>sudo port -f uninstall ncurses</userinput></programlisting>
    252       </note>
    253     </section>
    254 
    255     <section id="using.port.contents">
    256       <title>contents</title>
    257 
    258       <para>The <option>contents</option> action displays the files that have
    259       been installed by a given port. Uninstalled ports cannot have their
    260       contents listed.</para>
    261 
    262       <programlisting><prompt>%%</prompt> <userinput>port contents xorg-renderproto</userinput></programlisting>
    263 
    264       <screen>Port xorg-renderproto contains:
     418   workermpm: Use worker MPM
     419     * conflicts with eventmpm preforkmpm</screen>
     420
     421            <para>This output lists all variants followed by their description. If a variant depends on or conflicts
     422                with other variants, a line with the details on that follows. Variant lines that start with
     423                <option>[+]</option> are enabled by default by the <filename>Portfile</filename>. Variants that are
     424                marked with <option>(+)</option> are selected because of your configuration in
     425                <filename>$prefix/etc/macports/variants.conf</filename>. See <xref
     426                    linkend="internals.configuration-files.variants-conf" /> for more information on the
     427                <filename>variants.conf</filename> file.</para>
     428        </section>
     429
     430        <section id="using.port.install">
     431            <title>port install</title>
     432
     433            <para>The action <option>install</option> is used to install a port. Once you determined the name of a port
     434                you want (possibly using <link linkend="using.port.search"><command>port search</command></link>), you
     435                can install it using this command. See <xref linkend="using.variants.invoking" /> on how to choose
     436                variants when installing a new port. For example,</para>
     437
     438            <programlisting><prompt>$ </prompt><userinput>sudo port install apache2 -preforkmpm +workermpm</userinput></programlisting>
     439
     440            <para>installs the <option>apache2</option> port without the <option>preforkmpm</option>, but with the
     441                <option>workermpm</option> variant.</para>
     442
     443            <para>If the installation of a port fails, you can enable verbose or debug output by giving the
     444                <option>-v</option> or <option>-d</option> flag to port:</para>
     445
     446            <programlisting><prompt>$ </prompt><userinput>sudo port -v install apache2</userinput></programlisting>
     447
     448            <para>All debug information is also kept in the <filename>main.log</filename> file for the port you
     449                installed. Its path will be printed automatically if the installation fails. You can manually get the
     450                path using <command>port logfile <varname>&lt;portname&gt;</varname></command>. Note that logfiles will
     451                automatically be deleted on successful installation.</para>
     452
     453            <para>If the installation of a port fails, you should always clean and try again, i.e., run</para>
     454
     455            <programlisting><prompt>$ </prompt><userinput>sudo port clean <varname>&lt;portname&gt;</varname></userinput></programlisting>
     456
     457            <para>and re-execute the command you ran before.</para>
     458
     459            <para>You might also want to try enabling trace mode, which can prevent conflicts caused by files installed
     460                by other ports or in common system locations, such as <filename>/usr/local</filename>. To do that,
     461                re-run the installation with the <option>-t</option> flag, i.e.,</para>
     462
     463            <programlisting><prompt>$ </prompt><userinput>sudo port -t install <varname>&lt;portname&gt;</varname></userinput></programlisting>
     464
     465            <para>If the port still fails to install after you have followed these steps, please <link
     466                    linkend="project.tickets">file a ticket</link> and attach the <filename>main.log</filename> of
     467                a clean attempt.</para>
     468
     469            <note>
     470                <para>The installation of a single port consists of multiple phases. These phases are fetch, extract,
     471                    patch, configure, build, destroot, archive, and finally install. You may break up a port's
     472                    installation into smaller steps for troubleshooting by using the name of one of these phases as
     473                    action rather than <option>install</option>. For example</para>
     474
     475                <programlisting><prompt>$ </prompt><userinput>sudo port destroot apache2</userinput></programlisting>
     476
     477                <para>will run the installation of <option>apache2</option> until the destroot phase. See <xref
     478                    linkend="reference.phases" /> for a complete list of phases and a detailed description.</para>
     479            </note>
     480
     481            <para><option>install</option> takes the following switches:</para>
     482
     483            <variablelist>
     484                <varlistentry>
     485                    <term><option>--no-rev-upgrade</option></term>
     486                    <listitem>
     487                        <para>By default, a binary sanity check called <option>rev-upgrade</option> is run automatically
     488                            after each successful installation. Pass this flag, if you want to avoid running this step,
     489                            for example if you want to run it explicitly later after a number of installations using
     490                            <command>sudo port rev-upgrade</command>, or if you know it will detect problems but want to
     491                            defer dealing with them.</para>
     492                    </listitem>
     493                </varlistentry>
     494
     495                <varlistentry>
     496                    <term><option>--unrequested</option></term>
     497                    <listitem>
     498                        <para>By default, each port you install using the <option>install</option> (vs. as a dependency
     499                            of a different port) is marked as <quote>requested</quote>. If you want MacPorts to treat
     500                            a port you installed manually as if it was automatically installed as a dependency (e.g., if
     501                            a dependency failed to build and you re-tried installing the dependency only), pass this
     502                            flag.</para>
     503                    </listitem>
     504                </varlistentry>
     505            </variablelist>
     506        </section>
     507
     508        <section id="using.port.clean">
     509            <title>port clean</title>
     510
     511            <para>The action <option>clean</option> deletes intermediate files created by MacPorts while installing
     512                a port. A <command>port clean</command> is often necessary when builds fail and should be the first
     513                thing to try after a failed installation attempt.</para>
     514
     515            <programlisting><prompt>$ </prompt><userinput>sudo port clean <varname>&lt;portname&gt;</varname></userinput></programlisting>
     516
     517            <para><command>port clean</command> can also be used to remove corrupted downloads after a failed
     518                <option>fetch</option> phase, by specifying the <option>--dist</option> flag:</para>
     519
     520            <programlisting><prompt>$ </prompt><userinput>sudo port clean --dist <varname>&lt;portname&gt;</varname></userinput></programlisting>
     521
     522            <para>deletes all files that have been downloaded for the given port.</para>
     523
     524            <para><option>clean</option> accepts the following options:</para>
     525
     526            <variablelist>
     527                <varlistentry>
     528                    <term><option>--archive</option></term>
     529                    <listitem>
     530                        <para>Remove temporary archives.</para>
     531                    </listitem>
     532                </varlistentry>
     533
     534                <varlistentry>
     535                    <term><option>--dist</option></term>
     536                    <listitem>
     537                        <para>Remove downloaded files.</para>
     538                    </listitem>
     539                </varlistentry>
     540
     541                <varlistentry>
     542                    <term><option>--logs</option></term>
     543                    <listitem>
     544                        <para>Remove log files.</para>
     545                    </listitem>
     546                </varlistentry>
     547
     548                <varlistentry>
     549                    <term><option>--work</option></term>
     550                    <listitem>
     551                        <para>Remove the <filename>work</filename> directory, i.e., the directory used by MacPorts to
     552                            build a software. This removes all traces of an attempted build and is the default
     553                            operation.</para>
     554                    </listitem>
     555                </varlistentry>
     556
     557                <varlistentry>
     558                    <term><option>--all</option></term>
     559                    <listitem>
     560                        <para>All of the above combined.</para>
     561                    </listitem>
     562                </varlistentry>
     563            </variablelist>
     564        </section>
     565
     566        <section id="using.port.uninstall">
     567            <title>port uninstall</title>
     568
     569            <para>The <option>uninstall</option> action will remove an installed port. It is one of the actions you will
     570                use fairly often in MacPorts.</para>
     571
     572            <programlisting><prompt>$ </prompt><userinput>sudo port uninstall <varname>&lt;portname&gt;</varname></userinput></programlisting>
     573
     574            <para>MacPorts will refuse to uninstall ports that are still needed by other ports. For example:</para>
     575
     576            <programlisting><prompt>$ </prompt><userinput>sudo port uninstall libcomerr</userinput></programlisting>
     577
     578            <screen>
     579---&gt;  Unable to uninstall libcomerr @1.42.9_0, the following ports depend on it:
     580---&gt;    kerberos5 @1.11.3_0
     581---&gt;    subversion @1.8.9_0
     582---&gt;    subversion-perlbindings-5.16 @1.8.9_0
     583Error: port uninstall failed: Please uninstall the ports that depend on libcomerr first.</screen>
     584
     585            <para>You can recursively uninstall all ports that depend on the given port before uninstalling the port
     586                itself to work around this. To do that, use the <option>--follow-dependents</option> flag.</para>
     587
     588            <programlisting><prompt>$ </prompt><userinput>sudo port uninstall --follow-dependents libcomerr</userinput></programlisting>
     589
     590            <para>You can also override this safety check using the <option>-f</option> (force) flag. <emphasis>Since
     591                    this will obviously break the dependents you shouldn't do this unless you know what you are
     592                    doing.</emphasis></para>
     593
     594            <programlisting><prompt>$ </prompt><userinput>sudo port -f uninstall libcomerr</userinput></programlisting>
     595
     596            <para>Uninstalling a port will not uninstall ports that have been automatically installed as dependencies of
     597                the uninstalled port and are otherwise unused. You can trigger this behavior by passing the
     598                <option>--follow-dependencies</option> flag. Ports that were manually installed (i.e., are marked as
     599                <quote>requested</quote>) or have other dependents will not be removed. You can manually uninstall the
     600                unneeded ports later using the <option>leaves</option> pseudo-port, e.g., using <command>sudo port
     601                    uninstall leaves</command>.</para>
     602
     603            <para><option>uninstall</option> supports the following switches:</para>
     604
     605            <variablelist>
     606                <varlistentry>
     607                    <term><option>--follow-dependents</option></term>
     608                    <listitem>
     609                        <para>Recursively uninstall ports that depend on the specified port before uninstalling the port
     610                            itself. See also the textual description above.</para>
     611                    </listitem>
     612                </varlistentry>
     613
     614                <varlistentry>
     615                    <term><option>--follow-dependencies</option></term>
     616                    <listitem>
     617                        <para>Also uninstall ports that were automatically installed as dependencies of the removed port
     618                            and are no longer needed.</para>
     619                    </listitem>
     620                </varlistentry>
     621
     622                <varlistentry>
     623                    <term><option>--no-exec</option></term>
     624                    <listitem>
     625                        <para>Avoid running any uninstall hooks, such as commands that update cache files.</para>
     626                    </listitem>
     627                </varlistentry>
     628            </variablelist>
     629        </section>
     630
     631        <section id="using.port.contents">
     632            <title>port contents</title>
     633
     634            <para>The <option>contents</option> action displays a list of all files that have been installed by a given
     635                port. You can only use <option>contents</option> for ports you installed.</para>
     636
     637            <programlisting><prompt>$ </prompt><userinput>port contents xorg-renderproto</userinput></programlisting>
     638
     639            <screen>
     640Port xorg-renderproto contains:
    265641  /opt/local/include/X11/extensions/render.h
    266642  /opt/local/include/X11/extensions/renderproto.h
    267643  /opt/local/lib/pkgconfig/renderproto.pc
    268644  /opt/local/share/doc/renderproto/renderproto.txt</screen>
     645
     646            <para>Common uses for <option>contents</option> are finding the location of a port's executable after
     647                installing it. The following line is usually helpful in this case:</para>
     648
     649            <programlisting><prompt>$ </prompt><userinput>port -q contents <varname>&lt;portname&gt;</varname> | grep -E '/s?bin/'</userinput></programlisting>
     650
     651            <para>The <option>-q</option> (quiet) flag supresses the header line in this case, but is not strictly necessary.</para>
     652
     653            <para><option>contents</option> accepts:</para>
     654
     655            <variablelist>
     656                <varlistentry>
     657                    <term><option>--size</option></term>
     658                    <listitem>
     659                        <para>Prints a human-readable representation of the files' sizes.</para>
     660                    </listitem>
     661                </varlistentry>
     662
     663                <varlistentry>
     664                    <term><option>--units=UNIT</option></term>
     665                    <listitem>
     666                        <para>Used in conjunction with <option>--size</option> to choose the unit of the file size.
     667                            Valid parameters for <option>UNIT</option> are</para>
     668
     669                        <variablelist>
     670                            <varlistentry>
     671                                <term><option>B</option></term>
     672                                <listitem>
     673                                    <para>List sizes in bytes.</para>
     674                                </listitem>
     675                            </varlistentry>
     676                            <varlistentry>
     677                                <term><option>K</option>, <option>Ki</option>, or <option>KiB</option></term>
     678                                <listitem>
     679                                    <para>List sizes in <option>KiB</option>, i.e., 1024 bytes.</para>
     680                                </listitem>
     681                            </varlistentry>
     682                            <varlistentry>
     683                                <term><option>Mi</option>, or <option>MiB</option></term>
     684                                <listitem>
     685                                    <para>List sizes in <option>MiB</option>, i.e., 1024 * 1024 bytes.</para>
     686                                </listitem>
     687                            </varlistentry>
     688                            <varlistentry>
     689                                <term><option>Gi</option>, or <option>GiB</option></term>
     690                                <listitem>
     691                                    <para>List sizes in <option>GiB</option>, i.e., 1024 * 1024 * 1024 bytes.</para>
     692                                </listitem>
     693                            </varlistentry>
     694
     695                            <varlistentry>
     696                                <term><option>k</option>, or <option>kB</option></term>
     697                                <listitem>
     698                                    <para>List sizes in <option>kB</option>, i.e., 1000 bytes.</para>
     699                                </listitem>
     700                            </varlistentry>
     701                            <varlistentry>
     702                                <term><option>M</option>, or <option>MB</option></term>
     703                                <listitem>
     704                                    <para>List sizes in <option>MB</option>, i.e., 1000 * 1000 bytes.</para>
     705                                </listitem>
     706                            </varlistentry>
     707                            <varlistentry>
     708                                <term><option>G</option>, or <option>GB</option></term>
     709                                <listitem>
     710                                    <para>List sizes in <option>GB</option>, i.e., 1000 * 1000 * 1000 bytes.</para>
     711                                </listitem>
     712                            </varlistentry>
     713                        </variablelist>
     714                    </listitem>
     715                </varlistentry>
     716            </variablelist>
     717        </section>
     718
     719        <section id="using.port.installed">
     720            <title>port installed</title>
     721
     722            <para>The <option>installed</option> action displays the installed versions and variants of the specified
     723                ports, or if no ports are specified, all installed ports. It also displays whether a port is
     724                <quote>active</quote>, i.e., whether the files belonging to this port are currently present on disk or
     725                inactive, i.e., stashed away in a compressed tarball.</para>
     726
     727            <programlisting><prompt>$ </prompt><userinput>port installed</userinput></programlisting>
     728
     729            <screen>
     730The following ports are currently installed:
     731  a52dec @0.7.4_0 (active)
     732  adns @1.4_0 (active)
     733  apache2 @2.2.27_0+preforkmpm (active)
     734  apr @1.5.1_0 (active)
     735  apr-util @1.5.3_0 (active)
     736  aquaterm @1.1.1_0 (active)
     737  asciidoc @8.6.9_1+python27 (active)
     738  …
     739  XviD @1.3.3_0 (active)
     740  xz @5.0.5_0 (active)
     741  yasm @1.2.0_0 (active)
     742  ykpers @1.12.0_0 (active)
     743  youtube-dl @2014.07.25.1_0+python27 (active)
     744  yubico-c-client @2.12_0 (active)
     745  yubico-pam @2.16_0 (active)
     746  zlib @1.2.8_0 (active)</screen>
     747
     748            <para>Use the <option>-v</option> option to also display the platform and CPU architecture(s) for which the
     749                ports were built, and any variants which were explicitly negated.</para>
     750
     751            <programlisting><prompt>$ </prompt><userinput>port -v installed libsdl</userinput></programlisting>
     752            <screen>
     753The following ports are currently installed:
     754  libsdl @1.2.15_3-x11 (active) platform='darwin 13' archs='x86_64'</screen>
     755        </section>
     756
     757        <section id="using.port.outdated">
     758            <title>port outdated</title>
     759
     760            <para>The <option>outdated</option> action checks your installed ports against the current ports tree to see
     761                they have been updated since you installed them. Note that you will only get new versions by updating
     762                your ports tree using <option><link linkend="using.port.selfupdate">selfupdate</link></option> (or
     763                <option>sync</option>).</para>
     764
     765            <programlisting><prompt>$ </prompt><userinput>port outdated</userinput></programlisting>
     766
     767            <screen>
     768The following installed ports are outdated:
     769gnupg                          1.4.16_0 &lt; 1.4.18_0
     770gnupg2                         2.0.22_2 &lt; 2.0.25_0
     771gpg-agent                      2.0.22_1 &lt; 2.0.25_0
     772gpgme                          1.5.0_0 &lt; 1.5.1_0
     773HexFiend                       2.1.2_1 &lt; 2.3.0_0
     774libksba                        1.0.8_0 &lt; 1.3.0_0
     775p5.16-class-methodmaker        2.180.0_1 &lt; 2.210.0_0
     776p5.16-gnupg-interface          0.330.0_3 &lt; 0.500.0_1
     777p5.16-ipc-run                  0.910.0_1 &lt; 0.920.0_0</screen>
     778
     779            <para><command>port outdated</command> lists the ports for which an upgrade is available and on the second
     780                column, why MacPorts thinks the port needs an upgrade. In most cases, this will be an increase in the
     781                version number. If it isn't, more details will be given.</para>
     782        </section>
     783
     784        <section id="using.port.upgrade">
     785            <title>port upgrade</title>
     786
     787            <para>The <option>upgrade</option> action upgrades installed ports and their dependencies to the latest
     788                version available in MacPorts. In most cases, you will run</para>
     789
     790            <programlisting><prompt>$ </prompt><userinput>sudo port upgrade outdated</userinput></programlisting>
     791
     792            <para>to update all ports that have an upgrade available. You can, however, selectively upgrade ports if you
     793                want to delay other upgrades until later. To do that, specify the name(s) of the port(s) to upgrade:</para>
     794
     795            <programlisting><prompt>$ </prompt><userinput>sudo port upgrade gnupg2</userinput></programlisting>
     796
     797            <para>Note that MacPorts may decide to upgrade other dependent ports before upgrading the port you requested
     798                to be updated. Do not attempt to prevent this, since it will very likely lead to problems later.</para>
     799
     800            <note>
     801                <para><option>upgrade</option> does not uninstall the old version of a port. Instead, it deactivates it,
     802                    i.e., it stashes the files belonging to the older version away in a tarball. This allows you to go
     803                    back to the older version if there happens to be a problem with the updated one. To do that,
     804                    run</para>
     805
     806                <programlisting><prompt>$ </prompt><userinput>port installed <varname>&lt;portname&gt;</varname></userinput></programlisting>
     807
     808                <para>to determine the version number of the old version you want to re-activate, and run</para>
     809
     810                <programlisting><prompt>$ </prompt><userinput>sudo port activate <varname>&lt;portname&gt;</varname> @<varname>&lt;old-version&gt;</varname></userinput></programlisting>
     811
     812                <para>to go back to the old version.</para>
     813
     814                <para>If you do not want to keep the old versions around while upgrading, you can pass the
     815                    <option>-u</option> option when upgrading:</para>
     816
     817                <programlisting><prompt>$ </prompt><userinput>sudo port -u upgrade outdated</userinput></programlisting>
     818
     819                <para>However, we instead recommend keeping the older versions around for a while and running</para>
     820
     821                <programlisting><prompt>$ </prompt><userinput>sudo port uninstall inactive</userinput></programlisting>
     822
     823                <para>once in a while.</para>
     824            </note>
     825
     826            <para><option>upgrade</option> accepts a number of switches:</para>
     827
     828            <variablelist>
     829                <varlistentry>
     830                    <term><option>--force</option></term>
     831                    <listitem>
     832                        <para>Always consider the given ports outdated, regardless of whether they actually are.</para>
     833                    </listitem>
     834                </varlistentry>
     835
     836                <varlistentry>
     837                    <term><option>--enforce-variants</option></term>
     838                    <listitem>
     839                        <para>If the installed variants do not match those requested, upgrade (and change variants) even
     840                            if the port is not outdated. You can use this to switch the variant selection on an
     841                            installed port, e.g. using</para>
     842
     843                        <programlisting><prompt>$ </prompt><userinput>sudo port upgrade --enforce-variants apache2 -preforkmpm +workermpm</userinput></programlisting>
     844
     845                        <para>Note that <option>--enforce-variants</option> will also enforce your variant selection in
     846                            all dependencies. If you know this is not necessary, you can avoid processing dependencies
     847                            using the global <option>-n</option> flag:</para>
     848
     849                        <programlisting><prompt>$ </prompt><userinput>sudo port -n upgrade --enforce-variants apache2 -preforkmpm +workermpm</userinput></programlisting>
     850                    </listitem>
     851                </varlistentry>
     852
     853                <varlistentry>
     854                    <term><option>--no-replace</option></term>
     855                    <listitem>
     856                        <para>Do not automatically install replacement ports for a port that you have installed, but was
     857                            replaced with a different one.</para>
     858                    </listitem>
     859                </varlistentry>
     860            </variablelist>
     861        </section>
     862
     863        <section id="using.port.dependents">
     864            <title>port dependents</title>
     865
     866            <para>The <option>dependents</option> action reports what ports depend upon a given (installed) port, if
     867                any.</para>
     868
     869            <programlisting><prompt>$ </prompt><userinput>port dependents openssl</userinput></programlisting>
     870
     871            <screen>apache2 depends on openssl
     872curl depends on openssl
     873cyrus-sasl2 depends on openssl
     874git depends on openssl
     875kerberos5 depends on openssl
     876lftp depends on openssl
     877libssh depends on openssl
     878mosh depends on openssl
     879openldap depends on openssl
     880p5.16-net-ssleay depends on openssl
     881python27 depends on openssl
     882python32 depends on openssl
     883qt4-mac depends on openssl
     884ruby19 depends on openssl
     885serf1 depends on openssl
     886textmate2 depends on openssl
     887wireshark depends on openssl</screen>
     888
     889            <para>Note that <option>dependents</option> does not work for ports that are not installed on your system.
     890                If you want to find out, which ports depend on a port that you have not installed, you can use</para>
     891
     892            <programlisting><prompt>$ </prompt><userinput>port echo depends:<varname>&lt;portname&gt;</varname></userinput></programlisting>
     893
     894            <para>This command will, however, not cover dependencies that are only present in non-default variants.</para>
     895        </section>
     896
     897        <section id="using.port.livecheck">
     898            <title>port livecheck</title>
     899
     900            <para>The <option>livecheck</option> action checks to see if the application corresponding to a given port
     901                has been updated at the developer's download site. This action is mostly useful for port maintainers to
     902                determine whether their port needs to be updated, but other may also wish to see if a port packages the
     903                latest available version. See <xref linkend="reference.livecheck" /> for more information on
     904                livecheck.</para>
     905
     906            <programlisting><prompt>$ </prompt><userinput>port livecheck rb19-sass</userinput></programlisting>
     907
     908            <screen>rb19-sass seems to have been updated (port version: 3.3.10, new version: 3.3.14)</screen>
     909
     910            <note>
     911                <para>If <option>livecheck</option> finds no higher version at the port's download site, it prints
     912                    nothing. The option <option>-d</option> (debug) may be used for detailed livecheck processing
     913                    information.</para>
     914            </note>
     915        </section>
     916
     917        <section id="using.port.lint">
     918            <title>port lint</title>
     919
     920            <para>The lint action checks if the <filename>Portfile</filename> conforms to the MacPorts standards
     921                    specified in <link linkend="development">Portfile Development</link>. You should use this if you
     922                    modified a <filename>Portfile</filename> before submitting patches back to MacPorts.</para>
     923
     924            <para>If a <filename>Portfile</filename> validates fine the following message is shown.</para>
     925
     926            <programlisting><prompt>$ </prompt><userinput>port lint rb19-sass</userinput></programlisting>
     927
     928            <screen>
     929---&gt;  Verifying Portfile for rb19-sass
     930---&gt;  0 errors and 0 warnings found.</screen>
     931
     932            <para>Otherwise the warnings and errors are listed.</para>
     933
     934            <programlisting><prompt>$ </prompt><userinput>port lint abiword</userinput></programlisting>
     935
     936            <screen>
     937---&gt;  Verifying Portfile for abiword
     938Warning: Variant use_binary does not have a description
     939Warning: Variant use_source does not have a description
     940Warning: no license set
     941---&gt;  0 errors and 3 warnings found.</screen>
     942
     943            <para><option>lint</option> has the following flag:</para>
     944
     945            <variablelist>
     946                <varlistentry>
     947                    <term><option>--nitpick</option></term>
     948                    <listitem>
     949                        <para>Enables additional checks that are mostly whitespace-related and best practices.</para>
     950                    </listitem>
     951                </varlistentry>
     952            </variablelist>
     953        </section>
    269954    </section>
    270955
    271     <section id="using.port.installed">
    272       <title>installed</title>
    273 
    274       <para>The <option>installed</option> action displays the installed versions,
    275       variants and activation status of the
    276       specified ports, or if no ports are specified, all installed
    277       ports. Use the <option>-v</option> option to also display the platform and
    278       CPU architecture(s) for which the ports were built, and any variants which were
    279       explicitly negated.</para>
    280 
    281       <programlisting><prompt>%%</prompt> <userinput>port installed</userinput></programlisting>
    282 
    283       <screen>The following ports are currently installed:
    284   aalib @1.4rc5_2 (active)
    285   apr @1.2.8_0 (active)
    286   apr-util @1.2.8_2 (active)
    287   atk @1.18.0_0 (active)
    288 
    289 [ ... trimmed ...]
    290 
    291   wxWidgets @2.8.4_2 (active)
    292   Xft2 @2.1.7_0 (active)
    293   xrender @0.9.0_0 (active)
    294   zlib @1.2.3_1 (active)</screen>
    295 
    296     <programlisting><prompt>%%</prompt> <userinput>port -v installed atlas</userinput></programlisting>
    297     <screen>The following ports are currently installed:
    298   atlas @3.8.3_4+gcc44-gcc43 (active) platform='darwin 10' archs='x86_64'</screen>
     956    <section id="using.variants">
     957        <title>Port Variants</title>
     958
     959        <para>Variants are a way for port authors to provide options for a port that may be chosen at installation.
     960            Typically, variants are optional features that can be enabled, but are not necessarily useful for all users
     961            and are thus not enabled by default. To display the available variants for a port, if any, use this
     962            command:</para>
     963
     964        <programlisting><prompt>$ </prompt><userinput>port variants <varname>&lt;portname&gt;</varname></userinput></programlisting>
     965
     966        <para>For example:</para>
     967
     968        <programlisting><prompt>$ </prompt><userinput>port variants apache2</userinput></programlisting>
     969
     970        <screen>
     971apache2 has the variants:
     972   eventmpm: Use event MPM (experimental)
     973     * conflicts with preforkmpm workermpm
     974   openldap: Enable LDAP support through OpenLDAP
     975[+]preforkmpm: Use prefork MPM
     976     * conflicts with eventmpm workermpm
     977   universal: Build for multiple architectures
     978   workermpm: Use worker MPM
     979     * conflicts with eventmpm preforkmpm</screen>
     980
     981        <para>This output lists all variants followed by their description. If a variant depends on or conflicts with
     982            other variants, a line with the details on that follows. Variant lines that start with <option>[+]</option>
     983            are enabled by default by the <filename>Portfile</filename>. Variants that are marked with
     984            <option>(+)</option> are selected because of your configuration in
     985            <filename>$prefix/etc/macports/variants.conf</filename>. See <xref
     986                linkend="internals.configuration-files.variants-conf" /> for more information on the
     987            <filename>variants.conf</filename> file.</para>
     988
     989        <section id="using.variants.invoking">
     990            <title>Invoking Variants</title>
     991
     992            <para>A variant can only be invoked when a port is installed. After you have determined what variants
     993                a given port has, if any, you may install a port using the variant by specifying its name preceeded by
     994                a plus or minus sign on the command line, for example</para>
     995
     996            <programlisting><prompt>$ </prompt><userinput>sudo port install apache2 +openldap</userinput></programlisting>
     997            <programlisting><prompt>$ </prompt><userinput>sudo port install apache2 -preforkmpm +workermpm</userinput></programlisting>
     998
     999            <para>Note that you will not see any confirmation of successful variant selection and MacPorts will not warn
     1000                you if you misspelled a variant's name. If your installation is successful, but the chosen feature still
     1001                seems to be missing, check for possible typos. You can use <command><link
     1002                        linkend="using.port.installed">port installed</link></command> to verify that the port has been
     1003                installed with the chosen variant.</para>
     1004
     1005            <para>This happens because MacPorts will also use the specified variants for any dependencies. For example,</para>
     1006
     1007            <programlisting><prompt>$ </prompt><userinput>sudo port install apache2 +mariadb</userinput></programlisting>
     1008
     1009            <para>even though <option>apache2</option> does not have a <option>+mariadb</option> variant. Instead, this
     1010                will cause the <option>apr-util</option> port to be installed with the <option>+mariadb</option>
     1011                variant.</para>
     1012
     1013            <para>MacPorts will remember the variants that were used when installing a port. If you upgrade a port
     1014                later, the same variants will be used, unless you use manually specify different variants and use the
     1015                <option>--enforce-variants</option> flag of <option>upgrade</option>.</para>
     1016        </section>
     1017
     1018        <section id="using.variants.negating">
     1019            <title>Negating Default Variants</title>
     1020
     1021            <para>A <filename>Portfile</filename> can specify a default set of variants that will be used when you do
     1022                not manually override it. Not all ports specify default variants – if there are no default variants, no
     1023                variants are chosen by default.</para>
     1024
     1025            <para>If you wish to disable a variant that has been enabled by default, either by the
     1026                <filename>Portfile</filename>, or by your configuration in <filename>variants.conf</filename>, you can
     1027                negate the variant in question by prefixing the variant name with a minus on the command line:</para>
     1028
     1029            <programlisting><prompt>$ </prompt><userinput>sudo port install apache2 -preformmpm +workermpm</userinput></programlisting>
     1030        </section>
    2991031    </section>
    3001032
    301     <section id="using.port.outdated">
    302       <title>outdated</title>
    303 
    304       <para>The <option>outdated</option> action checks your installed ports
    305       against the current ports tree to see if updated Portfiles have been
    306       released since your ports were installed. Note that you will not see new
    307       versions unless you have updated your ports tree using <option>selfupdate</option>
    308       or <option>sync</option>.</para>
    309 
    310       <programlisting><prompt>%%</prompt> <userinput>port outdated</userinput></programlisting>
    311 
    312       <screen>apr                            1.2.8_0 &lt; 1.2.9_0
    313 autoconf                       2.61_0 &lt; 2.61_1
    314 gimp                           2.2.14_0 &lt; 2.2.16_0
    315 libtool                        1.5.22_0 &lt; 1.5.24_0
    316 pkgconfig                      0.21_0 &lt; 0.22_0</screen>
     1033    <section id="using.common-tasks">
     1034        <title>Common Tasks</title>
     1035
     1036        <para>This section lists common operations you may want to perform when managing a MacPorts installation. These
     1037            are the workflows you will need most while using MacPorts. We recommend you read at least this section as
     1038            a primer into how to use MacPorts. More details about the usage can be found in <xref linkend="using.port"/>
     1039            and the <option>port(1)</option> manpage available by running <command>man 1 port</command> in
     1040            a Terminal.</para>
     1041
     1042        <para>Mind the <quote>sudo</quote> for some of the subsequent examples, which is necessary if you have a default
     1043            MacPorts installation.</para>
     1044
     1045        <section id="using.common-tasks.updating">
     1046            <title>Updating Your Ports Tree</title>
     1047
     1048            <para>The local ports tree is a collection of files that contain information on which packages are available
     1049                through MacPorts and how they can be installed. You should regularly update your ports tree to get
     1050                access to updated versions of software and bug fixes. To do that, use <option>selfupdate</option>:</para>
     1051
     1052            <programlisting><prompt>$ </prompt><userinput>sudo port selfupdate</userinput></programlisting>
     1053
     1054            <screen>Password:
     1055<!--        -->---&gt; Updating MacPorts base sources using rsync
     1056<!--        -->MacPorts base version &macports-version; installed,
     1057<!--        -->MacPorts base version &macports-version; downloaded.
     1058<!--        -->---&gt; Updating the ports tree
     1059<!--        -->---&gt; MacPorts base is already the latest version
     1060<!--        -->
     1061<!--        -->The ports tree has been updated. To upgrade your installed ports, you should run
     1062<!--        -->  port upgrade outdated</screen>
     1063        </section>
     1064
     1065        <section id="using.common-tasks.showports">
     1066            <title>Show Ports Which Need Updating</title>
     1067
     1068            <para>To see what's new after running <option>selfupdate</option>, you can use <command>port
     1069                    outdated</command> to generate a list of ports that have newer versions available. This can help in
     1070                estimating the time required for <command>sudo port upgrade outdated</command>, even though this depends
     1071                on further factors such as binary package availability and a port's build time.</para>
     1072
     1073            <programlisting><prompt>$ </prompt><userinput>port outdated</userinput></programlisting>
     1074
     1075            <screen>
     1076<!--        -->The following installed ports are outdated:
     1077<!--        -->gnupg                          1.4.16_0 &lt; 1.4.18_0
     1078<!--        -->gnupg2                         2.0.22_2 &lt; 2.0.25_0
     1079<!--        -->gpg-agent                      2.0.22_1 &lt; 2.0.25_0
     1080<!--        -->gpgme                          1.5.0_0 &lt; 1.5.1_0
     1081<!--        -->HexFiend                       2.1.2_1 &lt; 2.3.0_0
     1082<!--        -->libksba                        1.0.8_0 &lt; 1.3.0_0
     1083<!--        -->p5.16-class-methodmaker        2.180.0_1 &lt; 2.210.0_0
     1084<!--        -->p5.16-gnupg-interface          0.330.0_3 &lt; 0.500.0_1
     1085<!--        -->p5.16-ipc-run                  0.910.0_1 &lt; 0.920.0_0</screen>
     1086        </section>
     1087
     1088        <section id="using.common-tasks.upgrading">
     1089            <title>Upgrading Outdated Ports</title>
     1090
     1091            <para>To upgrade all your installed and outdated ports, run</para>
     1092
     1093            <programlisting><prompt>$ </prompt><userinput>sudo port upgrade outdated</userinput></programlisting>
     1094
     1095            <para>In case you want to upgrade only a specific port, replace <quote>outdated</quote> in the command given
     1096                above with the port's name:</para>
     1097
     1098            <programlisting><prompt>$ </prompt><userinput>sudo port upgrade makedepend</userinput></programlisting>
     1099
     1100            <screen>Password:
     1101<!--        -->---&gt; Computing dependencies for makedepend
     1102<!--        -->---&gt; Fetching makedepend
     1103<!--        -->---&gt; Attempting to fetch makedepend-1.0.3.tar.bz2 from http://lil.fr.distfiles.macports.org/makedepend
     1104<!--        -->---&gt; Verifying checksum(s) for makedepend
     1105<!--        -->---&gt; Extracting makedepend
     1106<!--        -->---&gt; Configuring makedepend
     1107<!--        -->---&gt; Building makedepend
     1108<!--        -->---&gt; Staging makedepend into destroot
     1109<!--        -->---&gt; Computing dependencies for makedepend
     1110<!--        -->---&gt; Installing makedepend @1.0.3_0
     1111<!--        -->---&gt; Deactivating makedepend @1.0.2_0
     1112<!--        -->---&gt; Activating makedepend @1.0.3_0
     1113<!--        -->---&gt; Cleaning makedepend</screen>
     1114
     1115            <para>Note that MacPorts will upgrade any dependencies of a port first before updating the port itself. So
     1116                even if you request the update of a single port only, other ports may be upgraded first because they are
     1117                in the dependency tree. Do <emphasis>not</emphasis> try to avoid this, as it will very likely lead to
     1118                problems later on – the new version of the port you want to upgrade might require the newer dependency,
     1119                or it might only have been upgraded at all to be rebuilt against the updated dependency, in which case
     1120                avoiding the update of the dependency defeats the purpose of the reinstallation.</para>
     1121        </section>
     1122
     1123        <section id="using.common-tasks.removeinactive">
     1124            <title>Removing Inactive Version(s) of Upgraded Port(s)</title>
     1125
     1126            <para>By default, upgrading ports in MacPorts does not remove the older versions. This is a safety measure
     1127                to ensure you can go back to a working and tested version in case an update goes wrong. To save disk
     1128                space, you should periodically uninstall any old versions you no longer need.</para>
     1129
     1130            <para>Use</para>
     1131
     1132            <programlisting><prompt>$ </prompt><userinput>port installed inactive</userinput></programlisting>
     1133
     1134            <para>to get a list of inactive ports you likely no longer need.</para>
     1135
     1136            <screen>The following ports are currently installed:
     1137<!--        -->  gnupg @1.4.16_0
     1138<!--        -->  gnupg2 @2.0.22_2
     1139<!--        -->  gpg-agent @2.0.22_1
     1140<!--        -->  gpgme @1.5.0_0
     1141<!--        -->  HexFiend @2.1.2_1
     1142<!--        -->  libksba @1.0.8_0
     1143<!--        -->  p5.16-class-methodmaker @2.180.0_1
     1144<!--        -->  p5.16-gnupg-interface @0.330.0_3
     1145<!--        -->  p5.16-ipc-run @0.910.0_1</screen>
     1146
     1147            <para>Check the list for any ports you might still want to keep. To remove all of them at once, run</para>
     1148
     1149            <programlisting><prompt>$ </prompt><userinput>sudo port uninstall inactive</userinput></programlisting>
     1150
     1151            <screen>Password:
     1152<!--        -->---&gt;  Uninstalling p5.16-gnupg-interface @0.330.0_3
     1153<!--        -->---&gt;  Cleaning p5.16-gnupg-interface
     1154<!--        -->---&gt;  Uninstalling gnupg @1.4.16_0
     1155<!--        -->---&gt;  Cleaning gnupg
     1156<!--        -->---&gt;  Uninstalling gpgme @1.5.0_0
     1157<!--        -->---&gt;  Cleaning gpgme
     1158<!--        -->---&gt;  Uninstalling gnupg2 @2.0.22_2
     1159<!--        -->---&gt;  Cleaning gnupg2
     1160<!--        -->---&gt;  Uninstalling gpg-agent @2.0.22_1
     1161<!--        -->---&gt;  Cleaning gpg-agent
     1162<!--        -->---&gt;  Uninstalling HexFiend @2.1.2_1
     1163<!--        -->---&gt;  Cleaning HexFiend
     1164<!--        -->---&gt;  Uninstalling libksba @1.0.8_0
     1165<!--        -->---&gt;  Cleaning libksba
     1166<!--        -->---&gt;  Uninstalling p5.16-class-methodmaker @2.180.0_1
     1167<!--        -->---&gt;  Cleaning p5.16-class-methodmaker
     1168<!--        -->---&gt;  Uninstalling p5.16-ipc-run @0.910.0_1
     1169<!--        -->---&gt;  Cleaning p5.16-ipc-run</screen>
     1170
     1171            <para>Of course you could also select only a specific inactive port, but that requires to specify the exact
     1172                version:</para>
     1173
     1174            <programlisting><prompt>$ </prompt><userinput>sudo port uninstall HexFiend @2.1.2_1</userinput></programlisting>
     1175
     1176            <screen>Password:
     1177<!--        -->---&gt;  Uninstalling HexFiend @2.1.2_1
     1178<!--        -->---&gt;  Cleaning HexFiend</screen>
     1179
     1180            <para>To uninstall all inactive ports but a single one, you can use the following shortcut:</para>
     1181
     1182            <programlisting><prompt>$ </prompt><userinput>sudo port uninstall inactive and not <varname>&lt;portname&gt;</varname></userinput></programlisting>
     1183        </section>
     1184
     1185        <section id="using.common-tasks.finddepending">
     1186            <title>Finding Ports Depending on a Certain Port</title>
     1187
     1188            <para>If you want to find all ports that depend on a given other port, you can use</para>
     1189
     1190            <programlisting><prompt>$ </prompt><userinput>port echo depends:<varname>&lt;portname&gt;</varname></userinput></programlisting>
     1191
     1192            <para>If you are only interested in the dependent ports that you actually have installed, you can use the
     1193                quicker and more accurate <option>dependents</option>:</para>
     1194
     1195            <programlisting><prompt>$ </prompt><userinput>port dependents <varname>&lt;portname&gt;</varname></userinput></programlisting>
     1196
     1197            <programlisting><prompt>$ </prompt><userinput>port dependents libksba</userinput></programlisting>
     1198
     1199            <screen>gnupg2 depends on libksba
     1200<!--        -->gpg-agent depends on libksba</screen>
     1201
     1202            <para>MacPorts also has a recursive version of the <option>dependents</option> action called <option>rdependents</option>:</para>
     1203
     1204            <programlisting><prompt>$ </prompt><userinput>port rdependents libksba</userinput></programlisting>
     1205
     1206            <screen>The following ports are dependent on libksba:
     1207<!--        -->  gnupg2
     1208<!--        -->    gpgme
     1209<!--        -->  gpg-agent</screen>
     1210
     1211            <para>Finally, to find out which port you manually installed caused the automatic installation of
     1212                a dependency, use the following expression:</para>
     1213
     1214            <programlisting><prompt>$ </prompt><userinput>port installed requested and rdependentof:<varname>&lt;portname&gt;</varname></userinput></programlisting>
     1215
     1216            <programlisting><prompt>$ </prompt><userinput>port installed requested and rdependentof:libksba</userinput></programlisting>
     1217
     1218            <screen>The following ports are currently installed:
     1219<!--        -->  gnupg2 @2.0.25_0 (active)</screen>
     1220        </section>
     1221
     1222        <section id="using.common-tasks.findleaves">
     1223            <title>Finding Leaves</title>
     1224
     1225            <para>After a while of using MacPorts, installing and uninstalling ports, packages that have been
     1226                automatically installed as dependencies for other ports are left behind, even though they are no longer
     1227                necessary. Ports that have not been manually installed (<quote>requested</quote>) and do not have any
     1228                dependents are called <quote>leaves</quote> and can be identified using the <option>leaves</option>
     1229                pseudo-port, for example in conjunction with the <option>echo</option> or <option>installed</option>
     1230                action.</para>
     1231
     1232            <programlisting><prompt>$ </prompt><userinput>port echo leaves</userinput></programlisting>
     1233
     1234            <screen>
     1235<!--        -->git-flow                       @0.4.1_2
     1236<!--        -->gmake                          @4.0_0
     1237<!--        -->gpgme                          @1.5.1_0
     1238<!--        -->hs-download-curl               @0.1.4_0
     1239<!--        -->pkgconfig                      @0.28_0
     1240<!--        -->py27-docutils                  @0.12_0
     1241<!--        -->python32                       @3.2.5_0
     1242<!--        -->texi2html                      @5.0_1
     1243<!--        -->yasm                           @1.2.0_0</screen>
     1244
     1245            <para>These leaves may be wanted, but are in most cases unneeded. See <xref
     1246                    linkend="using.common-tasks.keeplean"/> to find out how to mark some of the leaves as requested. You
     1247                can uninstall all leaves using</para>
     1248
     1249            <programlisting><prompt>$ </prompt><userinput>sudo port uninstall leaves</userinput></programlisting>
     1250
     1251            <para>Note that the uninstallation can mark new ports as leaves. To uninstall all leaves, you have to repeat
     1252                the process until <command>port echo leaves</command> comes back empty. To simplify this, consider
     1253                installing the <option>port_cutleaves</option> port and running <command>sudo
     1254                    port_cutleaves</command>.</para>
     1255        </section>
     1256
     1257        <section id="using.common-tasks.keeplean">
     1258            <title>Keep Your Installation Lean by Defining Leaves as Requested Ports</title>
     1259
     1260            <para>Well, before we come to the procedure of defining your requested ports, let's have a look at a typical
     1261                scenario where you want to understand what is actually installed and what is on the other hand truly
     1262                necessary for your system. Say checking leaves of your MacPorts installation gives this output:</para>
     1263
     1264            <programlisting><prompt>$ </prompt><userinput>port echo leaves</userinput></programlisting>
     1265
     1266            <screen>
     1267<!--        -->git-flow                       @0.4.1_2
     1268<!--        -->gmake                          @4.0_0
     1269<!--        -->gpgme                          @1.5.1_0
     1270<!--        -->hs-download-curl               @0.1.4_0
     1271<!--        -->pkgconfig                      @0.28_0
     1272<!--        -->py27-docutils                  @0.12_0
     1273<!--        -->python32                       @3.2.5_0
     1274<!--        -->texi2html                      @5.0_1
     1275<!--        -->yasm                           @1.2.0_0</screen>
     1276
     1277            <para>Now it is up to the user to decide what's needed and what is not. We've noticed
     1278                <option>pkgconfig</option> is needed to build many ports, and while it is strictly not needed after
     1279                installation, we'd like to keep it around to avoid installing it over and over again.
     1280                <option>python32</option>, <option>texi2html</option>, and <option>yasm</option> are only needed to
     1281                update <option>mplayer2</option>, and since that software is rarely updated, we will re-install those
     1282                ports again when they are needed. Since they are all distributable, MacPorts will use pre-built binaries
     1283                for their installation anyway, so re-installing them wouldn't take long anyway. We don't really know why
     1284                the rest of the leaves were installed, so we're just going to remove them for now.</para>
     1285
     1286            <para>Since we decided to keep <option>pkgconfig</option>, we are going to mark it as manually installed
     1287                (<quote>requested</quote> in MacPorts lingo) using:</para>
     1288
     1289            <programlisting><prompt>$ </prompt><userinput>sudo port setrequested pkgconfig</userinput></programlisting>
     1290
     1291            <para>When you've step-by-step figured out which ports you want to keep on your system and have set them as
     1292                requested, you'll have a list of unnecessary ports, which you can get rid of using</para>
     1293
     1294            <programlisting><prompt>$ </prompt><userinput>sudo port uninstall leaves</userinput></programlisting>
     1295
     1296            <para>Note that uninstalling leaves may mark new ports as leaves, so you will have to repeat the process.
     1297                You can install the <option>port_cutleaves</option> port, which is a special script for the job. It
     1298                allows you to interactively decide whether to keep or uninstall a port. Run it as</para>
     1299
     1300            <programlisting><prompt>$ </prompt><userinput>sudo port_cutleaves</userinput></programlisting>
     1301
     1302            <screen>
     1303<!--        -->[Leaf 1 of 8] hs-download-curl @0.1.4_0 (active):
     1304<!--        -->  [keep] / (u)ninstall / (f)lush / (a)bort:
     1305<!--        -->** hs-download-curl @0.1.4_0 will be kept.
     1306<!--        -->
     1307<!--        -->[Leaf 2 of 8] gmake @4.0_0 (active):
     1308<!--        -->  [keep] / (u)ninstall / (f)lush / (a)bort: u
     1309<!--        -->** gmake @4.0_0 will be uninstalled.
     1310<!--        -->
     1311<!--        -->[Leaf 3 of 8] texi2html @5.0_1 (active):
     1312<!--        -->  [keep] / (u)ninstall / (f)lush / (a)bort: u
     1313<!--        -->** texi2html @5.0_1 will be uninstalled.
     1314<!--        -->
     1315<!--        -->[Leaf 4 of 8] yasm @1.2.0_0 (active):
     1316<!--        -->  [keep] / (u)ninstall / (f)lush / (a)bort: u
     1317<!--        -->** yasm @1.2.0_0 will be uninstalled.
     1318<!--        -->
     1319<!--        -->[Leaf 5 of 8] python32 @3.2.5_0 (active):
     1320<!--        -->  [keep] / (u)ninstall / (f)lush / (a)bort: u
     1321<!--        -->** python32 @3.2.5_0 will be uninstalled.
     1322<!--        -->
     1323<!--        -->[Leaf 6 of 8] py27-docutils @0.12_0 (active):
     1324<!--        -->  [keep] / (u)ninstall / (f)lush / (a)bort: u
     1325<!--        -->** py27-docutils @0.12_0 will be uninstalled.
     1326<!--        -->
     1327<!--        -->[Leaf 7 of 8] git-flow @0.4.1_2 (active):
     1328<!--        -->  [keep] / (u)ninstall / (f)lush / (a)bort: u
     1329<!--        -->** git-flow @0.4.1_2 will be uninstalled.
     1330<!--        -->
     1331<!--        -->[Leaf 8 of 8] gpgme @1.5.1_0 (active):
     1332<!--        -->  [keep] / (u)ninstall / (f)lush / (a)bort: u
     1333<!--        -->** gpgme @1.5.1_0 will be uninstalled.
     1334<!--        -->
     1335<!--        -->---&gt;  Deactivating gmake @4.0_0
     1336<!--        -->---&gt;  Cleaning gmake
     1337<!--        -->---&gt;  Uninstalling gmake @4.0_0
     1338<!--        -->---&gt;  Cleaning gmake
     1339<!--        -->---&gt;  Deactivating texi2html @5.0_1
     1340<!--        -->---&gt;  Cleaning texi2html
     1341<!--        -->---&gt;  Uninstalling texi2html @5.0_1
     1342<!--        -->---&gt;  Cleaning texi2html
     1343<!--        -->---&gt;  Deactivating yasm @1.2.0_0
     1344<!--        -->---&gt;  Cleaning yasm
     1345<!--        -->---&gt;  Uninstalling yasm @1.2.0_0
     1346<!--        -->---&gt;  Cleaning yasm
     1347<!--        -->---&gt;  Deactivating python32 @3.2.5_0
     1348<!--        -->---&gt;  Cleaning python32
     1349<!--        -->---&gt;  Uninstalling python32 @3.2.5_0
     1350<!--        -->---&gt;  Cleaning python32
     1351<!--        -->---&gt;  Deactivating py27-docutils @0.12_0
     1352<!--        -->---&gt;  Cleaning py27-docutils
     1353<!--        -->---&gt;  Uninstalling py27-docutils @0.12_0
     1354<!--        -->---&gt;  Cleaning py27-docutils
     1355<!--        -->---&gt;  Deactivating git-flow @0.4.1_2
     1356<!--        -->---&gt;  Cleaning git-flow
     1357<!--        -->---&gt;  Uninstalling git-flow @0.4.1_2
     1358<!--        -->---&gt;  Cleaning git-flow
     1359<!--        -->---&gt;  Deactivating gpgme @1.5.1_0
     1360<!--        -->---&gt;  Cleaning gpgme
     1361<!--        -->---&gt;  Uninstalling gpgme @1.5.1_0
     1362<!--        -->---&gt;  Cleaning gpgme
     1363<!--        -->
     1364<!--        -->The following ports were uninstalled:
     1365<!--        -->  gmake @4.0_0
     1366<!--        -->  texi2html @5.0_1
     1367<!--        -->  yasm @1.2.0_0
     1368<!--        -->  python32 @3.2.5_0
     1369<!--        -->  py27-docutils @0.12_0
     1370<!--        -->  git-flow @0.4.1_2
     1371<!--        -->  gpgme @1.5.1_0
     1372<!--        -->
     1373<!--        -->Search for new leaves?
     1374<!--        -->  [no] / (y)es: y
     1375<!--        -->
     1376<!--        -->[Leaf 1 of 1] py27-roman @2.0.0_0 (active):
     1377<!--        -->  [keep] / (u)ninstall / (f)lush / (a)bort: u
     1378<!--        -->** py27-roman @2.0.0_0 will be uninstalled.
     1379<!--        -->
     1380<!--        -->---&gt;  Deactivating py27-roman @2.0.0_0
     1381<!--        -->---&gt;  Cleaning py27-roman
     1382<!--        -->---&gt;  Uninstalling py27-roman @2.0.0_0
     1383<!--        -->---&gt;  Cleaning py27-roman
     1384<!--        -->
     1385<!--        -->The following ports were uninstalled:
     1386<!--        -->  py27-roman @2.0.0_0
     1387<!--        -->
     1388<!--        -->Search for new leaves?
     1389<!--        -->  [no] / (y)es: y
     1390<!--        -->
     1391<!--        -->There are no new leaves to process.</screen>
     1392
     1393            <para>You can get a list of all ports you previously set as requested (or installed manually) using:</para>
     1394
     1395            <programlisting><prompt>$ </prompt><userinput>port installed requested</userinput></programlisting>
     1396
     1397            <para>We recommend you check the list of leaves from time to time to keep your system free of too much
     1398                <quote>garbage</quote>. You should also periodically check the list of your requested ports and mark any
     1399                ports you no longer need as unrequested using</para>
     1400
     1401            <programlisting><prompt>$ </prompt><userinput>sudo port unsetrequested <varname>&lt;portname&gt;</varname></userinput></programlisting>
     1402
     1403            <para>Then check for new leaves to cut down the number of installed ports and the size of your MacPorts
     1404                installation.</para>
     1405        </section>
    3171406    </section>
    3181407
    319     <section id="using.port.upgrade">
    320       <title>upgrade</title>
    321 
    322       <para>The <option>upgrade</option> action upgrades installed ports and
    323       their dependencies when a <filename>Portfile</filename> in the
    324       repository has been updated after a port was installed.</para>
    325 
    326       <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade gnome</userinput></programlisting>
    327 
    328       <para>If you wish not to upgrade a port's dependencies, use the
    329       <option>-n</option> switch. Note that this will often cause problems.</para>
    330 
    331       <programlisting><prompt>%%</prompt> <userinput>sudo port -n upgrade gnome</userinput></programlisting>
    332 
    333       <para>If you'd like to upgrade all outdated ports, use this
    334       command.</para>
    335 
    336       <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade outdated</userinput></programlisting>
    337 
    338       <note>
    339         <para>The <option>upgrade</option> action by default does not
    340         uninstall an upgraded port —it deactivates it. See section <link
    341         linkend="internals.images">Port Images</link>, and also Destroot and
    342         Activate phases in <link linkend="reference.phases">Port
    343         Phases</link>. If you wish to uninstall the old version, use the
    344         <option>-u</option> option.</para>
    345 
    346         <programlisting><prompt>%%</prompt> <userinput>sudo port -u upgrade vile</userinput></programlisting>
    347       </note>
     1408    <section id="using.binaries">
     1409        <title>Port Binaries</title>
     1410
     1411        <para>MacPorts can pre-compile ports into binaries so applications need not be compiled when installing on
     1412            a target system. MacPorts supports two types of binaries: archives and packages.</para>
     1413
     1414        <section id="using.binaries.archives">
     1415            <title>Binary Archives</title>
     1416
     1417            <para>Binary archives can only be used on a target system running MacPorts. They allow MacPorts utilities to
     1418                skip the build (which is usually the phase that takes longest) and begin installation after the destroot
     1419                phase. Binary archives are automatically created whenever a port is installed, and can also be
     1420                downloaded from a server. MacPorts runs a buildbot infrastructure that creates prebuilt binary packages
     1421                for all ports in MacPorts for the default installation prefix. Buildbots exist for systems later or
     1422                equal to Snow Leopard. If a port builds successfully and its license and those of its dependencies allow
     1423                binary redistribution, they archives are uploaded to <option>packages.macports.org</option> and will be
     1424                automatically used by MacPorts during installation.</para>
     1425
     1426            <para>You can manually create an archive (and see debug output for its creation) using</para>
     1427
     1428            <programlisting><prompt>$ </prompt><userinput>sudo port -d archive logrotate</userinput></programlisting>
     1429            <screen>
     1430<!--        -->---&gt;  Installing logrotate @3.8.6_2+gzip
     1431<!--        -->[…]
     1432<!--        -->DEBUG: Creating logrotate-3.8.6_2+gzip.darwin_13.x86_64.tbz2
     1433<!--        -->[…]
     1434<!--        -->a .
     1435<!--        -->a ./+COMMENT
     1436<!--        -->a ./+CONTENTS
     1437<!--        -->a ./+DESC
     1438<!--        -->a ./+PORTFILE
     1439<!--        -->a ./+STATE
     1440<!--        -->a ./opt
     1441<!--        -->a ./opt/local
     1442<!--        -->a ./opt/local/etc
     1443<!--        -->a ./opt/local/sbin
     1444<!--        -->a ./opt/local/share
     1445<!--        -->a ./opt/local/var
     1446<!--        -->a ./opt/local/var/run
     1447<!--        -->a ./opt/local/var/run/logrotate
     1448<!--        -->a ./opt/local/var/run/logrotate/.turd_logrotate
     1449<!--        -->a ./opt/local/share/logrotate
     1450<!--        -->a ./opt/local/share/man
     1451<!--        -->a ./opt/local/share/man/man5
     1452<!--        -->a ./opt/local/share/man/man8
     1453<!--        -->a ./opt/local/share/man/man8/logrotate.8.gz
     1454<!--        -->a ./opt/local/share/man/man5/logrotate.conf.5.gz
     1455<!--        -->a ./opt/local/share/logrotate/CHANGES
     1456<!--        -->a ./opt/local/share/logrotate/COPYING
     1457<!--        -->a ./opt/local/share/logrotate/logrotate.conf.example
     1458<!--        -->a ./opt/local/share/logrotate/org.macports.logrotate.plist.example
     1459<!--        -->a ./opt/local/sbin/logrotate
     1460<!--        -->a ./opt/local/etc/logrotate.d
     1461<!--        -->a ./opt/local/etc/logrotate.d/.turd_logrotate
     1462<!--        -->DEBUG: Archive logrotate-3.8.6_2+gzip.darwin_13.x86_64.tbz2 packaged</screen>
     1463
     1464            <para>Binary archive files are placed in <filename>${prefix}/var/macports/software/</filename>. The archive
     1465                file type is set in the <filename>macports.conf</filename> file using the
     1466                <option>portarchivetype</option> key. The default format is <option>tbz2</option>; other options are:
     1467                <option>tar</option>, <option>tbz</option>, <option>tbz2</option>, <option>tgz</option>,
     1468                <option>tlz</option>, <option>txz</option>, <option>xar</option>, <option>zip</option>,
     1469                <option>cpgz</option>, and <option>cpio</option>. Note that changing this setting will prevent MacPorts
     1470                from downloading and using pre-built binaries, so you should probably leave it as-is.</para>
     1471        </section>
     1472
     1473        <section id="using.binaries.binary-packages">
     1474            <title>Binary Packages</title>
     1475
     1476            <para>Binary packages are standalone binary installers that are precompiled; they do not require MacPorts on
     1477                the target system. As such, they are helpful in generating disk images or installers to be redistributed
     1478                to users without relying on MacPorts for installation. Binary installers created with MacPorts are
     1479                usually <option>.pkg</option> (OS X Installer Packages). MacPorts can also convert
     1480                a <option>.pkg</option> package into an OS X <option>.dmg</option> disk image. You can create binary
     1481                packages with the <command>port</command> command as shown in the following examples.</para>
     1482
     1483            <warning>
     1484                <para>If you want to create installer packages using MacPorts for redistribution, make sure you do not
     1485                    use a standard installation of MacPorts in <filename>/opt/local</filename>. If you do that, your
     1486                    installer package conflicts with MacPorts on systems that <emphasis>do</emphasis> have MacPorts
     1487                    installed.</para>
     1488
     1489                <para>Instead, follow <xref linkend="installing.macports.source.multiple"/> and choose a prefix specific
     1490                    to the software you are trying to package, e.g., <filename>/opt/logrotate</filename> for
     1491                    <option>logrotate</option>. Then use this custom MacPorts installation to build your package.</para>
     1492            </warning>
     1493
     1494            <para>Create an OS X <option>.pkg</option> installer for the <option>pstree</option> port:</para>
     1495            <programlisting><prompt>$ </prompt><userinput>sudo port pkg pstree</userinput></programlisting>
     1496
     1497            <para>You may also create an OS X <option>.dmg</option> disk image file instead:</para>
     1498            <programlisting><prompt>$ </prompt><userinput>sudo port dmg pstree</userinput></programlisting>
     1499
     1500            <para>In most cases you probably want to package a port and all its library and runtime dependencies in
     1501                a single package. You can use a metapackage to do this. Create one using:</para>
     1502            <programlisting><prompt>$ </prompt><userinput>sudo port mpkg gimp2</userinput></programlisting>
     1503
     1504            <para>Just as with a single package, a metapackage can also be wrapped in a <option>.dmg</option>.</para>
     1505            <programlisting><prompt>$ </prompt><userinput>sudo port mdmg gimp2</userinput></programlisting>
     1506
     1507            <para>All packages are placed in a port's work directory, which you can locate using:</para>
     1508            <programlisting><prompt>$ </prompt><userinput>port work <varname>&lt;portname&gt;</varname></userinput></programlisting>
     1509        </section>
    3481510    </section>
    349 
    350     <section id="using.port.dependents">
    351       <title>dependents</title>
    352 
    353       <para>The <option>dependents</option> action reports what ports depend
    354       upon a given port, if any. MacPorts learns about dependents during port
    355       installation, so uninstalled ports will always report that there are no
    356       dependents.</para>
    357 
    358       <programlisting><prompt>%%</prompt> <userinput>port dependents openssl</userinput></programlisting>
    359 
    360       <screen>neon depends on openssl
    361 gnome-vfs depends on openssl
    362 libdap depends on openssl</screen>
    363     </section>
    364 
    365     <section id="using.port.livecheck">
    366       <title>livecheck</title>
    367 
    368       <para>The livecheck action checks to see if the application
    369       corresponding to a given port has been updated at the developer's
    370       download site. It's especially useful for port maintainers, but others
    371       may also wish to see if a port has the latest available distribution
    372       source. See section <link linkend="reference.livecheck">Livecheck</link>
    373       for more information.</para>
    374 
    375       <programlisting><prompt>%%</prompt> <userinput>port livecheck rrdtool</userinput></programlisting>
    376 
    377       <screen>rrdtool seems to have been updated (port version: 1.2.23, new version: 1.3beta1)</screen>
    378 
    379       <note>
    380         <para>If livecheck finds no higher version at the port's download
    381         site, it prints nothing. The option <option>-d</option> (debug) may be
    382         used for detailed livecheck processing information.</para>
    383       </note>
    384 
    385       <para></para>
    386     </section>
    387 
    388     <section id="using.port.lint">
    389       <title>lint</title>
    390 
    391       <para>The lint action checks if the Portfile conforms to the MacPorts
    392       standards specified in <link linkend="development">Portfile
    393       Development</link>.</para>
    394 
    395       <para>If a Portfile validates fine the following message is
    396       shown.</para>
    397 
    398       <programlisting><prompt>%%</prompt> <userinput>port lint chemtool</userinput></programlisting>
    399 
    400       <screen>--->  Verifying Portfile for chemtool
    401 --->  0 errors and 0 warnings found.</screen>
    402 
    403       <para>Otherwise the warnings and errors are listed.</para>
    404 
    405       <programlisting><prompt>%%</prompt> <userinput>port lint KeyArcher</userinput></programlisting>
    406 
    407       <screen>--->  Verifying Portfile for KeyArcher
    408 Warning: Line 2 should be a newline (after RCS tag)
    409 Warning: Line 5 has trailing whitespace before newline
    410 Error: Missing required variable: platforms
    411 --->  1 errors and 2 warnings found.
    412 </screen>
    413     </section>
    414   </section>
    415 
    416   <section id="using.variants">
    417     <title>Port Variants</title>
    418 
    419     <para>Variants are a way for port authors to provide options for a port
    420     that may be chosen during the port install. To display the available
    421     variants, if any, use this command:</para>
    422 
    423     <programlisting><prompt>%%</prompt> <userinput>port variants fetchmail</userinput></programlisting>
    424 
    425     <screen>fetchmail has the variants:
    426         universal
    427         ssl: Support secure connections using OpenSSL
    428         fetchmailconf: Install a graphical configurator
    429         ntlm: Enable NTLM authentication</screen>
    430 
    431     <note>
    432       <para>In some ports, you may find variants for which descriptions have
    433       not yet been written.</para>
    434     </note>
    435 
    436     <section id="using.variants.invoking">
    437       <title>Invoking Variants</title>
    438 
    439       <para>A variant can only be invoked when a port is installed. After you
    440       have determined what variants a given port has, if any, you may install
    441       a port using the variant as shown.</para>
    442 
    443       <programlisting><prompt>%%</prompt> <userinput>sudo port install fetchmail +ssl</userinput></programlisting>
    444 
    445       <para>Port variant execution may be verified using the
    446       <command>port</command> command with the verbose switch.</para>
    447 
    448       <programlisting><prompt>%%</prompt> <userinput>sudo port -v install fetchmail +ssl</userinput></programlisting>
    449 
    450       <para>When a port is installed using a valid variant and specified
    451       correctly, the verbose output will contain:</para>
    452 
    453       <screen>DEBUG: Executing variant ssl provides ssl</screen>
    454     </section>
    455 
    456     <section id="using.variants.negating">
    457       <title>Negating Default Variants</title>
    458 
    459       <para>For an explanation of default variants see <link
    460       linkend="development.variants">Port Variants</link>. Default variants
    461       are optional, and not all ports using variants have them. For ports with
    462       default variants, you may install a port without them by negating
    463       default variants using <quote>-</quote> as shown.</para>
    464 
    465       <programlisting><prompt>%%</prompt> <userinput>sudo port install fetchmail -ssl</userinput></programlisting>
    466 
    467       <para>To verify that you have properly negated a default variant, you
    468       may want to use verbose mode. But negated variants are simply not
    469       reported in any way by the <command>port</command> command, as if they
    470       did not exist. You will know you have successfully negated the default
    471       variant in the example above if you do <emphasis>not</emphasis> see this
    472       line in the verbose output.</para>
    473 
    474       <screen>DEBUG: Executing variant ssl provides ssl</screen>
    475     </section>
    476   </section>
    477 
    478   <section id="using.common-tasks">
    479     <title>Common Tasks</title>
    480 
    481     <para>This section lists common operations you may want to perform when managing a MacPorts
    482     installation. Some commands are described in further details elsewhere in the guide.</para>
    483 
    484     <para>Mind the 'sudo' for some of the subsequent examples, which is necessary if you have a
    485     root-MacPorts-installation.</para>
    486 
    487     <section id="using.common-tasks.updating">
    488       <title>Updating your ports tree</title>
    489 
    490       <para>is essential to stay up-to-date with MacPorts:</para>
    491 
    492       <programlisting><prompt>%%</prompt> <userinput>sudo port selfupdate</userinput></programlisting>
    493 
    494       <screen>Password:
    495 --->  Updating the ports tree
    496 --->  Updating MacPorts base sources using rsync
    497 MacPorts base version 1.9.1 installed,
    498 MacPorts base version 1.9.1 downloaded.
    499 --->  MacPorts base is already the latest version
    500 
    501 The ports tree has been updated. To upgrade your installed ports, you should run
    502   port upgrade outdated</screen>
    503     </section>
    504 
    505     <section id="using.common-tasks.showports">
    506       <title>Show all ports which actually need updating</title>
    507 
    508       <para>is often useful, in case you don't have time to wait for port upgrades
    509           (Every port needs to be downloaded, configured, built and installed, which can be -
    510           depending on your systems resources - a very time consuming procedure.):</para>
    511 
    512       <programlisting><prompt>%%</prompt> <userinput>port outdated</userinput></programlisting>
    513       <screen>The following installed ports are outdated:
    514 makedepend                     1.0.2_0 &lt; 1.0.3_0         
    515 Xft2                           2.1.14_0 &lt; 2.2.0_0       
    516 xorg-bigreqsproto              1.1.0_0 &lt; 1.1.1_0         
    517 xorg-compositeproto            0.4.1_0 &lt; 0.4.2_0         
    518 xorg-damageproto               1.2.0_0 &lt; 1.2.1_0         
    519 xorg-fixesproto                4.1.1_0 &lt; 4.1.2_0         
    520 xorg-libXdmcp                  1.0.3_0 &lt; 1.1.0_0         
    521 xorg-libXmu                    1.0.5_0 &lt; 1.1.0_0         
    522 xorg-libXScrnSaver             1.2.0_0 &lt; 1.2.1_0         
    523 xorg-randrproto                1.3.1_0 &lt; 1.3.2_0         
    524 xorg-scrnsaverproto            1.2.0_0 &lt; 1.2.1_0         
    525 xorg-xcmiscproto               1.2.0_0 &lt; 1.2.1_0         
    526 xpm                            3.5.8_0 &lt; 3.5.9_0         
    527 xorg-util-macros               1.10.1_0 &lt; 1.11.0_0</screen>
    528     </section>
    529 
    530     <section id="using.common-tasks.upgrading">
    531       <title>Upgrading outdated ports</title>
    532 
    533       <para>is usually done with the following command:</para>
    534 
    535       <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade outdated</userinput></programlisting>
    536 
    537       <para>In case you want to upgrade only a specific port (for whatever reason):</para>
    538 
    539       <programlisting><prompt>%%</prompt> <userinput>sudo port upgrade makedepend</userinput></programlisting>
    540       <screen>Password:
    541 --->  Computing dependencies for makedepend
    542 --->  Fetching makedepend
    543 --->  Attempting to fetch makedepend-1.0.3.tar.bz2 from http://lil.fr.distfiles.macports.org/makedepend
    544 --->  Verifying checksum(s) for makedepend
    545 --->  Extracting makedepend
    546 --->  Configuring makedepend
    547 --->  Building makedepend
    548 --->  Staging makedepend into destroot
    549 --->  Computing dependencies for makedepend
    550 --->  Installing makedepend @1.0.3_0
    551 --->  Deactivating makedepend @1.0.2_0
    552 --->  Activating makedepend @1.0.3_0
    553 --->  Cleaning makedepend</screen>
    554     </section>
    555 
    556     <section id="using.common-tasks.removeinactive">
    557       <title>Removing inactive version(s) of upgraded port(s)</title>
    558      
    559       <para>makes sense if you are sure that you won't change back to the older version(s)
    560             (which could be necessary in case of newly introduced bugs in the upgraded port
    561             version):</para>
    562 
    563       <programlisting><prompt>%%</prompt> <userinput>port installed inactive</userinput></programlisting>
    564       <screen>The following ports are currently installed:
    565   makedepend @1.0.2_0</screen>
    566  
    567       <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall inactive</userinput></programlisting>
    568       <screen>Password:
    569 --->  Uninstalling makedepend @1.0.2_0</screen>
    570 
    571       <para>Of course one could also select only a specific inactive port,
    572             but that requires to specify the exact version:</para>
    573       <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall makedepend @1.0.2_0</userinput></programlisting>
    574       <screen>Password:
    575 --->  Uninstalling makedepend @1.0.2_0</screen>
    576     </section>
    577 
    578     <section id="using.common-tasks.finddepending">
    579       <title>Finding ports depending on a certain port</title>
    580 
    581       <para>can sometimes be very helpful (example: find ports depending on 'xorg-util-macros'):</para>
    582 
    583       <programlisting><prompt>%%</prompt> <userinput>port echo depends:xorg-util-macros</userinput></programlisting>
    584 
    585       <screen>mkfontscale
    586 xorg-libAppleWM
    587 xorg-libX11
    588 xorg-libXaw
    589 xorg-libXevie
    590 xorg-libXp
    591 xorg-libXt
    592 xorg-server
    593 xorg-server-devel
    594 xscope
    595 xtrap</screen>
    596     </section>
    597 
    598     <section id="using.common-tasks.findleaves">
    599       <title>Finding leaves (nondependent ports)</title>
    600       <para>can be sometimes worthwhile, since often additional ports get installed when
    601             a specific port is installed. One can imagine that if one keeps installing and
    602             uninstalling ports for some time the MacPorts tree can be swamped with ports actually
    603             not necessary anymore. Leaves can be found by issuing the command:</para>
    604 
    605       <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
    606       <screen>aalib                          @1.4rc5_4
    607 autoconf                       @2.68_0
    608 autoconf263                    @2.63_0
    609 automake                       @1.11.1_0
    610 cmake                          @2.8.2_4
    611 coreutils                      @8.5_0</screen>
    612 
    613       <para>The following command delivers a similar result:</para>
    614       <programlisting><prompt>%%</prompt> <userinput>port installed leaves</userinput></programlisting>
    615       <screen>  aalib @1.4rc5_4 (active)
    616   autoconf @2.68_0 (active)
    617   autoconf263 @2.63_0 (active)
    618   automake @1.11.1_0 (active)
    619   cmake @2.8.2_4 (active)
    620   coreutils @8.5_0 (active)</screen>
    621 
    622       <para>These leaves may be wanted, but could also be unwanted ports. (See the following entry!)</para>
    623           </section>
    624 
    625     <section id="using.common-tasks.keeplean">
    626       <title>Keep your MacPorts installation lean by defining leaves as requested ports</title>
    627       <para>Well, before we come to the procedure of defining your requested ports,
    628             let's have a look at a typical scenario where you want to understand what is
    629             actually installed and what is on the other hand truly necessary for your system.
    630             Say checking leaves of your MacPorts installation gives this output:</para>
    631 
    632       <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
    633       <screen>aalib                          @1.4rc5_4
    634 autoconf                       @2.68_0
    635 autoconf263                    @2.63_0
    636 automake                       @1.11.1_0
    637 cmake                          @2.8.2_4
    638 coreutils                      @8.5_0
    639 physfs                         @2.0.1_0</screen>
    640 
    641       <para>Now it is up to the user to decide what's needed and what is not.
    642             Let's say one certainly would want ports starting with autoconf up to coreutils,
    643             since they are often used in port installation. Set those as requested ports using:</para>
    644 
    645       <programlisting><prompt>%%</prompt> <userinput>sudo port setrequested autoconf autoconf263 automake cmake coreutils</userinput></programlisting>
    646 
    647       <para>Say port aalib is not needed anymore, while physfs seems odd and since you don't
    648             know what to make of it, you need to check out what it actually is and which ports needed
    649             its installation at some time in the past.</para>
    650 
    651       <programlisting><prompt>%%</prompt> <userinput>port info physfs</userinput></programlisting>
    652       <screen>physfs @2.0.1 (devel)
    653 Variants:             debug, universal
    654 
    655 Description:          PhysicsFS is a library to provide abstract access to various
    656                       archives. It is intended for use in video games, and the design
    657                       was somewhat inspired by Quake 3's file subsystem.
    658 Homepage:             http://icculus.org/physfs/
    659 
    660 Build Dependencies:   cmake
    661 Library Dependencies: zlib
    662 Platforms:            darwin
    663 License:              unknown
    664 Maintainers:          nomaintainer@macports.org</screen>
    665 
    666       <para>Well, hmm, you certainly didn't want to install Quake 3 in the past. So, let's
    667             find out which ports actually depend on it, perhaps that might ring a bell:</para>
    668 
    669       <programlisting><prompt>%%</prompt> <userinput>port echo depends:physfs</userinput></programlisting>
    670       <screen>fbg                             
    671 libsdl_sound                   
    672 lincity-ng                     
    673 netpanzer</screen>
    674 
    675       <para>No, you didn't install netpanzer either,
    676             but - see there - fbg (The classic Falling Block Game!) was once on your agenda. But
    677             unfortunately that port was broken
    678             (see issue <ulink url="http://trac.macports.org/ticket/24641">#24641</ulink>) when
    679             you were trying to install it... Before you ran into the issue, of course, fbg's
    680             dependencies were resolved by MacPorts, which is why port physfs is still present on
    681             your system. Uff, great, confusion resolved. :-)</para>
    682 
    683       <para>When you've step-by-step figured out which ports you want to keep on your system and
    684             have set them as requested, you'll have a list of unnecessary ports, which might be
    685             eventually as short as this:</para>
    686 
    687       <programlisting><prompt>%%</prompt> <userinput>port echo leaves</userinput></programlisting>
    688       <screen>aalib                          @1.4rc5_4
    689 physfs                         @2.0.1_0 </screen>
    690 
    691       <para>Get rid of them by issuing the command:</para>
    692 
    693       <programlisting><prompt>%%</prompt> <userinput>sudo port uninstall leaves</userinput></programlisting>
    694       <screen>--->  Deactivating physfs @2.0.1_0
    695 --->  Cleaning physfs
    696 --->  Uninstalling physfs @2.0.1_0
    697 --->  Cleaning physfs
    698 --->  Deactivating aalib @1.4rc5_4
    699 --->  Uninstalling aalib @1.4rc5_4</screen>
    700 
    701       <para>Find all installed ports you previously set as requested using:</para>
    702 
    703       <programlisting><prompt>%%</prompt> <userinput>port installed requested</userinput></programlisting>
    704 
    705       <para>Checking the list of leaves from time to time will help to keep your system
    706             free of too much <quote>garbage</quote>. However, keep in mind that some ports may be dependencies
    707             only during the installation of a port (library dependencies, installation or
    708             configuration tools, etc.). So, be careful when removing seemingly unnecessary leaves,
    709             otherwise you'll see them being installed again and again.</para>
    710       </section>
    711   </section>
    712 
    713   <section id="using.binaries">
    714     <title>Port Binaries</title>
    715 
    716     <para>MacPorts can pre-compile ports into binaries so applications need
    717     not be compiled when installing on a target system. MacPorts may create
    718     two types of binaries: archives and packages.</para>
    719 
    720     <section id="using.binaries.archives">
    721       <title>Binary Archives</title>
    722 
    723       <para>Binary archives can only be used on a target system running
    724       MacPorts. Binary archives allow MacPorts utilities to begin installation
    725       after the destroot phase and install and activate a port on the target
    726       system. Binary archives are created whenever a port is installed, and can also
    727       be downloaded from a server.</para>
    728 
    729       <programlisting><prompt>%%</prompt> <userinput>sudo port -d archive logrotate</userinput></programlisting>
    730 
    731       <para>Debug output is shown below.</para>
    732 
    733       <screen>---&gt;  Creating logrotate-3.7_0.i386.tbz2
    734 
    735 [ ... trimmed ... ]
    736 
    737 DEBUG:
    738 ./
    739 ./+COMMENT
    740 ./+CONTENTS
    741 ./+DESC
    742 ./+PORTFILE
    743 ./+STATE
    744 ./opt/
    745 ./opt/local/
    746 ./opt/local/etc/
    747 ./opt/local/etc/logrotate.conf
    748 ./opt/local/man/
    749 ./opt/local/man/man8/
    750 ./opt/local/man/man8/logrotate.8
    751 ./opt/local/sbin/
    752 ./opt/local/sbin/logrotate
    753 ---&gt;  Archive logrotate-3.7_0.i386.tbz2 packaged
    754 DEBUG: Executing archive_finish
    755 ---&gt;  Archive for logrotate 3.7_0 packaged</screen>
    756 
    757       <para>Binary archive files are placed in
    758       <filename>${prefix}/var/macports/software/</filename>. The archive file
    759       type is set in the <filename>macports.conf</filename> file. The default
    760       format is .tbz2; other options are: tar, tbz, tbz2, tgz, tlz, txz, xar, zip, cpgz,
    761       cpio.</para>
    762     </section>
    763 
    764     <section id="using.binaries.binary-packages">
    765       <title>Binary Packages</title>
    766 
    767       <para>Binary packages are standalone binary installers that are
    768       precompiled; they do not require MacPorts on the target system. Binary
    769       files created with MacPorts may be either .pkg (OS X Installer
    770       Packages), or .rpm (RPM Package Manager) format. MacPorts may also
    771       process a .pkg package into a OS X .dmg disk image file. You may
    772       create binary packages with the <command>port</command> command as shown
    773       in these examples.</para>
    774 
    775       <programlisting><prompt>%%</prompt> <userinput>sudo port pkg pstree</userinput></programlisting>
    776 
    777       <para>You may create a OS X .dmg disk image file as shown.</para>
    778 
    779       <programlisting><prompt>%%</prompt> <userinput>sudo port dmg pstree</userinput></programlisting>
    780 
    781       <para>You can also create a metapackage containing packages of a port and all its
    782       dependencies:</para>
    783 
    784       <programlisting><prompt>%%</prompt> <userinput>sudo port mpkg gimp2</userinput></programlisting>
    785 
    786       <para>Just as with a single package, a metapackage can also be wrapped in a .dmg.</para>
    787 
    788       <programlisting><prompt>%%</prompt> <userinput>sudo port mdmg gimp2</userinput></programlisting>
    789 
    790       <para>You may compile a port into an RPM file as shown, in order to
    791       install it onto a target that has RPM utilities or a full package
    792       management system that can install RPMs.</para>
    793 
    794       <programlisting><prompt>%%</prompt> <userinput>sudo port rpm pstree</userinput></programlisting>
    795 
    796       <para>All packages are placed in a port's work directory,
    797       except for rpms that are placed under the regular <quote>RPMS</quote>:</para>
    798 
    799       <programlisting><prompt>%%</prompt> <userinput>port work pstree</userinput></programlisting>
    800       <programlisting><prompt>%%</prompt> <userinput>rpm --eval %{_rpmdir}</userinput></programlisting>
    801 
    802     </section>
    803   </section>
    804 
    805   <!--
    806   <section id="using.rsync-replication">
    807     <title>Rsync Replication Servers</title>
    808 
    809     <para>You may setup an rsync replication server on your local network to
    810     minimize internet delay and bandwidth when performing MacPorts selfupdate
    811     operations. An rsync replication server pulls the latest MacPorts base,
    812     development, and port sources from the remote MacPorts Subversion server,
    813     and then serves as the rsync source when rsync replication clients on the
    814     local network perform selfupdates. </para>
    815 
    816     <note>
    817       <para>Only advanced users should attempt to setup an rsync replication
    818       server. Before doing so, please contact <email>macports-mgr @
    819       lists.macosforge.org</email>. If the scripts are run too often you may overload
    820       the MacPorts rsync mirrors; it must not be run any more often than each
    821       one-half hour and should be run at an offset to the clock half hour
    822       periods.</para>
    823     </note>
    824 
    825     <section id="using.rsync-replication.server-setup">
    826       <title>Rsync Server Setup</title>
    827 
    828       <para>TODO: This section needs to be completed.</para>
    829 
    830       <para>To setup a host as an rsync replication server, follow these
    831       steps:</para>
    832 
    833       <orderedlist>
    834         <listitem>
    835           <para>Change to the portmgr directory where
    836           <filename>mprsyncup</filename> and <filename>rsync.repos</filename>
    837           reside.</para>
    838 
    839           <programlisting><prompt>%%</prompt> <userinput>cd ${prefix}/var/macports/sources/rsync.macports.org/release/ \
    840         base/portmgr</userinput>
    841 </programlisting>
    842         </listitem>
    843 
    844         <listitem>
    845           <para>Set variables in the <filename>mprsyncup</filename>
    846           script.</para>
    847 
    848           <programlisting>???</programlisting>
    849         </listitem>
    850 
    851         <listitem>
    852           <para>Set variables in the <filename>rsync.repos</filename>
    853           script.</para>
    854 
    855           <programlisting>???</programlisting>
    856         </listitem>
    857 
    858         <listitem>
    859           <para>Set the <filename>mprsyncup</filename> and
    860           <filename>rsync.repos</filename> scripts in
    861           <filename>crontab</filename>.</para>
    862 
    863           <note>
    864             <para>If you wish to setup and rsync replication server, please
    865             contact <email>macports-mgr@lists.macosforge.org</email>. If the
    866             scripts are run too often you may overload the MacPorts rsync mirrors;
    867             It must not be run any more often than each one-half hour and should
    868             be run at an offset to the clock half hour periods.</para>
    869           </note>
    870 
    871           <programlisting><prompt>%%</prompt> <userinput>sudo crontab -e</userinput></programlisting>
    872 
    873           <programlisting>15 * * * * ${prefix}/var/macports/sources/rsync.macports.org/release/ \
    874           base/portmgr/mprsyncup</programlisting>
    875         </listitem>
    876       </orderedlist>
    877     </section>
    878 
    879     <section id="using.rsync-replication.client-setup">
    880       <title>Rsync Client Setup</title>
    881 
    882       <para>To setup a host as an rsync replication client, follow these
    883       steps:</para>
    884 
    885       <orderedlist>
    886         <listitem>
    887           <para>Change to the MacPorts <filename>etc/</filename> directory to
    888           access <filename>macports.conf</filename> and
    889           <filename>sources.conf</filename>.</para>
    890 
    891           <programlisting><prompt>%%</prompt> <userinput>cd ${prefix}/etc/macports</userinput></programlisting>
    892         </listitem>
    893 
    894         <listitem>
    895           <para>In <filename>macports.conf</filename>, set variable
    896           <varname>rsync_server</varname> to the rsync replication server; the
    897           <varname>rsync_dir</varname> path variable can be left at the
    898           default if you follow the defaults that the MacPorts mirrors
    899           use.</para>
    900 
    901           <programlisting>rsync_server            rsync.mycompany.com
    902 
    903 rsync_dir               release/base/</programlisting>
    904         </listitem>
    905 
    906         <listitem>
    907           <para>In <filename>sources.conf</filename>, set the URL rsync:// to
    908           the rsync replication server.</para>
    909 
    910           <programlisting>rsync://rsync.mycompany.com/release/ports/</programlisting>
    911         </listitem>
    912       </orderedlist>
    913     </section>
    914   </section>
    915 -->
    9161511</chapter>
Note: See TracChangeset for help on using the changeset viewer.