[27639] trunk/doc/guide/new/xml/portfileref.xml
source_changes at macosforge.org
source_changes at macosforge.org
Fri Aug 10 23:00:08 PDT 2007
Revision: 27639
http://trac.macosforge.org/projects/macports/changeset/27639
Author: markd at macports.org
Date: 2007-08-10 23:00:07 -0700 (Fri, 10 Aug 2007)
Log Message:
-----------
Changes mostly to structure and organization of keyword reference section.
Modified Paths:
--------------
trunk/doc/guide/new/xml/portfileref.xml
Modified: trunk/doc/guide/new/xml/portfileref.xml
===================================================================
--- trunk/doc/guide/new/xml/portfileref.xml 2007-08-11 03:42:20 UTC (rev 27638)
+++ trunk/doc/guide/new/xml/portfileref.xml 2007-08-11 06:00:07 UTC (rev 27639)
@@ -207,79 +207,6 @@
</section>
<section>
- <title>Variants</title>
-
- <para>Variants are a way for port authors to provide options that may be
- invoked at install time. They are declared in a Porfile's global section
- using the "variant" keyword and may provide a description.</para>
-
- <section>
- <title>Append / Delete Keywords</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. In the example below, the global
- configure argument --without-x11 is removed and 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 Port Phases</title>
-
- <para>If a variant requires options in addition to those provided by
- keywords using -append and/or -delete, or actions that would normally
- take place within a port installation phase or its pre- and post-
- phases, 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>StartupItems</title>
<para>StartupItems are keywords that create Mac OS X LaunchDaemon startup
@@ -730,27 +657,34 @@
</section>
<section>
- <title>Keywords</title>
+ <title>Keyword Reference</title>
- <para>MacPorts keywords are used to specify required or optional items for
- a <filename>Portfile</filename> or to override default options when
- necessary. All the keywords are to be used within the global section of a
- <filename>Portfile</filename>. The keywords listed below in category
- "global" specify information for a port as a whole, whereas the keywords
- listed under a port phase specify information to be used during a
- particular installation phase.</para>
+ <para>MacPorts keywords are used to specify required or optional items
+ within a <filename>Portfile</filename> to override default options for
+ ports when necessary. Keywords are to be used within the "global" and
+ "variant" sections of Portfiles, and not within optional port phase
+ declarations. In other words, port phase keywords are not located within
+ port phase declaration; they <emphasis>refer</emphasis> to port phases and
+ set options for those phases, and they take affect whether or not phase
+ declarations have been explicitly defined by a port author.</para>
- <para>Remember that default port installation phase characteristics are
- determined by the MacPorts base, so <filename>Portfile</filename> phase
- declarations need only be defined for non-default characteristics. But
- keywords that specify options for port phases take affect whether or not
- phase characteristics are defined explicitly using
- <filename>Portfile</filename> declarations or set by default by the
- MacPorts base, or a combination.</para>
+ <para>The keywords listed below in category "global" specify information
+ for ports as a whole, whereas the keywords listed under a port phase
+ specify information to be used during a particular installation
+ phase.</para>
<section>
- <title>Global</title>
+ <title>Keywords using -append and -delete</title>
+ <para>These keywords are used to append or delete individual options
+ from a matching list of options without replacing it, whether the
+ options were defaults supplied by MacPorts base or options set with a
+ matching keyword set beforehand during execution of the Portfile.</para>
+ </section>
+
+ <section>
+ <title>Global Keywords</title>
+
<para>Global keywords.</para>
<variablelist>
@@ -859,6 +793,26 @@
<listitem>
<para></para>
+
+ <variablelist>
+ <varlistentry>
+ <term>depends_lib-append</term>
+
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <variablelist>
+ <varlistentry>
+ <term>depends_lib-delete</term>
+
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</listitem>
</varlistentry>
</variablelist>
@@ -869,76 +823,71 @@
<listitem>
<para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term>depends_run</term>
+ <variablelist>
+ <varlistentry>
+ <term>depends_build-append</term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <variablelist>
- <varlistentry>
- <term></term>
+ <variablelist>
+ <varlistentry>
+ <term>depends_build-delete</term>
- <listitem>
- <para></para>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
- <term></term>
+ <term>depends_run</term>
<listitem>
<para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term></term>
+ <variablelist>
+ <varlistentry>
+ <term>depends_run-append</term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <variablelist>
- <varlistentry>
- <term></term>
+ <variablelist>
+ <varlistentry>
+ <term>depends_run-delete</term>
- <listitem>
- <para></para>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
- <title>Fetch</title>
+ <title>Port Phase Keywords</title>
- <para>Fetch phase keywords.</para>
+ <para>MacPorts has ten distinct port installation phases. As previosly
+ stated, port phase keywords are not located within port phase
+ declarations; they <emphasis>refer</emphasis> to port phases and set
+ options for them.</para>
- <variablelist>
- <varlistentry>
- <term>fetch.keyword1</term>
+ <para>The fetch phase ...</para>
- <listitem>
- <para>Description fetch keyword 1.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
<variablelist>
<varlistentry>
<term></term>
@@ -968,25 +917,9 @@
</listitem>
</varlistentry>
</variablelist>
- </section>
- <section>
- <title>Checksum</title>
-
- <para>Checksum phase keywords.</para>
-
<variablelist>
<varlistentry>
- <term>checksum.keyword1</term>
-
- <listitem>
- <para>Description checksum keyword 1.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry>
<term></term>
<listitem>
@@ -1024,19 +957,15 @@
</listitem>
</varlistentry>
</variablelist>
- </section>
- <section>
- <title>Extract</title>
+ <para>The checksum phase ...</para>
- <para>Extract phase keywords.</para>
-
<variablelist>
<varlistentry>
- <term>extract.keyword1</term>
+ <term></term>
<listitem>
- <para>Description extract keyword 1.</para>
+ <para></para>
</listitem>
</varlistentry>
</variablelist>
@@ -1080,25 +1009,11 @@
</listitem>
</varlistentry>
</variablelist>
- </section>
- <section>
- <title>Patch</title>
+ <para>The extract phase ...</para>
- <para>Patch phase keywords.</para>
-
<variablelist>
<varlistentry>
- <term>patch.keyword1</term>
-
- <listitem>
- <para>Description patch keyword1.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry>
<term></term>
<listitem>
@@ -1126,51 +1041,9 @@
</listitem>
</varlistentry>
</variablelist>
- </section>
- <section>
- <title>Configuration</title>
-
- <para>Configuration phase keywords. Avoid using keywords with defaults
- defined or you will overwrite the default variables.</para>
-
<variablelist>
<varlistentry>
- <term>configure.env</term>
-
- <listitem>
- <para>Configure environment variables.</para>
-
- <para>Defaults: CFLAGS=-I<filename>${prefix}/include</filename>
- LDFLAGS=-L<filename>${prefix}/lib</filename></para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry>
- <term>configure.cflags-append</term>
-
- <listitem>
- <para>Set additional CFLAGS to be added to the variable
- defaults.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry>
- <term>configure.ldflags-append</term>
-
- <listitem>
- <para>Set additional LDFLAGS to be added to the variable
- defaults.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry>
<term></term>
<listitem>
@@ -1199,6 +1072,8 @@
</varlistentry>
</variablelist>
+ <para>The patch phase ...</para>
+
<variablelist>
<varlistentry>
<term></term>
@@ -1259,98 +1134,102 @@
</varlistentry>
</variablelist>
- <variablelist>
- <varlistentry>
- <term></term>
+ <para>The configuration phase ...</para>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>MacPorts base sets some important default configure options, so
+ you must be careful not to overwrite them with your Portfile keywords;
+ for this reason you should use the -append version of configure
+ keywords. For example, MacPorts base sets default
+ <literal>configure.ldflags</literal> so you should always use
+ <literal>configure.cflags-append</literal> to set additional CFLAGS in
+ Portfiles.</para>
<variablelist>
<varlistentry>
- <term></term>
+ <term>configure.args</term>
<listitem>
<para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term></term>
+ <variablelist>
+ <varlistentry>
+ <term>configure.args-append</term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <variablelist>
- <varlistentry>
- <term></term>
+ <variablelist>
+ <varlistentry>
+ <term>configure.args-delete</term>
- <listitem>
- <para></para>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
- <term></term>
+ <term>configure.cflags</term>
<listitem>
<para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- <section>
- <title>Build</title>
+ <variablelist>
+ <varlistentry>
+ <term>configure.cflags-append</term>
- <para>Build phase keywords.</para>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <variablelist>
- <varlistentry>
- <term>build.keyword1</term>
+ <variablelist>
+ <varlistentry>
+ <term>configure.cflags-delete</term>
- <listitem>
- <para>Description build.keyword 1.</para>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
- <term></term>
+ <term>configure.ldflags</term>
<listitem>
<para></para>
- </listitem>
- </varlistentry>
- </variablelist>
- <variablelist>
- <varlistentry>
- <term></term>
+ <variablelist>
+ <varlistentry>
+ <term>configure.ldflags-append</term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <variablelist>
- <varlistentry>
- <term></term>
+ <variablelist>
+ <varlistentry>
+ <term>configure.ldflags-delete</term>
- <listitem>
- <para></para>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</listitem>
</varlistentry>
</variablelist>
@@ -1375,16 +1254,8 @@
</varlistentry>
</variablelist>
- <variablelist>
- <varlistentry>
- <term></term>
+ <para>The build phase ...</para>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
-
<variablelist>
<varlistentry>
<term></term>
@@ -1394,25 +1265,9 @@
</listitem>
</varlistentry>
</variablelist>
- </section>
- <section>
- <title>Destroot</title>
-
- <para>Destroot phase keywords.</para>
-
<variablelist>
<varlistentry>
- <term>destroot.keyword1</term>
-
- <listitem>
- <para>Description destroot keyword1.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry>
<term></term>
<listitem>
@@ -1451,6 +1306,8 @@
</varlistentry>
</variablelist>
+ <para>The destroot phase ...</para>
+
<variablelist>
<varlistentry>
<term></term>
@@ -1490,25 +1347,9 @@
</listitem>
</varlistentry>
</variablelist>
- </section>
- <section>
- <title>Install</title>
-
- <para>Install phase keywords.</para>
-
<variablelist>
<varlistentry>
- <term>install.keyword1</term>
-
- <listitem>
- <para>Description install.keyword 1.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry>
<term></term>
<listitem>
@@ -1517,25 +1358,13 @@
</varlistentry>
</variablelist>
- <variablelist>
- <varlistentry>
- <term></term>
+ <para>The install phase ...</para>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>The activate phase ...</para>
- <variablelist>
- <varlistentry>
- <term></term>
+ <para></para>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para></para>
</section>
</section>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/macports-changes/attachments/20070810/d28ab10c/attachment.html
More information about the macports-changes
mailing list