Changeset 31621 for trunk/doc-new


Ignore:
Timestamp:
Nov 30, 2007, 7:09:37 PM (12 years ago)
Author:
simon@…
Message:

doc-new: Whitespace change only to fix indentation.

Location:
trunk/doc-new/guide/xml
Files:
7 edited

Legend:

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

    r29335 r31621  
    4545  </bookinfo>
    4646
    47   <xi:include href="intro.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     47  <xi:include href="intro.xml"
     48              xmlns:xi="http://www.w3.org/2001/XInclude" />
    4849
    49   <xi:include href="installing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     50  <xi:include href="installing.xml"
     51              xmlns:xi="http://www.w3.org/2001/XInclude" />
    5052
    51   <xi:include href="using.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     53  <xi:include href="using.xml"
     54              xmlns:xi="http://www.w3.org/2001/XInclude" />
    5255
    5356  <xi:include href="portfiledev.xml"
     
    5760              xmlns:xi="http://www.w3.org/2001/XInclude" />
    5861
    59   <xi:include href="internals.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     62  <xi:include href="internals.xml"
     63              xmlns:xi="http://www.w3.org/2001/XInclude" />
    6064
    61   <xi:include href="project.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     65  <xi:include href="project.xml"
     66              xmlns:xi="http://www.w3.org/2001/XInclude" />
    6267
    63   <xi:include href="glossary.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     68  <xi:include href="glossary.xml"
     69              xmlns:xi="http://www.w3.org/2001/XInclude" />
     70
    6471</book>
  • trunk/doc-new/guide/xml/internals.xml

    r30829 r31621  
    1212
    1313    <xi:include href="../../man/xml/porthier.7.xml"
    14       xmlns:xi="http://www.w3.org/2001/XInclude" />
     14                xmlns:xi="http://www.w3.org/2001/XInclude" />
    1515  </section>
    1616
  • trunk/doc-new/guide/xml/portfile-global-keywords.7.xml

    r31445 r31621  
    33"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
    44
     5<section>
     6  <title>Global Keywords</title>
     7
     8  <para>MacPorts keywords are used to specify required or optional items
     9  within a Portfile, or to override default options used by MacPorts base
     10  for individual ports. Keywords are to be used within the "global" and
     11  "variant" sections of Portfiles, and not within optional port phase
     12  declarations.</para>
     13
     14  <para>The global keywords listed below specify information for ports as a
     15  whole, whereas the keywords listed under a port phase specify information
     16  to be used during a particular installation phase.</para>
     17
    518  <section>
    6     <title>Global Keywords</title>
    7 
    8     <para>MacPorts keywords are used to specify required or optional items
    9     within a Portfile, or to override default options used by MacPorts base
    10     for individual ports. Keywords are to be used within the "global" and
    11     "variant" sections of Portfiles, and not within optional port phase
    12     declarations.</para>
    13 
    14     <para>The global keywords listed below specify information for ports as a
    15     whole, whereas the keywords listed under a port phase specify information
    16     to be used during a particular installation phase.</para>
    17 
    18     <section>
    19       <title>General</title>
    20 
    21       <para>The list of global keywords.</para>
    22 
    23       <variablelist>
    24         <varlistentry>
    25           <term>PortSystem</term>
    26 
    27           <listitem>
    28             <para>The top line of every Portfile; it must be followed by a
    29             blank line. It defines which version of the Portfile interpreter
    30             will be used.</para>
    31 
    32             <programlisting>PortSystem   1.0
     19    <title>General</title>
     20
     21    <para>The list of global keywords.</para>
     22
     23    <variablelist>
     24      <varlistentry>
     25        <term>PortSystem</term>
     26
     27        <listitem>
     28          <para>The top line of every Portfile; it must be followed by a
     29          blank line. It defines which version of the Portfile interpreter
     30          will be used.</para>
     31
     32          <programlisting>PortSystem   1.0
    3333
    3434</programlisting>
    35           </listitem>
    36         </varlistentry>
    37 
    38         <varlistentry>
    39           <term>name</term>
    40 
    41           <listitem>
    42             <para>The name of the Port; it should be lowercase.</para>
    43 
    44             <programlisting>name         foo</programlisting>
    45           </listitem>
    46         </varlistentry>
    47 
    48         <varlistentry>
    49           <term>version</term>
    50 
    51           <listitem>
    52             <para>The version of the ported software.</para>
    53 
    54             <programlisting>version      1.23.45</programlisting>
    55           </listitem>
    56         </varlistentry>
    57 
    58         <varlistentry>
    59           <term>revision</term>
    60 
    61           <listitem>
    62             <para>Optional keyword (default is 0) that is used to track port
    63             revisions. It should not be incremented for port revisions unless
    64             it would benefit users to upgrade an installed port, and cleared
    65             when the port is updated to a newer version.</para>
    66 
    67             <programlisting>revision     1</programlisting>
    68           </listitem>
    69         </varlistentry>
    70 
    71         <varlistentry>
    72           <term>epoch</term>
    73 
    74           <listitem>
    75             <para>Optional keyword (default is 0) that is used if the new port
    76             version looks older than the previous version (for example 1.10
    77             -&gt; 1.2). Often the epoch is formatted like a date, but it can
    78             simple a number like 1.</para>
    79 
    80             <programlisting>epoch        20070924</programlisting>
    81 
    82             <programlisting>epoch        1</programlisting>
    83           </listitem>
    84         </varlistentry>
    85 
    86         <varlistentry>
    87           <term>categories</term>
    88 
    89           <listitem>
    90             <para>The category under which the ported software falls. The
    91             first category should be the same as the directory within which
    92             the Portfile is stored; secondary and tertiary categories may be
    93             selected.</para>
    94 
    95             <programlisting>categories     net security</programlisting>
    96           </listitem>
    97         </varlistentry>
    98 
    99         <varlistentry>
    100           <term>maintainers</term>
    101 
    102           <listitem>
    103             <para>A port's maintainer is a person or persons who take
    104             responsibility for keeping the port up-to-date, and the maintainer
    105             keyword lists maintainer email addresses(s). However, many
    106             maintainers wish to hide these addresses from spambots; to do so
    107             follow these conventions:</para>
    108 
    109             <itemizedlist>
    110               <listitem>
    111                 <para>For addresses in domain @macports.org, simply omit the
    112                 domain name.</para>
    113               </listitem>
    114 
    115               <listitem>
    116                 <para>For addresses in other domains, say
    117                 <email>account@example.org</email>, use the convention
    118                 example.org:account to specify the address.</para>
    119               </listitem>
    120             </itemizedlist>
    121 
    122             <para>In the example below, the maintainer email addresses
    123             <email>jdoe@macports.org</email> and
    124             <email>julesverne@example.org</email> are hidden using these
    125             conventions.</para>
    126 
    127             <programlisting>maintainers       jdoe \
     35        </listitem>
     36      </varlistentry>
     37
     38      <varlistentry>
     39        <term>name</term>
     40
     41        <listitem>
     42          <para>The name of the Port; it should be lowercase.</para>
     43
     44          <programlisting>name         foo</programlisting>
     45        </listitem>
     46      </varlistentry>
     47
     48      <varlistentry>
     49        <term>version</term>
     50
     51        <listitem>
     52          <para>The version of the ported software.</para>
     53
     54          <programlisting>version      1.23.45</programlisting>
     55        </listitem>
     56      </varlistentry>
     57
     58      <varlistentry>
     59        <term>revision</term>
     60
     61        <listitem>
     62          <para>Optional keyword (default is 0) that is used to track port
     63          revisions. It should not be incremented for port revisions unless
     64          it would benefit users to upgrade an installed port, and cleared
     65          when the port is updated to a newer version.</para>
     66
     67          <programlisting>revision     1</programlisting>
     68        </listitem>
     69      </varlistentry>
     70
     71      <varlistentry>
     72        <term>epoch</term>
     73
     74        <listitem>
     75          <para>Optional keyword (default is 0) that is used if the new port
     76          version looks older than the previous version (for example 1.10
     77          -&gt; 1.2). Often the epoch is formatted like a date, but it can
     78          simple a number like 1.</para>
     79
     80          <programlisting>epoch        20070924</programlisting>
     81
     82          <programlisting>epoch        1</programlisting>
     83        </listitem>
     84      </varlistentry>
     85
     86      <varlistentry>
     87        <term>categories</term>
     88
     89        <listitem>
     90          <para>The category under which the ported software falls. The
     91          first category should be the same as the directory within which
     92          the Portfile is stored; secondary and tertiary categories may be
     93          selected.</para>
     94
     95          <programlisting>categories     net security</programlisting>
     96        </listitem>
     97      </varlistentry>
     98
     99      <varlistentry>
     100        <term>maintainers</term>
     101
     102        <listitem>
     103          <para>A port's maintainer is a person or persons who take
     104          responsibility for keeping the port up-to-date, and the maintainer
     105          keyword lists maintainer email addresses(s). However, many
     106          maintainers wish to hide these addresses from spambots; to do so
     107          follow these conventions:</para>
     108
     109          <itemizedlist>
     110            <listitem>
     111              <para>For addresses in domain @macports.org, simply omit the
     112              domain name.</para>
     113            </listitem>
     114
     115            <listitem>
     116              <para>For addresses in other domains, say
     117              <email>account@example.org</email>, use the convention
     118              example.org:account to specify the address.</para>
     119            </listitem>
     120          </itemizedlist>
     121
     122          <para>In the example below, the maintainer email addresses
     123          <email>jdoe@macports.org</email> and
     124          <email>julesverne@example.org</email> are hidden using these
     125          conventions.</para>
     126
     127          <programlisting>maintainers       jdoe \
    128128                  example.org:julesverne</programlisting>
    129           </listitem>
    130         </varlistentry>
    131 
    132         <varlistentry>
    133           <term>description</term>
    134 
    135           <listitem>
    136             <para>A one-sentence description of the ported software.</para>
    137 
    138             <programlisting>description    A classic shooter arcade game.</programlisting>
    139           </listitem>
    140         </varlistentry>
    141 
    142         <varlistentry>
    143           <term>long_description</term>
    144 
    145           <listitem>
    146             <para>A long description of the ported software. Break long lines
    147             with escaped newlines.</para>
    148 
    149             <programlisting>description    A classic shooter arcade game derived from \
     129        </listitem>
     130      </varlistentry>
     131
     132      <varlistentry>
     133        <term>description</term>
     134
     135        <listitem>
     136          <para>A one-sentence description of the ported software.</para>
     137
     138          <programlisting>description    A classic shooter arcade game.</programlisting>
     139        </listitem>
     140      </varlistentry>
     141
     142      <varlistentry>
     143        <term>long_description</term>
     144
     145        <listitem>
     146          <para>A long description of the ported software. Break long lines
     147          with escaped newlines.</para>
     148
     149          <programlisting>description    A classic shooter arcade game derived from \
    150150               the game alien-munchers.  Not suitable for \
    151151               children under two years old.      </programlisting>
    152           </listitem>
    153         </varlistentry>
    154 
    155         <varlistentry>
    156           <term>homepage</term>
    157 
    158           <listitem>
    159             <para>Port application's homepage.</para>
    160 
    161             <programlisting>homepage       http://www.somesite.org/apps</programlisting>
    162           </listitem>
    163         </varlistentry>
    164 
    165         <varlistentry>
    166           <term>platforms</term>
    167 
    168           <listitem>
    169             <para>The platforms on which the port has been tested.</para>
    170 
    171             <programlisting>platforms      darwin freebsd</programlisting>
    172           </listitem>
    173         </varlistentry>
    174       </variablelist>
     152        </listitem>
     153      </varlistentry>
     154
     155      <varlistentry>
     156        <term>homepage</term>
     157
     158        <listitem>
     159          <para>Port application's homepage.</para>
     160
     161          <programlisting>homepage       http://www.somesite.org/apps</programlisting>
     162        </listitem>
     163      </varlistentry>
     164
     165      <varlistentry>
     166        <term>platforms</term>
     167
     168        <listitem>
     169          <para>The platforms on which the port has been tested.</para>
     170
     171          <programlisting>platforms      darwin freebsd</programlisting>
     172        </listitem>
     173      </varlistentry>
     174    </variablelist>
     175  </section>
     176
     177  <section>
     178    <title>Dependencies</title>
     179
     180    <para>Free and open source software is highly modular, and MacPorts
     181    ports often require that other ports be installed beforehand; these
     182    prerequisites for a given port are called a port's
     183    <quote>dependencies</quote>.</para>
     184
     185    <para>There are three types of MacPorts dependencies: library, build,
     186    and run dependencies. Dependency types are important for proper port
     187    upgrade and uninstall behavior. For example, you may not uninstall a
     188    port that is a library dependency for another port, though you may
     189    remove one with a build dependency; likewise, upgrading a port will
     190    upgrade its library and build dependencies also, but not its run
     191    dependencies.</para>
     192
     193    <variablelist>
     194      <varlistentry>
     195        <term>depends_lib</term>
     196
     197        <term>depends_lib-append</term>
     198
     199        <term>depends_lib-delete</term>
     200
     201        <listitem>
     202          <para>The list of dependencies to check before phases
     203          <option>configure</option>, <option>build</option>,
     204          <option>destroot</option>, <option>install</option>, and
     205          <option>package</option>. Library dependencies are needed both at
     206          build time (for headers and libraries to link against) and at run
     207          time.</para>
     208        </listitem>
     209      </varlistentry>
     210
     211      <varlistentry>
     212        <term>depends_build</term>
     213
     214        <term>depends_build-append</term>
     215
     216        <term>depends_build-delete</term>
     217
     218        <listitem>
     219          <para>The list of dependencies to check before phases
     220          <option>build</option>, <option>destroot</option>,
     221          <option>install</option>, and <option>package</option>. Build
     222          dependencies are needed when software is compiled, but not needed
     223          at all once the software is compiled and installed.</para>
     224        </listitem>
     225      </varlistentry>
     226
     227      <varlistentry>
     228        <term>depends_run</term>
     229
     230        <term>depends_run-append</term>
     231
     232        <term>depends_run-delete</term>
     233
     234        <listitem>
     235          <para>The list of dependencies to check before phases
     236          <option>destroot</option>, <option>install</option>, and
     237          <option>package</option>. Run dependencies are needed when the
     238          software is run, but not to compile it.</para>
     239        </listitem>
     240      </varlistentry>
     241    </variablelist>
     242
     243    <section>
     244      <title>Port and Non-Port Dependencies</title>
     245
     246      <para>Port dependencies should be provided by MacPorts ports whenever
     247      possible, however dependencies may be provided by vendor-supplied
     248      software when satisfying a dependency by a port is not practical or
     249      desirable for a special reason. Dependencies of this type are called
     250      non-port dependencies.</para>
     251
     252      <para>Port dependencies, the preferred type, are specified as shown in
     253      these examples:</para>
     254
     255      <programlisting>depends_lib        port:rrdtool port:apache2
     256
     257depends_build      port:apache2 port:php5</programlisting>
     258
     259      <para>Non-port dependencies are specified as shown in these
     260      examples:</para>
     261
     262      <programlisting>depends_lib        lib:libX11.6:xorg
     263
     264depends_build      bin:rrdtool</programlisting>
    175265    </section>
    176 
    177     <section>
    178       <title>Dependencies</title>
    179 
    180       <para>Free and open source software is highly modular, and MacPorts
    181       ports often require that other ports be installed beforehand; these
    182       prerequisites for a given port are called a port's
    183       <quote>dependencies</quote>.</para>
    184 
    185       <para>There are three types of MacPorts dependencies: library, build,
    186       and run dependencies. Dependency types are important for proper port
    187       upgrade and uninstall behavior. For example, you may not uninstall a
    188       port that is a library dependency for another port, though you may
    189       remove one with a build dependency; likewise, upgrading a port will
    190       upgrade its library and build dependencies also, but not its run
    191       dependencies.</para>
    192 
    193       <variablelist>
    194         <varlistentry>
    195           <term>depends_lib</term>
    196 
    197           <term>depends_lib-append</term>
    198 
    199           <term>depends_lib-delete</term>
    200 
    201           <listitem>
    202             <para>The list of dependencies to check before phases
    203             <option>configure</option>, <option>build</option>,
    204             <option>destroot</option>, <option>install</option>, and
    205             <option>package</option>. Library dependencies are needed both at
    206             build time (for headers and libraries to link against) and at run
    207             time.</para>
    208           </listitem>
    209         </varlistentry>
    210 
    211         <varlistentry>
    212           <term>depends_build</term>
    213 
    214           <term>depends_build-append</term>
    215 
    216           <term>depends_build-delete</term>
    217 
    218           <listitem>
    219             <para>The list of dependencies to check before phases
    220             <option>build</option>, <option>destroot</option>,
    221             <option>install</option>, and <option>package</option>. Build
    222             dependencies are needed when software is compiled, but not needed
    223             at all once the software is compiled and installed.</para>
    224           </listitem>
    225         </varlistentry>
    226 
    227         <varlistentry>
    228           <term>depends_run</term>
    229 
    230           <term>depends_run-append</term>
    231 
    232           <term>depends_run-delete</term>
    233 
    234           <listitem>
    235             <para>The list of dependencies to check before phases
    236             <option>destroot</option>, <option>install</option>, and
    237             <option>package</option>. Run dependencies are needed when the
    238             software is run, but not to compile it.</para>
    239           </listitem>
    240         </varlistentry>
    241       </variablelist>
    242 
    243       <section>
    244         <title>Port and Non-Port Dependencies</title>
    245 
    246         <para>Port dependencies should be provided by MacPorts ports whenever
    247         possible, however dependencies may be provided by vendor-supplied
    248         software when satisfying a dependency by a port is not practical or
    249         desirable for a special reason. Dependencies of this type are called
    250         non-port dependencies.</para>
    251 
    252         <para>Port dependencies, the preferred type, are specified as shown in
    253         these examples:</para>
    254 
    255         <programlisting>depends_lib        port:rrdtool port:apache2
    256 
    257 depends_build      port:apache2 port:php5</programlisting>
    258 
    259         <para>Non-port dependencies are specified as shown in these
    260         examples:</para>
    261 
    262         <programlisting>depends_lib        lib:libX11.6:xorg
    263 
    264 depends_build      bin:rrdtool</programlisting>
    265       </section>
    266     </section>
    267 
    268     <section>
    269       <title>Variants</title>
    270 
    271       <para>MacPorts variants are conditional modifications of port
    272       installation behavior that may be invoked by a user at the time of port
    273       install.</para>
    274 
    275       <variablelist>
    276         <varlistentry>
    277           <term>variant [requires variant] [conflicts variant] [description
    278           description]</term>
    279 
    280           <listitem>
    281             <para>The variant declaration may contain any keywords that can be
    282             placed in a Portfile's global section. If you wish to execute
    283             system (shell) calls or Tcl extensions during the execution of a
    284             port phase, you should place those statements within a
    285             <literal>variant_isset</literal> conditional within a phase
    286             declaration and not within the variant declaration itself.
    287             Dependencies and conflicts with other variants in the same port
    288             can be expressed with requires and conflicts. See the isset Tcl
    289             extension.</para>
    290 
    291             <itemizedlist>
    292               <listitem>
    293                 <para>Default: no</para>
    294               </listitem>
    295 
    296               <listitem>
    297                 <para>Example:</para>
    298 
    299                 <programlisting>variant gnome requires glib {
    300       configure.args-append --with-gnome
    301       depends_lib-append port:gnome-session
     266  </section>
     267
     268  <section>
     269    <title>Variants</title>
     270
     271    <para>MacPorts variants are conditional modifications of port
     272    installation behavior that may be invoked by a user at the time of port
     273    install.</para>
     274
     275    <variablelist>
     276      <varlistentry>
     277        <term>variant [requires variant] [conflicts variant] [description
     278        description]</term>
     279
     280        <listitem>
     281          <para>The variant declaration may contain any keywords that can be
     282          placed in a Portfile's global section. If you wish to execute
     283          system (shell) calls or Tcl extensions during the execution of a
     284          port phase, you should place those statements within a
     285          <literal>variant_isset</literal> conditional within a phase
     286          declaration and not within the variant declaration itself.
     287          Dependencies and conflicts with other variants in the same port
     288          can be expressed with requires and conflicts. See the isset Tcl
     289          extension.</para>
     290
     291          <itemizedlist>
     292            <listitem>
     293              <para>Default: no</para>
     294            </listitem>
     295
     296            <listitem>
     297              <para>Example:</para>
     298
     299              <programlisting>variant gnome requires glib {
     300    configure.args-append --with-gnome
     301    depends_lib-append port:gnome-session
    302302}</programlisting>
    303               </listitem>
    304             </itemizedlist>
    305           </listitem>
    306         </varlistentry>
    307 
    308         <varlistentry>
    309           <term>default_variants</term>
    310 
    311           <listitem>
    312             <para>If variants are defined, then the default_variants value
    313             lists which variants are enabled by default. This allows for
    314             Portfile modularity and also allows users to suppress default
    315             variants if they wish.</para>
    316 
    317             <itemizedlist>
    318               <listitem>
    319                 <para>Default: none</para>
    320               </listitem>
    321 
    322               <listitem>
    323                 <para>Example:</para>
    324 
    325                 <programlisting>default_variants +ssl +tcpd
     303            </listitem>
     304          </itemizedlist>
     305        </listitem>
     306      </varlistentry>
     307
     308      <varlistentry>
     309        <term>default_variants</term>
     310
     311        <listitem>
     312          <para>If variants are defined, then the default_variants value
     313          lists which variants are enabled by default. This allows for
     314          Portfile modularity and also allows users to suppress default
     315          variants if they wish.</para>
     316
     317          <itemizedlist>
     318            <listitem>
     319              <para>Default: none</para>
     320            </listitem>
     321
     322            <listitem>
     323              <para>Example:</para>
     324
     325              <programlisting>default_variants +ssl +tcpd
    326326
    327327</programlisting>
    328               </listitem>
    329             </itemizedlist>
    330           </listitem>
    331 
    332           <listitem>
    333             <para>Default variants may be suppressed by preceding a variant
    334             name with a "-" as shown in this example.</para>
    335 
    336             <programlisting><prompt>%%</prompt> <userinput>port install foo -ssl</userinput></programlisting>
    337           </listitem>
    338         </varlistentry>
    339 
    340         <varlistentry>
    341           <term>universal_variant</term>
    342 
    343           <listitem>
    344             <para>When using MacPorts on Mac OS X, a universal variant is
    345             defined by default to configure ports with universal flags. The
    346             variant can be overridden if the default code does not work (see
    347             the Configure Universal section below), or suppressed if a
    348             universal variant is not possible for the port with this
    349             keyword.</para>
    350 
    351             <itemizedlist>
    352               <listitem>
    353                 <para>Default: yes</para>
    354               </listitem>
    355 
    356               <listitem>
    357                 <para>Example:</para>
    358 
    359                 <programlisting>universal_variant  no</programlisting>
    360               </listitem>
    361             </itemizedlist>
    362           </listitem>
    363         </varlistentry>
    364       </variablelist>
    365     </section>
    366 
    367     <section>
    368       <title>Livecheck / Distcheck</title>
    369 
    370       <para>Options livecheck and distcheck are especially useful for port
    371       maintainers, but others may also find this information valuable.</para>
    372 
    373       <para>Livecheck checks to see if MacPorts can query the developer's
    374       download site to determine if a newer version of the software has become
    375       available since the port was installed.</para>
    376 
    377       <variablelist>
    378         <varlistentry>
    379           <term>livecheck.check</term>
    380 
    381           <listitem>
    382             <para>Specify what kind of update check to perform.</para>
    383 
    384             <para>Open source mirror site options are to use the project's
    385             latest file release from <option>sourceforge</option> or
    386             <option>googlecode</option>, or the project's
    387             <literal>date_updated</literal> XML tag for
    388             <option>freshmeat</option>.</para>
    389 
    390             <para>Generic download site options are to specify a
    391             <option>moddate</option> (modification date) of a URL resource), a
    392             <option>regex</option> (retrieve the version by applying a regex
    393             to a URL resource), <option>regexm</option> (retrieve the version
    394             by applying a multi-line regex to a URL resource),
    395             <option>md5</option> (compares the md5 sum of a URL resource) or
    396             <option>none</option> (no check).</para>
    397 
    398             <itemizedlist>
    399               <listitem>
    400                 <para>Default: sourceforge or googlecode if the master_sites
    401                 is one of these, else freshmeat.</para>
    402               </listitem>
    403 
    404               <listitem>
    405                 <para>Values: freshmeat sourceforge googlecode moddate regex
    406                 regexm md5 none</para>
    407               </listitem>
    408 
    409               <listitem>
    410                 <para>Examples:</para>
    411 
    412                 <programlisting>livecheck.check     regex
     328            </listitem>
     329          </itemizedlist>
     330        </listitem>
     331
     332        <listitem>
     333          <para>Default variants may be suppressed by preceding a variant
     334          name with a "-" as shown in this example.</para>
     335
     336          <programlisting><prompt>%%</prompt> <userinput>port install foo -ssl</userinput></programlisting>
     337        </listitem>
     338      </varlistentry>
     339
     340      <varlistentry>
     341        <term>universal_variant</term>
     342
     343        <listitem>
     344          <para>When using MacPorts on Mac OS X, a universal variant is
     345          defined by default to configure ports with universal flags. The
     346          variant can be overridden if the default code does not work (see
     347          the Configure Universal section below), or suppressed if a
     348          universal variant is not possible for the port with this
     349          keyword.</para>
     350
     351          <itemizedlist>
     352            <listitem>
     353              <para>Default: yes</para>
     354            </listitem>
     355
     356            <listitem>
     357              <para>Example:</para>
     358
     359              <programlisting>universal_variant  no</programlisting>
     360            </listitem>
     361          </itemizedlist>
     362        </listitem>
     363      </varlistentry>
     364    </variablelist>
     365  </section>
     366
     367  <section>
     368    <title>Livecheck / Distcheck</title>
     369
     370    <para>Options livecheck and distcheck are especially useful for port
     371    maintainers, but others may also find this information valuable.</para>
     372
     373    <para>Livecheck checks to see if MacPorts can query the developer's
     374    download site to determine if a newer version of the software has become
     375    available since the port was installed.</para>
     376
     377    <variablelist>
     378      <varlistentry>
     379        <term>livecheck.check</term>
     380
     381        <listitem>
     382          <para>Specify what kind of update check to perform.</para>
     383
     384          <para>Open source mirror site options are to use the project's
     385          latest file release from <option>sourceforge</option> or
     386          <option>googlecode</option>, or the project's
     387          <literal>date_updated</literal> XML tag for
     388          <option>freshmeat</option>.</para>
     389
     390          <para>Generic download site options are to specify a
     391          <option>moddate</option> (modification date) of a URL resource), a
     392          <option>regex</option> (retrieve the version by applying a regex
     393          to a URL resource), <option>regexm</option> (retrieve the version
     394          by applying a multi-line regex to a URL resource),
     395          <option>md5</option> (compares the md5 sum of a URL resource) or
     396          <option>none</option> (no check).</para>
     397
     398          <itemizedlist>
     399            <listitem>
     400              <para>Default: sourceforge or googlecode if the master_sites
     401              is one of these, else freshmeat.</para>
     402            </listitem>
     403
     404            <listitem>
     405              <para>Values: freshmeat sourceforge googlecode moddate regex
     406              regexm md5 none</para>
     407            </listitem>
     408
     409            <listitem>
     410              <para>Examples:</para>
     411
     412              <programlisting>livecheck.check     regex
    413413livecheck.url       http://dev.mysql.com/
    414414livecheck.regex     "Generally Available (${major_version}\\.\[0-9.\]+)"
    415415</programlisting>
    416               </listitem>
    417             </itemizedlist>
    418           </listitem>
    419         </varlistentry>
    420 
    421         <varlistentry>
    422           <term>livecheck.name</term>
    423 
    424           <listitem>
    425             <para>Name of the project for live checks; only used with
    426             freshmeat, sourceforge, and googlecode livechecks.</para>
    427 
    428             <itemizedlist>
    429               <listitem>
    430                 <para>Default: <varname>${name}</varname> or the
    431                 sourceforge/freshmeat/googlecode project name if it can be
    432                 guessed from <literal>master_sites</literal>.</para>
    433               </listitem>
    434 
    435               <listitem>
    436                 <para>Values:
    437                 <replaceable>any_project_name</replaceable></para>
    438               </listitem>
    439 
    440               <listitem>
    441                 <para>Example:</para>
    442 
    443                 <programlisting>livecheck.name   hibernate</programlisting>
    444               </listitem>
    445             </itemizedlist>
    446           </listitem>
    447         </varlistentry>
    448 
    449         <varlistentry>
    450           <term>livecheck.distname</term>
    451 
    452           <listitem>
    453             <para>Name of the file release for sourceforge and googlecode
    454             checks. You may use this keyword without livecheck.version if you
    455             replace the version part of the name with "(.*)".</para>
    456 
    457             <itemizedlist>
    458               <listitem>
    459                 <para>Default: SourceForge:
    460                 <varname>${livecheck.name}</varname> ; GoogleCode: first
    461                 ${distfiles} item</para>
    462               </listitem>
    463 
    464               <listitem>
    465                 <para>Values: <replaceable>filename</replaceable></para>
    466               </listitem>
    467 
    468               <listitem>
    469                 <para>Example:</para>
    470 
    471                 <programlisting>livecheck.distname  faad2.src</programlisting>
    472               </listitem>
    473             </itemizedlist>
    474           </listitem>
    475         </varlistentry>
    476 
    477         <varlistentry>
    478           <term>livecheck.version</term>
    479 
    480           <listitem>
    481             <para>Version of the project for a check; used for regex-based
    482             checks.</para>
    483 
    484             <itemizedlist>
    485               <listitem>
    486                 <para>Default: <varname>${version}</varname></para>
    487               </listitem>
    488 
    489               <listitem>
    490                 <para>Values: <replaceable>any_version</replaceable></para>
    491               </listitem>
    492 
    493               <listitem>
    494                 <para>Example:</para>
    495 
    496                 <programlisting>livecheck.version   ${name}-${version}</programlisting>
    497               </listitem>
    498             </itemizedlist>
    499           </listitem>
    500         </varlistentry>
    501 
    502         <varlistentry>
    503           <term>livecheck.url</term>
    504 
    505           <listitem>
    506             <para>URL to query for a check.</para>
    507 
    508             <itemizedlist>
    509               <listitem>
    510                 <para>Default:</para>
    511 
    512                 <itemizedlist>
    513                   <listitem>
    514                     <para>homepage or the first hit among the following
    515                     sites</para>
    516                   </listitem>
    517 
    518                   <listitem>
    519                     <para>http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml</para>
    520                   </listitem>
    521 
    522                   <listitem>
    523                     <para>http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}</para>
    524                   </listitem>
    525 
    526                   <listitem>
    527                     <para>http://code.google.com/p/${livecheck.name}/downloads/list</para>
    528                   </listitem>
    529                 </itemizedlist>
    530               </listitem>
    531 
    532               <listitem>
    533                 <para>Values: <replaceable>any_url</replaceable></para>
    534               </listitem>
    535 
    536               <listitem>
    537                 <para>Example:</para>
    538 
    539                 <programlisting>livecheck.url  http://ftp.gnu.org/gnu/bison/</programlisting>
    540               </listitem>
    541             </itemizedlist>
    542           </listitem>
    543         </varlistentry>
    544 
    545         <varlistentry>
    546           <term>livecheck.regex</term>
    547 
    548           <listitem>
    549             <para>Regular expression to parse the resource for regex checks.
    550             Be sure to use a regular expression grouping around the version
    551             component.</para>
    552 
    553             <itemizedlist>
    554               <listitem>
    555                 <para>Default: none</para>
    556               </listitem>
    557 
    558               <listitem>
    559                 <para>Values: <replaceable>any_regex</replaceable></para>
    560               </listitem>
    561 
    562               <listitem>
    563                 <para>Example:</para>
    564 
    565                 <programlisting>livecheck.regex  4th-([a-z0-9.]+)-unix.tar.gz</programlisting>
    566               </listitem>
    567             </itemizedlist>
    568           </listitem>
    569         </varlistentry>
    570 
    571         <varlistentry>
    572           <term>livecheck.md5</term>
    573 
    574           <listitem>
    575             <para>md5 checksum to use for an md5 comparison.</para>
    576 
    577             <itemizedlist>
    578               <listitem>
    579                 <para>Default: none</para>
    580               </listitem>
    581 
    582               <listitem>
    583                 <para>Values:
    584                 <replaceable>any_md5_checksum</replaceable></para>
    585               </listitem>
    586 
    587               <listitem>
    588                 <para>Example:</para>
    589 
    590                 <programlisting>livecheck  md5 37e6a5b6516a680c7178b72021d3b706</programlisting>
    591               </listitem>
    592             </itemizedlist>
    593           </listitem>
    594         </varlistentry>
    595       </variablelist>
    596 
    597       <para>Distcheck reports whether or not the distfile(s) specified in a
    598       Portfile are still available on the developer's download site. Examples
    599       are given below.</para>
    600 
    601       <variablelist>
    602         <varlistentry>
    603           <term>distcheck.check</term>
    604 
    605           <listitem>
    606             <para>This option can be used to disable distcheck. It specifies
    607             what kind of check should be performed on distfiles: moddate
    608             (check if the Portfile is older than the distfile) or none (no
    609             check).</para>
    610 
    611             <itemizedlist>
    612               <listitem>
    613                 <para>Default: moddate</para>
    614               </listitem>
    615 
    616               <listitem>
    617                 <para>Values: moddate none</para>
    618               </listitem>
    619 
    620               <listitem>
    621                 <para>Example:</para>
    622 
    623                 <programlisting>distcheck.check  none</programlisting>
    624               </listitem>
    625             </itemizedlist>
    626           </listitem>
    627         </varlistentry>
    628       </variablelist>
    629     </section>
     416            </listitem>
     417          </itemizedlist>
     418        </listitem>
     419      </varlistentry>
     420
     421      <varlistentry>
     422        <term>livecheck.name</term>
     423
     424        <listitem>
     425          <para>Name of the project for live checks; only used with
     426          freshmeat, sourceforge, and googlecode livechecks.</para>
     427
     428          <itemizedlist>
     429            <listitem>
     430              <para>Default: <varname>${name}</varname> or the
     431              sourceforge/freshmeat/googlecode project name if it can be
     432              guessed from <literal>master_sites</literal>.</para>
     433            </listitem>
     434
     435            <listitem>
     436              <para>Values:
     437              <replaceable>any_project_name</replaceable></para>
     438            </listitem>
     439
     440            <listitem>
     441              <para>Example:</para>
     442
     443              <programlisting>livecheck.name   hibernate</programlisting>
     444            </listitem>
     445          </itemizedlist>
     446        </listitem>
     447      </varlistentry>
     448
     449      <varlistentry>
     450        <term>livecheck.distname</term>
     451
     452        <listitem>
     453          <para>Name of the file release for sourceforge and googlecode
     454          checks. You may use this keyword without livecheck.version if you
     455          replace the version part of the name with "(.*)".</para>
     456
     457          <itemizedlist>
     458            <listitem>
     459              <para>Default: SourceForge:
     460              <varname>${livecheck.name}</varname> ; GoogleCode: first
     461              ${distfiles} item</para>
     462            </listitem>
     463
     464            <listitem>
     465              <para>Values: <replaceable>filename</replaceable></para>
     466            </listitem>
     467
     468            <listitem>
     469              <para>Example:</para>
     470
     471              <programlisting>livecheck.distname  faad2.src</programlisting>
     472            </listitem>
     473          </itemizedlist>
     474        </listitem>
     475      </varlistentry>
     476
     477      <varlistentry>
     478        <term>livecheck.version</term>
     479
     480        <listitem>
     481          <para>Version of the project for a check; used for regex-based
     482          checks.</para>
     483
     484          <itemizedlist>
     485            <listitem>
     486              <para>Default: <varname>${version}</varname></para>
     487            </listitem>
     488
     489            <listitem>
     490              <para>Values: <replaceable>any_version</replaceable></para>
     491            </listitem>
     492
     493            <listitem>
     494              <para>Example:</para>
     495
     496              <programlisting>livecheck.version   ${name}-${version}</programlisting>
     497            </listitem>
     498          </itemizedlist>
     499        </listitem>
     500      </varlistentry>
     501
     502      <varlistentry>
     503        <term>livecheck.url</term>
     504
     505        <listitem>
     506          <para>URL to query for a check.</para>
     507
     508          <itemizedlist>
     509            <listitem>
     510              <para>Default:</para>
     511
     512              <itemizedlist>
     513                <listitem>
     514                  <para>homepage or the first hit among the following
     515                  sites</para>
     516                </listitem>
     517
     518                <listitem>
     519                  <para>http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml</para>
     520                </listitem>
     521
     522                <listitem>
     523                  <para>http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}</para>
     524                </listitem>
     525
     526                <listitem>
     527                  <para>http://code.google.com/p/${livecheck.name}/downloads/list</para>
     528                </listitem>
     529              </itemizedlist>
     530            </listitem>
     531
     532            <listitem>
     533              <para>Values: <replaceable>any_url</replaceable></para>
     534            </listitem>
     535
     536            <listitem>
     537              <para>Example:</para>
     538
     539              <programlisting>livecheck.url  http://ftp.gnu.org/gnu/bison/</programlisting>
     540            </listitem>
     541          </itemizedlist>
     542        </listitem>
     543      </varlistentry>
     544
     545      <varlistentry>
     546        <term>livecheck.regex</term>
     547
     548        <listitem>
     549          <para>Regular expression to parse the resource for regex checks.
     550          Be sure to use a regular expression grouping around the version
     551          component.</para>
     552
     553          <itemizedlist>
     554            <listitem>
     555              <para>Default: none</para>
     556            </listitem>
     557
     558            <listitem>
     559              <para>Values: <replaceable>any_regex</replaceable></para>
     560            </listitem>
     561
     562            <listitem>
     563              <para>Example:</para>
     564
     565              <programlisting>livecheck.regex  4th-([a-z0-9.]+)-unix.tar.gz</programlisting>
     566            </listitem>
     567          </itemizedlist>
     568        </listitem>
     569      </varlistentry>
     570
     571      <varlistentry>
     572        <term>livecheck.md5</term>
     573
     574        <listitem>
     575          <para>md5 checksum to use for an md5 comparison.</para>
     576
     577          <itemizedlist>
     578            <listitem>
     579              <para>Default: none</para>
     580            </listitem>
     581
     582            <listitem>
     583              <para>Values:
     584              <replaceable>any_md5_checksum</replaceable></para>
     585            </listitem>
     586
     587            <listitem>
     588              <para>Example:</para>
     589
     590              <programlisting>livecheck  md5 37e6a5b6516a680c7178b72021d3b706</programlisting>
     591            </listitem>
     592          </itemizedlist>
     593        </listitem>
     594      </varlistentry>
     595    </variablelist>
     596
     597    <para>Distcheck reports whether or not the distfile(s) specified in a
     598    Portfile are still available on the developer's download site. Examples
     599    are given below.</para>
     600
     601    <variablelist>
     602      <varlistentry>
     603        <term>distcheck.check</term>
     604
     605        <listitem>
     606          <para>This option can be used to disable distcheck. It specifies
     607          what kind of check should be performed on distfiles: moddate
     608          (check if the Portfile is older than the distfile) or none (no
     609          check).</para>
     610
     611          <itemizedlist>
     612            <listitem>
     613              <para>Default: moddate</para>
     614            </listitem>
     615
     616            <listitem>
     617              <para>Values: moddate none</para>
     618            </listitem>
     619
     620            <listitem>
     621              <para>Example:</para>
     622
     623              <programlisting>distcheck.check  none</programlisting>
     624            </listitem>
     625          </itemizedlist>
     626        </listitem>
     627      </varlistentry>
     628    </variablelist>
    630629  </section>
     630</section>
  • trunk/doc-new/guide/xml/portfile-global-variables.7.xml

    r31445 r31621  
    33"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
    44
    5   <section>
    6     <title>Global Variables</title>
     5<section>
     6  <title>Global Variables</title>
    77
    8     <para>Global variables are variables available to any Portfile. For a list
    9     of additional variables available to ports that are assigned to a MacPorts
    10     Portgroup, see portgroup(7).</para>
     8  <para>Global variables are variables available to any Portfile. For a list
     9  of additional variables available to ports that are assigned to a MacPorts
     10  Portgroup, see portgroup(7).</para>
    1111
    12     <variablelist>
    13       <varlistentry>
    14         <term>prefix</term>
     12  <variablelist>
     13    <varlistentry>
     14      <term>prefix</term>
    1515
    16         <listitem>
    17           <para>Installation prefix, set in
    18           <filename>${prefix}/etc/macports/macports.conf</filename> —may be
    19           overridden on a per port basis. For example, aqua applications are
    20           installed in <filename>/Applications/MacPorts</filename>.</para>
     16      <listitem>
     17        <para>Installation prefix, set in
     18        <filename>${prefix}/etc/macports/macports.conf</filename> —may be
     19        overridden on a per port basis. For example, aqua applications are
     20        installed in <filename>/Applications/MacPorts</filename>.</para>
    2121
    22           <para>Default: /opt/local</para>
    23         </listitem>
    24       </varlistentry>
     22        <para>Default: /opt/local</para>
     23      </listitem>
     24    </varlistentry>
    2525
    26       <varlistentry>
    27         <term>binpath</term>
     26    <varlistentry>
     27      <term>binpath</term>
    2828
    29         <listitem>
    30           <para>Default PATH to use in finding executables.</para>
    31         </listitem>
    32       </varlistentry>
     29      <listitem>
     30        <para>Default PATH to use in finding executables.</para>
     31      </listitem>
     32    </varlistentry>
    3333
    34       <varlistentry>
    35         <term>libpath</term>
     34    <varlistentry>
     35      <term>libpath</term>
    3636
    37         <listitem>
    38           <para>Path to the MacPorts TCL libraries.</para>
    39         </listitem>
    40       </varlistentry>
     37      <listitem>
     38        <para>Path to the MacPorts TCL libraries.</para>
     39      </listitem>
     40    </varlistentry>
    4141
    42       <varlistentry>
    43         <term>portpath</term>
     42    <varlistentry>
     43      <term>portpath</term>
    4444
    45         <listitem>
    46           <para>Full path to the Portfile location.</para>
    47         </listitem>
    48       </varlistentry>
     45      <listitem>
     46        <para>Full path to the Portfile location.</para>
     47      </listitem>
     48    </varlistentry>
    4949
    50       <varlistentry>
    51         <term>filesdir</term>
     50    <varlistentry>
     51      <term>filesdir</term>
    5252
    53         <listitem>
    54           <para>Path to port files relative to
    55           <varname>${portpath}</varname>.</para>
    56         </listitem>
    57       </varlistentry>
     53      <listitem>
     54        <para>Path to port files relative to
     55        <varname>${portpath}</varname>.</para>
     56      </listitem>
     57    </varlistentry>
    5858
    59       <varlistentry>
    60         <term>workpath</term>
     59    <varlistentry>
     60      <term>workpath</term>
    6161
    62         <listitem>
    63           <para>Full path to work directory.</para>
    64         </listitem>
    65       </varlistentry>
     62      <listitem>
     63        <para>Full path to work directory.</para>
     64      </listitem>
     65    </varlistentry>
    6666
    67       <varlistentry>
    68         <term>worksrcpath</term>
     67    <varlistentry>
     68      <term>worksrcpath</term>
    6969
    70         <listitem>
    71           <para>Full path to extracted source code. Equivalent to
    72           <varname>${workpath}/${worksrcdir}</varname>.</para>
    73         </listitem>
    74       </varlistentry>
     70      <listitem>
     71        <para>Full path to extracted source code. Equivalent to
     72        <varname>${workpath}/${worksrcdir}</varname>.</para>
     73      </listitem>
     74    </varlistentry>
    7575
    76       <varlistentry>
    77         <term>destroot</term>
     76    <varlistentry>
     77      <term>destroot</term>
    7878
    79         <listitem>
    80           <para>Full path into which software will be destrooted. Equivalent
    81           to <filename>${workpath}/destroot</filename>.</para>
    82         </listitem>
    83       </varlistentry>
     79      <listitem>
     80        <para>Full path into which software will be destrooted. Equivalent
     81        to <filename>${workpath}/destroot</filename>.</para>
     82      </listitem>
     83    </varlistentry>
    8484
    85       <varlistentry>
    86         <term>distpath</term>
     85    <varlistentry>
     86      <term>distpath</term>
    8787
    88         <listitem>
    89           <para>Location to store downloaded distfiles.</para>
    90         </listitem>
    91       </varlistentry>
     88      <listitem>
     89        <para>Location to store downloaded distfiles.</para>
     90      </listitem>
     91    </varlistentry>
    9292
    93       <varlistentry>
    94         <term>install.user</term>
     93    <varlistentry>
     94      <term>install.user</term>
    9595
    96         <listitem>
    97           <para>The Unix user at the time of port installation.</para>
    98         </listitem>
    99       </varlistentry>
     96      <listitem>
     97        <para>The Unix user at the time of port installation.</para>
     98      </listitem>
     99    </varlistentry>
    100100
    101       <varlistentry>
    102         <term>install.group</term>
     101    <varlistentry>
     102      <term>install.group</term>
    103103
    104         <listitem>
    105           <para>The Unix group at the time of port installation.</para>
    106         </listitem>
    107       </varlistentry>
     104      <listitem>
     105        <para>The Unix group at the time of port installation.</para>
     106      </listitem>
     107    </varlistentry>
    108108
    109       <varlistentry>
    110         <term>os.platform</term>
     109    <varlistentry>
     110      <term>os.platform</term>
    111111
    112         <listitem>
    113           <para>Identifies platform type (ie, "darwin", "freebsd",
    114           etc).</para>
    115         </listitem>
    116       </varlistentry>
     112      <listitem>
     113        <para>Identifies platform type (ie, "darwin", "freebsd",
     114        etc).</para>
     115      </listitem>
     116    </varlistentry>
    117117
    118       <varlistentry>
    119         <term>os.arch</term>
     118    <varlistentry>
     119      <term>os.arch</term>
    120120
    121         <listitem>
    122           <para>Identifies hardware type (ie, "powerpc", "intel").</para>
    123         </listitem>
    124       </varlistentry>
     121      <listitem>
     122        <para>Identifies hardware type (ie, "powerpc", "intel").</para>
     123      </listitem>
     124    </varlistentry>
    125125
    126       <varlistentry>
    127         <term>os.version</term>
     126    <varlistentry>
     127      <term>os.version</term>
    128128
    129         <listitem>
    130           <para>The version number of the host operating system (ie "8.0" for
    131           Darwin 8.0).</para>
    132         </listitem>
    133       </varlistentry>
     129      <listitem>
     130        <para>The version number of the host operating system (ie "8.0" for
     131        Darwin 8.0).</para>
     132      </listitem>
     133    </varlistentry>
    134134
    135       <varlistentry>
    136         <term>os.major</term>
     135    <varlistentry>
     136      <term>os.major</term>
    137137
    138         <listitem>
    139           <para>The major version number of the host operating system (ie "8"
    140           for Darwin 8.0).</para>
    141         </listitem>
    142       </varlistentry>
    143     </variablelist>
    144   </section>
     138      <listitem>
     139        <para>The major version number of the host operating system (ie "8"
     140        for Darwin 8.0).</para>
     141      </listitem>
     142    </varlistentry>
     143  </variablelist>
     144</section>
  • trunk/doc-new/guide/xml/portfile-phase.7.xml

    r31445 r31621  
    33"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
    44
    5   <section>
    6     <title>Port Phases</title>
     5<section>
     6  <title>Port Phases</title>
    77
    88  <section>
     
    123123  </section>
    124124
     125  <section>
     126    <title>Fetch Phase Keywords</title>
     127
     128    <para>The list of keywords related to the fetch phase.</para>
     129
     130    <variablelist>
     131      <varlistentry>
     132        <term>master_sites</term>
     133
     134        <listitem>
     135          <para>A list of URLs from which a port's download file(s) may be
     136          retrieved. For multiple master_sites, they are searched in order
     137          until a file matching <varname>${distfile}</varname> is
     138          found.</para>
     139
     140          <itemizedlist>
     141            <listitem>
     142              <para>Default: ???</para>
     143            </listitem>
     144
     145            <listitem>
     146              <para>Examples:</para>
     147
     148              <programlisting>master_sites   http://www.somesite.org/files/ \
     149               http://www.somemirror.org/somesite_org/files/
     150
     151</programlisting>
     152
     153              <para>You may also use mirror site lists predefined by
     154              MacPorts. Here the sourceforge and gnu mirrors are
     155              used.</para>
     156
     157              <programlisting>master_sites   sourceforge gnu
     158
     159</programlisting>
     160
     161              <para>When using mirror master_sites, the subdirectory
     162              <varname>${name}</varname> is checked on every mirror. If the
     163              mirror subdirectory does not match ${name}, then you may
     164              specify it using after the mirror separated by a colon.</para>
     165
     166              <programlisting>master_sites   sourceforge:widget \
     167               gnu:widget
     168
     169</programlisting>
     170
     171              <para>For ports that must fetch multiple download files from
     172              different locations, you must label the files with tags and
     173              match the tags in a distfiles statement. The format is
     174              <literal>mirror:subdirectory:tag</literal>.</para>
     175
     176              <para>In the example below, file_one.tar.gz is fetched from
     177              sourceforge mirrors in subdirectory
     178              <varname>${name}</varname>; file tagtwo.tar.gz is fetched from
     179              the gnu mirrors in subdirectory sources.</para>
     180
     181              <programlisting>master_sites    sourceforge::tagone \
     182                gnu:sources:tagtwo
     183
     184distfiles       file_one.tar.gz:tagone \
     185                file_two.tar.gz:tagtwo</programlisting>
     186            </listitem>
     187          </itemizedlist>
     188        </listitem>
     189      </varlistentry>
     190
     191      <varlistentry>
     192        <term>patch_sites</term>
     193
     194        <listitem>
     195          <para>A list of sites from which a port's patchfiles may be
     196          downloaded, where applicable.</para>
     197
     198          <itemizedlist>
     199            <listitem>
     200              <para>Default: <varname>${master_sites}</varname></para>
     201            </listitem>
     202
     203            <listitem>
     204              <para>Example:</para>
     205
     206              <programlisting>patch_sites    ftp://ftp.patchcityrepo.com/pub/magic/patches</programlisting>
     207            </listitem>
     208          </itemizedlist>
     209        </listitem>
     210      </varlistentry>
     211
     212      <varlistentry>
     213        <term>distname</term>
     214
     215        <listitem>
     216          <para>The name of the distribution filename, not including the
     217          extract suffix.</para>
     218
     219          <itemizedlist>
     220            <listitem>
     221              <para>Default: <varname>${name}-${version}</varname></para>
     222            </listitem>
     223
     224            <listitem>
     225              <para>Example:</para>
     226
     227              <programlisting>distname     ${name}</programlisting>
     228            </listitem>
     229          </itemizedlist>
     230        </listitem>
     231      </varlistentry>
     232
     233      <varlistentry>
     234        <term>distfiles</term>
     235
     236        <listitem>
     237          <para>The full distribution filename, including the extract
     238          suffix. Used to specify non-default distribution filenames; this
     239          keyword must be specified (and tags used) when a port has multiple
     240          download files (see master_sites).</para>
     241
     242          <itemizedlist>
     243            <listitem>
     244              <para>Default:
     245              <varname>${distname}${extract.suffix}</varname></para>
     246            </listitem>
     247
     248            <listitem>
     249              <para>Example:</para>
     250
     251              <programlisting>distfiles    ${name}-dev_src.tgz
     252
     253
     254distfiles       file_one.tar.gz:tagone \
     255                file_two.tar.gz:tagtwo</programlisting>
     256            </listitem>
     257          </itemizedlist>
     258        </listitem>
     259      </varlistentry>
     260
     261      <varlistentry>
     262        <term>extract.suffix</term>
     263
     264        <listitem>
     265          <para>This keyword is used to specify the extract suffix
     266          type.</para>
     267
     268          <itemizedlist>
     269            <listitem>
     270              <para>Default: <filename>.tar.gz</filename></para>
     271            </listitem>
     272
     273            <listitem>
     274              <para>Example:</para>
     275
     276              <programlisting>extract.suffix   .tgz</programlisting>
     277            </listitem>
     278          </itemizedlist>
     279        </listitem>
     280      </varlistentry>
     281
     282      <varlistentry>
     283        <term>extract.mkdir</term>
     284
     285        <listitem>
     286          <para>This option is used to specify if the directory
     287          <filename>worksrcdir</filename> is part of the distfile or if it
     288          should be created automatically and the distfiles should be
     289          extracted there instead. This is useful for distfiles with a flat
     290          structure which would pollute the <filename>worksrcdir</filename>
     291          with lots of files.</para>
     292
     293          <itemizedlist>
     294            <listitem>
     295              <para>Default: <option>no</option></para>
     296            </listitem>
     297
     298            <listitem>
     299              <para>Example:</para>
     300
     301              <programlisting>extract.mkdir   yes</programlisting>
     302            </listitem>
     303          </itemizedlist>
     304        </listitem>
     305      </varlistentry>
     306
     307      <varlistentry>
     308        <term>use_bzip2</term>
     309
     310        <listitem>
     311          <para>This keyword is for downloads that are tarred and bzipped.
     312          When invoked, it automatically sets:</para>
     313
     314          <literallayout>extract.suffix = .tar.bz
     315extract.cmd = bzip
     316
     317</literallayout>
     318
     319          <itemizedlist>
     320            <listitem>
     321              <para>Default: <option>no</option></para>
     322            </listitem>
     323
     324            <listitem>
     325              <para>Example:</para>
     326
     327              <programlisting>use_bzip2     yes</programlisting>
     328            </listitem>
     329          </itemizedlist>
     330        </listitem>
     331      </varlistentry>
     332
     333      <varlistentry>
     334        <term>use_zip</term>
     335
     336        <listitem>
     337          <para>This keyword is for downloads are zipped. When invoked, it
     338          automatically sets:</para>
     339
     340          <literallayout>extract.suffix = .zip
     341extract.cmd = unzip
     342extract.pre_args = -q
     343extract.post_args = "-d ${portpath}/${workdir}"
     344
     345</literallayout>
     346
     347          <itemizedlist>
     348            <listitem>
     349              <para>Default: <option>no</option></para>
     350            </listitem>
     351
     352            <listitem>
     353              <para>Example:</para>
     354
     355              <programlisting>use_zip       yes</programlisting>
     356            </listitem>
     357          </itemizedlist>
     358        </listitem>
     359      </varlistentry>
     360    </variablelist>
     361
    125362    <section>
    126       <title>Fetch Phase Keywords</title>
    127 
    128       <para>The list of keywords related to the fetch phase.</para>
     363      <title>Fetch from CVS</title>
     364
     365      <para><ulink url="http://www.nongnu.org/cvs/">CVS</ulink> may be used
     366      as an alternative method of fetching distribution files using the
     367      keywords in this section. However, fetching via CVS may cause
     368      non-reproducible builds, so it is strongly discouraged.</para>
    129369
    130370      <variablelist>
    131371        <varlistentry>
    132           <term>master_sites</term>
     372          <term>cvs.root</term>
    133373
    134374          <listitem>
    135             <para>A list of URLs from which a port's download file(s) may be
    136             retrieved. For multiple master_sites, they are searched in order
    137             until a file matching <varname>${distfile}</varname> is
    138             found.</para>
     375            <para>Specify the url from which to fetch files.</para>
    139376
    140377            <itemizedlist>
    141378              <listitem>
    142                 <para>Default: ???</para>
    143               </listitem>
    144 
    145               <listitem>
    146                 <para>Examples:</para>
    147 
    148                 <programlisting>master_sites   http://www.somesite.org/files/ \
    149                http://www.somemirror.org/somesite_org/files/
    150 
    151 </programlisting>
    152 
    153                 <para>You may also use mirror site lists predefined by
    154                 MacPorts. Here the sourceforge and gnu mirrors are
    155                 used.</para>
    156 
    157                 <programlisting>master_sites   sourceforge gnu
    158 
    159 </programlisting>
    160 
    161                 <para>When using mirror master_sites, the subdirectory
    162                 <varname>${name}</varname> is checked on every mirror. If the
    163                 mirror subdirectory does not match ${name}, then you may
    164                 specify it using after the mirror separated by a colon.</para>
    165 
    166                 <programlisting>master_sites   sourceforge:widget \
    167                gnu:widget
    168 
    169 </programlisting>
    170 
    171                 <para>For ports that must fetch multiple download files from
    172                 different locations, you must label the files with tags and
    173                 match the tags in a distfiles statement. The format is
    174                 <literal>mirror:subdirectory:tag</literal>.</para>
    175 
    176                 <para>In the example below, file_one.tar.gz is fetched from
    177                 sourceforge mirrors in subdirectory
    178                 <varname>${name}</varname>; file tagtwo.tar.gz is fetched from
    179                 the gnu mirrors in subdirectory sources.</para>
    180 
    181                 <programlisting>master_sites    sourceforge::tagone \
    182                 gnu:sources:tagtwo
    183 
    184 distfiles       file_one.tar.gz:tagone \
    185                 file_two.tar.gz:tagtwo</programlisting>
     379                <para>Default: none</para>
     380              </listitem>
     381
     382              <listitem>
     383                <para>Example:</para>
     384
     385                <programlisting>cvs.root :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs</programlisting>
    186386              </listitem>
    187387            </itemizedlist>
     
    190390
    191391        <varlistentry>
    192           <term>patch_sites</term>
     392          <term>cvs.tag</term>
    193393
    194394          <listitem>
    195             <para>A list of sites from which a port's patchfiles may be
    196             downloaded, where applicable.</para>
     395            <para>Optional for fetching with CVS, this specifies the code
     396            revision to checkout.</para>
    197397
    198398            <itemizedlist>
    199399              <listitem>
    200                 <para>Default: <varname>${master_sites}</varname></para>
     400                <para>Default: none</para>
    201401              </listitem>
    202402
     
    204404                <para>Example:</para>
    205405
    206                 <programlisting>patch_sites    ftp://ftp.patchcityrepo.com/pub/magic/patches</programlisting>
     406                <programlisting>cvs.tag  HEAD</programlisting>
    207407              </listitem>
    208408            </itemizedlist>
     
    211411
    212412        <varlistentry>
    213           <term>distname</term>
     413          <term>cvs.date</term>
    214414
    215415          <listitem>
    216             <para>The name of the distribution filename, not including the
    217             extract suffix.</para>
     416            <para>A date that identifies the CVS code set to
     417            checkout.</para>
    218418
    219419            <itemizedlist>
    220420              <listitem>
    221                 <para>Default: <varname>${name}-${version}</varname></para>
     421                <para>Default: none</para>
    222422              </listitem>
    223423
     
    225425                <para>Example:</para>
    226426
    227                 <programlisting>distname     ${name}</programlisting>
     427                <programlisting>cvs.date "12-April-2007"</programlisting>
    228428              </listitem>
    229429            </itemizedlist>
     
    232432
    233433        <varlistentry>
    234           <term>distfiles</term>
     434          <term>cvs.module</term>
    235435
    236436          <listitem>
    237             <para>The full distribution filename, including the extract
    238             suffix. Used to specify non-default distribution filenames; this
    239             keyword must be specified (and tags used) when a port has multiple
    240             download files (see master_sites).</para>
     437            <para>A CVS module from which to check out the code.</para>
    241438
    242439            <itemizedlist>
    243440              <listitem>
    244                 <para>Default:
    245                 <varname>${distname}${extract.suffix}</varname></para>
     441                <para>Default: none</para>
    246442              </listitem>
    247443
     
    249445                <para>Example:</para>
    250446
    251                 <programlisting>distfiles    ${name}-dev_src.tgz
    252 
    253 
    254 distfiles       file_one.tar.gz:tagone \
    255                 file_two.tar.gz:tagtwo</programlisting>
    256               </listitem>
    257             </itemizedlist>
    258           </listitem>
    259         </varlistentry>
    260 
    261         <varlistentry>
    262           <term>extract.suffix</term>
    263 
    264           <listitem>
    265             <para>This keyword is used to specify the extract suffix
    266             type.</para>
    267 
    268             <itemizedlist>
    269               <listitem>
    270                 <para>Default: <filename>.tar.gz</filename></para>
    271               </listitem>
    272 
    273               <listitem>
    274                 <para>Example:</para>
    275 
    276                 <programlisting>extract.suffix   .tgz</programlisting>
    277               </listitem>
    278             </itemizedlist>
    279           </listitem>
    280         </varlistentry>
    281 
    282         <varlistentry>
    283           <term>extract.mkdir</term>
    284 
    285           <listitem>
    286             <para>This option is used to specify if the directory
    287             <filename>worksrcdir</filename> is part of the distfile or if it
    288             should be created automatically and the distfiles should be
    289             extracted there instead. This is useful for distfiles with a flat
    290             structure which would pollute the <filename>worksrcdir</filename>
    291             with lots of files.</para>
    292 
    293             <itemizedlist>
    294               <listitem>
    295                 <para>Default: <option>no</option></para>
    296               </listitem>
    297 
    298               <listitem>
    299                 <para>Example:</para>
    300 
    301                 <programlisting>extract.mkdir   yes</programlisting>
    302               </listitem>
    303             </itemizedlist>
    304           </listitem>
    305         </varlistentry>
    306 
    307         <varlistentry>
    308           <term>use_bzip2</term>
    309 
    310           <listitem>
    311             <para>This keyword is for downloads that are tarred and bzipped.
    312             When invoked, it automatically sets:</para>
    313 
    314             <literallayout>extract.suffix = .tar.bz
    315 extract.cmd = bzip
    316 
    317 </literallayout>
    318 
    319             <itemizedlist>
    320               <listitem>
    321                 <para>Default: <option>no</option></para>
    322               </listitem>
    323 
    324               <listitem>
    325                 <para>Example:</para>
    326 
    327                 <programlisting>use_bzip2     yes</programlisting>
    328               </listitem>
    329             </itemizedlist>
    330           </listitem>
    331         </varlistentry>
    332 
    333         <varlistentry>
    334           <term>use_zip</term>
    335 
    336           <listitem>
    337             <para>This keyword is for downloads are zipped. When invoked, it
    338             automatically sets:</para>
    339 
    340             <literallayout>extract.suffix = .zip
    341 extract.cmd = unzip
    342 extract.pre_args = -q
    343 extract.post_args = "-d ${portpath}/${workdir}"
    344 
    345 </literallayout>
    346 
    347             <itemizedlist>
    348               <listitem>
    349                 <para>Default: <option>no</option></para>
    350               </listitem>
    351 
    352               <listitem>
    353                 <para>Example:</para>
    354 
    355                 <programlisting>use_zip       yes</programlisting>
     447                <programlisting>cvs.module  Sources</programlisting>
    356448              </listitem>
    357449            </itemizedlist>
     
    359451        </varlistentry>
    360452      </variablelist>
    361 
    362       <section>
    363         <title>Fetch from CVS</title>
    364 
    365         <para><ulink url="http://www.nongnu.org/cvs/">CVS</ulink> may be used
    366         as an alternative method of fetching distribution files using the
    367         keywords in this section. However, fetching via CVS may cause
    368         non-reproducible builds, so it is strongly discouraged.</para>
    369 
    370         <variablelist>
    371           <varlistentry>
    372             <term>cvs.root</term>
    373 
    374             <listitem>
    375               <para>Specify the url from which to fetch files.</para>
    376 
    377               <itemizedlist>
    378                 <listitem>
    379                   <para>Default: none</para>
    380                 </listitem>
    381 
    382                 <listitem>
    383                   <para>Example:</para>
    384 
    385                   <programlisting>cvs.root :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs</programlisting>
    386                 </listitem>
    387               </itemizedlist>
    388             </listitem>
    389           </varlistentry>
    390 
    391           <varlistentry>
    392             <term>cvs.tag</term>
    393 
    394             <listitem>
    395               <para>Optional for fetching with CVS, this specifies the code
    396               revision to checkout.</para>
    397 
    398               <itemizedlist>
    399                 <listitem>
    400                   <para>Default: none</para>
    401                 </listitem>
    402 
    403                 <listitem>
    404                   <para>Example:</para>
    405 
    406                   <programlisting>cvs.tag  HEAD</programlisting>
    407                 </listitem>
    408               </itemizedlist>
    409             </listitem>
    410           </varlistentry>
    411 
    412           <varlistentry>
    413             <term>cvs.date</term>
    414 
    415             <listitem>
    416               <para>A date that identifies the CVS code set to
    417               checkout.</para>
    418 
    419               <itemizedlist>
    420                 <listitem>
    421                   <para>Default: none</para>
    422                 </listitem>
    423 
    424                 <listitem>
    425                   <para>Example:</para>
    426 
    427                   <programlisting>cvs.date "12-April-2007"</programlisting>
    428                 </listitem>
    429               </itemizedlist>
    430             </listitem>
    431           </varlistentry>
    432 
    433           <varlistentry>
    434             <term>cvs.module</term>
    435 
    436             <listitem>
    437               <para>A CVS module from which to check out the code.</para>
    438 
    439               <itemizedlist>
    440                 <listitem>
    441                   <para>Default: none</para>
    442                 </listitem>
    443 
    444                 <listitem>
    445                   <para>Example:</para>
    446 
    447                   <programlisting>cvs.module  Sources</programlisting>
    448                 </listitem>
    449               </itemizedlist>
    450             </listitem>
    451           </varlistentry>
    452         </variablelist>
    453       </section>
    454 
    455       <section>
    456         <title>Fetch from Subversion</title>
    457 
    458         <para><ulink url="http://subversion.tigris.org/">Subversion</ulink>
    459         may be used as an alternative method of fetching distribution files
    460         using the keywords in this section. However, fetching via Subversion
    461         may cause non-reproducible builds, so it is strongly
    462         discouraged.</para>
    463 
    464         <variablelist>
    465           <varlistentry>
    466             <term>svn.url</term>
    467 
    468             <listitem>
    469               <para>This specifies the url from which to fetch files.</para>
    470 
    471               <itemizedlist>
    472                 <listitem>
    473                   <para>Default: none</para>
    474                 </listitem>
    475 
    476                 <listitem>
    477                   <para>Examples:</para>
    478 
    479                   <programlisting>svn.url http://www.domain.com/svn-repo/mydirectory
    480 svn.url svn://www.domain.com/svn-repo/mydirectory
    481 </programlisting>
    482                 </listitem>
    483               </itemizedlist>
    484             </listitem>
    485           </varlistentry>
    486 
    487           <varlistentry>
    488             <term>svn.tag</term>
    489 
    490             <listitem>
    491               <para>Optional tag for fetching with Subversion, this specifies
    492               the code revision to checkout; it corresponds to the -r option
    493               in the svn cli. You must use backslashes to escape characters
    494               that are meaningful to the Tcl interpreter, such as braces and
    495               double quotes.</para>
    496 
    497               <itemizedlist>
    498                 <listitem>
    499                   <para>Default: none</para>
    500                 </listitem>
    501 
    502                 <listitem>
    503                   <para>Examples:</para>
    504 
    505                   <programlisting>svn.tag 37192
    506 svn.tag \{\"2006-02-17 15:30 +0230\"\}</programlisting>
    507                 </listitem>
    508               </itemizedlist>
    509             </listitem>
    510           </varlistentry>
    511         </variablelist>
    512       </section>
    513453    </section>
    514454
    515455    <section>
    516       <title>Checksum Phase Keywords</title>
    517 
    518       <para>The list of keywords related to the checksum phase.</para>
     456      <title>Fetch from Subversion</title>
     457
     458      <para><ulink url="http://subversion.tigris.org/">Subversion</ulink>
     459      may be used as an alternative method of fetching distribution files
     460      using the keywords in this section. However, fetching via Subversion
     461      may cause non-reproducible builds, so it is strongly
     462      discouraged.</para>
    519463
    520464      <variablelist>
    521465        <varlistentry>
    522           <term>checksums</term>
     466          <term>svn.url</term>
    523467
    524468          <listitem>
    525             <para>Checksum(s) of the distribution files. For ports with
    526             multiple distribution files, filenames must be included to
    527             associate files with their checksums.</para>
     469            <para>This specifies the url from which to fetch files.</para>
    528470
    529471            <itemizedlist>
    530472              <listitem>
    531                 <para>Default: ???</para>
     473                <para>Default: none</para>
    532474              </listitem>
    533475
     
    535477                <para>Examples:</para>
    536478
    537                 <programlisting>checksums     md5 dafa161bc9c61e57636a6085c87c1fe8 \
     479                <programlisting>svn.url http://www.domain.com/svn-repo/mydirectory
     480svn.url svn://www.domain.com/svn-repo/mydirectory
     481</programlisting>
     482              </listitem>
     483            </itemizedlist>
     484          </listitem>
     485        </varlistentry>
     486
     487        <varlistentry>
     488          <term>svn.tag</term>
     489
     490          <listitem>
     491            <para>Optional tag for fetching with Subversion, this specifies
     492            the code revision to checkout; it corresponds to the -r option
     493            in the svn cli. You must use backslashes to escape characters
     494            that are meaningful to the Tcl interpreter, such as braces and
     495            double quotes.</para>
     496
     497            <itemizedlist>
     498              <listitem>
     499                <para>Default: none</para>
     500              </listitem>
     501
     502              <listitem>
     503                <para>Examples:</para>
     504
     505                <programlisting>svn.tag 37192
     506svn.tag \{\"2006-02-17 15:30 +0230\"\}</programlisting>
     507              </listitem>
     508            </itemizedlist>
     509          </listitem>
     510        </varlistentry>
     511      </variablelist>
     512    </section>
     513  </section>
     514
     515  <section>
     516    <title>Checksum Phase Keywords</title>
     517
     518    <para>The list of keywords related to the checksum phase.</para>
     519
     520    <variablelist>
     521      <varlistentry>
     522        <term>checksums</term>
     523
     524        <listitem>
     525          <para>Checksum(s) of the distribution files. For ports with
     526          multiple distribution files, filenames must be included to
     527          associate files with their checksums.</para>
     528
     529          <itemizedlist>
     530            <listitem>
     531              <para>Default: ???</para>
     532            </listitem>
     533
     534            <listitem>
     535              <para>Examples:</para>
     536
     537              <programlisting>checksums     md5 dafa161bc9c61e57636a6085c87c1fe8 \
    538538              sha1 5da610e1c8bc01b80abc21ab9e98e004363b429c \
    539539              rmd160 0c1147242adf476f5e93f4d59b553ee3ea378b23</programlisting>
    540540
    541                 <programlisting>checksums     ${distname}${extract.suffix} md5 dafa161bc9c61e57636a6085c87c1fe8 \
     541              <programlisting>checksums     ${distname}${extract.suffix} md5 dafa161bc9c61e57636a6085c87c1fe8 \
    542542                  sha1 5da610e1c8bc01b80abc21ab9e98e004363b429c \
    543543                  rmd160 0c1147242adf476f5e93f4d59b553ee3ea378b23 \
     
    545545                  sha1 27874638b23e66d39ed94fe716ca25c967f6e993 \
    546546                  rmd160 82b9991f3bf0ceedbf74c188c5fa44b98b5e40c9</programlisting>
     547            </listitem>
     548          </itemizedlist>
     549        </listitem>
     550      </varlistentry>
     551    </variablelist>
     552  </section>
     553
     554  <section>
     555    <title>Extract Phase Keywords</title>
     556
     557    <para>The list of keywords related to the extract phase.</para>
     558
     559    <variablelist>
     560      <varlistentry>
     561        <term>extract.only</term>
     562
     563        <term>extract.only-append</term>
     564
     565        <term>extract.only-delete</term>
     566
     567        <listitem>
     568          <para>List of files to extract into
     569          <varname>${worksrcpath}</varname>; the default is
     570          <varname>${distfiles}</varname>. Only use if default extract
     571          behavior is not correct for your port.</para>
     572
     573          <itemizedlist>
     574            <listitem>
     575              <para>Default: none</para>
     576            </listitem>
     577
     578            <listitem>
     579              <para>Example:</para>
     580
     581              <programlisting>extract.only     foo.tar.gz
     582
     583</programlisting>
     584            </listitem>
     585          </itemizedlist>
     586        </listitem>
     587
     588        <listitem>
     589          <para>List modifier examples:</para>
     590
     591          <programlisting>extract.only-append  bar.tar.gz
     592extract.only-delete  foo.tar.gz</programlisting>
     593        </listitem>
     594      </varlistentry>
     595
     596      <varlistentry>
     597        <term>extract.cmd</term>
     598
     599        <listitem>
     600          <para>Command to perform extraction.</para>
     601
     602          <itemizedlist>
     603            <listitem>
     604              <para>Default: gzip</para>
     605            </listitem>
     606
     607            <listitem>
     608              <para>Example:</para>
     609
     610              <programlisting>extract.cmd     gunzip</programlisting>
     611            </listitem>
     612          </itemizedlist>
     613        </listitem>
     614      </varlistentry>
     615
     616      <varlistentry>
     617        <term>extract.args</term>
     618
     619        <term>extract.pre_args</term>
     620
     621        <term>extract.post_args</term>
     622
     623        <listitem>
     624          <para>Main arguments to extract.cmd; additional arguments passed
     625          before and after the main arguments.</para>
     626
     627          <itemizedlist>
     628            <listitem>
     629              <para>Default: ${distpath}/${distfile}</para>
     630            </listitem>
     631
     632            <listitem>
     633              <para>Example:</para>
     634
     635              <programlisting>extract.args      ${distpath}/${distfile}
     636
     637</programlisting>
     638            </listitem>
     639          </itemizedlist>
     640        </listitem>
     641
     642        <listitem>
     643          <para>The following argument modifiers are available:</para>
     644
     645          <itemizedlist>
     646            <listitem>
     647              <para>extract.pre_args default: "-dc"</para>
     648            </listitem>
     649
     650            <listitem>
     651              <para>extract.post_args default: " | tar -xf"</para>
     652            </listitem>
     653
     654            <listitem>
     655              <para>Examples:</para>
     656
     657              <programlisting>extract.pre_args     xf
     658extract.post_args    "| gnutar –x"</programlisting>
     659            </listitem>
     660          </itemizedlist>
     661        </listitem>
     662      </varlistentry>
     663    </variablelist>
     664  </section>
     665
     666  <section>
     667    <title>Patch Phase Keywords</title>
     668
     669    <para>The list of keywords related to the patch phase.</para>
     670
     671    <variablelist>
     672      <varlistentry>
     673        <term>patch.dir</term>
     674
     675        <listitem>
     676          <para>Specify the base path for patch files.</para>
     677
     678          <itemizedlist>
     679            <listitem>
     680              <para>Default: <varname>${worksrcpath}</varname></para>
     681            </listitem>
     682
     683            <listitem>
     684              <para>Example:</para>
     685
     686              <programlisting>patch.dir      ${worksrcpath}/util</programlisting>
     687            </listitem>
     688          </itemizedlist>
     689        </listitem>
     690      </varlistentry>
     691
     692      <varlistentry>
     693        <term>patch.cmd</term>
     694
     695        <listitem>
     696          <para>Specify the command to be used for patching files.</para>
     697
     698          <itemizedlist>
     699            <listitem>
     700              <para>Default: <command>patch</command></para>
     701            </listitem>
     702
     703            <listitem>
     704              <para>Example:</para>
     705
     706              <programlisting>patch.cmd      cat</programlisting>
     707            </listitem>
     708          </itemizedlist>
     709        </listitem>
     710      </varlistentry>
     711
     712      <varlistentry>
     713        <term>patchfiles</term>
     714
     715        <term>patchfiles-append</term>
     716
     717        <term>patchfiles-delete</term>
     718
     719        <listitem>
     720          <para>Specify patch files to be applied for a port; list modifiers
     721          specify patchfiles to be added or removed from a previous
     722          patchfile declaration.</para>
     723
     724          <itemizedlist>
     725            <listitem>
     726              <para>Default: none</para>
     727            </listitem>
     728
     729            <listitem>
     730              <para>Example:</para>
     731
     732              <programlisting>patchfiles     patch-Makefile.in \
     733               patch-source.c
     734
     735</programlisting>
     736            </listitem>
     737          </itemizedlist>
     738        </listitem>
     739
     740        <listitem>
     741          <para>List modifier examples:</para>
     742
     743          <programlisting>patchfiles-append   patch-configure
     744patchfiles-delete   patch-src-Makefile.in
     745</programlisting>
     746        </listitem>
     747      </varlistentry>
     748
     749      <varlistentry>
     750        <term>patch.args</term>
     751
     752        <term>patch.pre_args</term>
     753
     754        <term>patch.post_args</term>
     755
     756        <listitem>
     757          <para>Main arguments to patch.cmd; optional argument modifiers
     758          pass arguments before and after the main arguments.</para>
     759
     760          <itemizedlist>
     761            <listitem>
     762              <para>Default: none</para>
     763            </listitem>
     764
     765            <listitem>
     766              <para>Example:</para>
     767
     768              <programlisting>patch.args   ???
     769
     770</programlisting>
     771            </listitem>
     772          </itemizedlist>
     773        </listitem>
     774
     775        <listitem>
     776          <para>The following argument modifiers are available:</para>
     777
     778          <itemizedlist>
     779            <listitem>
     780              <para>patch.pre_args default: -p0</para>
     781            </listitem>
     782
     783            <listitem>
     784              <para>patch.post_args default: none</para>
     785            </listitem>
     786
     787            <listitem>
     788              <para>Examples:</para>
     789
     790              <programlisting>patch.pre_args     -p1
     791patch.post_args    ???</programlisting>
     792            </listitem>
     793          </itemizedlist>
     794        </listitem>
     795      </varlistentry>
     796    </variablelist>
     797  </section>
     798
     799  <section>
     800    <title>Configure Phase Keywords</title>
     801
     802    <para>The list of keywords related to the configure phase.</para>
     803
     804    <para>MacPorts base sets some important default configure options, so
     805    should use the -append version of most configure keywords so you don't
     806    overwrite them. For example, MacPorts base sets default
     807    <literal>configure.cflags</literal> so you should always use
     808    <literal>configure.cflags-append</literal> to set additional CFLAGS in
     809    Portfiles.</para>
     810
     811    <variablelist>
     812      <varlistentry>
     813        <term>configure.env</term>
     814
     815        <term>configure.env-append</term>
     816
     817        <term>configure.env-delete</term>
     818
     819        <listitem>
     820          <para>Set environment variables for configure; list modifiers add
     821          and delete items from a previous Portfile configure.env keyword,
     822          or a default set by MacPorts base. If available, it is encouraged
     823          to use the predefined options (like configure.cflags) instead of
     824          modifying configure.env directly</para>
     825
     826          <itemizedlist>
     827            <listitem>
     828              <para>Default: <literal>CFLAGS=-I${prefix}/include
     829              LDFLAGS=-L${prefix}/lib</literal></para>
     830            </listitem>
     831
     832            <listitem>
     833              <para>Example:</para>
     834
     835              <programlisting>configure.env   QTDIR=${prefix}/lib/qt3
     836</programlisting>
     837            </listitem>
     838          </itemizedlist>
     839        </listitem>
     840
     841        <listitem>
     842          <para>List modifier examples:</para>
     843
     844          <programlisting>configure.env-append   ABI=32
     845configure.env-delete   TCLROOT=${prefix}</programlisting>
     846        </listitem>
     847      </varlistentry>
     848
     849      <varlistentry>
     850        <term>configure.cflags</term>
     851
     852        <term>configure.cflags-append</term>
     853
     854        <term>configure.cflags-delete</term>
     855
     856        <listitem>
     857          <para>Set CFLAGS compiler flags; list modifiers add or delete
     858          items from a previous Portfile configure.cflags keyword or the
     859          default set by MacPorts base.</para>
     860
     861          <itemizedlist>
     862            <listitem>
     863              <para>Default: <literal>-O2</literal></para>
     864            </listitem>
     865
     866            <listitem>
     867              <para>Example:</para>
     868
     869              <programlisting>configure.cflags    -Os -flat_namespace
     870
     871</programlisting>
     872            </listitem>
     873          </itemizedlist>
     874        </listitem>
     875
     876        <listitem>
     877          <para>List modifier examples:</para>
     878
     879          <programlisting>configure.cflags-append   "-undefined suppress"
     880configure.cflags-delete   -O2</programlisting>
     881        </listitem>
     882      </varlistentry>
     883
     884      <varlistentry>
     885        <term>configure.ldflags</term>
     886
     887        <term>configure.ldflags-append</term>
     888
     889        <term>configure.ldflags-delete</term>
     890
     891        <listitem>
     892          <para>Set LDFLAGS compiler flags; list modifiers add or delete
     893          items from a previous Portfile configure.ldflags keyword or the
     894          default set by MacPorts base.</para>
     895
     896          <itemizedlist>
     897            <listitem>
     898              <para>Default: <literal>-L${prefix}/lib</literal></para>
     899            </listitem>
     900
     901            <listitem>
     902              <para>Example:</para>
     903
     904              <programlisting>configure.ldflags    -L${worksrcpath}/zlib -lz
     905
     906</programlisting>
     907            </listitem>
     908          </itemizedlist>
     909        </listitem>
     910
     911        <listitem>
     912          <para>List modifier examples:</para>
     913
     914          <programlisting>configure.ldflags-append   "-L/usr/X11R6/lib -L${worksrcpath}/lib"
     915configure.ldflags-delete   -L${prefix}/lib/db44</programlisting>
     916        </listitem>
     917      </varlistentry>
     918
     919      <varlistentry>
     920        <term>configure.cppflags</term>
     921
     922        <term>configure.cppflags-append</term>
     923
     924        <term>configure.cppflags-delete</term>
     925
     926        <listitem>
     927          <para>Set CPPFLAGS to be passed to the C processor; list modifiers
     928          add or delete items from a previous Portfile configure.cppflags
     929          keyword or the default set by MacPorts base.</para>
     930
     931          <itemizedlist>
     932            <listitem>
     933              <para>Default: <literal>-I${prefix}/include</literal></para>
     934            </listitem>
     935
     936            <listitem>
     937              <para>Example:</para>
     938
     939              <programlisting>configure.cppflags    -I${worksrcpath}/include
     940
     941</programlisting>
     942            </listitem>
     943          </itemizedlist>
     944        </listitem>
     945
     946        <listitem>
     947          <para>List modifier examples:</para>
     948
     949          <programlisting>configure.cppflags-append   "-I/usr/X11R6/lib -I${worksrcpath}/lib -DHAVE_RRD_12X"
     950configure.cppflags-delete   -I${prefix}/lib/db44</programlisting>
     951        </listitem>
     952      </varlistentry>
     953
     954      <!-- fortran compiler options -->
     955
     956      <varlistentry>
     957        <term>configure.fflags</term>
     958
     959        <term>configure.fflags-append</term>
     960
     961        <term>configure.fflags-delete</term>
     962
     963        <listitem>
     964          <para>Set FFLAGS to be passed to the Fortran compiler; list
     965          modifiers add or delete items from a previous Portfile
     966          configure.fflags keyword or the default set by MacPorts
     967          base.</para>
     968
     969          <itemizedlist>
     970            <listitem>
     971              <para>Default: <literal>-O2</literal></para>
     972            </listitem>
     973
     974            <listitem>
     975              <para>Example:</para>
     976
     977              <programlisting>configure.fflags    -Os
     978
     979</programlisting>
     980            </listitem>
     981          </itemizedlist>
     982        </listitem>
     983      </varlistentry>
     984
     985      <varlistentry>
     986        <term>configure.fcflags</term>
     987
     988        <term>configure.fcflags-append</term>
     989
     990        <term>configure.fcflags-delete</term>
     991
     992        <listitem>
     993          <para>Set FCFLAGS to be passed to the Fortran compiler; list
     994          modifiers add or delete items from a previous Portfile
     995          configure.fcflags keyword or the default set by MacPorts
     996          base.</para>
     997
     998          <itemizedlist>
     999            <listitem>
     1000              <para>Default: <literal>-O2</literal></para>
     1001            </listitem>
     1002
     1003            <listitem>
     1004              <para>Example:</para>
     1005
     1006              <programlisting>configure.fcflags    -Os
     1007
     1008</programlisting>
     1009            </listitem>
     1010          </itemizedlist>
     1011        </listitem>
     1012      </varlistentry>
     1013
     1014      <varlistentry>
     1015        <term>configure.f90flags</term>
     1016
     1017        <term>configure.f90flags-append</term>
     1018
     1019        <term>configure.f90flags-delete</term>
     1020
     1021        <listitem>
     1022          <para>Set F90FLAGS to be passed to the Fortran 90 compiler; list
     1023          modifiers add or delete items from a previous Portfile
     1024          configure.f90flags keyword or the default set by MacPorts
     1025          base.</para>
     1026
     1027          <itemizedlist>
     1028            <listitem>
     1029              <para>Default: <literal>-O2</literal></para>
     1030            </listitem>
     1031
     1032            <listitem>
     1033              <para>Example:</para>
     1034
     1035              <programlisting>configure.f90flags    -Os
     1036
     1037</programlisting>
     1038            </listitem>
     1039          </itemizedlist>
     1040        </listitem>
     1041      </varlistentry>
     1042
     1043      <!-- fortran compiler options end -->
     1044
     1045      <!-- compiler selection arguments -->
     1046
     1047      <varlistentry>
     1048        <term>configure.cc</term>
     1049
     1050        <listitem>
     1051          <para>Set CC compiler flags for selecting a C compiler;</para>
     1052
     1053          <itemizedlist>
     1054            <listitem>
     1055              <para>Default: <literal></literal></para>
     1056            </listitem>
     1057
     1058            <listitem>
     1059              <para>Example:</para>
     1060
     1061              <programlisting>configure.cc    ${prefix}/bin/gcc-mp-4.2</programlisting>
     1062            </listitem>
     1063          </itemizedlist>
     1064        </listitem>
     1065      </varlistentry>
     1066
     1067      <varlistentry>
     1068        <term>configure.cpp</term>
     1069
     1070        <listitem>
     1071          <para>Set CPP compiler flags for selecting a C
     1072          preprocessor;</para>
     1073
     1074          <itemizedlist>
     1075            <listitem>
     1076              <para>Default: <literal></literal></para>
     1077            </listitem>
     1078
     1079            <listitem>
     1080              <para>Example:</para>
     1081
     1082              <programlisting>configure.cpp    /usr/bin/cpp-3.3</programlisting>
     1083            </listitem>
     1084          </itemizedlist>
     1085        </listitem>
     1086      </varlistentry>
     1087
     1088      <varlistentry>
     1089        <term>configure.cxx</term>
     1090
     1091        <listitem>
     1092          <para>Set CXX compiler flags for selecting a C++ compiler;</para>
     1093
     1094          <itemizedlist>
     1095            <listitem>
     1096              <para>Default: <literal></literal></para>
     1097            </listitem>
     1098
     1099            <listitem>
     1100              <para>Example:</para>
     1101
     1102              <programlisting>configure.cpp    /usr/bin/g++-4.0</programlisting>
     1103            </listitem>
     1104          </itemizedlist>
     1105        </listitem>
     1106      </varlistentry>
     1107
     1108      <varlistentry>
     1109        <term>configure.objc</term>
     1110
     1111        <listitem>
     1112          <para>Set OBJC compiler flags for selecting an Objective-C
     1113          compiler;</para>
     1114
     1115          <itemizedlist>
     1116            <listitem>
     1117              <para>Default: <literal></literal></para>
     1118            </listitem>
     1119
     1120            <listitem>
     1121              <para>Example:</para>
     1122
     1123              <programlisting>configure.objc    /usr/bin/gcc-4.0</programlisting>
     1124            </listitem>
     1125          </itemizedlist>
     1126        </listitem>
     1127      </varlistentry>
     1128
     1129      <varlistentry>
     1130        <term>configure.fc</term>
     1131
     1132        <listitem>
     1133          <para>Set FC compiler flags for selecting a Fortran
     1134          compiler;</para>
     1135
     1136          <itemizedlist>
     1137            <listitem>
     1138              <para>Default: <literal></literal></para>
     1139            </listitem>
     1140
     1141            <listitem>
     1142              <para>Example:</para>
     1143
     1144              <programlisting>configure.fc    ${prefix}/bin/gfortran-mp-4.2</programlisting>
     1145            </listitem>
     1146          </itemizedlist>
     1147        </listitem>
     1148      </varlistentry>
     1149
     1150      <varlistentry>
     1151        <term>configure.f77</term>
     1152
     1153        <listitem>
     1154          <para>Set F77 compiler flags for selecting a Fortran 77
     1155          compiler;</para>
     1156
     1157          <itemizedlist>
     1158            <listitem>
     1159              <para>Default: <literal></literal></para>
     1160            </listitem>
     1161
     1162            <listitem>
     1163              <para>Example:</para>
     1164
     1165              <programlisting>configure.f77    ${prefix}/bin/gfortran-mp-4.2</programlisting>
     1166            </listitem>
     1167          </itemizedlist>
     1168        </listitem>
     1169      </varlistentry>
     1170
     1171      <varlistentry>
     1172        <term>configure.f90</term>
     1173
     1174        <listitem>
     1175          <para>Set F90 compiler flags for selecting a Fortran 90
     1176          compiler;</para>
     1177
     1178          <itemizedlist>
     1179            <listitem>
     1180              <para>Default: <literal></literal></para>
     1181            </listitem>
     1182
     1183            <listitem>
     1184              <para>Example:</para>
     1185
     1186              <programlisting>configure.f90    ${prefix}/bin/gfortran-mp-4.2</programlisting>
     1187            </listitem>
     1188          </itemizedlist>
     1189        </listitem>
     1190      </varlistentry>
     1191
     1192      <varlistentry>
     1193        <term>configure.javac</term>
     1194
     1195        <listitem>
     1196          <para>Set JAVAC compiler flags for selecting a Java
     1197          compiler;</para>
     1198
     1199          <itemizedlist>
     1200            <listitem>
     1201              <para>Default: <literal></literal></para>
     1202            </listitem>
     1203
     1204            <listitem>
     1205              <para>Example:</para>
     1206
     1207              <programlisting>configure.javac    ${prefix}/bin/jikes</programlisting>
     1208            </listitem>
     1209          </itemizedlist>
     1210        </listitem>
     1211      </varlistentry>
     1212
     1213      <varlistentry>
     1214        <term>configure.compiler</term>
     1215
     1216        <listitem>
     1217          <para>Select a compiler suite to fill the compiler environment
     1218          variables. All variables/tools a compiler suite can provide are
     1219          set. Manually set variables are not overwritten. Dependencies are
     1220          not added for you, as they may be just build- or also
     1221          run-dependencies. Keep in mind that not all compiler suites might
     1222          be available on your platform.</para>
     1223
     1224          <itemizedlist>
     1225            <listitem>
     1226              <para>Default: <literal>gcc-3.3</literal>Mac OS X 10.3</para>
     1227
     1228              <para>Default: <literal>gcc-4.0</literal>Mac OS X 10.4,
     1229              10.5</para>
     1230            </listitem>
     1231
     1232            <listitem>
     1233              <para>Options:</para>
     1234
     1235              <programlisting>gcc-3.3 gcc-4.0 apple-gcc-3.3 apple-gcc-4.0 macports-gcc-3.3 macports-gcc-3.4 macports-gcc-4.0 macports-gcc-4.1 macports-gcc-4.2 macports-gcc-4.3</programlisting>
     1236            </listitem>
     1237
     1238            <listitem>
     1239              <para>Example:</para>
     1240
     1241              <programlisting>configure.compiler    macports-gcc-4.2</programlisting>
     1242            </listitem>
     1243          </itemizedlist>
     1244        </listitem>
     1245      </varlistentry>
     1246
     1247      <!-- compiler selection arguments end -->
     1248
     1249      <!-- interpreter selection arguments -->
     1250
     1251      <varlistentry>
     1252        <term>configure.perl</term>
     1253
     1254        <listitem>
     1255          <para>Set PERL flag for selecting a Perl interpreter;</para>
     1256
     1257          <itemizedlist>
     1258            <listitem>
     1259              <para>Default: <literal></literal></para>
     1260            </listitem>
     1261
     1262            <listitem>
     1263              <para>Example:</para>
     1264
     1265              <programlisting>configure.perl    ${prefix}/bin/perl5.8</programlisting>
     1266            </listitem>
     1267          </itemizedlist>
     1268        </listitem>
     1269      </varlistentry>
     1270
     1271      <varlistentry>
     1272        <term>configure.python</term>
     1273
     1274        <listitem>
     1275          <para>Set PYTHON flag for selecting a Python interpreter;</para>
     1276
     1277          <itemizedlist>
     1278            <listitem>
     1279              <para>Default: <literal></literal></para>
     1280            </listitem>
     1281
     1282            <listitem>
     1283              <para>Example:</para>
     1284
     1285              <programlisting>configure.python    ${prefix}/bin/python3.0</programlisting>
     1286            </listitem>
     1287          </itemizedlist>
     1288        </listitem>
     1289      </varlistentry>
     1290
     1291      <varlistentry>
     1292        <term>configure.ruby</term>
     1293
     1294        <listitem>
     1295          <para>Set RUBY flag for selecting a Ruby interpreter;</para>
     1296
     1297          <itemizedlist>
     1298            <listitem>
     1299              <para>Default: <literal></literal></para>
     1300            </listitem>
     1301
     1302            <listitem>
     1303              <para>Example:</para>
     1304
     1305              <programlisting>configure.ruby    ${prefix}/bin/ruby</programlisting>
     1306            </listitem>
     1307          </itemizedlist>
     1308        </listitem>
     1309      </varlistentry>
     1310
     1311      <!-- interpreter selection arguments end -->
     1312
     1313      <!-- other tools selection arguments -->
     1314
     1315      <varlistentry>
     1316        <term>configure.install</term>
     1317
     1318        <listitem>
     1319          <para>Set INSTALL flag for selecting an install tool; used for
     1320          copying files and creating directories</para>
     1321
     1322          <itemizedlist>
     1323            <listitem>
     1324              <para>Default: <literal>/usr/bin/install</literal></para>
     1325            </listitem>
     1326
     1327            <listitem>
     1328              <para>Example:</para>
     1329
     1330              <programlisting>configure.install    ${prefix}/bin/ginstall</programlisting>
     1331            </listitem>
     1332          </itemizedlist>
     1333        </listitem>
     1334      </varlistentry>
     1335
     1336      <varlistentry>
     1337        <term>configure.awk</term>
     1338
     1339        <listitem>
     1340          <para>Set AWK flag for selecting an awk executable</para>
     1341
     1342          <itemizedlist>
     1343            <listitem>
     1344              <para>Default: <literal></literal></para>
     1345            </listitem>
     1346
     1347            <listitem>
     1348              <para>Example:</para>
     1349
     1350              <programlisting>configure.awk    ${prefix}/bin/gawk</programlisting>
     1351            </listitem>
     1352          </itemizedlist>
     1353        </listitem>
     1354      </varlistentry>
     1355
     1356      <varlistentry>
     1357        <term>configure.bison</term>
     1358
     1359        <listitem>
     1360          <para>Set BISON flag for selecting a bison executable, a parser
     1361          generator</para>
     1362
     1363          <itemizedlist>
     1364            <listitem>
     1365              <para>Default: <literal></literal></para>
     1366            </listitem>
     1367
     1368            <listitem>
     1369              <para>Example:</para>
     1370
     1371              <programlisting>configure.bison    /usr/bin/bison</programlisting>
     1372            </listitem>
     1373          </itemizedlist>
     1374        </listitem>
     1375      </varlistentry>
     1376
     1377      <varlistentry>
     1378        <term>configure.pkg_config</term>
     1379
     1380        <listitem>
     1381          <para>Set PKG_CONFIG flag for helping find pkg_config, a tool for
     1382          retrieving information about installed libraries.</para>
     1383
     1384          <itemizedlist>
     1385            <listitem>
     1386              <para>Default: <literal></literal></para>
     1387            </listitem>
     1388
     1389            <listitem>
     1390              <para>Example:</para>
     1391
     1392              <programlisting>configure.pkg_config    ${prefix}/bin/pkg-config</programlisting>
     1393            </listitem>
     1394          </itemizedlist>
     1395        </listitem>
     1396      </varlistentry>
     1397
     1398      <varlistentry>
     1399        <term>configure.pkg_config_path</term>
     1400
     1401        <listitem>
     1402          <para>Set PKG_CONFIG_PATH flag for telling pkg_config where to
     1403          search for information about installed libraries.</para>
     1404
     1405          <itemizedlist>
     1406            <listitem>
     1407              <para>Default: <literal></literal></para>
     1408            </listitem>
     1409
     1410            <listitem>
     1411              <para>Example:</para>
     1412
     1413              <programlisting>configure.pkg_config_path    ${prefix}/lib/pkgconfig:${x11prefix}/lib/pkgconfig</programlisting>
     1414            </listitem>
     1415          </itemizedlist>
     1416        </listitem>
     1417      </varlistentry>
     1418
     1419      <!-- other tools selection arguments end -->
     1420
     1421      <varlistentry>
     1422        <term>configure.args</term>
     1423
     1424        <term>configure.pre_args</term>
     1425
     1426        <term>configure.post_args</term>
     1427
     1428        <listitem>
     1429          <para>Main arguments to configure.cmd; optional argument modifiers
     1430          pass arguments before and after the main arguments.</para>
     1431
     1432          <itemizedlist>
     1433            <listitem>
     1434              <para>Default: none</para>
     1435            </listitem>
     1436
     1437            <listitem>
     1438              <para>Example:</para>
     1439
     1440              <programlisting>configure.args    --bindir=${prefix}/bin
     1441
     1442</programlisting>
     1443            </listitem>
     1444          </itemizedlist>
     1445        </listitem>
     1446
     1447        <listitem>
     1448          <para>The following argument modifiers are available:</para>
     1449
     1450          <itemizedlist>
     1451            <listitem>
     1452              <para>configure.pre_args default: --prefix=${prefix}</para>
     1453            </listitem>
     1454
     1455            <listitem>
     1456              <para>configure.post_args default: none</para>
     1457            </listitem>
     1458
     1459            <listitem>
     1460              <para>Examples:</para>
     1461
     1462              <programlisting>configure.pre_args   --prefix=${prefix}/share/bro
     1463configure.post_args  OPT="-D__DARWIN_UNIX03"</programlisting>
     1464            </listitem>
     1465          </itemizedlist>
     1466        </listitem>
     1467      </varlistentry>
     1468    </variablelist>
     1469
     1470    <section>
     1471      <title>Configure Universal</title>
     1472
     1473      <para>Universal keywords are used to make a port compile on the OS X
     1474      platform to run on either PPC or Intel.</para>
     1475
     1476      <note>
     1477        <para>There is a default universal variant made available to all
     1478        ports by MacPorts base, so redefining universal keywords should only
     1479        be done to make a given port compile if the default options fail to
     1480        do so.</para>
     1481      </note>
     1482
     1483      <variablelist>
     1484        <varlistentry>
     1485          <term>configure.universal_args</term>
     1486
     1487          <listitem>
     1488            <para>Arguments used in the configure script to build the port
     1489            universal.</para>
     1490
     1491            <itemizedlist>
     1492              <listitem>
     1493                <para>Default: --disable-dependency-tracking</para>
     1494              </listitem>
     1495
     1496              <listitem>
     1497                <para>Example:</para>
     1498
     1499                <programlisting></programlisting>
     1500              </listitem>
     1501            </itemizedlist>
     1502          </listitem>
     1503        </varlistentry>
     1504
     1505        <varlistentry>
     1506          <term>configure.universal_cflags</term>
     1507
     1508          <listitem>
     1509            <para>Arguments appended to the configure script to build the
     1510            port universal.</para>
     1511
     1512            <itemizedlist>
     1513              <listitem>
     1514                <para>Default: -sysroot /Developer/SDKs/MacOSX10.4u.sdk
     1515                -arch i386 -arch ppc</para>
     1516              </listitem>
     1517
     1518              <listitem>
     1519                <para>Example:</para>
     1520
     1521                <programlisting></programlisting>
     1522              </listitem>
     1523            </itemizedlist>
     1524          </listitem>
     1525        </varlistentry>
     1526
     1527        <varlistentry>
     1528          <term>configure.universal_cppflags</term>
     1529
     1530          <listitem>
     1531            <para>Additional flags to put in the CPPFLAGS environment
     1532            variable when invoking the configure script.</para>
     1533
     1534            <itemizedlist>
     1535              <listitem>
     1536                <para>Default: ???</para>
     1537              </listitem>
     1538
     1539              <listitem>
     1540                <para>Example:</para>
     1541
     1542                <programlisting></programlisting>
     1543              </listitem>
     1544            </itemizedlist>
     1545          </listitem>
     1546        </varlistentry>
     1547
     1548        <varlistentry>
     1549          <term>configure.universal_cxxflags</term>
     1550
     1551          <listitem>
     1552            <para>Additional flags to put in the CXXFLAGS environment
     1553            variable when invoking the configure script.</para>
     1554
     1555            <itemizedlist>
     1556              <listitem>
     1557                <para>Default: -isysroot /Developer/SDKs/MacOSX10.4u.sdk
     1558                -arch i386 -arch ppc</para>
     1559              </listitem>
     1560
     1561              <listitem>
     1562                <para>Example:</para>
     1563
     1564                <programlisting></programlisting>
     1565              </listitem>
     1566            </itemizedlist>
     1567          </listitem>
     1568        </varlistentry>
     1569
     1570        <varlistentry>
     1571          <term>configure.universal_ldflags</term>
     1572
     1573          <listitem>
     1574            <para>Additional flags to put in the LDFLAGS environment
     1575            variable when invoking the configure script.</para>
     1576
     1577            <itemizedlist>
     1578              <listitem>
     1579                <para>Default: -arch i386 -arch ppc</para>
     1580              </listitem>
     1581
     1582              <listitem>
     1583                <para>Example:</para>
     1584
     1585                <programlisting></programlisting>
    5471586              </listitem>
    5481587            </itemizedlist>
     
    5531592
    5541593    <section>
    555       <title>Extract Phase Keywords</title>
    556 
    557       <para>The list of keywords related to the extract phase.</para>
     1594      <title>Automake and Autoconf</title>
     1595
     1596      <para>The list of configure keywords available for ports that need
     1597      automake and/or autoconf.</para>
    5581598
    5591599      <variablelist>
    5601600        <varlistentry>
    561           <term>extract.only</term>
    562 
    563           <term>extract.only-append</term>
    564 
    565           <term>extract.only-delete</term>
     1601          <term>use_automake</term>
    5661602
    5671603          <listitem>
    568             <para>List of files to extract into
    569             <varname>${worksrcpath}</varname>; the default is
    570             <varname>${distfiles}</varname>. Only use if default extract
    571             behavior is not correct for your port.</para>
    572 
    573             <itemizedlist>
    574               <listitem>
    575                 <para>Default: none</para>
    576               </listitem>
    577 
    578               <listitem>
    579                 <para>Example:</para>
    580 
    581                 <programlisting>extract.only     foo.tar.gz
    582 
    583 </programlisting>
    584               </listitem>
    585             </itemizedlist>
    586           </listitem>
    587 
    588           <listitem>
    589             <para>List modifier examples:</para>
    590 
    591             <programlisting>extract.only-append  bar.tar.gz
    592 extract.only-delete  foo.tar.gz</programlisting>
     1604            <para>Whether or not to use automake; the default is
     1605            "no".</para>
     1606
     1607            <programlisting>use_automake      yes</programlisting>
    5931608          </listitem>
    5941609        </varlistentry>
    5951610
    5961611        <varlistentry>
    597           <term>extract.cmd</term>
     1612          <term>automake.env</term>
    5981613
    5991614          <listitem>
    600             <para>Command to perform extraction.</para>
    601 
    602             <itemizedlist>
    603               <listitem>
    604                 <para>Default: gzip</para>
    605               </listitem>
    606 
    607               <listitem>
    608                 <para>Example:</para>
    609 
    610                 <programlisting>extract.cmd     gunzip</programlisting>
    611               </listitem>
    612             </itemizedlist>
     1615            <para>Environment variables to pass to automake.</para>
     1616
     1617            <programlisting>automake.env      CFLAGS=-I${prefix}/include</programlisting>
    6131618          </listitem>
    6141619        </varlistentry>
    6151620
    6161621        <varlistentry>
    617           <term>extract.args</term>
    618 
    619           <term>extract.pre_args</term>
    620 
    621           <term>extract.post_args</term>
     1622          <term>automake.args</term>
    6221623
    6231624          <listitem>
    624             <para>Main arguments to extract.cmd; additional arguments passed
    625             before and after the main arguments.</para>
    626 
    627             <itemizedlist>
    628               <listitem>
    629                 <para>Default: ${distpath}/${distfile}</para>
    630               </listitem>
    631 
    632               <listitem>
    633                 <para>Example:</para>
    634 
    635                 <programlisting>extract.args      ${distpath}/${distfile}
    636 
    637 </programlisting>
    638               </listitem>
    639             </itemizedlist>
    640           </listitem>
    641 
    642           <listitem>
    643             <para>The following argument modifiers are available:</para>
    644 
    645             <itemizedlist>
    646               <listitem>
    647                 <para>extract.pre_args default: "-dc"</para>
    648               </listitem>
    649 
    650               <listitem>
    651                 <para>extract.post_args default: " | tar -xf"</para>
    652               </listitem>
    653 
    654               <listitem>
    655                 <para>Examples:</para>
    656 
    657                 <programlisting>extract.pre_args     xf
    658 extract.post_args    "| gnutar –x"</programlisting>
    659               </listitem>
    660             </itemizedlist>
     1625            <para>Arguments to pass to automake.</para>
     1626
     1627            <programlisting>automake.args     --foreign</programlisting>
    6611628          </listitem>
    6621629        </varlistentry>
    663       </variablelist>
    664     </section>
    665 
    666     <section>
    667       <title>Patch Phase Keywords</title>
    668 
    669       <para>The list of keywords related to the patch phase.</para>
    670 
    671       <variablelist>
     1630
    6721631        <varlistentry>
    673           <term>patch.dir</term>
     1632          <term>automake.dir</term>
    6741633
    6751634          <listitem>
    676             <para>Specify the base path for patch files.</para>
    677 
    678             <itemizedlist>
    679               <listitem>
    680                 <para>Default: <varname>${worksrcpath}</varname></para>
    681               </listitem>
    682 
    683               <listitem>
    684                 <para>Example:</para>
    685 
    686                 <programlisting>patch.dir      ${worksrcpath}/util</programlisting>
    687               </listitem>
    688             </itemizedlist>
     1635            <para>Directory in which to run
     1636            <varname>${automake.cmd}</varname>; the default is
     1637            <varname>${worksrcpath}</varname>.</para>
     1638
     1639            <programlisting>automake.dir      ./src</programlisting>
    6891640          </listitem>
    6901641        </varlistentry>
    6911642
    6921643        <varlistentry>
    693           <term>patch.cmd</term>
     1644          <term>use_autoconf</term>
    6941645
    6951646          <listitem>
    696             <para>Specify the command to be used for patching files.</para>
    697 
    698             <itemizedlist>
    699               <listitem>
    700                 <para>Default: <command>patch</command></para>
    701               </listitem>
    702 
    703               <listitem>
    704                 <para>Example:</para>
    705 
    706                 <programlisting>patch.cmd      cat</programlisting>
    707               </listitem>
    708             </itemizedlist>
     1647            <para>Whether or not to use autoconf; the default is
     1648            "no".</para>
     1649
     1650            <programlisting>use_autoconf      yes</programlisting>
    7091651          </listitem>
    7101652        </varlistentry>
    7111653
    7121654        <varlistentry>
    713           <term>patchfiles</term>
    714 
    715           <term>patchfiles-append</term>
    716 
    717           <term>patchfiles-delete</term>
     1655          <term>autoconf.env</term>
    7181656
    7191657          <listitem>
    720             <para>Specify patch files to be applied for a port; list modifiers
    721             specify patchfiles to be added or removed from a previous
    722             patchfile declaration.</para>
    723 
    724             <itemizedlist>
    725               <listitem>
    726                 <para>Default: none</para>
    727               </listitem>
    728 
    729               <listitem>
    730                 <para>Example:</para>
    731 
    732                 <programlisting>patchfiles     patch-Makefile.in \
    733                patch-source.c
    734 
    735 </programlisting>
    736               </listitem>
    737             </itemizedlist>
    738           </listitem>
    739 
    740           <listitem>
    741             <para>List modifier examples:</para>
    742 
    743             <programlisting>patchfiles-append   patch-configure
    744 patchfiles-delete   patch-src-Makefile.in
    745 </programlisting>
     1658            <para>Environmental variables to pass to autoconf.</para>
     1659
     1660            <programlisting>autoconf.env      CFLAGS=-I${prefix}/include/gtk12</programlisting>
    7461661          </listitem>
    7471662        </varlistentry>
    7481663
    7491664        <varlistentry>
    750           <term>patch.args</term>
    751 
    752           <term>patch.pre_args</term>
    753 
    754           <term>patch.post_args</term>
     1665          <term>autoconf.args</term>
    7551666
    7561667          <listitem>
    757             <para>Main arguments to patch.cmd; optional argument modifiers
    758             pass arguments before and after the main arguments.</para>
    759 
    760             <itemizedlist>
    761               <listitem>
    762                 <para>Default: none</para>
    763               </listitem>
    764 
    765               <listitem>
    766                 <para>Example:</para>
    767 
    768                 <programlisting>patch.args   ???
    769 
    770 </programlisting>
    771               </listitem>
    772             </itemizedlist>
    773           </listitem>
    774 
    775           <listitem>
    776             <para>The following argument modifiers are available:</para>
    777 
    778             <itemizedlist>
    779               <listitem>
    780                 <para>patch.pre_args default: -p0</para>
    781               </listitem>
    782 
    783               <listitem>
    784                 <para>patch.post_args default: none</para>
    785               </listitem>
    786 
    787               <listitem>
    788                 <para>Examples:</para>
    789 
    790                 <programlisting>patch.pre_args     -p1
    791 patch.post_args    ???</programlisting>
    792               </listitem>
    793             </itemizedlist>
     1668            <para>Arguments to pass to autoconf.</para>
     1669
     1670            <programlisting>autoconf.args     -l src/aclocaldir</programlisting>
    7941671          </listitem>
    7951672        </varlistentry>
    796       </variablelist>
    797     </section>
    798 
    799     <section>
    800       <title>Configure Phase Keywords</title>
    801 
    802       <para>The list of keywords related to the configure phase.</para>
    803 
    804       <para>MacPorts base sets some important default configure options, so
    805       should use the -append version of most configure keywords so you don't
    806       overwrite them. For example, MacPorts base sets default
    807       <literal>configure.cflags</literal> so you should always use
    808       <literal>configure.cflags-append</literal> to set additional CFLAGS in
    809       Portfiles.</para>
    810 
    811       <variablelist>
     1673
    8121674        <varlistentry>
    813           <term>configure.env</term>
    814 
    815           <term>configure.env-append</term>
    816 
    817           <term>configure.env-delete</term>
     1675          <term>autoconf.dir</term>
    8181676
    8191677          <listitem>
    820             <para>Set environment variables for configure; list modifiers add
    821             and delete items from a previous Portfile configure.env keyword,
    822             or a default set by MacPorts base. If available, it is encouraged
    823             to use the predefined options (like configure.cflags) instead of
    824             modifying configure.env directly</para>
    825 
    826             <itemizedlist>
    827               <listitem>
    828                 <para>Default: <literal>CFLAGS=-I${prefix}/include
    829                 LDFLAGS=-L${prefix}/lib</literal></para>
    830               </listitem>
    831 
    832               <listitem>
    833                 <para>Example:</para>
    834 
    835                 <programlisting>configure.env   QTDIR=${prefix}/lib/qt3
    836 </programlisting>
    837               </listitem>
    838             </itemizedlist>
    839           </listitem>
    840 
    841           <listitem>
    842             <para>List modifier examples:</para>
    843 
    844             <programlisting>configure.env-append   ABI=32
    845 configure.env-delete   TCLROOT=${prefix}</programlisting>
    846           </listitem>
    847         </varlistentry>
    848 
    849         <varlistentry>
    850           <term>configure.cflags</term>
    851 
    852           <term>configure.cflags-append</term>
    853 
    854           <term>configure.cflags-delete</term>
    855 
    856           <listitem>
    857             <para>Set CFLAGS compiler flags; list modifiers add or delete
    858             items from a previous Portfile configure.cflags keyword or the
    859             default set by MacPorts base.</para>
    860 
    861             <itemizedlist>
    862               <listitem>
    863                 <para>Default: <literal>-O2</literal></para>
    864               </listitem>
    865 
    866               <listitem>
    867                 <para>Example:</para>
    868 
    869                 <programlisting>configure.cflags    -Os -flat_namespace
    870 
    871 </programlisting>
    872               </listitem>
    873             </itemizedlist>
    874           </listitem>
    875 
    876           <listitem>
    877             <para>List modifier examples:</para>
    878 
    879             <programlisting>configure.cflags-append   "-undefined suppress"
    880 configure.cflags-delete   -O2</programlisting>
    881           </listitem>
    882         </varlistentry>
    883 
    884         <varlistentry>
    885           <term>configure.ldflags</term>
    886 
    887           <term>configure.ldflags-append</term>
    888 
    889           <term>configure.ldflags-delete</term>
    890 
    891           <listitem>
    892             <para>Set LDFLAGS compiler flags; list modifiers add or delete
    893             items from a previous Portfile configure.ldflags keyword or the
    894             default set by MacPorts base.</para>
    895 
    896             <itemizedlist>
    897               <listitem>
    898                 <para>Default: <literal>-L${prefix}/lib</literal></para>
    899               </listitem>
    900 
    901               <listitem>
    902                 <para>Example:</para>
    903 
    904                 <programlisting>configure.ldflags    -L${worksrcpath}/zlib -lz
    905 
    906 </programlisting>
    907               </listitem>
    908             </itemizedlist>
    909           </listitem>
    910 
    911           <listitem>
    912             <para>List modifier examples:</para>
    913 
    914             <programlisting>configure.ldflags-append   "-L/usr/X11R6/lib -L${worksrcpath}/lib"
    915 configure.ldflags-delete   -L${prefix}/lib/db44</programlisting>
    916           </listitem>
    917         </varlistentry>
    918 
    919         <varlistentry>
    920           <term>configure.cppflags</term>
    921 
    922           <term>configure.cppflags-append</term>
    923 
    924           <term>configure.cppflags-delete</term>
    925 
    926           <listitem>
    927             <para>Set CPPFLAGS to be passed to the C processor; list modifiers
    928             add or delete items from a previous Portfile configure.cppflags
    929             keyword or the default set by MacPorts base.</para>
    930 
    931             <itemizedlist>
    932               <listitem>
    933                 <para>Default: <literal>-I${prefix}/include</literal></para>
    934               </listitem>
    935 
    936               <listitem>
    937                 <para>Example:</para>
    938 
    939                 <programlisting>configure.cppflags    -I${worksrcpath}/include
    940 
    941 </programlisting>
    942               </listitem>
    943             </itemizedlist>
    944           </listitem>
    945 
    946           <listitem>
    947             <para>List modifier examples:</para>
    948 
    949             <programlisting>configure.cppflags-append   "-I/usr/X11R6/lib -I${worksrcpath}/lib -DHAVE_RRD_12X"
    950 configure.cppflags-delete   -I${prefix}/lib/db44</programlisting>
    951           </listitem>
    952         </varlistentry>
    953 
    954         <!-- fortran compiler options -->
    955 
    956         <varlistentry>
    957           <term>configure.fflags</term>
    958 
    959           <term>configure.fflags-append</term>
    960 
    961           <term>configure.fflags-delete</term>
    962 
    963           <listitem>
    964             <para>Set FFLAGS to be passed to the Fortran compiler; list
    965             modifiers add or delete items from a previous Portfile
    966             configure.fflags keyword or the default set by MacPorts
    967             base.</para>
    968 
    969             <itemizedlist>
    970               <listitem>
    971                 <para>Default: <literal>-O2</literal></para>
    972               </listitem>
    973 
    974               <listitem>
    975                 <para>Example:</para>
    976 
    977                 <programlisting>configure.fflags    -Os
    978 
    979 </programlisting>
    980               </listitem>
    981             </itemizedlist>
    982           </listitem>
    983         </varlistentry>
    984 
    985         <varlistentry>
    986           <term>configure.fcflags</term>
    987 
    988           <term>configure.fcflags-append</term>
    989 
    990           <term>configure.fcflags-delete</term>
    991 
    992           <listitem>
    993             <para>Set FCFLAGS to be passed to the Fortran compiler; list
    994             modifiers add or delete items from a previous Portfile
    995             configure.fcflags keyword or the default set by MacPorts
    996             base.</para>
    997 
    998             <itemizedlist>
    999               <listitem>
    1000                 <para>Default: <literal>-O2</literal></para>
    1001               </listitem>
    1002 
    1003               <listitem>
    1004                 <para>Example:</para>
    1005 
    1006                 <programlisting>configure.fcflags    -Os
    1007 
    1008 </programlisting>
    1009               </listitem>
    1010             </itemizedlist>
    1011           </listitem>
    1012         </varlistentry>
    1013 
    1014         <varlistentry>
    1015           <term>configure.f90flags</term>
    1016 
    1017           <term>configure.f90flags-append</term>
    1018 
    1019           <term>configure.f90flags-delete</term>
    1020 
    1021           <listitem>
    1022             <para>Set F90FLAGS to be passed to the Fortran 90 compiler; list
    1023             modifiers add or delete items from a previous Portfile
    1024             configure.f90flags keyword or the default set by MacPorts
    1025             base.</para>
    1026 
    1027             <itemizedlist>
    1028               <listitem>
    1029                 <para>Default: <literal>-O2</literal></para>
    1030               </listitem>
    1031 
    1032               <listitem>
    1033                 <para>Example:</para>
    1034 
    1035                 <programlisting>configure.f90flags    -Os
    1036 
    1037 </programlisting>
    1038               </listitem>
    1039             </itemizedlist>
    1040           </listitem>
    1041         </varlistentry>
    1042 
    1043         <!-- fortran compiler options end -->
    1044 
    1045         <!-- compiler selection arguments -->
    1046 
    1047         <varlistentry>
    1048           <term>configure.cc</term>
    1049 
    1050           <listitem>
    1051             <para>Set CC compiler flags for selecting a C compiler;</para>
    1052 
    1053             <itemizedlist>
    1054               <listitem>
    1055                 <para>Default: <literal></literal></para>
    1056               </listitem>
    1057 
    1058               <listitem>
    1059                 <para>Example:</para>
    1060 
    1061                 <programlisting>configure.cc    ${prefix}/bin/gcc-mp-4.2</programlisting>
    1062               </listitem>
    1063             </itemizedlist>
    1064           </listitem>
    1065         </varlistentry>
    1066 
    1067         <varlistentry>
    1068           <term>configure.cpp</term>
    1069 
    1070           <listitem>
    1071             <para>Set CPP compiler flags for selecting a C
    1072             preprocessor;</para>
    1073 
    1074             <itemizedlist>
    1075               <listitem>
    1076                 <para>Default: <literal></literal></para>
    1077               </listitem>
    1078 
    1079               <listitem>
    1080                 <para>Example:</para>
    1081 
    1082                 <programlisting>configure.cpp    /usr/bin/cpp-3.3</programlisting>
    1083               </listitem>
    1084             </itemizedlist>
    1085           </listitem>
    1086         </varlistentry>
    1087 
    1088         <varlistentry>
    1089           <term>configure.cxx</term>
    1090 
    1091           <listitem>
    1092             <para>Set CXX compiler flags for selecting a C++ compiler;</para>
    1093 
    1094             <itemizedlist>
    1095               <listitem>
    1096                 <para>Default: <literal></literal></para>
    1097               </listitem>
    1098 
    1099               <listitem>
    1100                 <para>Example:</para>
    1101 
    1102                 <programlisting>configure.cpp    /usr/bin/g++-4.0</programlisting>
    1103               </listitem>
    1104             </itemizedlist>
    1105           </listitem>
    1106         </varlistentry>
    1107 
    1108         <varlistentry>
    1109           <term>configure.objc</term>
    1110 
    1111           <listitem>
    1112             <para>Set OBJC compiler flags for selecting an Objective-C
    1113             compiler;</para>
    1114 
    1115             <itemizedlist>
    1116               <listitem>
    1117                 <para>Default: <literal></literal></para>
    1118               </listitem>
    1119 
    1120               <listitem>
    1121                 <para>Example:</para>
    1122 
    1123                 <programlisting>configure.objc    /usr/bin/gcc-4.0</programlisting>
    1124               </listitem>
    1125             </itemizedlist>
    1126           </listitem>
    1127         </varlistentry>
    1128 
    1129         <varlistentry>
    1130           <term>configure.fc</term>
    1131 
    1132           <listitem>
    1133             <para>Set FC compiler flags for selecting a Fortran
    1134             compiler;</para>
    1135 
    1136             <itemizedlist>
    1137               <listitem>
    1138                 <para>Default: <literal></literal></para>
    1139               </listitem>
    1140 
    1141               <listitem>
    1142                 <para>Example:</para>
    1143 
    1144                 <programlisting>configure.fc    ${prefix}/bin/gfortran-mp-4.2</programlisting>
    1145               </listitem>
    1146             </itemizedlist>
    1147           </listitem>
    1148         </varlistentry>
    1149 
    1150         <varlistentry>
    1151           <term>configure.f77</term>
    1152 
    1153           <listitem>
    1154             <para>Set F77 compiler flags for selecting a Fortran 77
    1155             compiler;</para>
    1156 
    1157             <itemizedlist>
    1158               <listitem>
    1159                 <para>Default: <literal></literal></para>
    1160               </listitem>
    1161 
    1162               <listitem>
    1163                 <para>Example:</para>
    1164 
    1165                 <programlisting>configure.f77    ${prefix}/bin/gfortran-mp-4.2</programlisting>
    1166               </listitem>
    1167             </itemizedlist>
    1168           </listitem>
    1169         </varlistentry>
    1170 
    1171         <varlistentry>
    1172           <term>configure.f90</term>
    1173 
    1174           <listitem>
    1175             <para>Set F90 compiler flags for selecting a Fortran 90
    1176             compiler;</para>
    1177 
    1178             <itemizedlist>
    1179               <listitem>
    1180                 <para>Default: <literal></literal></para>
    1181               </listitem>
    1182 
    1183               <listitem>
    1184                 <para>Example:</para>
    1185 
    1186                 <programlisting>configure.f90    ${prefix}/bin/gfortran-mp-4.2</programlisting>
    1187               </listitem>
    1188             </itemizedlist>
    1189           </listitem>
    1190         </varlistentry>
    1191 
    1192         <varlistentry>
    1193           <term>configure.javac</term>
    1194 
    1195           <listitem>
    1196             <para>Set JAVAC compiler flags for selecting a Java
    1197             compiler;</para>
    1198 
    1199             <itemizedlist>
    1200               <listitem>
    1201                 <para>Default: <literal></literal></para>
    1202               </listitem>
    1203 
    1204               <listitem>
    1205                 <para>Example:</para>
    1206 
    1207                 <programlisting>configure.javac    ${prefix}/bin/jikes</programlisting>
    1208               </listitem>
    1209             </itemizedlist>
    1210           </listitem>
    1211         </varlistentry>
    1212 
    1213         <varlistentry>
    1214           <term>configure.compiler</term>
    1215 
    1216           <listitem>
    1217             <para>Select a compiler suite to fill the compiler environment
    1218             variables. All variables/tools a compiler suite can provide are
    1219             set. Manually set variables are not overwritten. Dependencies are
    1220             not added for you, as they may be just build- or also
    1221             run-dependencies. Keep in mind that not all compiler suites might
    1222             be available on your platform.</para>
    1223 
    1224             <itemizedlist>
    1225               <listitem>
    1226                 <para>Default: <literal>gcc-3.3</literal>Mac OS X 10.3</para>
    1227 
    1228                 <para>Default: <literal>gcc-4.0</literal>Mac OS X 10.4,
    1229                 10.5</para>
    1230               </listitem>
    1231 
    1232               <listitem>
    1233                 <para>Options:</para>
    1234 
    1235                 <programlisting>gcc-3.3 gcc-4.0 apple-gcc-3.3 apple-gcc-4.0 macports-gcc-3.3 macports-gcc-3.4 macports-gcc-4.0 macports-gcc-4.1 macports-gcc-4.2 macports-gcc-4.3</programlisting>
    1236               </listitem>
    1237 
    1238               <listitem>
    1239                 <para>Example:</para>
    1240 
    1241                 <programlisting>configure.compiler    macports-gcc-4.2</programlisting>
    1242               </listitem>
    1243             </itemizedlist>
    1244           </listitem>
    1245         </varlistentry>
    1246 
    1247         <!-- compiler selection arguments end -->
    1248 
    1249         <!-- interpreter selection arguments -->
    1250 
    1251         <varlistentry>
    1252           <term>configure.perl</term>
    1253 
    1254           <listitem>
    1255             <para>Set PERL flag for selecting a Perl interpreter;</para>
    1256 
    1257             <itemizedlist>
    1258               <listitem>
    1259                 <para>Default: <literal></literal></para>
    1260               </listitem>
    1261 
    1262               <listitem>
    1263                 <para>Example:</para>
    1264 
    1265                 <programlisting>configure.perl    ${prefix}/bin/perl5.8</programlisting>
    1266               </listitem>
    1267             </itemizedlist>
    1268           </listitem>
    1269         </varlistentry>
    1270 
    1271         <varlistentry>
    1272           <term>configure.python</term>
    1273 
    1274           <listitem>
    1275             <para>Set PYTHON flag for selecting a Python interpreter;</para>
    1276 
    1277             <itemizedlist>
    1278               <listitem>
    1279                 <para>Default: <literal></literal></para>
    1280               </listitem>
    1281 
    1282               <listitem>
    1283                 <para>Example:</para>
    1284 
    1285                 <programlisting>configure.python    ${prefix}/bin/python3.0</programlisting>
    1286               </listitem>
    1287             </itemizedlist>
    1288           </listitem>
    1289         </varlistentry>
    1290 
    1291         <varlistentry>
    1292           <term>configure.ruby</term>
    1293 
    1294           <listitem>
    1295             <para>Set RUBY flag for selecting a Ruby interpreter;</para>
    1296 
    1297             <itemizedlist>
    1298               <listitem>
    1299                 <para>Default: <literal></literal></para>
    1300               </listitem>
    1301 
    1302               <listitem>
    1303                 <para>Example:</para>
    1304 
    1305                 <programlisting>configure.ruby    ${prefix}/bin/ruby</programlisting>
    1306               </listitem>
    1307             </itemizedlist>
    1308           </listitem>
    1309         </varlistentry>
    1310 
    1311         <!-- interpreter selection arguments end -->
    1312 
    1313         <!-- other tools selection arguments -->
    1314 
    1315         <varlistentry>
    1316           <term>configure.install</term>
    1317 
    1318           <listitem>
    1319             <para>Set INSTALL flag for selecting an install tool; used for
    1320             copying files and creating directories</para>
    1321 
    1322             <itemizedlist>
    1323               <listitem>
    1324                 <para>Default: <literal>/usr/bin/install</literal></para>
    1325               </listitem>
    1326 
    1327               <listitem>
    1328                 <para>Example:</para>
    1329 
    1330                 <programlisting>configure.install    ${prefix}/bin/ginstall</programlisting>
    1331               </listitem>
    1332             </itemizedlist>
    1333           </listitem>
    1334         </varlistentry>
    1335 
    1336         <varlistentry>
    1337           <term>configure.awk</term>
    1338 
    1339           <listitem>
    1340             <para>Set AWK flag for selecting an awk executable</para>
    1341 
    1342             <itemizedlist>
    1343               <listitem>
    1344                 <para>Default: <literal></literal></para>
    1345               </listitem>
    1346 
    1347               <listitem>
    1348                 <para>Example:</para>
    1349 
    1350                 <programlisting>configure.awk    ${prefix}/bin/gawk</programlisting>
    1351               </listitem>
    1352             </itemizedlist>
    1353           </listitem>
    1354         </varlistentry>
    1355 
    1356         <varlistentry>
    1357           <term>configure.bison</term>
    1358 
    1359           <listitem>
    1360             <para>Set BISON flag for selecting a bison executable, a parser
    1361             generator</para>
    1362 
    1363             <itemizedlist>
    1364               <listitem>
    1365                 <para>Default: <literal></literal></para>
    1366               </listitem>
    1367 
    1368               <listitem>
    1369                 <para>Example:</para>
    1370 
    1371                 <programlisting>configure.bison    /usr/bin/bison</programlisting>
    1372               </listitem>
    1373             </itemizedlist>
    1374           </listitem>
    1375         </varlistentry>
    1376 
    1377         <varlistentry>
    1378           <term>configure.pkg_config</term>
    1379 
    1380           <listitem>
    1381             <para>Set PKG_CONFIG flag for helping find pkg_config, a tool for
    1382             retrieving information about installed libraries.</para>
    1383 
    1384             <itemizedlist>
    1385               <listitem>
    1386                 <para>Default: <literal></literal></para>
    1387               </listitem>
    1388 
    1389               <listitem>
    1390                 <para>Example:</para>
    1391 
    1392                 <programlisting>configure.pkg_config    ${prefix}/bin/pkg-config</programlisting>
    1393               </listitem>
    1394             </itemizedlist>
    1395           </listitem>
    1396         </varlistentry>
    1397 
    1398         <varlistentry>
    1399           <term>configure.pkg_config_path</term>
    1400 
    1401           <listitem>
    1402             <para>Set PKG_CONFIG_PATH flag for telling pkg_config where to
    1403             search for information about installed libraries.</para>
    1404 
    1405             <itemizedlist>
    1406               <listitem>
    1407                 <para>Default: <literal></literal></para>
    1408               </listitem>
    1409 
    1410               <listitem>
    1411                 <para>Example:</para>
    1412 
    1413                 <programlisting>configure.pkg_config_path    ${prefix}/lib/pkgconfig:${x11prefix}/lib/pkgconfig</programlisting>
    1414               </listitem>
    1415             </itemizedlist>
    1416           </listitem>
    1417         </varlistentry>
    1418 
    1419         <!-- other tools selection arguments end -->
    1420 
    1421         <varlistentry>
    1422           <term>configure.args</term>
    1423 
    1424           <term>configure.pre_args</term>
    1425 
    1426           <term>configure.post_args</term>
    1427 
    1428           <listitem>
    1429             <para>Main arguments to configure.cmd; optional argument modifiers
    1430             pass arguments before and after the main arguments.</para>
    1431 
    1432             <itemizedlist>
    1433               <listitem>
    1434                 <para>Default: none</para>
    1435               </listitem>
    1436 
    1437               <listitem>
    1438                 <para>Example:</para>
    1439 
    1440                 <programlisting>configure.args    --bindir=${prefix}/bin
    1441 
    1442 </programlisting>
    1443               </listitem>
    1444             </itemizedlist>
    1445           </listitem>
    1446 
    1447           <listitem>
    1448             <para>The following argument modifiers are available:</para>
    1449 
    1450             <itemizedlist>
    1451               <listitem>
    1452                 <para>configure.pre_args default: --prefix=${prefix}</para>
    1453               </listitem>
    1454 
    1455               <listitem>
    1456                 <para>configure.post_args default: none</para>
    1457               </listitem>
    1458 
    1459               <listitem>
    1460                 <para>Examples:</para>
    1461 
    1462                 <programlisting>configure.pre_args   --prefix=${prefix}/share/bro
    1463 configure.post_args  OPT="-D__DARWIN_UNIX03"</programlisting>
    1464               </listitem>
    1465             </itemizedlist>
    1466           </listitem>
    1467         </varlistentry>
    1468       </variablelist>
    1469 
    1470       <section>
    1471         <title>Configure Universal</title>
    1472 
    1473         <para>Universal keywords are used to make a port compile on the OS X
    1474         platform to run on either PPC or Intel.</para>
    1475 
    1476         <note>
    1477           <para>There is a default universal variant made available to all
    1478           ports by MacPorts base, so redefining universal keywords should only
    1479           be done to make a given port compile if the default options fail to
    1480           do so.</para>
    1481         </note>
    1482 
    1483         <variablelist>
    1484           <varlistentry>
    1485             <term>configure.universal_args</term>
    1486 
    1487             <listitem>
    1488               <para>Arguments used in the configure script to build the port
    1489               universal.</para>
    1490 
    1491               <itemizedlist>
    1492                 <listitem>
    1493                   <para>Default: --disable-dependency-tracking</para>
    1494                 </listitem>
    1495 
    1496                 <listitem>
    1497                   <para>Example:</para>
    1498 
    1499                   <programlisting></programlisting>
    1500                 </listitem>
    1501               </itemizedlist>
    1502             </listitem>
    1503           </varlistentry>
    1504 
    1505           <varlistentry>
    1506             <term>configure.universal_cflags</term>
    1507 
    1508             <listitem>
    1509               <para>Arguments appended to the configure script to build the
    1510               port universal.</para>
    1511 
    1512               <itemizedlist>
    1513                 <listitem>
    1514                   <para>Default: -sysroot /Developer/SDKs/MacOSX10.4u.sdk
    1515                   -arch i386 -arch ppc</para>
    1516                 </listitem>
    1517 
    1518                 <listitem>
    1519                   <para>Example:</para>
    1520 
    1521                   <programlisting></programlisting>
    1522                 </listitem>
    1523               </itemizedlist>
    1524             </listitem>
    1525           </varlistentry>
    1526 
    1527           <varlistentry>
    1528             <term>configure.universal_cppflags</term>
    1529 
    1530             <listitem>
    1531               <para>Additional flags to put in the CPPFLAGS environment
    1532               variable when invoking the configure script.</para>
    1533 
    1534               <itemizedlist>
    1535                 <listitem>
    1536                   <para>Default: ???</para>
    1537                 </listitem>
    1538 
    1539                 <listitem>
    1540                   <para>Example:</para>
    1541 
    1542                   <programlisting></programlisting>
    1543                 </listitem>
    1544               </itemizedlist>
    1545             </listitem>
    1546           </varlistentry>
    1547 
    1548           <varlistentry>
    1549             <term>configure.universal_cxxflags</term>
    1550 
    1551             <listitem>
    1552               <para>Additional flags to put in the CXXFLAGS environment
    1553               variable when invoking the configure script.</para>
    1554 
    1555               <itemizedlist>
    1556                 <listitem>
    1557                   <para>Default: -isysroot /Developer/SDKs/MacOSX10.4u.sdk
    1558                   -arch i386 -arch ppc</para>
    1559                 </listitem>
    1560 
    1561                 <listitem>
    1562                   <para>Example:</para>
    1563 
    1564                   <programlisting></programlisting>
    1565                 </listitem>
    1566               </itemizedlist>
    1567             </listitem>
    1568           </varlistentry>
    1569 
    1570           <varlistentry>
    1571             <term>configure.universal_ldflags</term>
    1572 
    1573             <listitem>
    1574               <para>Additional flags to put in the LDFLAGS environment
    1575               variable when invoking the configure script.</para>
    1576 
    1577               <itemizedlist>
    1578                 <listitem>
    1579                   <para>Default: -arch i386 -arch ppc</para>
    1580                 </listitem>
    1581 
    1582                 <listitem>
    1583                   <para>Example:</para>
    1584 
    1585                   <programlisting></programlisting>
    1586                 </listitem>
    1587               </itemizedlist>
    1588             </listitem>
    1589           </varlistentry>
    1590         </variablelist>
    1591       </section>
    1592 
    1593       <section>
    1594         <title>Automake and Autoconf</title>
    1595 
    1596         <para>The list of configure keywords available for ports that need
    1597         automake and/or autoconf.</para>
    1598 
    1599         <variablelist>
    1600           <varlistentry>
    1601             <term>use_automake</term>
    1602 
    1603             <listitem>
    1604               <para>Whether or not to use automake; the default is
    1605               "no".</para>
    1606 
    1607               <programlisting>use_automake      yes</programlisting>
    1608             </listitem>
    1609           </varlistentry>
    1610 
    1611           <varlistentry>
    1612             <term>automake.env</term>
    1613 
    1614             <listitem>
    1615               <para>Environment variables to pass to automake.</para>
    1616 
    1617               <programlisting>automake.env      CFLAGS=-I${prefix}/include</programlisting>
    1618             </listitem>
    1619           </varlistentry>
    1620 
    1621           <varlistentry>
    1622             <term>automake.args</term>
    1623 
    1624             <listitem>
    1625               <para>Arguments to pass to automake.</para>
    1626 
    1627               <programlisting>automake.args     --foreign</programlisting>
    1628             </listitem>
    1629           </varlistentry>
    1630 
    1631           <varlistentry>
    1632             <term>automake.dir</term>
    1633 
    1634             <listitem>
    1635               <para>Directory in which to run
    1636               <varname>${automake.cmd}</varname>; the default is
    1637               <varname>${worksrcpath}</varname>.</para>
    1638 
    1639               <programlisting>automake.dir      ./src</programlisting>
    1640             </listitem>
    1641           </varlistentry>
    1642 
    1643           <varlistentry>
    1644             <term>use_autoconf</term>
    1645 
    1646             <listitem>
    1647               <para>Whether or not to use autoconf; the default is
    1648               "no".</para>
    1649 
    1650               <programlisting>use_autoconf      yes</programlisting>
    1651             </listitem>
    1652           </varlistentry>
    1653 
    1654           <varlistentry>
    1655             <term>autoconf.env</term>
    1656 
    1657             <listitem>
    1658               <para>Environmental variables to pass to autoconf.</para>
    1659 
    1660               <programlisting>autoconf.env      CFLAGS=-I${prefix}/include/gtk12</programlisting>
    1661             </listitem>
    1662           </varlistentry>
    1663 
    1664           <varlistentry>
    1665             <term>autoconf.args</term>
    1666 
    1667             <listitem>
    1668               <para>Arguments to pass to autoconf.</para>
    1669 
    1670               <programlisting>autoconf.args     -l src/aclocaldir</programlisting>
    1671             </listitem>
    1672           </varlistentry>
    1673 
    1674           <varlistentry>
    1675             <term>autoconf.dir</term>
    1676 
    1677             <listitem>
    1678               <para>Directory in which to run
    1679               <varname>${autoconf.cmd}</varname>; the default is
    1680               <varname>${worksrcpath}</varname>.</para>
    1681 
    1682               <programlisting>autoconf.dir      src</programlisting>
    1683             </listitem>
    1684           </varlistentry>
    1685         </variablelist>
    1686       </section>
    1687     </section>
    1688 
    1689     <section>
    1690       <title>Build Phase Keywords</title>
    1691 
    1692       <para>The list of keywords related to the build phase.</para>
    1693 
    1694       <variablelist>
    1695         <varlistentry>
    1696           <term>build.cmd</term>
    1697 
    1698           <listitem>
    1699             <para>Make command to run in <varname>${worksrcdir}</varname>; the
    1700             default is "make".</para>
    1701 
    1702             <programlisting>build.cmd      pbxbuild</programlisting>
    1703           </listitem>
    1704         </varlistentry>
    1705 
    1706         <varlistentry>
    1707           <term>build.type</term>
    1708 
    1709           <listitem>
    1710             <para>Defines which "make" is required: "gnu" or "bsd". Sets
    1711             build.cmd to either "gnumake" or "bsdmake" accordingly.</para>
    1712 
    1713             <programlisting>build.type     gnu</programlisting>
    1714           </listitem>
    1715         </varlistentry>
    1716 
    1717         <varlistentry>
    1718           <term>build.args</term>
    1719 
    1720           <term>build.pre_args</term>
    1721 
    1722           <term>build.post_args</term>
    1723 
    1724           <listitem>
    1725             <para>Main arguments to build.cmd; optional argument modifiers
    1726             pass arguments before and after the main arguments.</para>
    1727 
    1728             <itemizedlist>
    1729               <listitem>
    1730                 <para>Default: none</para>
    1731               </listitem>
    1732 
    1733               <listitem>
    1734                 <para>Example:</para>
    1735 
    1736                 <programlisting>build.args    -DNOWARN
    1737 
    1738 </programlisting>
    1739               </listitem>
    1740             </itemizedlist>
    1741           </listitem>
    1742 
    1743           <listitem>
    1744             <para>The following argument modifiers are available:</para>
    1745 
    1746             <itemizedlist>
    1747               <listitem>
    1748                 <para>build.pre_args default:
    1749                 <varname>${build.target.current}</varname></para>
    1750               </listitem>
    1751 
    1752               <listitem>
    1753                 <para>build.post_args default: none</para>
    1754               </listitem>
    1755 
    1756               <listitem>
    1757                 <para>Examples:</para>
    1758 
    1759                 <programlisting>build.pre_args  -project AudioSlicer.xcode
    1760 build.post_args CFLAGS_SYS="-DUSE_FREETYPE -DPREFER_FREETYPE"</programlisting>
    1761               </listitem>
    1762             </itemizedlist>
    1763           </listitem>
    1764         </varlistentry>
    1765 
    1766         <varlistentry>
    1767           <term>build.target</term>
    1768 
    1769           <term>build.target-append</term>
    1770 
    1771           <term>build.target-delete</term>
    1772 
    1773           <listitem>
    1774             <para>Build target to pass to ${build.cmd}; list modifiers add or
    1775             delete items from a previous Portfile build.target keyword or the
    1776             default set by MacPorts base.</para>
    1777 
    1778             <itemizedlist>
    1779               <listitem>
    1780                 <para>Default: all</para>
    1781               </listitem>
    1782 
    1783               <listitem>
    1784                 <para>Example:</para>
    1785 
    1786                 <programlisting>build.target    all-src
    1787 
    1788 </programlisting>
    1789               </listitem>
    1790             </itemizedlist>
    1791           </listitem>
    1792 
    1793           <listitem>
    1794             <para>List modifier examples:</para>
    1795 
    1796             <programlisting>build.target-append   doc extra
    1797 build.target-delete   compat</programlisting>
    1798           </listitem>
    1799         </varlistentry>
    1800 
    1801         <varlistentry>
    1802           <term>use_parallel_build</term>
    1803 
    1804           <listitem>
    1805             <para>This keyword is for specifying whether or not it is safe for
    1806             a port to use multiple cpus or multiple cores in parallel during
    1807             its build phase. If a port is declared to be builadble this way,
    1808             the option <option>-j N</option> may be passed to the
    1809             <command>make</command> command if parallel builds are enabled
    1810             system-wide.  This can be obtained by setting
    1811             <varname>buildmakejobs</varname> in
    1812             <filename>macports.conf</filename>. The integer <option>N</option>
    1813             refers to the number of parallel build threads.</para>
    1814 
    1815             <itemizedlist>
    1816               <listitem>
    1817                 <para>Default: <option>no</option></para>
    1818               </listitem>
    1819 
    1820               <listitem>
    1821                 <para>Example:</para>
    1822 
    1823                 <programlisting>use_parallel_build     yes</programlisting>
    1824               </listitem>
    1825             </itemizedlist>
    1826           </listitem>
    1827         </varlistentry>
    1828       </variablelist>
    1829     </section>
    1830 
    1831     <section>
    1832       <title>Destroot Phase Keywords</title>
    1833 
    1834       <para>The list of keywords related to the destroot phase.</para>
    1835 
    1836       <variablelist>
    1837         <varlistentry>
    1838           <term>destroot.cmd</term>
    1839 
    1840           <listitem>
    1841             <para>Install command to run relative to
    1842             <varname>${worksrcdir}</varname>; default is
    1843             <varname>${build.cmd}</varname>.</para>
    1844 
    1845             <programlisting>destroot.cmd         pbxbuild</programlisting>
    1846           </listitem>
    1847         </varlistentry>
    1848 
    1849         <varlistentry>
    1850           <term>destroot.type</term>
    1851 
    1852           <listitem>
    1853             <para>Defines which "make" is required: either "gnu" or "bsd".
    1854             Sets install.cmd to either "gnumake" or "bsdmake"
    1855             accordingly.</para>
    1856 
    1857             <programlisting>destroot.type        gnu</programlisting>
    1858           </listitem>
    1859         </varlistentry>
    1860 
    1861         <varlistentry>
    1862           <term>destroot.args</term>
    1863 
    1864           <term>destroot.pre_args</term>
    1865 
    1866           <term>destroot.post_args</term>
    1867 
    1868           <listitem>
    1869             <para>Main arguments to ${destroot.cmd}; optional argument
    1870             modifiers pass arguments before and after the main
    1871             arguments.</para>
    1872 
    1873             <itemizedlist>
    1874               <listitem>
    1875                 <para>Default: none</para>
    1876               </listitem>
    1877 
    1878               <listitem>
    1879                 <para>Example:</para>
    1880 
    1881                 <programlisting>destroot.args    BINDIR=${prefix}/bin
    1882 
    1883 </programlisting>
    1884               </listitem>
    1885             </itemizedlist>
    1886           </listitem>
    1887 
    1888           <listitem>
    1889             <para>The following argument modifiers are available:</para>
    1890 
    1891             <itemizedlist>
    1892               <listitem>
    1893                 <para>destroot.pre_args default:
    1894                 <varname>${destroot.target}</varname></para>
    1895               </listitem>
    1896 
    1897               <listitem>
    1898                 <para>destroot.post_args default: none</para>
    1899               </listitem>
    1900 
    1901               <listitem>
    1902                 <para>Examples:</para>
    1903 
    1904                 <programlisting>destroot.pre_args  -project AudioSlicer.xcode
    1905 destroot.post_args INSTDIR=${destroot}${prefix}</programlisting>
    1906               </listitem>
    1907             </itemizedlist>
    1908           </listitem>
    1909         </varlistentry>
    1910 
    1911         <varlistentry>
    1912           <term>destroot.target</term>
    1913 
    1914           <term>destroot.target-append</term>
    1915 
    1916           <term>destroot.target-delete</term>
    1917 
    1918           <listitem>
    1919             <para>Install target to pass to ${destroot.cmd}; list modifiers
    1920             add or delete items from a previous Portfile destroot.target
    1921             keyword or the default set by MacPorts base.</para>
    1922 
    1923             <itemizedlist>
    1924               <listitem>
    1925                 <para>Default: <literal>install</literal></para>
    1926               </listitem>
    1927 
    1928               <listitem>
    1929                 <para>Example:</para>
    1930 
    1931                 <programlisting>destroot.target    install install-config install-commandmode
    1932 
    1933 </programlisting>
    1934               </listitem>
    1935             </itemizedlist>
    1936           </listitem>
    1937 
    1938           <listitem>
    1939             <para>List modifier examples:</para>
    1940 
    1941             <programlisting>destroot.target-append   install-plugins
    1942 destroot.target-delete   install-commandmode</programlisting>
    1943           </listitem>
    1944         </varlistentry>
    1945 
    1946         <varlistentry>
    1947           <term>destroot.destdir</term>
    1948 
    1949           <listitem>
    1950             <para>Arguments passed to ${destroot.cmd} to install correctly
    1951             into the destroot.</para>
    1952 
    1953             <programlisting>destroot.destdir     prefix=${destroot}${prefix}</programlisting>
    1954 
    1955             <note>
    1956               <para>If an application's Makefile properly supports the DESTDIR
    1957               variable, MacPorts will automatically destroot the port
    1958               properly. A port must destroot properly or the port will not
    1959               install correctly, upgrade, or uninstall. If not, you may need
    1960               to set this variable, or even patch the application's
    1961               Makefile.</para>
    1962             </note>
    1963           </listitem>
    1964         </varlistentry>
    1965 
    1966         <varlistentry>
    1967           <term>destroot.keepdirs</term>
    1968 
    1969           <listitem>
    1970             <para>A list of directories that should not be removed if empty
    1971             upon destroot completion.</para>
    1972 
    1973             <programlisting>destroot.keepdirs \
    1974                 ${destroot}${prefix}/var/run \
    1975                 ${destroot}${prefix}/var/log \
    1976                 ${destroot}${prefix}/var/cache/mrtg</programlisting>
    1977           </listitem>
    1978         </varlistentry>
    1979 
    1980         <varlistentry>
    1981           <term>destroot.violate_mtree</term>
    1982 
    1983           <listitem>
    1984             <para>MacPorts tests for compliance to the common directory
    1985             structure in ${prefix}; the default is "no". If a port is not
    1986             compliant with the standard, set it to "yes".</para>
    1987 
    1988             <programlisting>destroot.violate_mtree    yes</programlisting>
     1678            <para>Directory in which to run
     1679            <varname>${autoconf.cmd}</varname>; the default is
     1680            <varname>${worksrcpath}</varname>.</para>
     1681
     1682            <programlisting>autoconf.dir      src</programlisting>
    19891683          </listitem>
    19901684        </varlistentry>
     
    19921686    </section>
    19931687  </section>
     1688
     1689  <section>
     1690    <title>Build Phase Keywords</title>
     1691
     1692    <para>The list of keywords related to the build phase.</para>
     1693
     1694    <variablelist>
     1695      <varlistentry>
     1696        <term>build.cmd</term>
     1697
     1698        <listitem>
     1699          <para>Make command to run in <varname>${worksrcdir}</varname>; the
     1700          default is "make".</para>
     1701
     1702          <programlisting>build.cmd      pbxbuild</programlisting>
     1703        </listitem>
     1704      </varlistentry>
     1705
     1706      <varlistentry>
     1707        <term>build.type</term>
     1708
     1709        <listitem>
     1710          <para>Defines which "make" is required: "gnu" or "bsd". Sets
     1711          build.cmd to either "gnumake" or "bsdmake" accordingly.</para>
     1712
     1713          <programlisting>build.type     gnu</programlisting>
     1714        </listitem>
     1715      </varlistentry>
     1716
     1717      <varlistentry>
     1718        <term>build.args</term>
     1719
     1720        <term>build.pre_args</term>
     1721
     1722        <term>build.post_args</term>
     1723
     1724        <listitem>
     1725          <para>Main arguments to build.cmd; optional argument modifiers
     1726          pass arguments before and after the main arguments.</para>
     1727
     1728          <itemizedlist>
     1729            <listitem>
     1730              <para>Default: none</para>
     1731            </listitem>
     1732
     1733            <listitem>
     1734              <para>Example:</para>
     1735
     1736              <programlisting>build.args    -DNOWARN
     1737
     1738</programlisting>
     1739            </listitem>
     1740          </itemizedlist>
     1741        </listitem>
     1742
     1743        <listitem>
     1744          <para>The following argument modifiers are available:</para>
     1745
     1746          <itemizedlist>
     1747            <listitem>
     1748              <para>build.pre_args default:
     1749              <varname>${build.target.current}</varname></para>
     1750            </listitem>
     1751
     1752            <listitem>
     1753              <para>build.post_args default: none</para>
     1754            </listitem>
     1755
     1756            <listitem>
     1757              <para>Examples:</para>
     1758
     1759              <programlisting>build.pre_args  -project AudioSlicer.xcode
     1760build.post_args CFLAGS_SYS="-DUSE_FREETYPE -DPREFER_FREETYPE"</programlisting>
     1761            </listitem>
     1762          </itemizedlist>
     1763        </listitem>
     1764      </varlistentry>
     1765
     1766      <varlistentry>
     1767        <term>build.target</term>
     1768
     1769        <term>build.target-append</term>
     1770
     1771        <term>build.target-delete</term>
     1772
     1773        <listitem>
     1774          <para>Build target to pass to ${build.cmd}; list modifiers add or
     1775          delete items from a previous Portfile build.target keyword or the
     1776          default set by MacPorts base.</para>
     1777
     1778          <itemizedlist>
     1779            <listitem>
     1780              <para>Default: all</para>
     1781            </listitem>
     1782
     1783            <listitem>
     1784              <para>Example:</para>
     1785
     1786              <programlisting>build.target    all-src
     1787
     1788</programlisting>
     1789            </listitem>
     1790          </itemizedlist>
     1791        </listitem>
     1792
     1793        <listitem>
     1794          <para>List modifier examples:</para>
     1795
     1796          <programlisting>build.target-append   doc extra
     1797build.target-delete   compat</programlisting>
     1798        </listitem>
     1799      </varlistentry>
     1800
     1801      <varlistentry>
     1802        <term>use_parallel_build</term>
     1803
     1804        <listitem>
     1805          <para>This keyword is for specifying whether or not it is safe for
     1806          a port to use multiple cpus or multiple cores in parallel during
     1807          its build phase. If a port is declared to be builadble this way,
     1808          the option <option>-j N</option> may be passed to the
     1809          <command>make</command> command if parallel builds are enabled
     1810          system-wide.  This can be obtained by setting
     1811          <varname>buildmakejobs</varname> in
     1812          <filename>macports.conf</filename>. The integer <option>N</option>
     1813          refers to the number of parallel build threads.</para>
     1814
     1815          <itemizedlist>
     1816            <listitem>
     1817              <para>Default: <option>no</option></para>
     1818            </listitem>
     1819
     1820            <listitem>
     1821              <para>Example:</para>
     1822
     1823              <programlisting>use_parallel_build     yes</programlisting>
     1824            </listitem>
     1825          </itemizedlist>
     1826        </listitem>
     1827      </varlistentry>
     1828    </variablelist>
     1829  </section>
     1830
     1831  <section>
     1832    <title>Destroot Phase Keywords</title>
     1833
     1834    <para>The list of keywords related to the destroot phase.</para>
     1835
     1836    <variablelist>
     1837      <varlistentry>
     1838        <term>destroot.cmd</term>
     1839
     1840        <listitem>
     1841          <para>Install command to run relative to
     1842          <varname>${worksrcdir}</varname>; default is
     1843          <varname>${build.cmd}</varname>.</para>
     1844
     1845          <programlisting>destroot.cmd         pbxbuild</programlisting>
     1846        </listitem>
     1847      </varlistentry>
     1848
     1849      <varlistentry>
     1850        <term>destroot.type</term>
     1851
     1852        <listitem>
     1853          <para>Defines which "make" is required: either "gnu" or "bsd".
     1854          Sets install.cmd to either "gnumake" or "bsdmake"
     1855          accordingly.</para>
     1856
     1857          <programlisting>destroot.type        gnu</programlisting>
     1858        </listitem>
     1859      </varlistentry>
     1860
     1861      <varlistentry>
     1862        <term>destroot.args</term>
     1863
     1864        <term>destroot.pre_args</term>
     1865
     1866        <term>destroot.post_args</term>
     1867
     1868        <listitem>
     1869          <para>Main arguments to ${destroot.cmd}; optional argument
     1870          modifiers pass arguments before and after the main
     1871          arguments.</para>
     1872
     1873          <itemizedlist>
     1874            <listitem>
     1875              <para>Default: none</para>
     1876            </listitem>
     1877
     1878            <listitem>
     1879              <para>Example:</para>
     1880
     1881              <programlisting>destroot.args    BINDIR=${prefix}/bin
     1882
     1883</programlisting>
     1884            </listitem>
     1885          </itemizedlist>
     1886        </listitem>
     1887
     1888        <listitem>
     1889          <para>The following argument modifiers are available:</para>
     1890
     1891          <itemizedlist>
     1892            <listitem>
     1893              <para>destroot.pre_args default:
     1894              <varname>${destroot.target}</varname></para>
     1895            </listitem>
     1896
     1897            <listitem>
     1898              <para>destroot.post_args default: none</para>
     1899            </listitem>
     1900
     1901            <listitem>
     1902              <para>Examples:</para>
     1903
     1904              <programlisting>destroot.pre_args  -project AudioSlicer.xcode
     1905destroot.post_args INSTDIR=${destroot}${prefix}</programlisting>
     1906            </listitem>
     1907          </itemizedlist>
     1908        </listitem>
     1909      </varlistentry>
     1910
     1911      <varlistentry>
     1912        <term>destroot.target</term>
     1913
     1914        <term>destroot.target-append</term>
     1915
     1916        <term>destroot.target-delete</term>
     1917
     1918        <listitem>
     1919          <para>Install target to pass to ${destroot.cmd}; list modifiers
     1920          add or delete items from a previous Portfile destroot.target
     1921          keyword or the default set by MacPorts base.</para>
     1922
     1923          <itemizedlist>
     1924            <listitem>
     1925              <para>Default: <literal>install</literal></para>
     1926            </listitem>
     1927
     1928            <listitem>
     1929              <para>Example:</para>
     1930
     1931              <programlisting>destroot.target    install install-config install-commandmode
     1932
     1933</programlisting>
     1934            </listitem>
     1935          </itemizedlist>
     1936        </listitem>
     1937
     1938        <listitem>
     1939          <para>List modifier examples:</para>
     1940
     1941          <programlisting>destroot.target-append   install-plugins
     1942destroot.target-delete   install-commandmode</programlisting>
     1943        </listitem>
     1944      </varlistentry>
     1945
     1946      <varlistentry>
     1947        <term>destroot.destdir</term>
     1948
     1949        <listitem>
     1950          <para>Arguments passed to ${destroot.cmd} to install correctly
     1951          into the destroot.</para>
     1952
     1953          <programlisting>destroot.destdir     prefix=${destroot}${prefix}</programlisting>
     1954
     1955          <note>
     1956            <para>If an application's Makefile properly supports the DESTDIR
     1957            variable, MacPorts will automatically destroot the port
     1958            properly. A port must destroot properly or the port will not
     1959            install correctly, upgrade, or uninstall. If not, you may need
     1960            to set this variable, or even patch the application's
     1961            Makefile.</para>
     1962          </note>
     1963        </listitem>
     1964      </varlistentry>
     1965
     1966      <varlistentry>
     1967        <term>destroot.keepdirs</term>
     1968
     1969        <listitem>
     1970          <para>A list of directories that should not be removed if empty
     1971          upon destroot completion.</para>
     1972
     1973          <programlisting>destroot.keepdirs \
     1974              ${destroot}${prefix}/var/run \
     1975              ${destroot}${prefix}/var/log \
     1976              ${destroot}${prefix}/var/cache/mrtg</programlisting>
     1977        </listitem>
     1978      </varlistentry>
     1979
     1980      <varlistentry>
     1981        <term>destroot.violate_mtree</term>
     1982
     1983        <listitem>
     1984          <para>MacPorts tests for compliance to the common directory
     1985          structure in ${prefix}; the default is "no". If a port is not
     1986          compliant with the standard, set it to "yes".</para>
     1987
     1988          <programlisting>destroot.violate_mtree    yes</programlisting>
     1989        </listitem>
     1990      </varlistentry>
     1991    </variablelist>
     1992  </section>
     1993
     1994</section>
  • trunk/doc-new/guide/xml/portfile-startupitem.7.xml

    r31445 r31621  
    33"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
    44
    5     <section>
    6       <title>StartupItems</title>
    7 
    8       <para>A StartupItem is a MacPort facility to run "daemons," a Unix term
    9       for programs that run continuously in the background, rather than under
    10       the direct control of a user; for example, mail servers, network
    11       listeners, etc. Ports that use StartupItem keywords create Mac OS X
    12       scripts for <ulink
    13       url="http://developer.apple.com/macosx/launchd.html">launchd</ulink>,
    14       which is the Apple facility introduced with OS X 10.4 to replace xinetd
    15       for starting and managing daemons. To support
    16       <command>launchd</command>, a program named <command>daemondo</command>
    17       is provided by MacPorts base that serves as an adapter between OS X's
    18       <command>launchd</command> and daemons (<quote>executable</quote>
    19       StartupItems) or traditional Unix startup scripts that start daemons
    20       (<quote>script</quote> StartupItems).</para>
    21 
    22       <para>There are three categories of StartupItem keywords. Those that
    23       trigger StartupItem creation and logging, those that specify attributes
    24       of <quote>executable</quote> StartupItems, and those that specify
    25       attributes of <quote>script</quote> StartupItems.</para>
    26 
    27       <note>
    28         <para>The variable <varname>startupitem_type</varname> in
    29         ${prefix}/etc/macports/macports.conf may be set to
    30         <option>none</option> to globally override all StartupItem keywords
    31         found in Portfiles; this prevents StartupItems from being
    32         created.</para>
    33       </note>
    34 
    35       <section>
    36         <title>StartupItem Attributes</title>
    37 
    38         <para>The keywords in this section may be used with either
    39         <quote>executable</quote> or <quote>script</quote> StartupItems (see
    40         below).</para>
    41 
    42         <variablelist>
    43           <varlistentry>
    44             <term>startupitem.create</term>
    45 
    46             <listitem>
    47               <para>Trigger the creation of a StartupItem.</para>
    48 
    49               <itemizedlist>
    50                 <listitem>
    51                   <para>Type: optional</para>
    52                 </listitem>
    53 
    54                 <listitem>
    55                   <para>Default: no</para>
    56                 </listitem>
    57 
    58                 <listitem>
    59                   <para>Values: yes no</para>
    60                 </listitem>
    61 
    62                 <listitem>
    63                   <para>Example:</para>
    64 
    65                   <programlisting>startupitem.create  yes</programlisting>
    66                 </listitem>
    67               </itemizedlist>
    68             </listitem>
    69           </varlistentry>
    70 
    71           <varlistentry>
    72             <term>startupitem.name</term>
    73 
    74             <listitem>
    75               <para>Sets the name for the StartupItem.</para>
    76 
    77               <itemizedlist>
    78                 <listitem>
    79                   <para>Type: required</para>
    80                 </listitem>
    81 
    82                 <listitem>
    83                   <para>Default: none</para>
    84                 </listitem>
    85 
    86                 <listitem>
    87                   <para>Values: <replaceable>any_name</replaceable></para>
    88                 </listitem>
    89 
    90                 <listitem>
    91                   <para>Example:</para>
    92 
    93                   <programlisting>startupitem.name  OpenSSH</programlisting>
    94                 </listitem>
    95               </itemizedlist>
    96             </listitem>
    97           </varlistentry>
    98 
    99           <varlistentry>
    100             <term>startupitem.logfile</term>
    101 
    102             <listitem>
    103               <para>Path to a logfile for logging events about the lifetime of
    104               the StartupItem. Depending on the type of StartupItem, and the
    105               manner in which it is started, standard output from the daemon
    106               may also be directed to the logfile.</para>
    107 
    108               <itemizedlist>
    109                 <listitem>
    110                   <para>Type: optional</para>
    111                 </listitem>
    112 
    113                 <listitem>
    114                   <para>Default: <filename>/dev/null</filename></para>
    115                 </listitem>
    116 
    117                 <listitem>
    118                   <para>Values: <replaceable>/file/path</replaceable></para>
    119                 </listitem>
    120 
    121                 <listitem>
    122                   <para>Example:</para>
    123 
    124                   <programlisting>startupitem.logfile  ${prefix}/var/log/mydaemon.log</programlisting>
    125                 </listitem>
    126               </itemizedlist>
    127             </listitem>
    128           </varlistentry>
    129 
    130           <varlistentry>
    131             <term>startupitem.logevents</term>
    132 
    133             <listitem>
    134               <para>Control whether or not to log events to the log file. If
    135               logevents is set, events with timestamps are logged to the
    136               logfile.</para>
    137 
    138               <itemizedlist>
    139                 <listitem>
    140                   <para>Type: optional</para>
    141                 </listitem>
    142 
    143                 <listitem>
    144                   <para>Default: no</para>
    145                 </listitem>
    146 
    147                 <listitem>
    148                   <para>Values: yes no</para>
    149                 </listitem>
    150 
    151                 <listitem>
    152                   <para>Example:</para>
    153 
    154                   <programlisting>startupitem.logevents   yes</programlisting>
    155                 </listitem>
    156               </itemizedlist>
    157             </listitem>
    158           </varlistentry>
    159 
    160           <varlistentry>
    161             <term>startupitem.netchange</term>
    162 
    163             <listitem>
    164               <para>Cause the daemon to be restarted when a change in network
    165               state is detected.</para>
    166 
    167               <itemizedlist>
    168                 <listitem>
    169                   <para>Type: optional</para>
    170                 </listitem>
    171 
    172                 <listitem>
    173                   <para>Default: no</para>
    174                 </listitem>
    175 
    176                 <listitem>
    177                   <para>Values: yes no</para>
    178                 </listitem>
    179 
    180                 <listitem>
    181                   <para>Example:</para>
    182 
    183                   <programlisting>startupitem.netchange  yes</programlisting>
    184                 </listitem>
    185               </itemizedlist>
    186             </listitem>
    187           </varlistentry>
    188         </variablelist>
    189       </section>
    190 
    191       <section>
    192         <title>Executable StartupItems</title>
    193 
    194         <para>Daemons run continuously, so monitoring the health of daemon
    195         processes and restarting them if they die is an important
    196         StartupItems' feature. <quote>Executable</quote> StartupItems are
    197         preferred over <quote>script</quote> StartupItems because
    198         <command>daemondo</command> launches the daemon
    199         <emphasis>directly</emphasis>, rather than
    200         <emphasis>indirectly</emphasis> via a script, and therefore it
    201         automatically knows how to monitor a daemon process and restart it if
    202         it dies. Daemons used with <quote>executable</quote> StartupItems may
    203         be programs or scripts (shell, perl, python, etc.), but when a script
    204         the script <emphasis>itself</emphasis> must be the daemon, rather than
    205         a script that launches a daemon. <quote>Script</quote> StartupItems
    206         are to be used for the latter.</para>
    207 
    208         <note>
    209           <para>For a given port, the <quote>executable</quote> StartupItem
    210           keyword may not be used with any keywords in the
    211           <quote>script</quote> StartupItem category.</para>
    212         </note>
    213 
    214         <variablelist>
    215           <varlistentry>
    216             <term>startupitem.executable</term>
    217 
    218             <listitem>
    219               <para>Specifies the name of the daemon to be run in the
    220               background. It may have multiple arguments, but they must be
    221               appropriate for a call to exec; arbitrary shell code may not be
    222               used.</para>
    223 
    224               <itemizedlist>
    225                 <listitem>
    226                   <para>Type: optional</para>
    227                 </listitem>
    228 
    229                 <listitem>
    230                   <para>Default: no</para>
    231                 </listitem>
    232 
    233                 <listitem>
    234                   <para>Values: <replaceable>/path/to/daemon</replaceable>
    235                   [<replaceable>args</replaceable>]</para>
    236                 </listitem>
    237 
    238                 <listitem>
    239                   <para>Example:</para>
    240 
    241                   <programlisting>startupitem.executable  ${prefix}/sbin/vm-pop3d -d 10 -t 600</programlisting>
    242                 </listitem>
    243               </itemizedlist>
    244 
    245               <note>
    246                 <para>Do not to wrap the value in quotes if passing arguments
    247                 to the daemon; unlike with<quote>script</quote> StartupItem
    248                 values, executable StartupItem value elements must be tagged
    249                 separately as shown in this example .plist file
    250                 snippet.</para>
    251 
    252                 <programlisting>&lt;key&gt;ProgramArguments&lt;/key&gt;
    253         &lt;array&gt;
    254                 &lt;string&gt;/opt/local/bin/daemondo&lt;/string&gt;
    255                 &lt;string&gt;--label=vm-pop3d&lt;/string&gt;
    256                 &lt;string&gt;--start-cmd&lt;/string&gt;
    257                 &lt;string&gt;/opt/local/sbin/vm-pop3d&lt;/string&gt;
    258                 &lt;string&gt;-d&lt;/string&gt;
    259                 &lt;string&gt;10&lt;/string&gt;
    260                 &lt;string&gt;-t&lt;/string&gt;
    261                 &lt;string&gt;600&lt;/string&gt;
    262                 &lt;string&gt;;&lt;/string&gt;
    263         &lt;/array&gt;</programlisting>
    264               </note>
    265             </listitem>
    266           </varlistentry>
    267         </variablelist>
    268       </section>
    269 
    270       <section>
    271         <title>Script StartupItems</title>
    272 
    273         <para>StartupItems of type <quote>script</quote> use
    274         <command>daemondo</command> to launch a daemon
    275         <emphasis>indirectly</emphasis> via a startup script. A typical
    276         snippet of a startup script that may be used with a
    277         <quote>script</quote> StartupItem is shown below. Notice that the
    278         script is not a daemon; rather the script indirectly launches the
    279         vm-pop3d daemon.</para>
    280 
    281         <programlisting>#!/bin/sh
     5<section>
     6  <title>StartupItems</title>
     7
     8  <para>A StartupItem is a MacPort facility to run "daemons," a Unix term
     9  for programs that run continuously in the background, rather than under
     10  the direct control of a user; for example, mail servers, network
     11  listeners, etc. Ports that use StartupItem keywords create Mac OS X
     12  scripts for <ulink
     13  url="http://developer.apple.com/macosx/launchd.html">launchd</ulink>,
     14  which is the Apple facility introduced with OS X 10.4 to replace xinetd
     15  for starting and managing daemons. To support
     16  <command>launchd</command>, a program named <command>daemondo</command>
     17  is provided by MacPorts base that serves as an adapter between OS X's
     18  <command>launchd</command> and daemons (<quote>executable</quote>
     19  StartupItems) or traditional Unix startup scripts that start daemons
     20  (<quote>script</quote> StartupItems).</para>
     21
     22  <para>There are three categories of StartupItem keywords. Those that
     23  trigger StartupItem creation and logging, those that specify attributes
     24  of <quote>executable</quote> StartupItems, and those that specify
     25  attributes of <quote>script</quote> StartupItems.</para>
     26
     27  <note>
     28    <para>The variable <varname>startupitem_type</varname> in
     29    ${prefix}/etc/macports/macports.conf may be set to
     30    <option>none</option> to globally override all StartupItem keywords
     31    found in Portfiles; this prevents StartupItems from being
     32    created.</para>
     33  </note>
     34
     35  <section>
     36    <title>StartupItem Attributes</title>
     37
     38    <para>The keywords in this section may be used with either
     39    <quote>executable</quote> or <quote>script</quote> StartupItems (see
     40    below).</para>
     41
     42    <variablelist>
     43      <varlistentry>
     44        <term>startupitem.create</term>
     45
     46        <listitem>
     47          <para>Trigger the creation of a StartupItem.</para>
     48
     49          <itemizedlist>
     50            <listitem>
     51              <para>Type: optional</para>
     52            </listitem>
     53
     54            <listitem>
     55              <para>Default: no</para>
     56            </listitem>
     57
     58            <listitem>
     59              <para>Values: yes no</para>
     60            </listitem>
     61
     62            <listitem>
     63              <para>Example:</para>
     64
     65              <programlisting>startupitem.create  yes</programlisting>
     66            </listitem>
     67          </itemizedlist>
     68        </listitem>
     69      </varlistentry>
     70
     71      <varlistentry>
     72        <term>startupitem.name</term>
     73
     74        <listitem>
     75          <para>Sets the name for the StartupItem.</para>
     76
     77          <itemizedlist>
     78            <listitem>
     79              <para>Type: required</para>
     80            </listitem>
     81
     82            <listitem>
     83              <para>Default: none</para>
     84            </listitem>
     85
     86            <listitem>
     87              <para>Values: <replaceable>any_name</replaceable></para>
     88            </listitem>
     89
     90            <listitem>
     91              <para>Example:</para>
     92
     93              <programlisting>startupitem.name  OpenSSH</programlisting>
     94            </listitem>
     95          </itemizedlist>
     96        </listitem>
     97      </varlistentry>
     98
     99      <varlistentry>
     100        <term>startupitem.logfile</term>
     101
     102        <listitem>
     103          <para>Path to a logfile for logging events about the lifetime of
     104          the StartupItem. Depending on the type of StartupItem, and the
     105          manner in which it is started, standard output from the daemon
     106          may also be directed to the logfile.</para>
     107
     108          <itemizedlist>
     109            <listitem>
     110              <para>Type: optional</para>
     111            </listitem>
     112
     113            <listitem>
     114              <para>Default: <filename>/dev/null</filename></para>
     115            </listitem>
     116
     117            <listitem>
     118              <para>Values: <replaceable>/file/path</replaceable></para>
     119            </listitem>
     120
     121            <listitem>
     122              <para>Example:</para>
     123
     124              <programlisting>startupitem.logfile  ${prefix}/var/log/mydaemon.log</programlisting>
     125            </listitem>
     126          </itemizedlist>
     127        </listitem>
     128      </varlistentry>
     129
     130      <varlistentry>
     131        <term>startupitem.logevents</term>
     132
     133        <listitem>
     134          <para>Control whether or not to log events to the log file. If
     135          logevents is set, events with timestamps are logged to the
     136          logfile.</para>
     137
     138          <itemizedlist>
     139            <listitem>
     140              <para>Type: optional</para>
     141            </listitem>
     142
     143            <listitem>
     144              <para>Default: no</para>
     145            </listitem>
     146
     147            <listitem>
     148              <para>Values: yes no</para>
     149            </listitem>
     150
     151            <listitem>
     152              <para>Example:</para>
     153
     154              <programlisting>startupitem.logevents   yes</programlisting>
     155            </listitem>
     156          </itemizedlist>
     157        </listitem>
     158      </varlistentry>
     159
     160      <varlistentry>
     161        <term>startupitem.netchange</term>
     162
     163        <listitem>
     164          <para>Cause the daemon to be restarted when a change in network
     165          state is detected.</para>
     166
     167          <itemizedlist>
     168            <listitem>
     169              <para>Type: optional</para>
     170            </listitem>
     171
     172            <listitem>
     173              <para>Default: no</para>
     174            </listitem>
     175
     176            <listitem>
     177              <para>Values: yes no</para>
     178            </listitem>
     179
     180            <listitem>
     181              <para>Example:</para>
     182
     183              <programlisting>startupitem.netchange  yes</programlisting>
     184            </listitem>
     185          </itemizedlist>
     186        </listitem>
     187      </varlistentry>
     188    </variablelist>
     189  </section>
     190
     191  <section>
     192    <title>Executable StartupItems</title>
     193
     194    <para>Daemons run continuously, so monitoring the health of daemon
     195    processes and restarting them if they die is an important
     196    StartupItems' feature. <quote>Executable</quote> StartupItems are
     197    preferred over <quote>script</quote> StartupItems because
     198    <command>daemondo</command> launches the daemon
     199    <emphasis>directly</emphasis>, rather than
     200    <emphasis>indirectly</emphasis> via a script, and therefore it
     201    automatically knows how to monitor a daemon process and restart it if
     202    it dies. Daemons used with <quote>executable</quote> StartupItems may
     203    be programs or scripts (shell, perl, python, etc.), but when a script
     204    the script <emphasis>itself</emphasis> must be the daemon, rather than
     205    a script that launches a daemon. <quote>Script</quote> StartupItems
     206    are to be used for the latter.</para>
     207
     208    <note>
     209      <para>For a given port, the <quote>executable</quote> StartupItem
     210      keyword may not be used with any keywords in the
     211      <quote>script</quote> StartupItem category.</para>
     212    </note>
     213
     214    <variablelist>
     215      <varlistentry>
     216        <term>startupitem.executable</term>
     217
     218        <listitem>
     219          <para>Specifies the name of the daemon to be run in the
     220          background. It may have multiple arguments, but they must be
     221          appropriate for a call to exec; arbitrary shell code may not be
     222          used.</para>
     223
     224          <itemizedlist>
     225            <listitem>
     226              <para>Type: optional</para>
     227            </listitem>
     228
     229            <listitem>
     230              <para>Default: no</para>
     231            </listitem>
     232
     233            <listitem>
     234              <para>Values: <replaceable>/path/to/daemon</replaceable>
     235              [<replaceable>args</replaceable>]</para>
     236            </listitem>
     237
     238            <listitem>
     239              <para>Example:</para>
     240
     241              <programlisting>startupitem.executable  ${prefix}/sbin/vm-pop3d -d 10 -t 600</programlisting>
     242            </listitem>
     243          </itemizedlist>
     244
     245          <note>
     246            <para>Do not to wrap the value in quotes if passing arguments
     247            to the daemon; unlike with<quote>script</quote> StartupItem
     248            values, executable StartupItem value elements must be tagged
     249            separately as shown in this example .plist file
     250            snippet.</para>
     251
     252            <programlisting>&lt;key&gt;ProgramArguments&lt;/key&gt;
     253&lt;array&gt;
     254        &lt;string&gt;/opt/local/bin/daemondo&lt;/string&gt;
     255        &lt;string&gt;--label=vm-pop3d&lt;/string&gt;
     256        &lt;string&gt;--start-cmd&lt;/string&gt;
     257        &lt;string&gt;/opt/local/sbin/vm-pop3d&lt;/string&gt;
     258        &lt;string&gt;-d&lt;/string&gt;
     259        &lt;string&gt;10&lt;/string&gt;
     260        &lt;string&gt;-t&lt;/string&gt;
     261        &lt;string&gt;600&lt;/string&gt;
     262        &lt;string&gt;;&lt;/string&gt;
     263&lt;/array&gt;</programlisting>
     264          </note>
     265        </listitem>
     266      </varlistentry>
     267    </variablelist>
     268  </section>
     269
     270  <section>
     271    <title>Script StartupItems</title>
     272
     273    <para>StartupItems of type <quote>script</quote> use
     274    <command>daemondo</command> to launch a daemon
     275    <emphasis>indirectly</emphasis> via a startup script. A typical
     276    snippet of a startup script that may be used with a
     277    <quote>script</quote> StartupItem is shown below. Notice that the
     278    script is not a daemon; rather the script indirectly launches the
     279    vm-pop3d daemon.</para>
     280
     281    <programlisting>#!/bin/sh
    282282#
    283283case "$1" in
     
    289289[... trimmed ...]</programlisting>
    290290
    291         <para>But if a script itself is a daemon, use the
    292         <quote>executable</quote> StartupItem type since that way it will be
    293         launched directly and its health tracked automatically. When using
    294         <quote>script</quote> StartupItems, the
    295         <code>startupitem.pidfile</code> keyword must be used if you want
    296         <command>daemondo</command> to monitor a daemon process and restart it
    297         if it dies.</para>
    298 
    299         <note>
    300           <para>For a given port, StartupItem keywords in category
    301           <quote>script</quote> may not be used with an
    302           <quote>executable</quote> StartupItem keyword.</para>
    303         </note>
    304 
    305         <variablelist>
    306           <varlistentry>
    307             <term>startupitem.start</term>
    308 
    309             <term>startupitem.stop</term>
    310 
    311             <term>startupitem.restart</term>
    312 
    313             <listitem>
    314               <para>Specify a shell script to start, stop, and restart the
    315               daemon. In the absence of a restart key, the daemon will be
    316               restarted by taking the stop action, followed by the start
    317               action.</para>
    318 
    319               <itemizedlist>
    320                 <listitem>
    321                   <para>Type: optional</para>
    322                 </listitem>
    323 
    324                 <listitem>
    325                   <para>Default: none</para>
    326                 </listitem>
    327 
    328                 <listitem>
    329                   <para>Values: <replaceable>shell_script</replaceable></para>
    330                 </listitem>
    331 
    332                 <listitem>
    333                   <para>Examples:</para>
    334 
    335                   <programlisting>startupitem.start "${prefix}/share/mysql/mysql.server start"
     291    <para>But if a script itself is a daemon, use the
     292    <quote>executable</quote> StartupItem type since that way it will be
     293    launched directly and its health tracked automatically. When using
     294    <quote>script</quote> StartupItems, the
     295    <code>startupitem.pidfile</code> keyword must be used if you want
     296    <command>daemondo</command> to monitor a daemon process and restart it
     297    if it dies.</para>
     298
     299    <note>
     300      <para>For a given port, StartupItem keywords in category
     301      <quote>script</quote> may not be used with an
     302      <quote>executable</quote> StartupItem keyword.</para>
     303    </note>
     304
     305    <variablelist>
     306      <varlistentry>
     307        <term>startupitem.start</term>
     308
     309        <term>startupitem.stop</term>
     310
     311        <term>startupitem.restart</term>
     312
     313        <listitem>
     314          <para>Specify a shell script to start, stop, and restart the
     315          daemon. In the absence of a restart key, the daemon will be
     316          restarted by taking the stop action, followed by the start
     317          action.</para>
     318
     319          <itemizedlist>
     320            <listitem>
     321              <para>Type: optional</para>
     322            </listitem>
     323
     324            <listitem>
     325              <para>Default: none</para>
     326            </listitem>
     327
     328            <listitem>
     329              <para>Values: <replaceable>shell_script</replaceable></para>
     330            </listitem>
     331
     332            <listitem>
     333              <para>Examples:</para>
     334
     335              <programlisting>startupitem.start "${prefix}/share/mysql/mysql.server start"
    336336startupitem.stop "${prefix}/share/mysql/mysql.server stop"
    337337startupitem.restart "${prefix}/share/mysql/mysql.server restart"</programlisting>
    338                 </listitem>
    339               </itemizedlist>
    340 
    341               <note>
    342                 <para>Wrap the stop, start, and restart values in quotes so
    343                 they will be placed in the wrapper as a single command.</para>
    344               </note>
    345             </listitem>
    346           </varlistentry>
    347 
    348           <varlistentry>
    349             <term>startupitem.init</term>
    350 
    351             <listitem>
    352               <para>Shell code that will be executed prior to any of the
    353               options <code>startupitem.start</code>,
    354               <code>startupitem.stop</code> and
    355               <code>startupitem.restart</code>.</para>
    356 
    357               <itemizedlist>
    358                 <listitem>
    359                   <para>Type: optional</para>
    360                 </listitem>
    361 
    362                 <listitem>
    363                   <para>Default: no</para>
    364                 </listitem>
    365 
    366                 <listitem>
    367                   <para>Values: <replaceable>shell_script</replaceable></para>
    368                 </listitem>
    369 
    370                 <listitem>
    371                   <para>Example:</para>
    372 
    373                   <programlisting>startupitem.init "BIN=${prefix}/sbin/bacula-fd"</programlisting>
    374                 </listitem>
    375               </itemizedlist>
    376             </listitem>
    377           </varlistentry>
    378 
    379           <varlistentry>
    380             <term>startupitem.pidfile</term>
    381 
    382             <listitem>
    383               <para>This keyword must be defined properly for
    384               <command>daemondo</command> to be able to monitor daemons
    385               launched via <quote>script</quote> StartupItems and restart them
    386               if they die. It specifies two things: a process id (PID) file
    387               handling method, and a pidfile name and path.</para>
    388 
    389               <itemizedlist>
    390                 <listitem>
    391                   <para>Type: optional</para>
    392                 </listitem>
    393 
    394                 <listitem>
    395                   <para>Default: [none] |
    396                   [<filename>${prefix}/var/run/${name}.pid</filename>]</para>
    397                 </listitem>
    398 
    399                 <listitem>
    400                   <para>Values [none auto manual clean]
    401                   [<replaceable>/path/to/pidfile</replaceable>]</para>
    402                 </listitem>
    403 
    404                 <listitem>
    405                   <para>Example:</para>
    406 
    407                   <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
    408                 </listitem>
    409               </itemizedlist>
    410 
    411               <para>PID file handling options:</para>
    412 
    413               <itemizedlist>
    414                 <listitem>
    415                   <para><option>none</option> - daemondo will not create or
    416                   track a PID file, so it won't know when a daemon
    417                   dies.</para>
    418                 </listitem>
    419 
    420                 <listitem>
    421                   <para><option>auto</option> - The started process is
    422                   expected to create a PID file that contains the PID of the
    423                   running daemon; daemondo then reads the PID from the file
    424                   and tracks the process. The started process must delete the
    425                   PID file if this is necessary.</para>
    426                 </listitem>
    427 
    428                 <listitem>
    429                   <para><option>clean</option> - The started process is
    430                   expected to create a PID file that contains the PID of the
    431                   running daemon; daemondo then reads the PID from the file
    432                   and tracks the process, and deletes the PID file if it
    433                   detects the daemon has died.</para>
    434                 </listitem>
    435 
    436                 <listitem>
    437                   <para><option>manual</option> - This option should only be
    438                   used if an <quote>executable</quote> StartupItem could be
    439                   used (daemondo launches a daemon directly)
    440                   <emphasis>and</emphasis> a port author wants a PID file
    441                   written for some special use. A PID file is not needed to
    442                   detect process death for daemons launched directly by
    443                   daemondo. As with executale StartupItems, daemondo remembers
    444                   the PID of the launched process and tracks it
    445                   automatically.</para>
    446                 </listitem>
    447               </itemizedlist>
    448             </listitem>
    449           </varlistentry>
    450         </variablelist>
    451       </section>
    452 
    453       <section>
    454         <title>Loading / Unloading StartupItems into launchd</title>
    455 
    456         <para>A port with a StartupItem places a link to a .plist file for the
    457         port's daemon within <filename>/Library/LaunchDaemons/</filename>. A
    458         .plist file is an XML file; MacPorts installs .plist files tagged as
    459         <quote>disabled</quote> for the sake of security. You may enable a
    460         startup script (tag the.plist file as <quote>enabled</quote>) and load
    461         it into <command>launchd</command> with a single command as
    462         shown.</para>
    463 
    464         <programlisting><prompt>%%</prompt> <userinput>sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
    465 
    466         <para>You may stop a running startup script, disable it (tag the.plist
    467         file as <quote>disabled</quote>), and unload it from
    468         <command>launchd</command> with a single command as shown.</para>
    469 
    470         <programlisting><prompt>%%</prompt> <userinput>sudo launchctl unload -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
    471       </section>
    472 
    473       <section>
    474         <title>StartupItem Internals</title>
    475 
    476         <para>During port installation a MacPorts StartupItem creates a .plist
    477         file in <filename>${prefix}/etc/LaunchDaemons/</filename>, and places
    478         a symbolic link to the .plist file within
    479         <filename>/Library/LaunchDaemons/</filename>.</para>
    480 
    481         <para>For example, the StartupItem for the mysql5 port is
    482         <filename>org.macports.mysql5.plist</filename>, and it is linked as
    483         shown.</para>
    484 
    485         <programlisting><prompt>%%</prompt> <userinput>ls -l /Library/LaunchDaemons</userinput></programlisting>
    486 
    487         <screen>org.macports.mysql5.plist -&gt;
     338            </listitem>
     339          </itemizedlist>
     340
     341          <note>
     342            <para>Wrap the stop, start, and restart values in quotes so
     343            they will be placed in the wrapper as a single command.</para>
     344          </note>
     345        </listitem>
     346      </varlistentry>
     347
     348      <varlistentry>
     349        <term>startupitem.init</term>
     350
     351        <listitem>
     352          <para>Shell code that will be executed prior to any of the
     353          options <code>startupitem.start</code>,
     354          <code>startupitem.stop</code> and
     355          <code>startupitem.restart</code>.</para>
     356
     357          <itemizedlist>
     358            <listitem>
     359              <para>Type: optional</para>
     360            </listitem>
     361
     362            <listitem>
     363              <para>Default: no</para>
     364            </listitem>
     365
     366            <listitem>
     367  &nb