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

Last change on this file since 65968 was 65968, checked in by jmr@…, 10 years ago

guide: update configure.compiler section

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