source: trunk/doc-new/guide/xml/portfile-phase.xml @ 96872

Last change on this file since 96872 was 96872, checked in by cal@…, 7 years ago

document destroot.post_args defaulting to DESTDIR=${destdir}

File size: 92.4 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4<section id="reference.phases">
5  <title>Port Phases</title>
6
7  <section id="reference.phases.introduction">
8    <title>Introduction</title>
9
10    <para>The MacPorts port installation process has a number of distinct
11    phases that are described in detail in this section. The default scripts
12    coded into MacPorts base performs the standard
13    <command>configure</command>, <command>make</command>, and <command>make
14    install</command> steps. For applications that do not conform to this
15    standard, installation phases may be declared in a Portfile to <link
16    linkend="development.examples.augment">augment</link> or <link
17    linkend="development.examples.override">override</link> the default
18    behavior as described in the <link linkend="development">Portfile
19    Development</link> chapter.</para>
20
21    <variablelist>
22      <varlistentry>
23        <term>fetch</term>
24
25        <listitem>
26          <para>Fetch the <varname>${distfiles}</varname> from
27          <varname>${master_sites}</varname> and place it in
28          <filename>${prefix}/var/macports/distfiles/${name}</filename>.</para>
29        </listitem>
30      </varlistentry>
31
32      <varlistentry>
33        <term>checksum</term>
34
35        <listitem>
36          <para>Compare <varname>${checksums}</varname> specified in a
37          <filename>Portfile</filename> to the checksums of the fetched
38          ${distfiles}.</para>
39        </listitem>
40      </varlistentry>
41
42      <varlistentry>
43        <term>extract</term>
44
45        <listitem>
46          <para>Unzip and untar the <varname>${distfiles}</varname> into the
47          path ${prefix}/var/macports/build/..../work</para>
48        </listitem>
49      </varlistentry>
50
51      <varlistentry>
52        <term>patch</term>
53
54        <listitem>
55          <para>Apply optional <ulink
56          url="http://en.wikipedia.org/wiki/Patch_(Unix)">patch</ulink> files
57          specified in <varname>${patchfiles}</varname> to modify a port's
58          source code file(s).</para>
59        </listitem>
60      </varlistentry>
61
62      <varlistentry>
63        <term>configure</term>
64
65        <listitem>
66          <para>Execute the command <command>configure</command> in
67          <varname>${worksrcpath}</varname>.</para>
68        </listitem>
69      </varlistentry>
70
71      <varlistentry>
72        <term>build</term>
73
74        <listitem>
75          <para>Execute <varname>${build.cmd}</varname> in
76          <varname>${worksrcpath}</varname>.</para>
77        </listitem>
78      </varlistentry>
79
80      <varlistentry>
81        <term>test</term>
82
83        <listitem>
84          <para>Execute commands to run test suites bundled with a
85          port.</para>
86        </listitem>
87      </varlistentry>
88
89      <varlistentry>
90        <term>destroot</term>
91
92        <listitem>
93          <para>Execute the command <command>make install</command>
94          <varname>DESTDIR=${destroot}</varname>in
95          <varname>${worksrcpath}</varname>.</para>
96
97          <note>
98            <para>Using a <ulink
99            url="http://www.gnu.org/prep/standards/html_node/DESTDIR.html"><varname>DESTDIR</varname>
100            variable</ulink> is a part of standard GNU coding practices, and
101            this variable must be supported in an application's install
102            routines for MacPorts' destroot phase to work without manual
103            Portfile scripting or source patching. Urge developers to fully
104            support <varname>DESTDIR</varname> in their applications.</para>
105          </note>
106
107          <para>Understanding the destroot phase is critical to understanding
108          MacPorts, because, unlike some port systems, MacPorts "stages" an
109          installation into an intermediate location —not the final file
110          destination. MacPorts uses the destroot phase to provide:</para>
111
112          <itemizedlist>
113            <listitem>
114              <para>Port uninstalls - a port's files may be cleanly
115              uninstalled because all files and directories are recorded
116              during install.</para>
117            </listitem>
118
119            <listitem>
120              <para>Multiple port versions may be installed on the same host,
121              since a port's files are not directly inserted into
122              <varname>${prefix}</varname> but rather hard-linked into
123              <varname>${prefix}</varname> from an intermediate location
124              during a later activation phase.</para>
125            </listitem>
126          </itemizedlist>
127
128          <para>Any empty directories in <varname>${destroot}</varname> upon
129          completion of the destroot phase are removed unless a directory name
130          is placed in the value field of the optional
131          <code>destroot.keepdirs</code> keyword.</para>
132        </listitem>
133      </varlistentry>
134
135      <varlistentry>
136        <term>install</term>
137
138        <listitem>
139          <para>Archive a port's destrooted files into
140          <filename>${prefix}/var/macports/software</filename>. See <link
141          linkend="internals.images">Port Images</link> in the <link
142          linkend="internals">MacPorts Internals</link> chapter for
143          details.</para>
144        </listitem>
145      </varlistentry>
146
147      <varlistentry>
148        <term>activate</term>
149
150        <listitem>
151          <para>Extract the port's files from the archive in
152          <filename>${prefix}/var/macports/software</filename> to
153          their final installed locations, usually inside
154          <varname>${prefix}</varname>.</para>
155        </listitem>
156      </varlistentry>
157    </variablelist>
158  </section>
159
160  <section id="reference.phases.installation">
161    <title>Installation Phase Keywords</title>
162
163    <para>MacPorts keywords are used to specify required or optional items
164    within a Portfile, or to override default options used by MacPorts base
165    for individual ports. Keywords are to be used within the "global" and
166    "variant" sections of Portfiles, and not within optional port phase
167    declarations.</para>
168
169    <para>In other words, port phase keywords are not located within port
170    phase declarations, but rather they <emphasis>refer</emphasis> to port
171    phases and set options for those phases, and they take effect whether or
172    not phase declarations have been explicitly defined in a Portfile.</para>
173
174    <section id="reference.phases.installation.list-modifiers">
175      <title>Keyword List Modifiers (-append, -delete, -replace)</title>
176
177      <para>Keyword list modifiers are keywords that end in -append, -delete or
178      -replace. Keywords that support list modifiers are identified under
179      appropriate reference sections below.</para>
180
181      <para>-append adds a value to the keyword, -delete removes a previously
182      added item. -replace treats the keyword value as a string and filters it
183      through <link linkend="reference.tcl-extensions.strsed">strsed</link>
184      using a given pattern.</para>
185
186      <para>Keyword list modifiers are most frequently used for these three
187      purposes:</para>
188
189      <orderedlist>
190        <listitem>
191          <para>Preserve configure defaults set by a previously executed
192          Portfile keyword or by MacPorts base</para>
193
194          <para>MacPorts base sets the gcc compiler flags CFLAGS and LDFLAGS
195          for all ports using <literal>configure.cflags</literal> and
196          <literal>configure.ldflags</literal>, therefore to keep from
197          overwriting the default compiler flags use
198          <literal>configure.cflags-append</literal> and
199          <literal>configure.ldflags-append</literal>.</para>
200
201          <itemizedlist>
202            <listitem>
203              <para><code>configure.cflags-append</code></para>
204            </listitem>
205
206            <listitem>
207              <para><code>configure.ldflags-append</code></para>
208            </listitem>
209          </itemizedlist>
210        </listitem>
211
212        <listitem>
213          <para>Preserve PortGroup Dependencies</para>
214
215          <para>Ports in a PortGroup have default library dependencies set by
216          MacPorts base. Therefore, never use <literal>depends_lib</literal>
217          in ports belonging to a PortGroup or it will overwrite the default
218          library dependencies. Instead, use
219          <literal>depends_lib-append</literal>.</para>
220        </listitem>
221
222        <listitem>
223          <para>Add or Delete Items for Variants</para>
224
225          <para>When a variant requires more or fewer dependencies, distfiles,
226          or patchfiles, when the variant is invoked you want to add or remove
227          items to the appropriate keyword values list set in the global
228          section of the Portfile. Use the appropriate keywords, for
229          example:</para>
230
231          <itemizedlist>
232            <listitem>
233              <para><code>depends_lib-append</code> or
234              <code>depends_lib-delete</code>
235              <code>depends_lib-replace</code>
236              </para>
237            </listitem>
238
239            <listitem>
240              <para><code>distfiles-append</code> or
241              <code>distfiles-delete</code>
242              <code>distfiles-replace</code></para>
243            </listitem>
244
245            <listitem>
246              <para><code>patchfiles-append</code> or
247              <code>patchfiles-delete</code>
248              <code>patchfiles-replace</code></para>
249            </listitem>
250          </itemizedlist>
251        </listitem>
252      </orderedlist>
253    </section>
254
255    <section id="reference.phases.installation.argument-modifiers">
256      <title>Keyword Argument Modifiers (.pre_args / .post_args)</title>
257
258      <para>Keywords that support pre_args and post_args are used to assemble
259      command strings together in a row, as described in the reference
260      sections below. But it should be noted that all keyword argument
261      modifiers implicitly support keyword list modifiers. For example, the
262      keyword <literal>configure.pre_args</literal> also supports
263      <literal>configure.pre_args-append</literal> and
264      <literal>configure.pre_args-delete</literal>.</para>
265    </section>
266  </section>
267
268  <section id="reference.phases.fetch">
269    <title>Fetch Phase Keywords</title>
270
271    <para>The list of keywords related to the fetch phase.</para>
272
273    <variablelist>
274      <varlistentry>
275        <term>master_sites</term>
276
277        <listitem>
278          <para>A list of URLs from which a port's
279          <varname>${distfiles}</varname> may be retrieved.</para>
280
281          <para>Keyword values for <code>master_sites</code> may include
282          predefined site lists known as <quote>mirrors</quote>, such as
283          sourceforge, gnu, etc. If the file(s) declared in
284          <varname>${distfiles}</varname> are not successfully fetched after
285          trying the <code>master_sites</code> values, the MacPorts Project
286          svn server is always tried last before giving up.</para>
287
288          <para>For a complete list of mirrors and their list of sites, see
289          the file <filename>mirror_sites.tcl</filename> located in
290          <filename>_resources/port1.0/fetch/</filename> in the ports tree.</para>
291
292          <note>
293            <para>If a <code>master_sites</code> keyword has multiple values,
294            after any mirrors are expanded the list of sites is sorted by ping
295            response times. The sites are then tried in sorted order until
296            matching <varname>${distfiles}</varname> are found.</para>
297          </note>
298
299          <itemizedlist>
300            <listitem>
301              <para>Default: <code>none</code> (but the <code>macports_distfiles</code>
302              mirror is always implicitly appended)</para>
303            </listitem>
304
305            <listitem>
306              <para>Examples:</para>
307
308              <programlisting>master_sites        http://www.example.org/files/ \
309                    http://www.examplemirror.org/example_org/files/
310
311</programlisting>
312
313              <para>You may also use mirror site lists predefined by MacPorts.
314              Here the sourceforge, gnu, and freebsd mirrors are
315              used.</para>
316
317              <programlisting>master_sites        sourceforge gnu freebsd
318
319</programlisting>
320
321              <para>When using mirror master_sites, the subdirectory
322              <varname>${name}</varname> is checked on every mirror. If the
323              mirror subdirectory does not match ${name}, then you may specify
324              it using after the mirror separated by a colon.</para>
325
326              <programlisting>master_sites        sourceforge:widget \
327                    gnu:widget
328
329</programlisting>
330
331              <para>For ports that must fetch multiple download files from
332              different locations, you must label the files with tags and
333              match the tags to a <literal>distfiles</literal> keyword. The
334              format is <literal>mirror:subdirectory:tag</literal>.</para>
335
336              <para>In the example below, file_one.tar.gz is fetched from
337              sourceforge mirrors in subdirectory <varname>${name}</varname>;
338              file tagtwo.tar.gz is fetched from the gnu mirrors in
339              subdirectory sources.</para>
340
341              <programlisting>master_sites        sourceforge::tagone \
342                    gnu:sources:tagtwo
343
344distfiles           file_one.tar.gz:tagone \
345                    file_two.tar.gz:tagtwo</programlisting>
346            </listitem>
347          </itemizedlist>
348        </listitem>
349      </varlistentry>
350
351      <varlistentry>
352        <term>master_sites.mirror_subdir</term>
353
354        <listitem>
355          <para>Subdirectory to append to all mirror sites for any list
356          specified in <varname>${master_sites}</varname>.</para>
357
358          <!-- TODO: add a better explanation -->
359
360          <itemizedlist>
361            <listitem>
362              <para>Default: <varname>${name}</varname></para>
363            </listitem>
364
365            <listitem>
366              <para>Example:</para>
367
368              <programlisting>master_sites.mirror_subdir  magic</programlisting>
369            </listitem>
370          </itemizedlist>
371        </listitem>
372      </varlistentry>
373
374      <varlistentry>
375        <term>patch_sites</term>
376
377        <listitem>
378          <para>A list of sites from which a port's patchfiles may be
379          downloaded, where applicable.</para>
380
381          <itemizedlist>
382            <listitem>
383              <para>Default: <varname>${master_sites}</varname></para>
384            </listitem>
385
386            <listitem>
387              <para>Example:</para>
388
389              <programlisting>patch_sites         ftp://ftp.patchcityrepo.com/pub/magic/patches</programlisting>
390            </listitem>
391          </itemizedlist>
392        </listitem>
393      </varlistentry>
394
395      <varlistentry>
396        <term>patch_sites.mirror_subdir</term>
397
398        <listitem>
399          <para>Subdirectory to append to all mirror sites for any list
400          specified in <varname>${patch_sites}</varname>.</para>
401
402          <!-- TODO: add a better explanation -->
403
404          <itemizedlist>
405            <listitem>
406              <para>Default: <varname>${name}</varname></para>
407            </listitem>
408
409            <listitem>
410              <para>Example:</para>
411
412              <programlisting>patch_sites.mirror_subdir   magic</programlisting>
413            </listitem>
414          </itemizedlist>
415        </listitem>
416      </varlistentry>
417
418      <varlistentry>
419        <term>distname</term>
420
421        <listitem>
422          <para>The name of the distribution filename, not including the
423          extract suffix (see below).</para>
424
425          <itemizedlist>
426            <listitem>
427              <para>Default: <varname>${name}-${version}</varname></para>
428            </listitem>
429
430            <listitem>
431              <para>Example:</para>
432
433              <programlisting>distname            ${name}</programlisting>
434            </listitem>
435          </itemizedlist>
436        </listitem>
437      </varlistentry>
438
439      <varlistentry>
440        <term>distfiles</term>
441
442        <listitem>
443          <para>The full distribution filename, including the extract suffix.
444          Used to specify non-default distribution filenames; this keyword
445          must be specified (and tags used) when a port has multiple download
446          files (see master_sites).</para>
447
448          <itemizedlist>
449            <listitem>
450              <para>Default:
451              <varname>${distname}${extract.suffix}</varname></para>
452            </listitem>
453
454            <listitem>
455              <para>Examples:</para>
456
457              <programlisting>distfiles           ${name}-dev_src.tgz</programlisting>
458
459              <programlisting>distfiles           file_one.tar.gz:tagone \
460                    file_two.tar.gz:tagtwo</programlisting>
461            </listitem>
462          </itemizedlist>
463        </listitem>
464      </varlistentry>
465
466      <varlistentry>
467        <term>dist_subdir</term>
468
469        <listitem>
470          <para>Create a sub-directory in distpath to store all fetched
471          files.</para>
472
473          <itemizedlist>
474            <listitem>
475              <para>Default: <varname>${name}</varname></para>
476            </listitem>
477
478            <listitem>
479              <para>Example:</para>
480
481              <programlisting>dist_subdir         vim${version}</programlisting>
482            </listitem>
483          </itemizedlist>
484        </listitem>
485      </varlistentry>
486
487      <varlistentry>
488        <term>worksrcdir</term>
489
490        <listitem>
491          <para>Sets the path to source directory relative to workpath. It can
492          be used if the extracted source directory has a different name then
493          the distfile. Also used if the source to be built is in a
494          subdirectory.</para>
495
496          <itemizedlist>
497            <listitem>
498              <para>Default: <varname>${distname}</varname></para>
499            </listitem>
500
501            <listitem>
502              <para>Examples:</para>
503
504              <programlisting>worksrcdir          ${name}-src-${version}</programlisting>
505              <programlisting>worksrcdir          ${distname}/src</programlisting>
506            </listitem>
507          </itemizedlist>
508        </listitem>
509      </varlistentry>
510    </variablelist>
511
512    <section id="reference.phases.fetch.advanced">
513      <title>Advanced Fetch Options</title>
514
515      <para>Some mirrors require special options for a resource to be properly
516      fetched.</para>
517
518      <variablelist>
519        <varlistentry id="reference.phases.fetch.advanced.fetch-type">
520          <term>fetch.type</term>
521
522          <listitem>
523            <para>Change the fetch type. This is only necessary if a <link
524            linkend="reference.phases.fetch.cvs">CVS</link>, <link
525            linkend="reference.phases.fetch.svn">svn</link>, <link
526            linkend="reference.phases.fetch.git">git</link> or <link
527            linkend="reference.phases.fetch.hg">hg</link> checkout is be used.
528            <option>standard</option> is used for a normal http or ftp fetch
529            using <varname>${distfiles}</varname> and is used as
530            default.</para>
531
532            <itemizedlist>
533              <listitem>
534                <para>Default: <option>standard</option></para>
535              </listitem>
536
537              <listitem>
538                <para>Values: <option>standard</option> <option>cvs</option>
539                <option>svn</option> <option>git</option></para>
540              </listitem>
541
542              <listitem>
543                <para>Example:</para>
544
545                <programlisting>fetch.type          svn
546svn.url             svn://example.org
547svn.revision        2100</programlisting>
548              </listitem>
549            </itemizedlist>
550          </listitem>
551        </varlistentry>
552
553        <varlistentry>
554          <term>fetch.user</term>
555
556          <listitem>
557            <para>HTTP or FTP user to fetch the resource.</para>
558
559            <itemizedlist>
560              <listitem>
561                <para>Default: none</para>
562              </listitem>
563
564              <listitem>
565                <para>Example:</para>
566
567                <programlisting>TODO: add example</programlisting>
568              </listitem>
569            </itemizedlist>
570          </listitem>
571        </varlistentry>
572
573        <varlistentry>
574          <term>fetch.password</term>
575
576          <listitem>
577            <para>HTTP or FTP password to fetch the resource.</para>
578
579            <itemizedlist>
580              <listitem>
581                <para>Default: none</para>
582              </listitem>
583
584              <listitem>
585                <para>Example:</para>
586
587                <programlisting>TODO: add example</programlisting>
588              </listitem>
589            </itemizedlist>
590          </listitem>
591        </varlistentry>
592
593        <varlistentry>
594          <term>fetch.use_epsv</term>
595
596          <listitem>
597            <para>Whether to use EPSV command for FTP transfers.</para>
598
599            <itemizedlist>
600              <listitem>
601                <para>Default: <option>yes</option></para>
602              </listitem>
603
604              <listitem>
605                <para>Example:</para>
606
607                <programlisting>fetch.use_epsv      no</programlisting>
608              </listitem>
609            </itemizedlist>
610          </listitem>
611        </varlistentry>
612
613        <varlistentry>
614          <term>fetch.ignore_sslcert</term>
615
616          <listitem>
617            <para>Whether to ignore the host SSL certificate (for
618            HTTPS).</para>
619
620            <itemizedlist>
621              <listitem>
622                <para>Default: <option>no</option></para>
623              </listitem>
624
625              <listitem>
626                <para>Example:</para>
627
628                <programlisting>fetch.ignore_sslcert    yes</programlisting>
629              </listitem>
630            </itemizedlist>
631          </listitem>
632        </varlistentry>
633      </variablelist>
634    </section>
635
636    <section id="reference.phases.fetch.cvs">
637      <title>Fetch from CVS</title>
638
639      <para><ulink url="http://www.nongnu.org/cvs/">CVS</ulink> may be used as
640      an alternative method of fetching distribution files using the keywords
641      in this section. However, fetching via CVS may cause non-reproducible
642      builds, so it is strongly discouraged.</para>
643
644      <para>The <option>cvs</option> <link
645      linkend="reference.phases.fetch.advanced.fetch-type">fetch.type</link>
646      is used to fetch source code from a CVS repository.</para>
647
648      <variablelist>
649        <varlistentry>
650          <term>cvs.root</term>
651
652          <listitem>
653            <para>Specify the url from which to fetch files.</para>
654
655            <itemizedlist>
656              <listitem>
657                <para>Default: none</para>
658              </listitem>
659
660              <listitem>
661                <para>Example:</para>
662
663                <programlisting>cvs.root            :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs</programlisting>
664              </listitem>
665            </itemizedlist>
666          </listitem>
667        </varlistentry>
668
669        <varlistentry>
670          <term>cvs.password</term>
671
672          <listitem>
673            <para>Password to login to the CVS server.</para>
674
675            <itemizedlist>
676              <listitem>
677                <para>Default: none</para>
678              </listitem>
679
680              <listitem>
681                <para>Example:</para>
682
683                <programlisting>cvs.password        nice-password</programlisting>
684              </listitem>
685            </itemizedlist>
686          </listitem>
687        </varlistentry>
688
689        <varlistentry>
690          <term>cvs.tag</term>
691
692          <listitem>
693            <para>Optional for fetching with CVS, this specifies the code
694            revision to checkout.</para>
695
696            <itemizedlist>
697              <listitem>
698                <para>Default: none</para>
699              </listitem>
700
701              <listitem>
702                <para>Example:</para>
703
704                <programlisting>cvs.tag             HEAD</programlisting>
705              </listitem>
706            </itemizedlist>
707          </listitem>
708        </varlistentry>
709
710        <varlistentry>
711          <term>cvs.date</term>
712
713          <listitem>
714            <para>A date that identifies the CVS code set to checkout.</para>
715
716            <itemizedlist>
717              <listitem>
718                <para>Default: none</para>
719              </listitem>
720
721              <listitem>
722                <para>Example:</para>
723
724                <programlisting>cvs.date            "12-April-2007"</programlisting>
725              </listitem>
726            </itemizedlist>
727          </listitem>
728        </varlistentry>
729
730        <varlistentry>
731          <term>cvs.module</term>
732
733          <listitem>
734            <para>A CVS module from which to check out the code.</para>
735
736            <itemizedlist>
737              <listitem>
738                <para>Default: none</para>
739              </listitem>
740
741              <listitem>
742                <para>Example:</para>
743
744                <programlisting>cvs.module          Sources</programlisting>
745              </listitem>
746            </itemizedlist>
747          </listitem>
748        </varlistentry>
749      </variablelist>
750    </section>
751
752    <section id="reference.phases.fetch.svn">
753      <title>Fetch from Subversion</title>
754
755      <para><ulink url="http://subversion.apache.org/">Subversion</ulink> may
756      be used as an alternative method of fetching distribution files using
757      the keywords in this section. However, fetching via Subversion may cause
758      non-reproducible builds, so it is strongly discouraged.</para>
759
760      <para>The <option>svn</option> <link
761      linkend="reference.phases.fetch.advanced.fetch-type">fetch.type</link>
762      is used to fetch source code from an svn repository.</para>
763
764      <variablelist>
765        <varlistentry>
766          <term>svn.url</term>
767
768          <listitem>
769            <para>This specifies the url from which to fetch files.</para>
770
771            <itemizedlist>
772              <listitem>
773                <para>Default: none</para>
774              </listitem>
775
776              <listitem>
777                <para>Examples:</para>
778
779                <programlisting>svn.url             http://www.domain.com/svn-repo/mydirectory</programlisting>
780
781                <programlisting>svn.url             svn://www.domain.com/svn-repo/mydirectory</programlisting>
782              </listitem>
783            </itemizedlist>
784          </listitem>
785        </varlistentry>
786
787        <varlistentry>
788          <term>svn.revision</term>
789
790          <listitem>
791            <para>Optional tag for fetching with Subversion, this specifies
792            the peg revision to checkout; it corresponds to the @REV syntax of
793            the svn cli.</para>
794
795            <itemizedlist>
796              <listitem>
797                <para>Default: none</para>
798              </listitem>
799
800              <listitem>
801                <para>Example:</para>
802
803                <programlisting>svn.revision        37192</programlisting>
804              </listitem>
805            </itemizedlist>
806          </listitem>
807        </varlistentry>
808
809        <varlistentry>
810          <term>svn.method</term>
811
812          <listitem>
813            <para>Optional tag for fetching with Subversion, this specifies
814            whether to check out the code into a working copy, or just export
815            it without the working copy metadata. An export is preferable
816            because it takes half the disk space, but some software expects
817            to be built in a working copy (for example because it wants to
818            record the revision number into itself somewhere).</para>
819
820            <itemizedlist>
821              <listitem>
822                <para>Default: export</para>
823              </listitem>
824
825              <listitem>
826                <para>Example:</para>
827
828                <programlisting>svn.method          checkout</programlisting>
829              </listitem>
830            </itemizedlist>
831          </listitem>
832        </varlistentry>
833      </variablelist>
834    </section>
835
836    <section id="reference.phases.fetch.git">
837      <title>Fetch from Git</title>
838
839      <para><ulink url="http://git-scm.com/">Git</ulink> may be used as an
840      alternative method of fetching distribution files using the keywords in
841      this section. However, fetching via Git may cause non-reproducible
842      builds, so it is strongly discouraged.</para>
843
844      <para>The <option>git</option> <link
845      linkend="reference.phases.fetch.advanced.fetch-type">fetch.type</link>
846      is used to fetch source code from a git repository.</para>
847
848      <variablelist>
849        <varlistentry>
850          <term>git.url</term>
851
852          <listitem>
853            <para>This specifies the url from which to fetch files.</para>
854
855            <itemizedlist>
856              <listitem>
857                <para>Default: none</para>
858              </listitem>
859
860              <listitem>
861                <para>Examples:</para>
862
863                <programlisting>git.url             git://git.kernel.org/pub/scm/git/git.git</programlisting>
864
865                <programlisting>git.url             http://www.kernel.org/pub/scm/git/git.git</programlisting>
866              </listitem>
867            </itemizedlist>
868          </listitem>
869        </varlistentry>
870
871        <varlistentry>
872          <term>git.branch</term>
873
874          <listitem>
875            <para>Optional tag for fetching with git, this specifies the tag
876            or other commit-ish that git should checkout. Note that any tag on
877            a branch besides HEAD should be prefixed by origin/.</para>
878
879            <itemizedlist>
880              <listitem>
881                <para>Default: none</para>
882              </listitem>
883
884              <listitem>
885                <para>Example:</para>
886
887                <programlisting>git.branch             72bf1c8</programlisting>
888
889                <programlisting>git.branch             origin/next</programlisting>
890              </listitem>
891            </itemizedlist>
892          </listitem>
893        </varlistentry>
894      </variablelist>
895    </section>
896
897    <section id="reference.phases.fetch.hg">
898      <title>Fetch from Mercurial</title>
899
900      <para><ulink url="http://mercurial.selenic.com/">Mercurial</ulink> may be
901      used as an alternative method of fetching distribution files using the
902      keywords in this section. However, fetching via Mercurial may cause
903      non-reproducible builds, so it is strongly discouraged.</para>
904
905      <para>The <option>hg</option> <link
906      linkend="reference.phases.fetch.advanced.fetch-type">fetch.type</link>
907      is used to fetch fource code from a Mercurial repository.</para>
908
909      <variablelist>
910        <varlistentry>
911          <term>hg.url</term>
912
913          <listitem>
914            <para>This specifies the url from which to fetch files.</para>
915
916            <itemizedlist>
917              <listitem>
918                <para>Default: none</para>
919              </listitem>
920
921              <listitem>
922                <para>Examples:</para>
923
924                <programlisting>hg.url              http://www.kernel.org/hg/index.cgi/linux-2.6/</programlisting>
925
926                <programlisting>hg.url              http://hg.intevation.org/mercurial</programlisting>
927              </listitem>
928            </itemizedlist>
929          </listitem>
930        </varlistentry>
931
932        <varlistentry>
933          <term>hg.tag</term>
934
935          <listitem>
936            <para>Optional tag which should be fetched. Can be a Mercurial tag
937            or a revision. To prevent non-reproducible builds use of tip as
938            revision is discouraged.</para>
939
940            <itemizedlist>
941              <listitem>
942                <para>Default: tip</para>
943              </listitem>
944
945              <listitem>
946                <para>Example:</para>
947
948                <programlisting>hg.tag              v1.3</programlisting>
949
950                <programlisting>hg.tag              ceb884843737</programlisting>
951              </listitem>
952            </itemizedlist>
953          </listitem>
954        </varlistentry>
955      </variablelist>
956    </section>
957  </section>
958
959  <section id="reference.phases.checksum">
960    <title>Checksum Phase Keywords</title>
961
962    <para>The list of keywords related to the checksum phase.</para>
963
964    <variablelist>
965      <varlistentry>
966        <term>checksums</term>
967
968        <listitem>
969          <para>Checksum(s) of the distribution files. For ports with multiple
970          distribution files, filenames must be included to associate files
971          with their checksums.</para>
972
973          <para>At least two checksum types (e.g., rmd160 and sha256) should be used to
974          ensure the integrity of the distfiles.</para>
975
976          <itemizedlist>
977            <listitem>
978              <para>Default: none</para>
979            </listitem>
980
981            <listitem>
982              <para>Examples:</para>
983
984              <programlisting>checksums           rmd160  0c1147242adf476f5e93f4d59b553ee3ea378b23 \
985                    sha256  baf8a29ff721178317aac7b864c2d392b1accc02de8677dd24c18fd5717bf26e</programlisting>
986
987              <programlisting>checksums           ${distname}${extract.suffix} \
988                        rmd160  0c1147242adf476f5e93f4d59b553ee3ea378b23 \
989                        sha256  883715307c31ae2c145db15d2404d89a837f4d03d7e6932aed21d1d1f21dad89 \
990                    hobbit.tar.gz \
991                        rmd160  82b9991f3bf0ceedbf74c188c5fa44b98b5e40c9 \
992                        sha256  2c3afd16915e9f8eac2351673f8b599f5fd2ff9064d4dfe61f750d72bab740b3</programlisting>
993            </listitem>
994          </itemizedlist>
995        </listitem>
996      </varlistentry>
997    </variablelist>
998  </section>
999
1000  <section id="reference.phases.extract">
1001    <title>Extract Phase Keywords</title>
1002
1003    <para>The list of keywords related to the extract phase.</para>
1004
1005    <variablelist>
1006      <varlistentry>
1007        <term>extract.asroot</term>
1008
1009        <listitem>
1010          <para>This keyword is used to specify that the extract
1011          phase should be done as the root user.</para>
1012
1013          <itemizedlist>
1014            <listitem>
1015              <para>Default: <option>no</option></para>
1016            </listitem>
1017
1018            <listitem>
1019              <para>Example:</para>
1020
1021              <programlisting>extract.asroot      no</programlisting>
1022            </listitem>
1023          </itemizedlist>
1024        </listitem>
1025      </varlistentry>
1026       
1027      <varlistentry>
1028        <term>extract.suffix</term>
1029
1030        <listitem>
1031          <para>This keyword is used to specify the extract suffix
1032          type.</para>
1033
1034          <itemizedlist>
1035            <listitem>
1036              <para>Default: <filename>.tar.gz</filename></para>
1037            </listitem>
1038
1039            <listitem>
1040              <para>Example:</para>
1041
1042              <programlisting>extract.suffix      .tgz</programlisting>
1043            </listitem>
1044          </itemizedlist>
1045        </listitem>
1046      </varlistentry>
1047
1048      <varlistentry>
1049        <term>use_7z</term>
1050
1051        <listitem>
1052          <para>This keyword is for downloads that are compressed using the
1053          7z algorithm.  When invoked, it automatically sets:</para>
1054
1055          <literallayout>extract.suffix = .7z
1056extract.cmd    = 7za
1057
1058</literallayout>
1059
1060          <itemizedlist>
1061            <listitem>
1062              <para>Default: <option>no</option></para>
1063            </listitem>
1064
1065            <listitem>
1066              <para>Example:</para>
1067
1068              <programlisting>use_7z           yes</programlisting>
1069            </listitem>
1070          </itemizedlist>
1071        </listitem>
1072      </varlistentry>
1073
1074      <varlistentry>
1075        <term>use_bzip2</term>
1076
1077        <listitem>
1078          <para>This keyword is for downloads that are tarred and bzipped.
1079          When invoked, it automatically sets:</para>
1080
1081          <literallayout>extract.suffix = .tar.bz2
1082extract.cmd    = bzip
1083
1084</literallayout>
1085
1086          <itemizedlist>
1087            <listitem>
1088              <para>Default: <option>no</option></para>
1089            </listitem>
1090
1091            <listitem>
1092              <para>Example:</para>
1093
1094              <programlisting>use_bzip2           yes</programlisting>
1095            </listitem>
1096          </itemizedlist>
1097        </listitem>
1098      </varlistentry>
1099
1100      <varlistentry>
1101        <term>use_lzma</term>
1102
1103        <listitem>
1104          <para>This keyword is for downloads that are compressed using the
1105          lzma algorithm. When invoked, it automatically sets:</para>
1106
1107          <literallayout>extract.suffix    = .lzma
1108extract.cmd       = lzma
1109
1110</literallayout>
1111
1112          <itemizedlist>
1113            <listitem>
1114              <para>Default: <option>no</option></para>
1115            </listitem>
1116
1117            <listitem>
1118              <para>Example:</para>
1119
1120              <programlisting>use_lzma             yes</programlisting>
1121            </listitem>
1122          </itemizedlist>
1123        </listitem>
1124      </varlistentry>
1125
1126      <varlistentry>
1127        <term>use_zip</term>
1128
1129        <listitem>
1130          <para>This keyword is for downloads that are zipped. When invoked,
1131          it automatically sets:</para>
1132
1133          <literallayout>extract.suffix    = .zip
1134extract.cmd       = unzip
1135extract.pre_args  = -q
1136extract.post_args = "-d ${portpath}/${workdir}"
1137
1138</literallayout>
1139
1140          <itemizedlist>
1141            <listitem>
1142              <para>Default: <option>no</option></para>
1143            </listitem>
1144
1145            <listitem>
1146              <para>Example:</para>
1147
1148              <programlisting>use_zip             yes</programlisting>
1149            </listitem>
1150          </itemizedlist>
1151        </listitem>
1152      </varlistentry>
1153
1154      <varlistentry>
1155        <term>use_xz</term>
1156
1157        <listitem>
1158          <para>This keyword is for downloads that are compressed using the xz tool.
1159          When invoked, it automatically sets:</para>
1160
1161          <literallayout>extract.suffix    = .tar.xz
1162extract.cmd       = xz
1163
1164</literallayout>
1165
1166          <itemizedlist>
1167            <listitem>
1168              <para>Default: <option>no</option></para>
1169            </listitem>
1170
1171            <listitem>
1172              <para>Example:</para>
1173
1174              <programlisting>use_xz             yes</programlisting>
1175            </listitem>
1176          </itemizedlist>
1177        </listitem>
1178      </varlistentry>
1179
1180
1181      <varlistentry>
1182        <term>extract.mkdir</term>
1183
1184        <listitem>
1185          <para>This keyword is used to specify if the directory
1186          <filename>worksrcdir</filename> is part of the distfile or if it
1187          should be created automatically and the distfiles should be
1188          extracted there instead. This is useful for distfiles with a flat
1189          structure which would pollute the <filename>worksrcdir</filename>
1190          with lots of files.</para>
1191
1192          <itemizedlist>
1193            <listitem>
1194              <para>Default: <option>no</option></para>
1195            </listitem>
1196
1197            <listitem>
1198              <para>Example:</para>
1199
1200              <programlisting>extract.mkdir       yes</programlisting>
1201            </listitem>
1202          </itemizedlist>
1203        </listitem>
1204      </varlistentry>
1205
1206      <varlistentry>
1207        <term>extract.only</term>
1208
1209        <term>extract.only-append</term>
1210
1211        <term>extract.only-delete</term>
1212
1213        <listitem>
1214          <para>List of files to extract into
1215          <varname>${worksrcpath}</varname>. Only use if default extract
1216          behavior is not correct for your port.</para>
1217
1218          <itemizedlist>
1219            <listitem>
1220              <para>Default: <varname>${distfiles}</varname></para>
1221            </listitem>
1222
1223            <listitem>
1224              <para>Example:</para>
1225
1226              <programlisting>extract.only        foo.tar.gz</programlisting>
1227
1228              <programlisting>extract.only-append     bar.tar.gz
1229extract.only-delete     foo.tar.gz</programlisting>
1230            </listitem>
1231          </itemizedlist>
1232        </listitem>
1233      </varlistentry>
1234
1235      <varlistentry>
1236        <term>extract.cmd</term>
1237
1238        <listitem>
1239          <para>Command to perform extraction.</para>
1240
1241          <itemizedlist>
1242            <listitem>
1243              <para>Default: <command>gzip</command></para>
1244            </listitem>
1245
1246            <listitem>
1247              <para>Example:</para>
1248
1249              <programlisting>extract.cmd         gunzip</programlisting>
1250            </listitem>
1251          </itemizedlist>
1252        </listitem>
1253      </varlistentry>
1254
1255      <varlistentry>
1256        <term>extract.args</term>
1257
1258        <term>extract.pre_args</term>
1259
1260        <term>extract.post_args</term>
1261
1262        <listitem>
1263          <para>Main arguments to <varname>extract.cmd</varname>; additional
1264          arguments passed before and after the main arguments.</para>
1265
1266          <itemizedlist>
1267            <listitem>
1268              <para>Default: <varname>${distpath}/${distfile}</varname></para>
1269            </listitem>
1270
1271            <listitem>
1272              <para>Example:</para>
1273
1274              <programlisting>extract.args        ${distpath}/${distfile}
1275
1276</programlisting>
1277            </listitem>
1278          </itemizedlist>
1279
1280          <para>The following argument modifiers are available:</para>
1281
1282          <itemizedlist>
1283            <listitem>
1284              <para><literal>extract.pre_args</literal>, defaults to:
1285              <literal>-dc</literal></para>
1286            </listitem>
1287
1288            <listitem>
1289              <para><literal>extract.post_args</literal>, defaults to:
1290              <literal>"| tar -xf -"</literal></para>
1291            </listitem>
1292
1293            <listitem>
1294              <para>Examples:</para>
1295
1296              <programlisting>extract.pre_args    xf
1297extract.post_args   "| gnutar -x"</programlisting>
1298            </listitem>
1299          </itemizedlist>
1300        </listitem>
1301      </varlistentry>
1302    </variablelist>
1303  </section>
1304
1305  <section id="reference.phases.patch">
1306    <title>Patch Phase Keywords</title>
1307
1308    <para>The list of keywords related to the patch phase.</para>
1309
1310    <variablelist>
1311      <varlistentry>
1312        <term>patch.dir</term>
1313
1314        <listitem>
1315          <para>Specify the base path for patch files.</para>
1316
1317          <itemizedlist>
1318            <listitem>
1319              <para>Default: <varname>${worksrcpath}</varname></para>
1320            </listitem>
1321
1322            <listitem>
1323              <para>Example:</para>
1324
1325              <programlisting>patch.dir           ${worksrcpath}/util</programlisting>
1326            </listitem>
1327          </itemizedlist>
1328        </listitem>
1329      </varlistentry>
1330
1331      <varlistentry>
1332        <term>patch.cmd</term>
1333
1334        <listitem>
1335          <para>Specify the command to be used for patching files.</para>
1336
1337          <itemizedlist>
1338            <listitem>
1339              <para>Default: <command>patch</command></para>
1340            </listitem>
1341
1342            <listitem>
1343              <para>Example:</para>
1344
1345              <programlisting>patch.cmd           cat</programlisting>
1346            </listitem>
1347          </itemizedlist>
1348        </listitem>
1349      </varlistentry>
1350
1351      <varlistentry>
1352        <term>patchfiles</term>
1353
1354        <term>patchfiles-append</term>
1355
1356        <term>patchfiles-delete</term>
1357
1358        <listitem>
1359          <para>Specify patch files to be applied for a port; list modifiers
1360          specify patchfiles to be added or removed from a previous patchfile
1361          declaration.</para>
1362
1363          <itemizedlist>
1364            <listitem>
1365              <para>Default: none</para>
1366            </listitem>
1367
1368            <listitem>
1369              <para>Example:</para>
1370
1371              <programlisting>patchfiles          patch-Makefile.in \
1372                    patch-source.c</programlisting>
1373
1374              <programlisting>patchfiles-append   patch-configure
1375patchfiles-delete   patch-src-Makefile.in</programlisting>
1376            </listitem>
1377          </itemizedlist>
1378        </listitem>
1379      </varlistentry>
1380
1381      <varlistentry>
1382        <term>patch.args</term>
1383
1384        <term>patch.pre_args</term>
1385
1386        <term>patch.post_args</term>
1387
1388        <listitem>
1389          <para>Main arguments to <varname>patch.cmd</varname>; optional
1390          argument modifiers pass arguments before and after the main
1391          arguments.</para>
1392
1393          <itemizedlist>
1394            <listitem>
1395              <para>Default: none</para>
1396            </listitem>
1397
1398            <listitem>
1399              <para>Example:</para>
1400
1401              <programlisting>patch.args          ???
1402
1403</programlisting>
1404            </listitem>
1405          </itemizedlist>
1406
1407          <para>The following argument modifiers are available:</para>
1408
1409          <itemizedlist>
1410            <listitem>
1411              <para><literal>patch.pre_args</literal>, defaults to:
1412              <literal>-p0</literal></para>
1413            </listitem>
1414
1415            <listitem>
1416              <para><literal>patch.post_args</literal>, defaults to:
1417              none</para>
1418            </listitem>
1419
1420            <listitem>
1421              <para>Examples:</para>
1422
1423              <programlisting>patch.pre_args      -p1
1424patch.post_args     ???</programlisting>
1425            </listitem>
1426          </itemizedlist>
1427        </listitem>
1428      </varlistentry>
1429    </variablelist>
1430  </section>
1431
1432  <section id="reference.phases.configure">
1433    <title>Configure Phase Keywords</title>
1434
1435    <para>The list of keywords related to the configure phase.</para>
1436
1437    <para>MacPorts base sets some important default configure options, so
1438    should use the -append version of most configure keywords so you don't
1439    overwrite them. For example, MacPorts base sets default
1440    <literal>configure.cflags</literal> so you should always use
1441    <literal>configure.cflags-append</literal> to set additional CFLAGS in
1442    Portfiles.</para>
1443
1444    <variablelist>
1445      <varlistentry>
1446        <term>use_configure</term>
1447
1448        <listitem>
1449          <para>Sets if the configure phase should be run. Can be used if the
1450          port has no <filename>./configure</filename> script.</para>
1451
1452          <itemizedlist>
1453            <listitem>
1454              <para>Default: <option>yes</option></para>
1455            </listitem>
1456
1457            <listitem>
1458              <para>Example:</para>
1459
1460              <programlisting>use_configure    no</programlisting>
1461            </listitem>
1462          </itemizedlist>
1463        </listitem>
1464      </varlistentry>
1465
1466      <varlistentry>
1467        <term>configure.env</term>
1468
1469        <term>configure.env-append</term>
1470
1471        <term>configure.env-delete</term>
1472
1473        <listitem>
1474          <para>Set environment variables for configure; list modifiers add
1475          and delete items from a previous Portfile configure.env keyword, or
1476          a default set by MacPorts base. If available, it is encouraged to
1477          use the predefined options (like <link
1478          linkend="reference.phases.configure.cflags">configure.cflags</link>)
1479          instead of modifying configure.env directly.</para>
1480
1481          <itemizedlist>
1482            <listitem>
1483              <para>Default: <literal>CFLAGS=-I${prefix}/include
1484              LDFLAGS=-L${prefix}/lib</literal></para>
1485            </listitem>
1486
1487            <listitem>
1488              <para>Example:</para>
1489
1490              <programlisting>configure.env       QTDIR=${prefix}/lib/qt3</programlisting>
1491
1492              <programlisting>configure.env-append    ABI=32
1493configure.env-delete    TCLROOT=${prefix}</programlisting>
1494            </listitem>
1495          </itemizedlist>
1496        </listitem>
1497      </varlistentry>
1498
1499      <varlistentry id="reference.phases.configure.optflags">
1500        <term>configure.optflags</term>
1501
1502        <term>configure.optflags-append</term>
1503
1504        <term>configure.optflags-delete</term>
1505
1506        <listitem>
1507          <para>Set optimization compiler flags; list modifiers add or delete items
1508          from a previous Portfile configure.optflags keyword or the default set
1509          by MacPorts base.</para>
1510
1511          <itemizedlist>
1512            <listitem>
1513              <para>Default: <literal>-O2</literal></para>
1514            </listitem>
1515
1516            <listitem>
1517              <para>Example:</para>
1518
1519              <programlisting>configure.optflags    -Os</programlisting>
1520
1521              <programlisting>configure.optflags-append     -finline-functions
1522configure.optflags-delete     -O2</programlisting>
1523            </listitem>
1524          </itemizedlist>
1525        </listitem>
1526      </varlistentry>
1527
1528      <varlistentry id="reference.phases.configure.cflags">
1529        <term>configure.cflags</term>
1530
1531        <term>configure.cflags-append</term>
1532
1533        <term>configure.cflags-delete</term>
1534
1535        <listitem>
1536          <para>Set CFLAGS compiler flags; list modifiers add or delete items
1537          from a previous Portfile configure.cflags keyword or the default set
1538          by MacPorts base.</para>
1539
1540          <itemizedlist>
1541            <listitem>
1542              <para>Default: <literal>${configure.optflags}</literal></para>
1543            </listitem>
1544
1545            <listitem>
1546              <para>Example:</para>
1547
1548              <programlisting>configure.cflags    -Os -flat_namespace</programlisting>
1549
1550              <programlisting>configure.cflags-append     "-undefined suppress"
1551configure.cflags-delete     -O2</programlisting>
1552            </listitem>
1553          </itemizedlist>
1554        </listitem>
1555      </varlistentry>
1556
1557      <varlistentry>
1558        <term>configure.ldflags</term>
1559
1560        <term>configure.ldflags-append</term>
1561
1562        <term>configure.ldflags-delete</term>
1563
1564        <listitem>
1565          <para>Set LDFLAGS compiler flags; list modifiers add or delete items
1566          from a previous Portfile configure.ldflags keyword or the default
1567          set by MacPorts base.</para>
1568
1569          <itemizedlist>
1570            <listitem>
1571              <para>Default: <literal>-L${prefix}/lib</literal></para>
1572            </listitem>
1573
1574            <listitem>
1575              <para>Example:</para>
1576
1577              <programlisting>configure.ldflags   "-L${worksrcpath}/zlib -lz"</programlisting>
1578
1579              <programlisting>configure.ldflags-append    "-L/usr/X11R6/lib -L${worksrcpath}/lib"
1580configure.ldflags-delete    -L${prefix}/lib/db44</programlisting>
1581            </listitem>
1582          </itemizedlist>
1583        </listitem>
1584      </varlistentry>
1585
1586      <varlistentry>
1587        <term>configure.cppflags</term>
1588
1589        <term>configure.cppflags-append</term>
1590
1591        <term>configure.cppflags-delete</term>
1592
1593        <listitem>
1594          <para>Set CPPFLAGS to be passed to the C processor; list modifiers
1595          add or delete items from a previous Portfile configure.cppflags
1596          keyword or the default set by MacPorts base.</para>
1597
1598          <itemizedlist>
1599            <listitem>
1600              <para>Default: <literal>-I${prefix}/include</literal></para>
1601            </listitem>
1602
1603            <listitem>
1604              <para>Example:</para>
1605
1606              <programlisting>configure.cppflags  -I${worksrcpath}/include</programlisting>
1607
1608              <programlisting>configure.cppflags-append   "-I/usr/X11R6/lib -I${worksrcpath}/lib -DHAVE_RRD_12X"
1609configure.cppflags-delete   -I${prefix}/lib/db44</programlisting>
1610            </listitem>
1611          </itemizedlist>
1612        </listitem>
1613      </varlistentry>
1614
1615      <varlistentry>
1616        <term>configure.cxxflags</term>
1617
1618        <term>configure.cxxflags-append</term>
1619
1620        <term>configure.cxxflags-delete</term>
1621
1622        <listitem>
1623          <para>Set CXXFLAGS to be passed to the C++ processor; list modifiers
1624          add or delete items from a previous Portfile configure.cxxflags
1625          keyword or the default set by MacPorts base.</para>
1626
1627          <itemizedlist>
1628            <listitem>
1629              <para>Default: <literal>${configure.optflags}</literal></para>
1630            </listitem>
1631
1632            <listitem>
1633              <para>Example:</para>
1634
1635              <programlisting>TODO: add example</programlisting>
1636            </listitem>
1637          </itemizedlist>
1638        </listitem>
1639      </varlistentry>
1640
1641      <varlistentry>
1642        <term>configure.objcflags</term>
1643
1644        <term>configure.objcflags-append</term>
1645
1646        <term>configure.objcflags-delete</term>
1647
1648        <listitem>
1649          <para>TODO: add description</para>
1650
1651          <itemizedlist>
1652            <listitem>
1653              <para>Default: <literal>${configure.optflags}</literal></para>
1654            </listitem>
1655
1656            <listitem>
1657              <para>Example:</para>
1658
1659              <programlisting>TODO: add example</programlisting>
1660            </listitem>
1661          </itemizedlist>
1662        </listitem>
1663      </varlistentry>
1664
1665      <varlistentry>
1666        <term>configure.classpath</term>
1667
1668        <term>configure.classpath-append</term>
1669
1670        <term>configure.classpath-delete</term>
1671
1672        <listitem>
1673          <para>TODO: add description</para>
1674
1675          <itemizedlist>
1676            <listitem>
1677              <para>Default: ???</para>
1678            </listitem>
1679
1680            <listitem>
1681              <para>Example:</para>
1682
1683              <programlisting>TODO: add example</programlisting>
1684            </listitem>
1685          </itemizedlist>
1686        </listitem>
1687      </varlistentry>
1688
1689      <varlistentry>
1690        <term>configure.macosx_deployment_target</term>
1691
1692        <term>configure.macosx_deployment_target-append</term>
1693
1694        <term>configure.macosx_deployment_target-delete</term>
1695
1696        <listitem>
1697          <para>TODO: add description</para>
1698
1699          <itemizedlist>
1700            <listitem>
1701              <para>Default: ???</para>
1702            </listitem>
1703
1704            <listitem>
1705              <para>Example:</para>
1706
1707              <programlisting>TODO: add example</programlisting>
1708            </listitem>
1709          </itemizedlist>
1710        </listitem>
1711      </varlistentry>
1712
1713      <!-- fortran compiler options -->
1714
1715      <varlistentry>
1716        <term>configure.fflags</term>
1717
1718        <term>configure.fflags-append</term>
1719
1720        <term>configure.fflags-delete</term>
1721
1722        <listitem>
1723          <para>Set FFLAGS to be passed to the Fortran compiler; list
1724          modifiers add or delete items from a previous Portfile
1725          configure.fflags keyword or the default set by MacPorts base.</para>
1726
1727          <itemizedlist>
1728            <listitem>
1729              <para>Default: <literal>${configure.optflags}</literal></para>
1730            </listitem>
1731
1732            <listitem>
1733              <para>Example:</para>
1734
1735              <programlisting>configure.fflags    -Os</programlisting>
1736            </listitem>
1737          </itemizedlist>
1738        </listitem>
1739      </varlistentry>
1740
1741      <varlistentry>
1742        <term>configure.fcflags</term>
1743
1744        <term>configure.fcflags-append</term>
1745
1746        <term>configure.fcflags-delete</term>
1747
1748        <listitem>
1749          <para>Set FCFLAGS to be passed to the Fortran compiler; list
1750          modifiers add or delete items from a previous Portfile
1751          configure.fcflags keyword or the default set by MacPorts
1752          base.</para>
1753
1754          <itemizedlist>
1755            <listitem>
1756              <para>Default: <literal>${configure.optflags}</literal></para>
1757            </listitem>
1758
1759            <listitem>
1760              <para>Example:</para>
1761
1762              <programlisting>configure.fcflags   -Os</programlisting>
1763            </listitem>
1764          </itemizedlist>
1765        </listitem>
1766      </varlistentry>
1767
1768      <varlistentry>
1769        <term>configure.f90flags</term>
1770
1771        <term>configure.f90flags-append</term>
1772
1773        <term>configure.f90flags-delete</term>
1774
1775        <listitem>
1776          <para>Set F90FLAGS to be passed to the Fortran 90 compiler; list
1777          modifiers add or delete items from a previous Portfile
1778          configure.f90flags keyword or the default set by MacPorts
1779          base.</para>
1780
1781          <itemizedlist>
1782            <listitem>
1783              <para>Default: <literal>${configure.optflags}</literal></para>
1784            </listitem>
1785
1786            <listitem>
1787              <para>Example:</para>
1788
1789              <programlisting>configure.f90flags  -Os</programlisting>
1790            </listitem>
1791          </itemizedlist>
1792        </listitem>
1793      </varlistentry>
1794
1795      <!-- fortran compiler options end -->
1796
1797      <!-- compiler selection arguments -->
1798
1799      <varlistentry>
1800        <term>configure.cc</term>
1801
1802        <listitem>
1803          <para>Set CC compiler flags for selecting a C compiler.</para>
1804
1805          <itemizedlist>
1806            <listitem>
1807              <para>Default: <literal>???</literal></para>
1808            </listitem>
1809
1810            <listitem>
1811              <para>Example:</para>
1812
1813              <programlisting>configure.cc        ${prefix}/bin/gcc-mp-4.2</programlisting>
1814            </listitem>
1815          </itemizedlist>
1816        </listitem>
1817      </varlistentry>
1818
1819      <varlistentry>
1820        <term>configure.cpp</term>
1821
1822        <listitem>
1823          <para>Set CPP compiler flags for selecting a C preprocessor.</para>
1824
1825          <itemizedlist>
1826            <listitem>
1827              <para>Default: <literal>???</literal></para>
1828            </listitem>
1829
1830            <listitem>
1831              <para>Example:</para>
1832
1833              <programlisting>configure.cpp       /usr/bin/cpp-3.3</programlisting>
1834            </listitem>
1835          </itemizedlist>
1836        </listitem>
1837      </varlistentry>
1838
1839      <varlistentry>
1840        <term>configure.cxx</term>
1841
1842        <listitem>
1843          <para>Set CXX compiler flags for selecting a C++ compiler.</para>
1844
1845          <itemizedlist>
1846            <listitem>
1847              <para>Default: <literal>???</literal></para>
1848            </listitem>
1849
1850            <listitem>
1851              <para>Example:</para>
1852
1853              <programlisting>configure.cxx       /usr/bin/g++-4.0</programlisting>
1854            </listitem>
1855          </itemizedlist>
1856        </listitem>
1857      </varlistentry>
1858
1859      <varlistentry>
1860        <term>configure.objc</term>
1861
1862        <listitem>
1863          <para>Set OBJC compiler flags for selecting an Objective-C
1864          compiler.</para>
1865
1866          <itemizedlist>
1867            <listitem>
1868              <para>Default: <literal>???</literal></para>
1869            </listitem>
1870
1871            <listitem>
1872              <para>Example:</para>
1873
1874              <programlisting>configure.objc      /usr/bin/gcc-4.0</programlisting>
1875            </listitem>
1876          </itemizedlist>
1877        </listitem>
1878      </varlistentry>
1879
1880      <varlistentry>
1881        <term>configure.fc</term>
1882
1883        <listitem>
1884          <para>Set FC compiler flags for selecting a Fortran compiler.</para>
1885
1886          <itemizedlist>
1887            <listitem>
1888              <para>Default: <literal>???</literal></para>
1889            </listitem>
1890
1891            <listitem>
1892              <para>Example:</para>
1893
1894              <programlisting>configure.fc        ${prefix}/bin/gfortran-mp-4.2</programlisting>
1895            </listitem>
1896          </itemizedlist>
1897        </listitem>
1898      </varlistentry>
1899
1900      <varlistentry>
1901        <term>configure.f77</term>
1902
1903        <listitem>
1904          <para>Set F77 compiler flags for selecting a Fortran 77
1905          compiler.</para>
1906
1907          <itemizedlist>
1908            <listitem>
1909              <para>Default: <literal>???</literal></para>
1910            </listitem>
1911
1912            <listitem>
1913              <para>Example:</para>
1914
1915              <programlisting>configure.f77       ${prefix}/bin/gfortran-mp-4.2</programlisting>
1916            </listitem>
1917          </itemizedlist>
1918        </listitem>
1919      </varlistentry>
1920
1921      <varlistentry>
1922        <term>configure.f90</term>
1923
1924        <listitem>
1925          <para>Set F90 compiler flags for selecting a Fortran 90
1926          compiler.</para>
1927
1928          <itemizedlist>
1929            <listitem>
1930              <para>Default: <literal>???</literal></para>
1931            </listitem>
1932
1933            <listitem>
1934              <para>Example:</para>
1935
1936              <programlisting>configure.f90       ${prefix}/bin/gfortran-mp-4.2</programlisting>
1937            </listitem>
1938          </itemizedlist>
1939        </listitem>
1940      </varlistentry>
1941
1942      <varlistentry>
1943        <term>configure.javac</term>
1944
1945        <listitem>
1946          <para>Set JAVAC compiler flags for selecting a Java compiler.</para>
1947
1948          <itemizedlist>
1949            <listitem>
1950              <para>Default: <literal>???</literal></para>
1951            </listitem>
1952
1953            <listitem>
1954              <para>Example:</para>
1955
1956              <programlisting>configure.javac     ${prefix}/bin/jikes</programlisting>
1957            </listitem>
1958          </itemizedlist>
1959        </listitem>
1960      </varlistentry>
1961
1962      <varlistentry>
1963        <term>configure.compiler</term>
1964
1965        <listitem>
1966          <para>Select a compiler suite to fill the compiler environment
1967          variables. All variables/tools a compiler suite can provide are set.
1968          Manually set variables are not overwritten. Dependencies are not
1969          added for you, as they may be just build- or also run-dependencies.
1970          Keep in mind that not all compiler suites might be available on your
1971          platform: <option>gcc-3.3</option> is available on Mac OS X 10.3 and
1972          10.4 PowerPC, <option>gcc-4.0</option> is available on 10.4+,
1973          <option>gcc-4.2</option> and <option>llvm-gcc-4.2</option> are
1974          available on 10.5 and 10.6, and clang is available on 10.6.</para>
1975
1976          <para>Only use it if a port really needs a different
1977          compiler.</para>
1978
1979          <itemizedlist>
1980            <listitem>
1981              <para>Default: <option>gcc-4.0</option> on Mac OS X 10.4 and
1982              10.5</para>
1983            </listitem>
1984           
1985            <listitem>
1986              <para>Default: <option>gcc-4.2</option> with Xcode 3.2 on Mac OS X 10.6</para>
1987            </listitem>
1988
1989            <listitem>
1990              <para>Default: <option>llvm-gcc-4.2</option> with Xcode 4.0 and 4.1 on Mac OS X 10.6 and 10.7</para>
1991            </listitem>
1992
1993            <listitem>
1994              <para>Default: <option>clang</option> with Xcode 4.2 and up on Mac OS X 10.6 and up</para>
1995            </listitem>
1996
1997            <listitem>
1998              <para>Values: <option>gcc-3.3</option> <option>gcc-4.0</option>
1999              <option>gcc-4.2</option> <option>llvm-gcc-4.2</option>
2000              <option>clang</option>
2001              <option>apple-gcc-4.0</option>
2002              <option>apple-gcc-4.2</option>
2003              <option>macports-gcc-4.1</option>
2004              <option>macports-gcc-4.2</option>
2005              <option>macports-gcc-4.3</option>
2006              <option>macports-gcc-4.4</option>
2007              <option>macports-gcc-4.5</option>
2008              <option>macports-gcc-4.6</option>
2009              <option>macports-gcc-4.7</option>
2010              <option>macports-gcc-4.8</option>
2011              <option>macports-clang-2.9</option>
2012              <option>macports-clang-3.0</option>
2013              <option>macports-clang-3.1</option>
2014              <option>macports-clang-3.2</option></para>
2015            </listitem>
2016
2017            <listitem>
2018              <para>Example:</para>
2019
2020              <programlisting>configure.compiler  macports-gcc-4.5</programlisting>
2021            </listitem>
2022          </itemizedlist>
2023        </listitem>
2024      </varlistentry>
2025
2026      <!-- compiler selection arguments end -->
2027
2028      <!-- interpreter selection arguments -->
2029
2030      <varlistentry>
2031        <term>configure.perl</term>
2032
2033        <listitem>
2034          <para>Set PERL flag for selecting a Perl interpreter.</para>
2035
2036          <itemizedlist>
2037            <listitem>
2038              <para>Default: <literal>???</literal></para>
2039            </listitem>
2040
2041            <listitem>
2042              <para>Example:</para>
2043
2044              <programlisting>configure.perl      ${prefix}/bin/perl5.12</programlisting>
2045            </listitem>
2046          </itemizedlist>
2047        </listitem>
2048      </varlistentry>
2049
2050      <varlistentry>
2051        <term>configure.python</term>
2052
2053        <listitem>
2054          <para>Set PYTHON flag for selecting a Python interpreter.</para>
2055
2056          <itemizedlist>
2057            <listitem>
2058              <para>Default: <literal>???</literal></para>
2059            </listitem>
2060
2061            <listitem>
2062              <para>Example:</para>
2063
2064              <programlisting>configure.python    ${prefix}/bin/python2.7</programlisting>
2065            </listitem>
2066          </itemizedlist>
2067        </listitem>
2068      </varlistentry>
2069
2070      <varlistentry>
2071        <term>configure.ruby</term>
2072
2073        <listitem>
2074          <para>Set RUBY flag for selecting a Ruby interpreter.</para>
2075
2076          <itemizedlist>
2077            <listitem>
2078              <para>Default: <literal>???</literal></para>
2079            </listitem>
2080
2081            <listitem>
2082              <para>Example:</para>
2083
2084              <programlisting>configure.ruby      ${prefix}/bin/ruby</programlisting>
2085            </listitem>
2086          </itemizedlist>
2087        </listitem>
2088      </varlistentry>
2089
2090      <!-- interpreter selection arguments end -->
2091
2092      <!-- other tools selection arguments -->
2093
2094      <varlistentry>
2095        <term>configure.install</term>
2096
2097        <listitem>
2098          <para>Set <literal>INSTALL</literal> flag for selecting an install
2099          tool; used for copying files and creating directories.</para>
2100
2101          <itemizedlist>
2102            <listitem>
2103              <para>Default: <filename>/usr/bin/install</filename></para>
2104            </listitem>
2105
2106            <listitem>
2107              <para>Example:</para>
2108
2109              <programlisting>configure.install   ${prefix}/bin/ginstall</programlisting>
2110            </listitem>
2111          </itemizedlist>
2112        </listitem>
2113      </varlistentry>
2114
2115      <varlistentry>
2116        <term>configure.awk</term>
2117
2118        <listitem>
2119          <para>Set AWK flag for selecting an awk executable.</para>
2120
2121          <itemizedlist>
2122            <listitem>
2123              <para>Default: <literal>???</literal></para>
2124            </listitem>
2125
2126            <listitem>
2127              <para>Example:</para>
2128
2129              <programlisting>configure.awk       ${prefix}/bin/gawk</programlisting>
2130            </listitem>
2131          </itemizedlist>
2132        </listitem>
2133      </varlistentry>
2134
2135      <varlistentry>
2136        <term>configure.bison</term>
2137
2138        <listitem>
2139          <para>Set BISON flag for selecting a bison executable, a parser
2140          generator.</para>
2141
2142          <itemizedlist>
2143            <listitem>
2144              <para>Default: <literal>???</literal></para>
2145            </listitem>
2146
2147            <listitem>
2148              <para>Example:</para>
2149
2150              <programlisting>configure.bison     /usr/bin/bison</programlisting>
2151            </listitem>
2152          </itemizedlist>
2153        </listitem>
2154      </varlistentry>
2155
2156      <varlistentry>
2157        <term>configure.pkg_config</term>
2158
2159        <listitem>
2160          <para>Set PKG_CONFIG flag for helping find pkg_config, a tool for
2161          retrieving information about installed libraries.</para>
2162
2163          <itemizedlist>
2164            <listitem>
2165              <para>Default: <literal>???</literal></para>
2166            </listitem>
2167
2168            <listitem>
2169              <para>Example:</para>
2170
2171              <programlisting>configure.pkg_config    ${prefix}/bin/pkg-config</programlisting>
2172            </listitem>
2173          </itemizedlist>
2174        </listitem>
2175      </varlistentry>
2176
2177      <varlistentry>
2178        <term>configure.pkg_config_path</term>
2179
2180        <listitem>
2181          <para>Set PKG_CONFIG_PATH flag for telling pkg_config where to
2182          search for information about installed libraries.</para>
2183
2184          <itemizedlist>
2185            <listitem>
2186              <para>Default: <literal>${prefix}/lib/pkgconfig:${prefix}/share/pkgconfig</literal></para>
2187            </listitem>
2188
2189            <listitem>
2190              <para>Example:</para>
2191
2192              <programlisting>configure.pkg_config_path   ${python.prefix}/lib/pkgconfig</programlisting>
2193            </listitem>
2194          </itemizedlist>
2195        </listitem>
2196      </varlistentry>
2197
2198      <!-- other tools selection arguments end -->
2199
2200      <varlistentry>
2201        <term>configure.args</term>
2202
2203        <term>configure.pre_args</term>
2204
2205        <term>configure.post_args</term>
2206
2207        <listitem>
2208          <para>Main arguments to <literal>configure.cmd</literal>; optional
2209          argument modifiers pass arguments before and after the main
2210          arguments.</para>
2211
2212          <itemizedlist>
2213            <listitem>
2214              <para>Default: none</para>
2215            </listitem>
2216
2217            <listitem>
2218              <para>Example:</para>
2219
2220              <programlisting>configure.args      --bindir=${prefix}/bin
2221
2222</programlisting>
2223            </listitem>
2224          </itemizedlist>
2225
2226          <para>The following argument modifiers are available:</para>
2227
2228          <itemizedlist>
2229            <listitem>
2230              <para><literal>configure.pre_args</literal>, defaults to:
2231              <literal>--prefix=${prefix}</literal></para>
2232            </listitem>
2233
2234            <listitem>
2235              <para><literal>configure.post_args</literal>, defaults to:
2236              none</para>
2237            </listitem>
2238
2239            <listitem>
2240              <para>Examples:</para>
2241
2242              <programlisting>configure.pre_args  --prefix=${prefix}/share/bro
2243configure.post_args OPT="-D__DARWIN_UNIX03"</programlisting>
2244            </listitem>
2245          </itemizedlist>
2246        </listitem>
2247      </varlistentry>
2248    </variablelist>
2249
2250    <section id="reference.phases.configure.universal">
2251      <title>Configure Universal</title>
2252
2253      <para>Universal keywords are used to make a port compile on OS X for
2254      multiple architectures.</para>
2255
2256      <note>
2257        <para>There is a default universal variant made available to all ports
2258        by MacPorts base, so redefining universal keywords should only be done
2259        to make a given port compile if the default options fail to do
2260        so.</para>
2261      </note>
2262
2263      <variablelist>
2264        <varlistentry>
2265          <term>configure.universal_args</term>
2266
2267          <listitem>
2268            <para>Arguments used in the configure script to build the port
2269            universal.</para>
2270
2271            <itemizedlist>
2272              <listitem>
2273                <para>Default:
2274                <literal>--disable-dependency-tracking</literal></para>
2275              </listitem>
2276
2277              <listitem>
2278                <para>Example:</para>
2279
2280                <programlisting>TODO: add example</programlisting>
2281              </listitem>
2282            </itemizedlist>
2283          </listitem>
2284        </varlistentry>
2285
2286        <varlistentry>
2287          <term>configure.universal_cflags</term>
2288
2289          <listitem>
2290            <para>Additional flags to put in the CFLAGS environment variable
2291            when invoking the configure script. Default value is based on
2292            <literal>${configure.universal_archs}</literal>.</para>
2293
2294            <itemizedlist>
2295              <listitem>
2296                <para>Default: </para>
2297                <para>(PowerPC Tiger) <literal>-isysroot ${developer_dir}/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc</literal></para>
2298                <para>(Leopard / Intel Tiger) <literal>-arch i386 -arch ppc</literal></para>
2299                <para>(Snow Leopard) <literal>-arch x86_64 -arch i386</literal></para>
2300              </listitem>
2301
2302              <listitem>
2303                <para>Example:</para>
2304
2305                <programlisting>TODO: add example</programlisting>
2306              </listitem>
2307            </itemizedlist>
2308          </listitem>
2309        </varlistentry>
2310
2311        <varlistentry>
2312          <term>configure.universal_cppflags</term>
2313
2314          <listitem>
2315            <para>Additional flags to put in the CPPFLAGS environment variable
2316            when invoking the configure script.</para>
2317
2318            <itemizedlist>
2319              <listitem>
2320                <para>Default: </para>
2321                <para>(PowerPC Tiger) <literal>-isysroot ${developer_dir}/SDKs/MacOSX10.4u.sdk</literal></para>
2322                <para>(Others) none</para>
2323              </listitem>
2324
2325              <listitem>
2326                <para>Example:</para>
2327
2328                <programlisting>TODO: add example</programlisting>
2329              </listitem>
2330            </itemizedlist>
2331          </listitem>
2332        </varlistentry>
2333
2334        <varlistentry>
2335          <term>configure.universal_cxxflags</term>
2336
2337          <listitem>
2338            <para>Additional flags to put in the CXXFLAGS environment variable
2339            when invoking the configure script. Default value is based on
2340            <literal>${configure.universal_archs}</literal>.</para>
2341
2342            <itemizedlist>
2343              <listitem>
2344                <para>Default: </para>
2345                <para>(PowerPC Tiger) <literal>-isysroot ${developer_dir}/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc</literal></para>
2346                <para>(Leopard / Intel Tiger) <literal>-arch i386 -arch ppc</literal></para>
2347                <para>(Snow Leopard) <literal>-arch x86_64 -arch i386</literal></para>
2348              </listitem>
2349
2350              <listitem>
2351                <para>Example:</para>
2352
2353                <programlisting>TODO: add example</programlisting>
2354              </listitem>
2355            </itemizedlist>
2356          </listitem>
2357        </varlistentry>
2358
2359        <varlistentry>
2360          <term>configure.universal_ldflags</term>
2361
2362          <listitem>
2363            <para>Additional flags to put in the LDFLAGS environment variable
2364            when invoking the configure script.</para>
2365
2366            <itemizedlist>
2367              <listitem>
2368                <para>Default: </para>
2369                <para>(PowerPC Tiger) <literal>-Wl,-syslibroot,${developer_dir}/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc</literal></para>
2370                <para>(Leopard / Intel Tiger) <literal>-arch i386 -arch ppc</literal></para>
2371                <para>(Snow Leopard) <literal>-arch x86_64 -arch i386</literal></para>
2372              </listitem>
2373
2374              <listitem>
2375                <para>Example:</para>
2376
2377                <programlisting>TODO: add example</programlisting>
2378              </listitem>
2379            </itemizedlist>
2380          </listitem>
2381        </varlistentry>
2382      </variablelist>
2383    </section>
2384
2385    <section id="reference.phases.configure.automake-autoconf">
2386      <title>Automake, Autoconf, and Autoreconf</title>
2387
2388      <para>The list of configure keywords available for ports that need
2389      automake and/or autoconf.</para>
2390
2391      <variablelist>
2392        <varlistentry>
2393          <term>use_autoreconf</term>
2394          <listitem>
2395            <para>Whether or not to use autoreconf</para>
2396            <itemizedlist>
2397              <listitem>
2398                <para>Default: <option>no</option></para>
2399              </listitem>
2400
2401              <listitem>
2402                <para>Example:</para>
2403
2404                <programlisting>use_autoreconf      yes</programlisting>
2405              </listitem>
2406            </itemizedlist>
2407          </listitem>
2408        </varlistentry>
2409
2410        <varlistentry>
2411          <term>use_automake</term>
2412
2413          <listitem>
2414            <para>Whether or not to use automake.</para>
2415
2416            <itemizedlist>
2417              <listitem>
2418                <para>Default: <option>no</option></para>
2419              </listitem>
2420
2421              <listitem>
2422                <para>Example:</para>
2423
2424                <programlisting>use_automake        yes</programlisting>
2425              </listitem>
2426            </itemizedlist>
2427          </listitem>
2428        </varlistentry>
2429
2430        <varlistentry>
2431          <term>automake.env</term>
2432
2433          <listitem>
2434            <para>Environment variables to pass to automake.</para>
2435
2436            <itemizedlist>
2437              <listitem>
2438                <para>Default: ???</para>
2439              </listitem>
2440
2441              <listitem>
2442                <para>Example:</para>
2443
2444                <programlisting>automake.env        CFLAGS=-I${prefix}/include</programlisting>
2445              </listitem>
2446            </itemizedlist>
2447          </listitem>
2448        </varlistentry>
2449
2450        <varlistentry>
2451          <term>automake.args</term>
2452
2453          <listitem>
2454            <para>Arguments to pass to automake.</para>
2455
2456            <itemizedlist>
2457              <listitem>
2458                <para>Default: ???</para>
2459              </listitem>
2460
2461              <listitem>
2462                <para>Example:</para>
2463
2464                <programlisting>automake.args       --foreign</programlisting>
2465              </listitem>
2466            </itemizedlist>
2467          </listitem>
2468        </varlistentry>
2469
2470        <varlistentry>
2471          <term>automake.dir</term>
2472
2473          <listitem>
2474            <para>Directory in which to run
2475            <varname>${automake.cmd}</varname>.</para>
2476
2477            <itemizedlist>
2478              <listitem>
2479                <para>Default: <varname>${worksrcpath}</varname></para>
2480              </listitem>
2481
2482              <listitem>
2483                <para>Example:</para>
2484
2485                <programlisting>automake.dir        ./src</programlisting>
2486              </listitem>
2487            </itemizedlist>
2488          </listitem>
2489        </varlistentry>
2490
2491        <varlistentry>
2492          <term>use_autoconf</term>
2493
2494          <listitem>
2495            <para>Whether or not to use autoconf.</para>
2496
2497            <itemizedlist>
2498              <listitem>
2499                <para>Default: <option>no</option></para>
2500              </listitem>
2501
2502              <listitem>
2503                <para>Example:</para>
2504
2505                <programlisting>use_autoconf        yes</programlisting>
2506              </listitem>
2507            </itemizedlist>
2508          </listitem>
2509        </varlistentry>
2510
2511        <varlistentry>
2512          <term>autoconf.env</term>
2513
2514          <listitem>
2515            <para>Environmental variables to pass to autoconf.</para>
2516
2517            <itemizedlist>
2518              <listitem>
2519                <para>Default: ???</para>
2520              </listitem>
2521
2522              <listitem>
2523                <para>Example:</para>
2524
2525                <programlisting>autoconf.env        CFLAGS=-I${prefix}/include/gtk12</programlisting>
2526              </listitem>
2527            </itemizedlist>
2528          </listitem>
2529        </varlistentry>
2530
2531        <varlistentry>
2532          <term>autoconf.args</term>
2533
2534          <listitem>
2535            <para>Arguments to pass to autoconf.</para>
2536
2537            <itemizedlist>
2538              <listitem>
2539                <para>Default: ???</para>
2540              </listitem>
2541
2542              <listitem>
2543                <para>Example:</para>
2544
2545                <programlisting>autoconf.args       "-l src/aclocaldir"</programlisting>
2546              </listitem>
2547            </itemizedlist>
2548          </listitem>
2549        </varlistentry>
2550
2551        <varlistentry>
2552          <term>autoconf.dir</term>
2553
2554          <listitem>
2555            <para>Directory in which to run
2556            <varname>${autoconf.cmd}</varname>.</para>
2557
2558            <itemizedlist>
2559              <listitem>
2560                <para>Default: <varname>${worksrcpath}</varname></para>
2561              </listitem>
2562
2563              <listitem>
2564                <para>Example:</para>
2565
2566                <programlisting>autoconf.dir        src</programlisting>
2567              </listitem>
2568            </itemizedlist>
2569          </listitem>
2570        </varlistentry>
2571      </variablelist>
2572    </section>
2573  </section>
2574
2575  <section id="reference.phases.build">
2576    <title>Build Phase Keywords</title>
2577
2578    <para>The list of keywords related to the build phase.</para>
2579
2580    <variablelist>
2581      <varlistentry>
2582        <term>build.cmd</term>
2583
2584        <listitem>
2585          <para>Make command to run in <varname>${worksrcdir}</varname>. Only
2586          use it if you can't use <literal>build.type</literal>.</para>
2587
2588          <itemizedlist>
2589            <listitem>
2590              <para>Default: <command>make</command></para>
2591            </listitem>
2592
2593            <listitem>
2594              <para>Example:</para>
2595
2596              <programlisting>build.cmd           scons</programlisting>
2597            </listitem>
2598          </itemizedlist>
2599        </listitem>
2600      </varlistentry>
2601
2602      <varlistentry>
2603        <term>build.type</term>
2604
2605        <listitem>
2606          <para>Defines which "make" is required. Sets
2607          <varname>${build.cmd}</varname> to either "gnumake" or "bsdmake"
2608          accordingly.</para>
2609
2610          <itemizedlist>
2611            <listitem>
2612              <para>Default: <option>gnu</option></para>
2613            </listitem>
2614
2615            <listitem>
2616              <para>Values: <option>gnu</option> <option>bsd</option> <option>pbx</option></para>
2617            </listitem>
2618
2619            <listitem>
2620              <para>Example:</para>
2621
2622              <programlisting>build.type          bsd</programlisting>
2623            </listitem>
2624          </itemizedlist>
2625        </listitem>
2626      </varlistentry>
2627
2628      <varlistentry>
2629        <term>build.args</term>
2630
2631        <term>build.pre_args</term>
2632
2633        <term>build.post_args</term>
2634
2635        <listitem>
2636          <para>Main arguments to <varname>${build.cmd}</varname>; optional
2637          argument modifiers pass arguments before and after the main
2638          arguments.</para>
2639
2640          <itemizedlist>
2641            <listitem>
2642              <para>Default: none</para>
2643            </listitem>
2644
2645            <listitem>
2646              <para>Example:</para>
2647
2648              <programlisting>build.args          -DNOWARN
2649
2650</programlisting>
2651            </listitem>
2652          </itemizedlist>
2653
2654          <para>The following argument modifiers are available:</para>
2655
2656          <itemizedlist>
2657            <listitem>
2658              <para><literal>build.pre_args</literal>, defaults to:
2659              <varname>${build.target}</varname></para>
2660            </listitem>
2661
2662            <listitem>
2663              <para><literal>build.post_args</literal>, defaults to:
2664              none</para>
2665            </listitem>
2666
2667            <listitem>
2668              <para>Examples:</para>
2669
2670              <programlisting>build.pre_args      -project AudioSlicer.xcode
2671build.post_args     CFLAGS_SYS="-DUSE_FREETYPE -DPREFER_FREETYPE"</programlisting>
2672            </listitem>
2673          </itemizedlist>
2674        </listitem>
2675      </varlistentry>
2676
2677      <varlistentry>
2678        <term>build.target</term>
2679
2680        <term>build.target-append</term>
2681
2682        <term>build.target-delete</term>
2683
2684        <listitem>
2685          <para>Build target to pass to <varname>${build.cmd}</varname>; list
2686          modifiers add or delete items from a previous Portfile build.target
2687          keyword or the default set by MacPorts base.</para>
2688
2689          <itemizedlist>
2690            <listitem>
2691              <para>Default: <literal>all</literal></para>
2692            </listitem>
2693
2694            <listitem>
2695              <para>Example:</para>
2696
2697              <programlisting>build.target        all-src</programlisting>
2698
2699              <programlisting>build.target-append     doc extra
2700build.target-delete     compat</programlisting>
2701            </listitem>
2702          </itemizedlist>
2703        </listitem>
2704      </varlistentry>
2705
2706      <varlistentry>
2707        <term>build.env</term>
2708
2709        <term>build.env-append</term>
2710
2711        <term>build.env-delete</term>
2712
2713        <listitem>
2714          <para>Set environment variables for build; list modifiers add
2715          and delete items from a previous Portfile build.env keyword, or
2716          a default set by MacPorts base.</para>
2717
2718          <itemizedlist>
2719            <listitem>
2720              <para>Default: none</para>
2721            </listitem>
2722          </itemizedlist>
2723        </listitem>
2724      </varlistentry>
2725
2726      <varlistentry>
2727        <term>use_parallel_build</term>
2728
2729        <listitem>
2730          <para>This keyword is for specifying whether or not it is safe for a
2731          port to use multiple CPUs or multiple cores in parallel during its
2732          build phase. If <code>use_parallel_build</code> is not set to
2733          <quote>no</quote> in a given port, the option <option>-j${build.jobs}</option>
2734          is passed to <varname>${build.cmd}</varname> (if
2735          <varname>${build.cmd}</varname> is <command>make</command> or
2736          <command>scons</command>).</para>
2737
2738          <itemizedlist>
2739            <listitem>
2740              <para>Default: <option>yes</option></para>
2741            </listitem>
2742
2743            <listitem>
2744              <para>Example:</para>
2745
2746              <programlisting>use_parallel_build  no</programlisting>
2747            </listitem>
2748          </itemizedlist>
2749        </listitem>
2750      </varlistentry>
2751     
2752      <varlistentry>
2753        <term>build.jobs</term>
2754
2755        <listitem>
2756          <para>The number of simultaneous jobs to run when parallel build is
2757          enabled. The default value is based on the variable
2758          <varname>buildmakejobs</varname> in
2759          <filename>macports.conf</filename>.</para>
2760
2761          <itemizedlist>
2762            <listitem>
2763              <para>Default: If <varname>buildmakejobs</varname> is 0, the
2764              number of CPU cores in the machine, or the number of GB of
2765              physical memory plus one, whichever is less. Otherwise,
2766              the actual value of <literal>${buildmakejobs}</literal>.</para>
2767            </listitem>
2768          </itemizedlist>
2769        </listitem>
2770      </varlistentry>
2771     
2772    </variablelist>
2773  </section>
2774
2775  <section id="reference.phases.test">
2776    <title>Test Phase Keywords</title>
2777
2778    <para>The list of keywords related to the test phase.</para>
2779
2780    <variablelist>
2781      <varlistentry>
2782        <term>test.run</term>
2783
2784        <listitem>
2785          <para>Enable running test suites bundled with a port.</para>
2786
2787          <itemizedlist>
2788            <listitem>
2789              <para>Default: <option>no</option></para>
2790            </listitem>
2791
2792            <listitem>
2793              <para>Example:</para>
2794
2795              <programlisting>test.run            yes</programlisting>
2796            </listitem>
2797          </itemizedlist>
2798        </listitem>
2799      </varlistentry>
2800
2801      <varlistentry>
2802        <term>test.cmd</term>
2803
2804        <listitem>
2805          <para>Test command to run relative to
2806          <varname>${worksrcdir}</varname>.</para>
2807
2808          <itemizedlist>
2809            <listitem>
2810              <para>Default: <varname>${build.cmd}</varname></para>
2811            </listitem>
2812
2813            <listitem>
2814              <para>Example:</para>
2815
2816              <programlisting>test.cmd            checks.sh</programlisting>
2817            </listitem>
2818          </itemizedlist>
2819        </listitem>
2820      </varlistentry>
2821
2822      <varlistentry>
2823        <term>test.target</term>
2824
2825        <listitem>
2826          <para>Test target to pass to <varname>${test.cmd}</varname>.</para>
2827
2828          <itemizedlist>
2829            <listitem>
2830              <para>Default: <literal>test</literal></para>
2831            </listitem>
2832
2833            <listitem>
2834              <para>Example:</para>
2835
2836              <programlisting>test.target         checks</programlisting>
2837            </listitem>
2838          </itemizedlist>
2839        </listitem>
2840      </varlistentry>
2841
2842      <varlistentry>
2843        <term>test.env</term>
2844
2845        <term>test.env-append</term>
2846
2847        <term>test.env-delete</term>
2848
2849        <listitem>
2850          <para>Set environment variables for test; list modifiers add
2851          and delete items from a previous Portfile test.env keyword, or
2852          a default set by MacPorts base.</para>
2853
2854          <para>Often <literal>DYLD_LIBRARY_PATH</literal> is set here to
2855          support testing dynamically linked libraries.</para>
2856
2857          <itemizedlist>
2858            <listitem>
2859              <para>Default: none</para>
2860            </listitem>
2861
2862            <listitem>
2863              <para>Example:</para>
2864
2865              <programlisting>test.env       <literal>DYLD_LIBRARY_PATH=${worksrcpath}/src/.libs</literal></programlisting>
2866            </listitem>
2867          </itemizedlist>
2868        </listitem>
2869      </varlistentry>
2870    </variablelist>
2871  </section>
2872
2873  <section id="reference.phases.destroot">
2874    <title>Destroot Phase Keywords</title>
2875
2876    <para>The list of keywords related to the destroot phase.</para>
2877
2878    <variablelist>
2879      <varlistentry>
2880        <term>destroot.cmd</term>
2881
2882        <listitem>
2883          <para>Install command to run relative to
2884          <varname>${worksrcdir}</varname>.</para>
2885
2886          <itemizedlist>
2887            <listitem>
2888              <para>Default: <varname>${build.cmd}</varname></para>
2889            </listitem>
2890
2891            <listitem>
2892              <para>Example:</para>
2893
2894              <programlisting>destroot.cmd        scons</programlisting>
2895            </listitem>
2896          </itemizedlist>
2897        </listitem>
2898      </varlistentry>
2899
2900      <varlistentry>
2901        <term>destroot.args</term>
2902
2903        <term>destroot.pre_args</term>
2904
2905        <term>destroot.post_args</term>
2906
2907        <listitem>
2908          <para>Main arguments to <varname>${destroot.cmd}</varname>; optional
2909          argument modifiers pass arguments before and after the main
2910          arguments.</para>
2911
2912          <itemizedlist>
2913            <listitem>
2914              <para>Default: none</para>
2915            </listitem>
2916
2917            <listitem>
2918              <para>Example:</para>
2919
2920              <programlisting>destroot.args       BINDIR=${prefix}/bin
2921
2922</programlisting>
2923            </listitem>
2924          </itemizedlist>
2925
2926          <para>The following argument modifiers are available:</para>
2927
2928          <itemizedlist>
2929            <listitem>
2930              <para><literal>destroot.pre_args</literal>, defaults to:
2931              <varname>${destroot.target}</varname></para>
2932            </listitem>
2933
2934            <listitem>
2935              <para><literal>destroot.post_args</literal>, defaults to:
2936                <varname>${destroot.destdir}</varname></para>
2937            </listitem>
2938
2939            <listitem>
2940              <para>Examples:</para>
2941
2942              <programlisting>destroot.pre_args   -project AudioSlicer.xcode
2943destroot.post_args  INSTDIR=${destroot}${prefix}</programlisting>
2944            </listitem>
2945          </itemizedlist>
2946        </listitem>
2947      </varlistentry>
2948
2949      <varlistentry>
2950        <term>destroot.target</term>
2951
2952        <term>destroot.target-append</term>
2953
2954        <term>destroot.target-delete</term>
2955
2956        <listitem>
2957          <para>Install target to pass to <varname>${destroot.cmd}</varname>;
2958          list modifiers add or delete items from a previous Portfile
2959          destroot.target keyword or the default set by MacPorts base.</para>
2960
2961          <itemizedlist>
2962            <listitem>
2963              <para>Default: <literal>install</literal></para>
2964            </listitem>
2965
2966            <listitem>
2967              <para>Example:</para>
2968
2969              <programlisting>destroot.target     install install-config install-commandmode</programlisting>
2970
2971              <programlisting>destroot.target-append  install-plugins
2972destroot.target-delete  install-commandmode</programlisting>
2973            </listitem>
2974          </itemizedlist>
2975        </listitem>
2976      </varlistentry>
2977
2978      <varlistentry>
2979        <term>destroot.destdir</term>
2980
2981        <listitem>
2982          <para>Arguments passed to <varname>${destroot.cmd}</varname> via
2983            <varname>${destroot.post_args}</varname> to install correctly
2984            into the destroot.</para>
2985
2986          <itemizedlist>
2987            <listitem>
2988              <para>Default: <literal>DESTDIR=${destroot}</literal></para>
2989            </listitem>
2990
2991            <listitem>
2992              <para>Example:</para>
2993
2994              <programlisting>destroot.destdir    prefix=${destroot}${prefix}</programlisting>
2995            </listitem>
2996          </itemizedlist>
2997
2998          <note>
2999            <para>If an application's Makefile properly supports the DESTDIR
3000            variable, MacPorts will automatically destroot the port properly.
3001            A port must destroot properly or the port will not install
3002            correctly, upgrade, or uninstall. If not, you may need to set this
3003            variable, or even patch the application's Makefile.</para>
3004          </note>
3005        </listitem>
3006      </varlistentry>
3007
3008      <varlistentry>
3009        <term>destroot.umask</term>
3010
3011        <listitem>
3012          <para>Umask to use during destroot.</para>
3013
3014          <itemizedlist>
3015            <listitem>
3016              <para>Default: <literal>022</literal></para>
3017            </listitem>
3018
3019            <listitem>
3020              <para>Example:</para>
3021
3022              <programlisting>destroot.umask      002</programlisting>
3023            </listitem>
3024          </itemizedlist>
3025        </listitem>
3026      </varlistentry>
3027
3028      <varlistentry>
3029        <term>destroot.keepdirs</term>
3030
3031        <listitem>
3032          <para>A list of directories that should not be removed if empty upon
3033          destroot completion.</para>
3034
3035          <itemizedlist>
3036            <listitem>
3037              <para>Default: ???</para>
3038            </listitem>
3039
3040            <listitem>
3041              <para>Example:</para>
3042
3043              <programlisting>destroot.keepdirs   ${destroot}${prefix}/var/run \
3044                    ${destroot}${prefix}/var/log \
3045                    ${destroot}${prefix}/var/cache/mrtg</programlisting>
3046            </listitem>
3047          </itemizedlist>
3048        </listitem>
3049      </varlistentry>
3050
3051      <varlistentry>
3052        <term>destroot.violate_mtree</term>
3053
3054        <listitem>
3055          <para>MacPorts tests for compliance to the common directory
3056          structure in <varname>${prefix}</varname>. If a port is not
3057          compliant with the standard, set it to <option>yes</option>.</para>
3058
3059          <para>You can find the macports standard in <link
3060          linkend="internals.hierarchy">MacPorts File Hierarchy</link> or in
3061          the porthier(7) man page.</para>
3062
3063          <para>If <code>destroot.violate_mtree</code> is set to
3064          <option>yes</option>, the following warning is issued during the
3065          installation.</para>
3066
3067          <screen>Warning: <replaceable>portname</replaceable> requests to install files outside the common directory structure!</screen>
3068
3069          <para>This means that the port installed files outside of their
3070          normal locations in <varname>${prefix}</varname>. These could be
3071          files totally outside of <varname>${prefix}</varname>, which could
3072          cause problems on your computer, or files inside of
3073          <varname>${prefix}</varname> that are not in a standard location.
3074          Use <literal>port contents
3075          <replaceable>portname</replaceable></literal> to see the location
3076          for all files that were installed by a given port.</para>
3077
3078          <itemizedlist>
3079            <listitem>
3080              <para>Default: <option>no</option></para>
3081            </listitem>
3082
3083            <listitem>
3084              <para>Example:</para>
3085
3086              <programlisting>destroot.violate_mtree      yes</programlisting>
3087            </listitem>
3088          </itemizedlist>
3089        </listitem>
3090      </varlistentry>
3091    </variablelist>
3092  </section>
3093</section>
Note: See TracBrowser for help on using the repository browser.