Changeset 27640 for trunk/doc


Ignore:
Timestamp:
Aug 11, 2007, 6:02:12 AM (12 years ago)
Author:
markd@…
Message:

Added a separate variants section and modified examples.

File:
1 edited

Legend:

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

    r27555 r27640  
    278278
    279279    <section>
    280       <title>A Simple Portfile</title>
     280      <title>A Basic Portfile</title>
    281281
    282282      <para></para>
     
    335335
    336336    <section>
    337       <title>Portfile Using a Variant</title>
    338 
    339       <para>Here is an example of a port providing four variants that add
    340       additional configure arguments to a port. See "Variants" in the Portfile
    341       Reference section for full information.</para>
    342 
    343       <programlisting>variant pop     { configure.args-append --enable-pop }
    344 variant imap    { configure.args-append --enable-imap }
    345 variant ssl     { configure.args-append --with-ssl }
    346 variant debug   { configure.args-append --enable-debug }</programlisting>
    347     </section>
    348 
    349     <section>
    350337      <title>Portfile Using a StartupItem</title>
    351338
     
    365352    startupitem.stop "${prefix}/share/${name}/vm-pop3d.init stop"
    366353}</programlisting>
     354    </section>
     355  </section>
     356
     357  <section>
     358    <title>Port Variants</title>
     359
     360    <para>Variants are a way for port authors to provide options that may be
     361    invoked at install time. They are declared in the global section of a
     362    <filename>Portfile</filename> using the "variant" keyword and may provide
     363    a description.</para>
     364
     365    <section>
     366      <title>Variants to Modify Options</title>
     367
     368      <para>The most common use for a variant is to add or remove
     369      dependencies, configure arguments, and build arguments from the global
     370      <filename>Portfile</filename> section. Here is an example of a port
     371      providing four variants that add additional configure arguments to a
     372      port. See "Variants" in the Portfile Reference section for full
     373      information.</para>
     374
     375      <programlisting>variant pop     { configure.args-append --enable-pop }
     376variant imap    { configure.args-append --enable-imap }
     377variant ssl     { configure.args-append --with-ssl }
     378variant debug   { configure.args-append --enable-debug }</programlisting>
     379
     380      <para>In the example variant declaration, the configure argument
     381      <literal>--without-x</literal> is removed and a numner of others are
     382      appended.</para>
     383
     384      <programlisting>variant x11 description {Builds port as an X11 program with Lucid widgets} {
     385    configure.args-delete   --without-x
     386    configure.args-append   --with-x-toolkit=lucid \
     387                            --without-carbon \
     388                            --with-xpm \
     389                            --with-jpeg \
     390                            --with-tiff \
     391                            --with-gif \
     392                            --with-png
     393    depends_lib-append      lib:libX11:XFree86 \
     394                            lib:libXpm:XFree86 \
     395                            port:jpeg \
     396                            port:tiff \
     397                            port:libungif \
     398                            port:libpng
     399}</programlisting>
     400    </section>
     401
     402    <section>
     403      <title>Variant Actions in a Phase</title>
     404
     405      <para>If a variant requires options in addition to those provided by
     406      keywords using -append and/or -delete, in other words, any actions that
     407      would normally take place within a port installation phase, do not try
     408      to do this within the variant declaration. Rather, modify the behavior
     409      of any affected phases when the variant is invoked using the
     410      variant_isset keyword.</para>
     411
     412      <programlisting>post-destroot {
     413    xinstall -m 755 -d ${destroot}${prefix}/etc/
     414    xinstall ${worksrcpath}/examples/foo.conf \
     415        ${destroot}${prefix}/etc/
     416
     417    if {[variant_isset] carbon]} {
     418        delete ${destroot}${prefix}/bin/emacs
     419        delete ${destroot}${prefix}/bin/emacs-${version}
     420    }
     421}</programlisting>
     422    </section>
     423
     424    <section>
     425      <title>Default Variants</title>
     426
     427      <para>Variants are used to specify actions that lie outside the core
     428      functions of an application or port, but there may be some cases where
     429      you wish to specify these non-core functions by default. For this
     430      purpose you may use the keyword default_variants.</para>
     431
     432      <programlisting>default_variants +foo +bar</programlisting>
     433
     434      <note>
     435        <para>The default_variant keyword may only be used in the global
     436        <filename>Portfile</filename> section.</para>
     437      </note>
    367438    </section>
    368439  </section>
Note: See TracChangeset for help on using the changeset viewer.