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

Last change on this file since 73791 was 73791, checked in by and.damore@…, 9 years ago

fixed default argument for extract.post_args in Portfile Reference of Guide, added a trailing dash

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