[27640] trunk/doc/guide/new/xml/portfiledev.xml

[source_changes at macosforge.org]

Revision: 27640
          http://trac.macosforge.org/projects/macports/changeset/27640
Author:   markd at macports.org
Date:     2007-08-10 23:02:12 -0700 (Fri, 10 Aug 2007)

Log Message:
-----------
Added a separate variants section and modified examples.

Modified Paths:
--------------
    trunk/doc/guide/new/xml/portfiledev.xml

Modified: trunk/doc/guide/new/xml/portfiledev.xml
===================================================================
--- trunk/doc/guide/new/xml/portfiledev.xml	2007-08-11 06:00:07 UTC (rev 27639)
+++ trunk/doc/guide/new/xml/portfiledev.xml	2007-08-11 06:02:12 UTC (rev 27640)
@@ -277,7 +277,7 @@
     default phases.</para>
 
     <section>
-      <title>A Simple Portfile</title>
+      <title>A Basic Portfile</title>
 
       <para></para>
 
@@ -334,19 +334,6 @@
     </section>
 
     <section>
-      <title>Portfile Using a Variant</title>
-
-      <para>Here is an example of a port providing four variants that add
-      additional configure arguments to a port. See "Variants" in the Portfile
-      Reference section for full information.</para>
-
-      <programlisting>variant pop     { configure.args-append --enable-pop }
-variant imap    { configure.args-append --enable-imap }
-variant ssl     { configure.args-append --with-ssl }
-variant debug   { configure.args-append --enable-debug }</programlisting>
-    </section>
-
-    <section>
       <title>Portfile Using a StartupItem</title>
 
       <para>Startupitems may be placed in the global section of a
@@ -368,6 +355,90 @@
   </section>
 
   <section>
+    <title>Port Variants</title>
+
+    <para>Variants are a way for port authors to provide options that may be
+    invoked at install time. They are declared in the global section of a
+    <filename>Portfile</filename> using the "variant" keyword and may provide
+    a description.</para>
+
+    <section>
+      <title>Variants to Modify Options</title>
+
+      <para>The most common use for a variant is to add or remove
+      dependencies, configure arguments, and build arguments from the global
+      <filename>Portfile</filename> section. Here is an example of a port
+      providing four variants that add additional configure arguments to a
+      port. See "Variants" in the Portfile Reference section for full
+      information.</para>
+
+      <programlisting>variant pop     { configure.args-append --enable-pop }
+variant imap    { configure.args-append --enable-imap }
+variant ssl     { configure.args-append --with-ssl }
+variant debug   { configure.args-append --enable-debug }</programlisting>
+
+      <para>In the example variant declaration, the configure argument
+      <literal>--without-x</literal> is removed and a numner of others are
+      appended.</para>
+
+      <programlisting>variant x11 description {Builds port as an X11 program with Lucid widgets} {
+    configure.args-delete   --without-x
+    configure.args-append   --with-x-toolkit=lucid \
+                            --without-carbon \
+                            --with-xpm \
+                            --with-jpeg \
+                            --with-tiff \
+                            --with-gif \
+                            --with-png
+    depends_lib-append      lib:libX11:XFree86 \
+                            lib:libXpm:XFree86 \
+                            port:jpeg \
+                            port:tiff \
+                            port:libungif \
+                            port:libpng
+}</programlisting>
+    </section>
+
+    <section>
+      <title>Variant Actions in a Phase</title>
+
+      <para>If a variant requires options in addition to those provided by
+      keywords using -append and/or -delete, in other words, any actions that
+      would normally take place within a port installation phase, do not try
+      to do this within the variant declaration. Rather, modify the behavior
+      of any affected phases when the variant is invoked using the
+      variant_isset keyword.</para>
+
+      <programlisting>post-destroot {
+    xinstall -m 755 -d ${destroot}${prefix}/etc/
+    xinstall ${worksrcpath}/examples/foo.conf \
+        ${destroot}${prefix}/etc/
+
+    if {[variant_isset] carbon]} {
+        delete ${destroot}${prefix}/bin/emacs
+        delete ${destroot}${prefix}/bin/emacs-${version}
+    }
+}</programlisting>
+    </section>
+
+    <section>
+      <title>Default Variants</title>
+
+      <para>Variants are used to specify actions that lie outside the core
+      functions of an application or port, but there may be some cases where
+      you wish to specify these non-core functions by default. For this
+      purpose you may use the keyword default_variants.</para>
+
+      <programlisting>default_variants +foo +bar</programlisting>
+
+      <note>
+        <para>The default_variant keyword may only be used in the global
+        <filename>Portfile</filename> section.</para>
+      </note>
+    </section>
+  </section>
+
+  <section>
     <title>Creating Patch Files</title>
 
     <para>Patch files are files created with the Unix command

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/macports-changes/attachments/20070810/d915f9c9/attachment.html