Changeset 32713 for trunk/doc-new


Ignore:
Timestamp:
Jan 11, 2008, 10:31:25 PM (12 years ago)
Author:
markd@…
Message:

General improvements to better mesh the presentation of the platform statement as a variant.

File:
1 edited

Legend:

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

    r32539 r32713  
    22<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    33"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
    4 
    54<section id="reference.variants">
    65  <title>Variants</title>
    76
    87  <para>MacPorts variants are conditional modifications of port installation
    9   behavior that may be invoked by a user at the time of port install.</para>
     8  behavior during port installation. There are two types of variants:
     9  user-selected variants and platform variants. User-selected variants are
     10  options selected by a user when a port is installed; platform variants are
     11  selected automatically by MacPorts base according to the OS or hardware
     12  platform (darwin, freebsd, linux, i386, ppc, etc.)</para>
    1013
    11   <variablelist>
    12     <varlistentry>
    13       <term>variant [requires <replaceable>variant</replaceable>] [conflicts
    14       <replaceable>variant</replaceable>] [description
    15       <replaceable>description</replaceable>]</term>
     14  <section>
     15    <title>User-Selected Variants</title>
    1616
    17       <listitem>
    18         <para>The variant declaration may contain any keywords that can be
    19         placed in a Portfile's global section. If you wish to execute system
    20         (shell) calls or Tcl extensions during the execution of a port
    21         phase, you should place those statements within a
    22         <literal>variant_isset</literal> conditional within a phase
    23         declaration and not within the variant declaration itself.
    24         Dependencies and conflicts with other variants in the same port can
    25         be expressed with requires and conflicts. See the isset Tcl
    26         extension.</para>
     17    <para>User-selected variants are those that are defined so that a user or
     18    port author can use them at their discretion.</para>
    2719
    28         <itemizedlist>
    29           <listitem>
    30             <!-- TODO: should this really be no, not none? -->
    31             <para>Default: no</para>
    32           </listitem>
     20    <variablelist>
     21      <varlistentry>
     22        <term>variant [requires <replaceable>variant</replaceable>] [conflicts
     23        <replaceable>variant</replaceable>] [description
     24        <replaceable>description</replaceable>]</term>
    3325
    34           <listitem>
    35             <para>Example:</para>
     26        <listitem>
     27          <para>The variant declaration may contain any keywords that can be
     28          placed in a Portfile's global section. If you wish to execute system
     29          (shell) calls or Tcl extensions during the execution of a port
     30          phase, you should place those statements within a
     31          <literal>variant_isset</literal> conditional within a phase
     32          declaration and not within the variant declaration itself.
     33          Dependencies and conflicts with other variants in the same port can
     34          be expressed with <quote>requires</quote> and
     35          <quote>conflicts</quote> options as shown below.</para>
    3636
    37             <programlisting>variant gnome requires glib {
     37          <itemizedlist>
     38            <listitem>
     39              <para>Default: none</para>
     40            </listitem>
     41
     42            <listitem>
     43              <para>Examples:</para>
     44
     45              <programlisting>variant gnome requires glib {
    3846    configure.args-append   --with-gnome
    3947    depends_lib-append      port:gnome-session
    4048}</programlisting>
    41           </listitem>
    42         </itemizedlist>
    43       </listitem>
    44     </varlistentry>
    4549
    46     <varlistentry>
    47       <term>default_variants</term>
     50              <programlisting>variant apache2 conflicts apache {
     51        configure.args-append \
     52                --with-apxs2=${prefix}/apache2/bin/apxs
     53}</programlisting>
     54            </listitem>
     55          </itemizedlist>
     56        </listitem>
     57      </varlistentry>
    4858
    49       <listitem>
    50         <para>If variants are defined, then the default_variants value lists
    51         which variants are enabled by default. This allows for Portfile
    52         modularity and also allows users to suppress default variants if
    53         they wish.</para>
     59      <varlistentry>
     60        <term>default_variants</term>
    5461
    55         <note>
    56           <para>Due to a bug in the current MacPorts base default_variants
    57           shouldn't be used at the moment as they cause problems while
    58           upgrading ports.</para>
    59         </note>
     62        <listitem>
     63          <para>The optional default_variants keyword is used to specify
     64          variants that a port author wishes to have enabled by default. This
     65          allows for Portfile modularity and also allows users to suppress
     66          default variants if they wish.</para>
    6067
    61         <itemizedlist>
    62           <listitem>
    63             <para>Default: none</para>
    64           </listitem>
     68          <note>
     69            <para>Due to a bug in the current MacPorts base default_variants
     70            shouldn't be used at the moment as they cause problems while
     71            upgrading ports.</para>
     72          </note>
    6573
    66           <listitem>
    67             <para>Example:</para>
     74          <itemizedlist>
     75            <listitem>
     76              <para>Default: none</para>
     77            </listitem>
    6878
    69             <programlisting>default_variants    +ssl +tcpd
     79            <listitem>
     80              <para>Example:</para>
     81
     82              <programlisting>default_variants    +ssl +tcpd
    7083
    7184</programlisting>
    72           </listitem>
    73         </itemizedlist>
    74       </listitem>
     85            </listitem>
     86          </itemizedlist>
     87        </listitem>
    7588
    76       <listitem>
    77         <para>Default variants may be suppressed by preceding a variant name
    78         with a "-" as shown in this example.</para>
     89        <listitem>
     90          <para>Default variants may be suppressed by preceding a variant name
     91          with a "-" as shown in this example.</para>
    7992
    80         <programlisting><prompt>%%</prompt> <userinput>port install foo -ssl</userinput></programlisting>
    81       </listitem>
    82     </varlistentry>
     93          <programlisting><prompt>%%</prompt> <userinput>port install foo -ssl</userinput></programlisting>
     94        </listitem>
     95      </varlistentry>
    8396
    84     <varlistentry>
    85       <term>universal_variant</term>
     97      <varlistentry>
     98        <term>universal_variant</term>
    8699
    87       <listitem>
    88         <para>When using MacPorts on Mac OS X, a universal variant is defined
    89         by default to configure ports with universal flags. The variant can be
    90         overridden if the default code does not work (see the <link
    91         linkend="reference.phases.configure.universal">Configure
    92         Universal</link> section above), or suppressed if a universal variant
    93         is not possible for the port with this keyword.</para>
     100        <listitem>
     101          <para>When using MacPorts on Mac OS X, a universal variant is
     102          defined by default to configure ports with universal flags. The
     103          variant can be overridden if the default code does not work (see the
     104          <link linkend="reference.phases.configure.universal">Configure
     105          Universal</link> section above), or suppressed if a universal
     106          variant does not function properly for a given port.</para>
    94107
    95         <itemizedlist>
    96           <listitem>
    97             <para>Default: <option>yes</option></para>
    98           </listitem>
     108          <itemizedlist>
     109            <listitem>
     110              <para>Default: <option>yes</option></para>
     111            </listitem>
    99112
    100           <listitem>
    101             <para>Example:</para>
     113            <listitem>
     114              <para>Example:</para>
    102115
    103             <programlisting>universal_variant   no</programlisting>
    104           </listitem>
    105         </itemizedlist>
    106       </listitem>
    107     </varlistentry>
     116              <programlisting>universal_variant   no</programlisting>
     117            </listitem>
     118          </itemizedlist>
     119        </listitem>
     120      </varlistentry>
     121    </variablelist>
     122  </section>
    108123
    109     <varlistentry>
    110       <term>platform <replaceable>platform</replaceable>
    111       [<replaceable>version</replaceable>]
    112       [<replaceable>arch</replaceable>]</term>
     124  <section>
     125    <title>Platform Variants</title>
    113126
    114       <listitem>
    115         <para>MacPorts allows for platform-specific conditional modification
    116         to be specified in a Portfile, much like variants, for handling
    117         differences between platforms and versions of the same
    118         platform.</para>
     127    <para>Platform variants are either defined by default in MacPorts base, or
     128    defined by a port author port installation customization by OS or hardware
     129    platform.</para>
    119130
    120         <para><literal>platform darwin
    121         <replaceable>version</replaceable></literal> can be used to handle
    122         different tasks depending on the version of Mac OS X.
    123         <replaceable>version</replaceable> can be <literal>6</literal> for
    124         10.2 Jaguar, <literal>7</literal> for 10.3 Panther,
    125         <literal>8</literal> for 10.4 Tiger or <literal>9</literal> for 10.5
    126         Leopard.</para>
     131    <variablelist>
     132      <varlistentry>
     133        <term>platform <replaceable>platform</replaceable>
     134        [<replaceable>version</replaceable>]
     135        [<replaceable>arch</replaceable>]</term>
    127136
    128         <itemizedlist>
    129           <listitem>
    130             <para>Default: ???</para>
    131           </listitem>
     137        <listitem>
     138          <para>MacPorts allows platform-specific port options to be specified
     139          in a Portfile for handling differences between platforms and
     140          versions of the same platform.</para>
    132141
    133           <listitem>
    134             <para>Examples:</para>
     142          <para><literal>platform darwin
     143          <replaceable>version</replaceable></literal> can be used to handle
     144          different tasks depending on the version of Mac OS X.
     145          <replaceable>version</replaceable> can be <literal>6</literal> for
     146          10.2 Jaguar, <literal>7</literal> for 10.3 Panther,
     147          <literal>8</literal> for 10.4 Tiger or <literal>9</literal> for 10.5
     148          Leopard.</para>
    135149
    136             <programlisting>
     150          <itemizedlist>
     151            <listitem>
     152              <para>Default: ???</para>
     153            </listitem>
     154
     155            <listitem>
     156              <para>Examples:</para>
     157
     158              <programlisting>
    137159platform darwin 7 {
    138160    # Only used on Mac OS X 10.3.
     
    141163        --with-tcl=/System/Library/Tcl/8.3
    142164}</programlisting>
    143             <programlisting>
     165
     166              <programlisting>
    144167platform darwin powerpc {
    145168    # Only used if Mac OS X is running on a PowerPC processor.
     
    152175        --host=i386-gnu-rhapsody${os.version}
    153176}</programlisting>
    154           </listitem>
    155         </itemizedlist>
    156       </listitem>
    157     </varlistentry>
    158   </variablelist>
     177            </listitem>
     178          </itemizedlist>
     179        </listitem>
     180      </varlistentry>
     181    </variablelist>
     182  </section>
    159183</section>
Note: See TracChangeset for help on using the changeset viewer.