Changeset 27721 for trunk/doc


Ignore:
Timestamp:
Aug 12, 2007, 9:45:34 PM (11 years ago)
Author:
markd@…
Message:

Add guidance about -append and -delete keywords.

File:
1 edited

Legend:

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

    r27639 r27721  
    658658
    659659  <section>
    660     <title>Keyword Reference</title>
     660    <title>Keywords</title>
    661661
    662662    <para>MacPorts keywords are used to specify required or optional items
    663     within a <filename>Portfile</filename> to override default options for
    664     ports when necessary. Keywords are to be used within the "global" and
    665     "variant" sections of Portfiles, and not within optional port phase
    666     declarations. In other words, port phase keywords are not located within
    667     port phase declaration; they <emphasis>refer</emphasis> to port phases and
    668     set options for those phases, and they take affect whether or not phase
    669     declarations have been explicitly defined by a port author.</para>
     663    within a <filename>Portfile</filename>, or to override default options
     664    used by MacPorts base for individual ports when necessary. Keywords are to
     665    be used within the "global" and "variant" sections of Portfiles, and not
     666    within optional port phase declarations. In other words, port phase
     667    keywords are not located within port phase declaration; they
     668    <emphasis>refer</emphasis> to port phases and set options for those
     669    phases, and they take affect whether or not phase declarations have been
     670    explicitly defined by a port author.</para>
    670671
    671672    <para>The keywords listed below in category "global" specify information
     
    677678      <title>Keywords using -append and -delete</title>
    678679
    679       <para>These keywords are used to append or delete individual options
    680       from a matching list of options without replacing it, whether the
    681       options were defaults supplied by MacPorts base or options set with a
    682       matching keyword set beforehand during execution of the Portfile.</para>
     680      <para>Frequently it is necessary to add to a list of keyword values
     681      previously set by MacPorts base or set by a prior Portfile keyword. In
     682      these cases we generally don't want to replace the current list, but
     683      rather to add or delete values from the list. Keywords that use
     684      "-append" or "-delete" append or delete individual options from a
     685      matching list of options without overwriting the list. The three most
     686      common practical uses for these keywords are:</para>
     687
     688      <itemizedlist>
     689        <listitem>
     690          <para>Configure arguments. MacPorts base sets the gcc complier flags
     691          CFLAGS and LDFLAGS for all ports, therefore to keep from overwriting
     692          the defaults use:</para>
     693
     694          <itemizedlist>
     695            <listitem>
     696              <para><literal>configure.cflags-append</literal></para>
     697            </listitem>
     698
     699            <listitem>
     700              <para><literal>configure.ldflags-append</literal></para>
     701            </listitem>
     702          </itemizedlist>
     703        </listitem>
     704
     705        <listitem>
     706          <para>Ports belonging to a PortGroup. Ports in a PortGroup have
     707          default dependencies set by the Portgroup. Therefore, never use
     708          <literal>depends_lib</literal> or it will overwrite the default
     709          library dependencies. Use instead:</para>
     710
     711          <itemizedlist>
     712            <listitem>
     713              <para><literal>depends_lib-append</literal></para>
     714            </listitem>
     715          </itemizedlist>
     716        </listitem>
     717
     718        <listitem>
     719          <para>Port variants. When adding or removing dependencies to a port
     720          when a variant is specified, you want to add items to the list of
     721          dependency keyword values that were set previously in the Portfile.
     722          Use the appropriate keywords.</para>
     723
     724          <itemizedlist>
     725            <listitem>
     726              <para><literal>depends_lib-append</literal> or
     727              <literal>depends_lib-delete</literal></para>
     728            </listitem>
     729
     730            <listitem>
     731              <para><literal>depends_build-append</literal> or
     732              <literal>depends_build-delete</literal></para>
     733            </listitem>
     734
     735            <listitem>
     736              <para><literal>depends_run-append</literal> or
     737              <literal>depends_run-delete</literal></para>
     738            </listitem>
     739          </itemizedlist>
     740        </listitem>
     741      </itemizedlist>
    683742    </section>
    684743
Note: See TracChangeset for help on using the changeset viewer.