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

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

update master_sites guide entry

File size: 89.7 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 and
1902          10.5, <option>gcc-4.2</option> is available as preview for
1903          10.5.</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-3.3</option> on Mac OS X 10.3</para>
1911            </listitem>
1912
1913            <listitem>
1914              <para>Default: <option>gcc-4.0</option> on Mac OS X 10.4 and
1915              10.5</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>apple-gcc-3.3</option> <option>apple-gcc-4.0</option>
1922              <option>macports-gcc-3.3</option>
1923              <option>macports-gcc-3.4</option>
1924              <option>macports-gcc-4.0</option>
1925              <option>macports-gcc-4.1</option>
1926              <option>macports-gcc-4.2</option>
1927              <option>macports-gcc-4.3</option>
1928              <option>macports-gcc-4.4</option></para>
1929            </listitem>
1930
1931            <listitem>
1932              <para>Example:</para>
1933
1934              <programlisting>configure.compiler  macports-gcc-4.2</programlisting>
1935            </listitem>
1936          </itemizedlist>
1937        </listitem>
1938      </varlistentry>
1939
1940      <!-- compiler selection arguments end -->
1941
1942      <!-- interpreter selection arguments -->
1943
1944      <varlistentry>
1945        <term>configure.perl</term>
1946
1947        <listitem>
1948          <para>Set PERL flag for selecting a Perl interpreter.</para>
1949
1950          <itemizedlist>
1951            <listitem>
1952              <para>Default: <literal>???</literal></para>
1953            </listitem>
1954
1955            <listitem>
1956              <para>Example:</para>
1957
1958              <programlisting>configure.perl      ${prefix}/bin/perl5.8</programlisting>
1959            </listitem>
1960          </itemizedlist>
1961        </listitem>
1962      </varlistentry>
1963
1964      <varlistentry>
1965        <term>configure.python</term>
1966
1967        <listitem>
1968          <para>Set PYTHON flag for selecting a Python interpreter.</para>
1969
1970          <itemizedlist>
1971            <listitem>
1972              <para>Default: <literal>???</literal></para>
1973            </listitem>
1974
1975            <listitem>
1976              <para>Example:</para>
1977
1978              <programlisting>configure.python    ${prefix}/bin/python3.0</programlisting>
1979            </listitem>
1980          </itemizedlist>
1981        </listitem>
1982      </varlistentry>
1983
1984      <varlistentry>
1985        <term>configure.ruby</term>
1986
1987        <listitem>
1988          <para>Set RUBY flag for selecting a Ruby interpreter.</para>
1989
1990          <itemizedlist>
1991            <listitem>
1992              <para>Default: <literal>???</literal></para>
1993            </listitem>
1994
1995            <listitem>
1996              <para>Example:</para>
1997
1998              <programlisting>configure.ruby      ${prefix}/bin/ruby</programlisting>
1999            </listitem>
2000          </itemizedlist>
2001        </listitem>
2002      </varlistentry>
2003
2004      <!-- interpreter selection arguments end -->
2005
2006      <!-- other tools selection arguments -->
2007
2008      <varlistentry>
2009        <term>configure.install</term>
2010
2011        <listitem>
2012          <para>Set <literal>INSTALL</literal> flag for selecting an install
2013          tool; used for copying files and creating directories.</para>
2014
2015          <itemizedlist>
2016            <listitem>
2017              <para>Default: <filename>/usr/bin/install</filename></para>
2018            </listitem>
2019
2020            <listitem>
2021              <para>Example:</para>
2022
2023              <programlisting>configure.install   ${prefix}/bin/ginstall</programlisting>
2024            </listitem>
2025          </itemizedlist>
2026        </listitem>
2027      </varlistentry>
2028
2029      <varlistentry>
2030        <term>configure.awk</term>
2031
2032        <listitem>
2033          <para>Set AWK flag for selecting an awk executable.</para>
2034
2035          <itemizedlist>
2036            <listitem>
2037              <para>Default: <literal>???</literal></para>
2038            </listitem>
2039
2040            <listitem>
2041              <para>Example:</para>
2042
2043              <programlisting>configure.awk       ${prefix}/bin/gawk</programlisting>
2044            </listitem>
2045          </itemizedlist>
2046        </listitem>
2047      </varlistentry>
2048
2049      <varlistentry>
2050        <term>configure.bison</term>
2051
2052        <listitem>
2053          <para>Set BISON flag for selecting a bison executable, a parser
2054          generator.</para>
2055
2056          <itemizedlist>
2057            <listitem>
2058              <para>Default: <literal>???</literal></para>
2059            </listitem>
2060
2061            <listitem>
2062              <para>Example:</para>
2063
2064              <programlisting>configure.bison     /usr/bin/bison</programlisting>
2065            </listitem>
2066          </itemizedlist>
2067        </listitem>
2068      </varlistentry>
2069
2070      <varlistentry>
2071        <term>configure.pkg_config</term>
2072
2073        <listitem>
2074          <para>Set PKG_CONFIG flag for helping find pkg_config, a tool for
2075          retrieving information about installed libraries.</para>
2076
2077          <itemizedlist>
2078            <listitem>
2079              <para>Default: <literal>???</literal></para>
2080            </listitem>
2081
2082            <listitem>
2083              <para>Example:</para>
2084
2085              <programlisting>configure.pkg_config    ${prefix}/bin/pkg-config</programlisting>
2086            </listitem>
2087          </itemizedlist>
2088        </listitem>
2089      </varlistentry>
2090
2091      <varlistentry>
2092        <term>configure.pkg_config_path</term>
2093
2094        <listitem>
2095          <para>Set PKG_CONFIG_PATH flag for telling pkg_config where to
2096          search for information about installed libraries.</para>
2097
2098          <itemizedlist>
2099            <listitem>
2100              <para>Default: <literal>${prefix}/lib/pkgconfig:${prefix}/share/pkgconfig</literal></para>
2101            </listitem>
2102
2103            <listitem>
2104              <para>Example:</para>
2105
2106              <programlisting>configure.pkg_config_path   ${python.prefix}/lib/pkgconfig</programlisting>
2107            </listitem>
2108          </itemizedlist>
2109        </listitem>
2110      </varlistentry>
2111
2112      <!-- other tools selection arguments end -->
2113
2114      <varlistentry>
2115        <term>configure.args</term>
2116
2117        <term>configure.pre_args</term>
2118
2119        <term>configure.post_args</term>
2120
2121        <listitem>
2122          <para>Main arguments to <literal>configure.cmd</literal>; optional
2123          argument modifiers pass arguments before and after the main
2124          arguments.</para>
2125
2126          <itemizedlist>
2127            <listitem>
2128              <para>Default: none</para>
2129            </listitem>
2130
2131            <listitem>
2132              <para>Example:</para>
2133
2134              <programlisting>configure.args      --bindir=${prefix}/bin
2135
2136</programlisting>
2137            </listitem>
2138          </itemizedlist>
2139
2140          <para>The following argument modifiers are available:</para>
2141
2142          <itemizedlist>
2143            <listitem>
2144              <para><literal>configure.pre_args</literal>, defaults to:
2145              <literal>--prefix=${prefix}</literal></para>
2146            </listitem>
2147
2148            <listitem>
2149              <para><literal>configure.post_args</literal>, defaults to:
2150              none</para>
2151            </listitem>
2152
2153            <listitem>
2154              <para>Examples:</para>
2155
2156              <programlisting>configure.pre_args  --prefix=${prefix}/share/bro
2157configure.post_args OPT="-D__DARWIN_UNIX03"</programlisting>
2158            </listitem>
2159          </itemizedlist>
2160        </listitem>
2161      </varlistentry>
2162    </variablelist>
2163
2164    <section id="reference.phases.configure.universal">
2165      <title>Configure Universal</title>
2166
2167      <para>Universal keywords are used to make a port compile on the Mac OS X
2168      platform to run on both PPC and Intel processors.</para>
2169
2170      <note>
2171        <para>There is a default universal variant made available to all ports
2172        by MacPorts base, so redefining universal keywords should only be done
2173        to make a given port compile if the default options fail to do
2174        so.</para>
2175      </note>
2176
2177      <variablelist>
2178        <varlistentry>
2179          <term>configure.universal_args</term>
2180
2181          <listitem>
2182            <para>Arguments used in the configure script to build the port
2183            universal.</para>
2184
2185            <itemizedlist>
2186              <listitem>
2187                <para>Default:
2188                <literal>--disable-dependency-tracking</literal></para>
2189              </listitem>
2190
2191              <listitem>
2192                <para>Example:</para>
2193
2194                <programlisting>TODO: add example</programlisting>
2195              </listitem>
2196            </itemizedlist>
2197          </listitem>
2198        </varlistentry>
2199
2200        <varlistentry>
2201          <term>configure.universal_cflags</term>
2202
2203          <listitem>
2204            <para>Additional flags to put in the CFLAGS environment variable
2205            when invoking the configure script. Default value is based on
2206            <literal>${configure.universal_archs}</literal>.</para>
2207
2208            <itemizedlist>
2209              <listitem>
2210                <para>Default: </para>
2211                <para>(PowerPC Tiger) <literal>-isysroot ${developer_dir}/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc</literal></para>
2212                <para>(Leopard / Intel Tiger) <literal>-arch i386 -arch ppc</literal></para>
2213                <para>(Snow Leopard) <literal>-arch x86_64 -arch i386</literal></para>
2214              </listitem>
2215
2216              <listitem>
2217                <para>Example:</para>
2218
2219                <programlisting>TODO: add example</programlisting>
2220              </listitem>
2221            </itemizedlist>
2222          </listitem>
2223        </varlistentry>
2224
2225        <varlistentry>
2226          <term>configure.universal_cppflags</term>
2227
2228          <listitem>
2229            <para>Additional flags to put in the CPPFLAGS environment variable
2230            when invoking the configure script.</para>
2231
2232            <itemizedlist>
2233              <listitem>
2234                <para>Default: </para>
2235                <para>(PowerPC Tiger) <literal>-isysroot ${developer_dir}/SDKs/MacOSX10.4u.sdk</literal></para>
2236                <para>(Others) none</para>
2237              </listitem>
2238
2239              <listitem>
2240                <para>Example:</para>
2241
2242                <programlisting>TODO: add example</programlisting>
2243              </listitem>
2244            </itemizedlist>
2245          </listitem>
2246        </varlistentry>
2247
2248        <varlistentry>
2249          <term>configure.universal_cxxflags</term>
2250
2251          <listitem>
2252            <para>Additional flags to put in the CXXFLAGS environment variable
2253            when invoking the configure script. Default value is based on
2254            <literal>${configure.universal_archs}</literal>.</para>
2255
2256            <itemizedlist>
2257              <listitem>
2258                <para>Default: </para>
2259                <para>(PowerPC Tiger) <literal>-isysroot ${developer_dir}/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc</literal></para>
2260                <para>(Leopard / Intel Tiger) <literal>-arch i386 -arch ppc</literal></para>
2261                <para>(Snow Leopard) <literal>-arch x86_64 -arch i386</literal></para>
2262              </listitem>
2263
2264              <listitem>
2265                <para>Example:</para>
2266
2267                <programlisting>TODO: add example</programlisting>
2268              </listitem>
2269            </itemizedlist>
2270          </listitem>
2271        </varlistentry>
2272
2273        <varlistentry>
2274          <term>configure.universal_ldflags</term>
2275
2276          <listitem>
2277            <para>Additional flags to put in the LDFLAGS environment variable
2278            when invoking the configure script.</para>
2279
2280            <itemizedlist>
2281              <listitem>
2282                <para>Default: </para>
2283                <para>(PowerPC Tiger) <literal>-Wl,-syslibroot,${developer_dir}/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc</literal></para>
2284                <para>(Leopard / Intel Tiger) <literal>-arch i386 -arch ppc</literal></para>
2285                <para>(Snow Leopard) <literal>-arch x86_64 -arch i386</literal></para>
2286              </listitem>
2287
2288              <listitem>
2289                <para>Example:</para>
2290
2291                <programlisting>TODO: add example</programlisting>
2292              </listitem>
2293            </itemizedlist>
2294          </listitem>
2295        </varlistentry>
2296      </variablelist>
2297    </section>
2298
2299    <section id="reference.phases.configure.automake-autoconf">
2300      <title>Automake and Autoconf</title>
2301
2302      <para>The list of configure keywords available for ports that need
2303      automake and/or autoconf.</para>
2304
2305      <variablelist>
2306        <varlistentry>
2307          <term>use_automake</term>
2308
2309          <listitem>
2310            <para>Whether or not to use automake.</para>
2311
2312            <itemizedlist>
2313              <listitem>
2314                <para>Default: <option>no</option></para>
2315              </listitem>
2316
2317              <listitem>
2318                <para>Example:</para>
2319
2320                <programlisting>use_automake        yes</programlisting>
2321              </listitem>
2322            </itemizedlist>
2323          </listitem>
2324        </varlistentry>
2325
2326        <varlistentry>
2327          <term>automake.env</term>
2328
2329          <listitem>
2330            <para>Environment variables to pass to automake.</para>
2331
2332            <itemizedlist>
2333              <listitem>
2334                <para>Default: ???</para>
2335              </listitem>
2336
2337              <listitem>
2338                <para>Example:</para>
2339
2340                <programlisting>automake.env        CFLAGS=-I${prefix}/include</programlisting>
2341              </listitem>
2342            </itemizedlist>
2343          </listitem>
2344        </varlistentry>
2345
2346        <varlistentry>
2347          <term>automake.args</term>
2348
2349          <listitem>
2350            <para>Arguments to pass to automake.</para>
2351
2352            <itemizedlist>
2353              <listitem>
2354                <para>Default: ???</para>
2355              </listitem>
2356
2357              <listitem>
2358                <para>Example:</para>
2359
2360                <programlisting>automake.args       --foreign</programlisting>
2361              </listitem>
2362            </itemizedlist>
2363          </listitem>
2364        </varlistentry>
2365
2366        <varlistentry>
2367          <term>automake.dir</term>
2368
2369          <listitem>
2370            <para>Directory in which to run
2371            <varname>${automake.cmd}</varname>.</para>
2372
2373            <itemizedlist>
2374              <listitem>
2375                <para>Default: <varname>${worksrcpath}</varname></para>
2376              </listitem>
2377
2378              <listitem>
2379                <para>Example:</para>
2380
2381                <programlisting>automake.dir        ./src</programlisting>
2382              </listitem>
2383            </itemizedlist>
2384          </listitem>
2385        </varlistentry>
2386
2387        <varlistentry>
2388          <term>use_autoconf</term>
2389
2390          <listitem>
2391            <para>Whether or not to use autoconf.</para>
2392
2393            <itemizedlist>
2394              <listitem>
2395                <para>Default: <option>no</option></para>
2396              </listitem>
2397
2398              <listitem>
2399                <para>Example:</para>
2400
2401                <programlisting>use_autoconf        yes</programlisting>
2402              </listitem>
2403            </itemizedlist>
2404          </listitem>
2405        </varlistentry>
2406
2407        <varlistentry>
2408          <term>autoconf.env</term>
2409
2410          <listitem>
2411            <para>Environmental variables to pass to autoconf.</para>
2412
2413            <itemizedlist>
2414              <listitem>
2415                <para>Default: ???</para>
2416              </listitem>
2417
2418              <listitem>
2419                <para>Example:</para>
2420
2421                <programlisting>autoconf.env        CFLAGS=-I${prefix}/include/gtk12</programlisting>
2422              </listitem>
2423            </itemizedlist>
2424          </listitem>
2425        </varlistentry>
2426
2427        <varlistentry>
2428          <term>autoconf.args</term>
2429
2430          <listitem>
2431            <para>Arguments to pass to autoconf.</para>
2432
2433            <itemizedlist>
2434              <listitem>
2435                <para>Default: ???</para>
2436              </listitem>
2437
2438              <listitem>
2439                <para>Example:</para>
2440
2441                <programlisting>autoconf.args       "-l src/aclocaldir"</programlisting>
2442              </listitem>
2443            </itemizedlist>
2444          </listitem>
2445        </varlistentry>
2446
2447        <varlistentry>
2448          <term>autoconf.dir</term>
2449
2450          <listitem>
2451            <para>Directory in which to run
2452            <varname>${autoconf.cmd}</varname>.</para>
2453
2454            <itemizedlist>
2455              <listitem>
2456                <para>Default: <varname>${worksrcpath}</varname></para>
2457              </listitem>
2458
2459              <listitem>
2460                <para>Example:</para>
2461
2462                <programlisting>autoconf.dir        src</programlisting>
2463              </listitem>
2464            </itemizedlist>
2465          </listitem>
2466        </varlistentry>
2467      </variablelist>
2468    </section>
2469  </section>
2470
2471  <section id="reference.phases.build">
2472    <title>Build Phase Keywords</title>
2473
2474    <para>The list of keywords related to the build phase.</para>
2475
2476    <variablelist>
2477      <varlistentry>
2478        <term>build.cmd</term>
2479
2480        <listitem>
2481          <para>Make command to run in <varname>${worksrcdir}</varname>. Only
2482          use it if you can't use <literal>build.type</literal>.</para>
2483
2484          <itemizedlist>
2485            <listitem>
2486              <para>Default: <command>make</command></para>
2487            </listitem>
2488
2489            <listitem>
2490              <para>Example:</para>
2491
2492              <programlisting>build.cmd           pbxbuild</programlisting>
2493            </listitem>
2494          </itemizedlist>
2495        </listitem>
2496      </varlistentry>
2497
2498      <varlistentry>
2499        <term>build.type</term>
2500
2501        <listitem>
2502          <para>Defines which "make" is required. Sets
2503          <varname>${build.cmd}</varname> to either "gnumake" or "bsdmake"
2504          accordingly.</para>
2505
2506          <itemizedlist>
2507            <listitem>
2508              <para>Default: <option>gnu</option></para>
2509            </listitem>
2510
2511            <listitem>
2512              <para>Values: <option>gnu</option> <option>bsd</option></para>
2513            </listitem>
2514
2515            <listitem>
2516              <para>Example:</para>
2517
2518              <programlisting>build.type          bsd</programlisting>
2519            </listitem>
2520          </itemizedlist>
2521        </listitem>
2522      </varlistentry>
2523
2524      <varlistentry>
2525        <term>build.args</term>
2526
2527        <term>build.pre_args</term>
2528
2529        <term>build.post_args</term>
2530
2531        <listitem>
2532          <para>Main arguments to <varname>${build.cmd}</varname>; optional
2533          argument modifiers pass arguments before and after the main
2534          arguments.</para>
2535
2536          <itemizedlist>
2537            <listitem>
2538              <para>Default: none</para>
2539            </listitem>
2540
2541            <listitem>
2542              <para>Example:</para>
2543
2544              <programlisting>build.args          -DNOWARN
2545
2546</programlisting>
2547            </listitem>
2548          </itemizedlist>
2549
2550          <para>The following argument modifiers are available:</para>
2551
2552          <itemizedlist>
2553            <listitem>
2554              <para><literal>build.pre_args</literal>, defaults to:
2555              <varname>${build.target.current}</varname></para>
2556            </listitem>
2557
2558            <listitem>
2559              <para><literal>build.post_args</literal>, defaults to:
2560              none</para>
2561            </listitem>
2562
2563            <listitem>
2564              <para>Examples:</para>
2565
2566              <programlisting>build.pre_args      -project AudioSlicer.xcode
2567build.post_args     CFLAGS_SYS="-DUSE_FREETYPE -DPREFER_FREETYPE"</programlisting>
2568            </listitem>
2569          </itemizedlist>
2570        </listitem>
2571      </varlistentry>
2572
2573      <varlistentry>
2574        <term>build.target</term>
2575
2576        <term>build.target-append</term>
2577
2578        <term>build.target-delete</term>
2579
2580        <listitem>
2581          <para>Build target to pass to <varname>${build.cmd}</varname>; list
2582          modifiers add or delete items from a previous Portfile build.target
2583          keyword or the default set by MacPorts base.</para>
2584
2585          <itemizedlist>
2586            <listitem>
2587              <para>Default: <literal>all</literal></para>
2588            </listitem>
2589
2590            <listitem>
2591              <para>Example:</para>
2592
2593              <programlisting>build.target        all-src</programlisting>
2594
2595              <programlisting>build.target-append     doc extra
2596build.target-delete     compat</programlisting>
2597            </listitem>
2598          </itemizedlist>
2599        </listitem>
2600      </varlistentry>
2601
2602      <varlistentry>
2603        <term>build.env</term>
2604
2605        <term>build.env-append</term>
2606
2607        <term>build.env-delete</term>
2608
2609        <listitem>
2610          <para>Set environment variables for build; list modifiers add
2611          and delete items from a previous Portfile build.env keyword, or
2612          a default set by MacPorts base.</para>
2613
2614          <itemizedlist>
2615            <listitem>
2616              <para>Default: none</para>
2617            </listitem>
2618          </itemizedlist>
2619        </listitem>
2620      </varlistentry>
2621
2622      <varlistentry>
2623        <term>use_parallel_build</term>
2624
2625        <listitem>
2626          <para>This keyword is for specifying whether or not it is safe for a
2627          port to use multiple CPUs or multiple cores in parallel during its
2628          build phase. If <code>use_parallel_build</code> is not set to
2629          <quote>no</quote> in a given port, the option <option>-j${build.jobs}</option>
2630          is passed to <varname>${build.cmd}</varname> (if
2631          <varname>${build.cmd}</varname> is <command>make</command> or
2632          <command>scons</command>).</para>
2633
2634          <itemizedlist>
2635            <listitem>
2636              <para>Default: <option>yes</option></para>
2637            </listitem>
2638
2639            <listitem>
2640              <para>Example:</para>
2641
2642              <programlisting>use_parallel_build  no</programlisting>
2643            </listitem>
2644          </itemizedlist>
2645        </listitem>
2646      </varlistentry>
2647     
2648      <varlistentry>
2649        <term>build.jobs</term>
2650
2651        <listitem>
2652          <para>The number of simultaneous jobs to run when parallel build is
2653          enabled. The default value is based on the variable
2654          <varname>buildmakejobs</varname> in
2655          <filename>macports.conf</filename>.</para>
2656
2657          <itemizedlist>
2658            <listitem>
2659              <para>Default: If <varname>buildmakejobs</varname> is 0, the
2660              number of CPU cores in the machine, or the number of GB of
2661              physical memory plus one, whichever is less. Otherwise,
2662              the actual value of <literal>${buildmakejobs}</literal>.</para>
2663            </listitem>
2664          </itemizedlist>
2665        </listitem>
2666      </varlistentry>
2667     
2668    </variablelist>
2669  </section>
2670
2671  <section id="reference.phases.test">
2672    <title>Test Phase Keywords</title>
2673
2674    <para>The list of keywords related to the test phase.</para>
2675
2676    <variablelist>
2677      <varlistentry>
2678        <term>test.run</term>
2679
2680        <listitem>
2681          <para>Enable running test suites bundled with a port.</para>
2682
2683          <itemizedlist>
2684            <listitem>
2685              <para>Default: <option>no</option></para>
2686            </listitem>
2687
2688            <listitem>
2689              <para>Example:</para>
2690
2691              <programlisting>test.run            yes</programlisting>
2692            </listitem>
2693          </itemizedlist>
2694        </listitem>
2695      </varlistentry>
2696
2697      <varlistentry>
2698        <term>test.cmd</term>
2699
2700        <listitem>
2701          <para>Test command to run relative to
2702          <varname>${worksrcdir}</varname>.</para>
2703
2704          <itemizedlist>
2705            <listitem>
2706              <para>Default: <varname>${build.cmd}</varname></para>
2707            </listitem>
2708
2709            <listitem>
2710              <para>Example:</para>
2711
2712              <programlisting>test.cmd            checks.sh</programlisting>
2713            </listitem>
2714          </itemizedlist>
2715        </listitem>
2716      </varlistentry>
2717
2718      <varlistentry>
2719        <term>test.target</term>
2720
2721        <listitem>
2722          <para>Test target to pass to <varname>${test.cmd}</varname>.</para>
2723
2724          <itemizedlist>
2725            <listitem>
2726              <para>Default: <literal>test</literal></para>
2727            </listitem>
2728
2729            <listitem>
2730              <para>Example:</para>
2731
2732              <programlisting>test.target         checks</programlisting>
2733            </listitem>
2734          </itemizedlist>
2735        </listitem>
2736      </varlistentry>
2737
2738      <varlistentry>
2739        <term>test.env</term>
2740
2741        <term>test.env-append</term>
2742
2743        <term>test.env-delete</term>
2744
2745        <listitem>
2746          <para>Set environment variables for test; list modifiers add
2747          and delete items from a previous Portfile test.env keyword, or
2748          a default set by MacPorts base.</para>
2749
2750          <para>Often <literal>DYLD_LIBRARY_PATH</literal> is set here to
2751          support testing dynamically linked libraries.</para>
2752
2753          <itemizedlist>
2754            <listitem>
2755              <para>Default: none</para>
2756            </listitem>
2757
2758            <listitem>
2759              <para>Example:</para>
2760
2761              <programlisting>test.env       <literal>DYLD_LIBRARY_PATH=${worksrcpath}/src/.libs</literal></programlisting>
2762            </listitem>
2763          </itemizedlist>
2764        </listitem>
2765      </varlistentry>
2766    </variablelist>
2767  </section>
2768
2769  <section id="reference.phases.destroot">
2770    <title>Destroot Phase Keywords</title>
2771
2772    <para>The list of keywords related to the destroot phase.</para>
2773
2774    <variablelist>
2775      <varlistentry>
2776        <term>destroot.cmd</term>
2777
2778        <listitem>
2779          <para>Install command to run relative to
2780          <varname>${worksrcdir}</varname>. Only use it if you can't use
2781          <literal>destroot.type</literal>.</para>
2782
2783          <itemizedlist>
2784            <listitem>
2785              <para>Default: <varname>${build.cmd}</varname></para>
2786            </listitem>
2787
2788            <listitem>
2789              <para>Example:</para>
2790
2791              <programlisting>destroot.cmd        pbxbuild</programlisting>
2792            </listitem>
2793          </itemizedlist>
2794        </listitem>
2795      </varlistentry>
2796
2797      <varlistentry>
2798        <term>destroot.type</term>
2799
2800        <listitem>
2801          <para>Defines which "make" is required. Sets
2802          <varname>${destroot.cmd}</varname> to either "gnumake" or "bsdmake"
2803          accordingly.</para>
2804
2805          <itemizedlist>
2806            <listitem>
2807              <para>Default: <varname>${build.type}</varname></para>
2808            </listitem>
2809
2810            <listitem>
2811              <para>Values: <option>gnu</option> <option>bsd</option></para>
2812            </listitem>
2813
2814            <listitem>
2815              <para>Example:</para>
2816
2817              <programlisting>destroot.type       bsd</programlisting>
2818            </listitem>
2819          </itemizedlist>
2820        </listitem>
2821      </varlistentry>
2822
2823      <varlistentry>
2824        <term>destroot.args</term>
2825
2826        <term>destroot.pre_args</term>
2827
2828        <term>destroot.post_args</term>
2829
2830        <listitem>
2831          <para>Main arguments to <varname>${destroot.cmd}</varname>; optional
2832          argument modifiers pass arguments before and after the main
2833          arguments.</para>
2834
2835          <itemizedlist>
2836            <listitem>
2837              <para>Default: none</para>
2838            </listitem>
2839
2840            <listitem>
2841              <para>Example:</para>
2842
2843              <programlisting>destroot.args       BINDIR=${prefix}/bin
2844
2845</programlisting>
2846            </listitem>
2847          </itemizedlist>
2848
2849          <para>The following argument modifiers are available:</para>
2850
2851          <itemizedlist>
2852            <listitem>
2853              <para><literal>destroot.pre_args</literal>, defaults to:
2854              <varname>${destroot.target}</varname></para>
2855            </listitem>
2856
2857            <listitem>
2858              <para><literal>destroot.post_args</literal>, defaults to:
2859              none</para>
2860            </listitem>
2861
2862            <listitem>
2863              <para>Examples:</para>
2864
2865              <programlisting>destroot.pre_args   -project AudioSlicer.xcode
2866destroot.post_args  INSTDIR=${destroot}${prefix}</programlisting>
2867            </listitem>
2868          </itemizedlist>
2869        </listitem>
2870      </varlistentry>
2871
2872      <varlistentry>
2873        <term>destroot.target</term>
2874
2875        <term>destroot.target-append</term>
2876
2877        <term>destroot.target-delete</term>
2878
2879        <listitem>
2880          <para>Install target to pass to <varname>${destroot.cmd}</varname>;
2881          list modifiers add or delete items from a previous Portfile
2882          destroot.target keyword or the default set by MacPorts base.</para>
2883
2884          <itemizedlist>
2885            <listitem>
2886              <para>Default: <literal>install</literal></para>
2887            </listitem>
2888
2889            <listitem>
2890              <para>Example:</para>
2891
2892              <programlisting>destroot.target     install install-config install-commandmode</programlisting>
2893
2894              <programlisting>destroot.target-append  install-plugins
2895destroot.target-delete  install-commandmode</programlisting>
2896            </listitem>
2897          </itemizedlist>
2898        </listitem>
2899      </varlistentry>
2900
2901      <varlistentry>
2902        <term>destroot.destdir</term>
2903
2904        <listitem>
2905          <para>Arguments passed to <varname>${destroot.cmd}</varname> to
2906          install correctly into the destroot.</para>
2907
2908          <itemizedlist>
2909            <listitem>
2910              <para>Default: <literal>DESTDIR=${destroot}</literal></para>
2911            </listitem>
2912
2913            <listitem>
2914              <para>Example:</para>
2915
2916              <programlisting>destroot.destdir    prefix=${destroot}${prefix}</programlisting>
2917            </listitem>
2918          </itemizedlist>
2919
2920          <note>
2921            <para>If an application's Makefile properly supports the DESTDIR
2922            variable, MacPorts will automatically destroot the port properly.
2923            A port must destroot properly or the port will not install
2924            correctly, upgrade, or uninstall. If not, you may need to set this
2925            variable, or even patch the application's Makefile.</para>
2926          </note>
2927        </listitem>
2928      </varlistentry>
2929
2930      <varlistentry>
2931        <term>destroot.umask</term>
2932
2933        <listitem>
2934          <para>Umask to use during destroot.</para>
2935
2936          <itemizedlist>
2937            <listitem>
2938              <para>Default: <literal>022</literal></para>
2939            </listitem>
2940
2941            <listitem>
2942              <para>Example:</para>
2943
2944              <programlisting>destroot.umask      002</programlisting>
2945            </listitem>
2946          </itemizedlist>
2947        </listitem>
2948      </varlistentry>
2949
2950      <varlistentry>
2951        <term>destroot.keepdirs</term>
2952
2953        <listitem>
2954          <para>A list of directories that should not be removed if empty upon
2955          destroot completion.</para>
2956
2957          <itemizedlist>
2958            <listitem>
2959              <para>Default: ???</para>
2960            </listitem>
2961
2962            <listitem>
2963              <para>Example:</para>
2964
2965              <programlisting>destroot.keepdirs   ${destroot}${prefix}/var/run \
2966                    ${destroot}${prefix}/var/log \
2967                    ${destroot}${prefix}/var/cache/mrtg</programlisting>
2968            </listitem>
2969          </itemizedlist>
2970        </listitem>
2971      </varlistentry>
2972
2973      <varlistentry>
2974        <term>destroot.violate_mtree</term>
2975
2976        <listitem>
2977          <para>MacPorts tests for compliance to the common directory
2978          structure in <varname>${prefix}</varname>. If a port is not
2979          compliant with the standard, set it to <option>yes</option>.</para>
2980
2981          <para>You can find the macports standard in <link
2982          linkend="internals.hierarchy">MacPorts File Hierarchy</link> or in
2983          the porthier(7) man page.</para>
2984
2985          <para>If <code>destroot.violate_mtree</code> is set to
2986          <option>yes</option>, the following warning is issued during the
2987          installation.</para>
2988
2989          <screen>Warning: <replaceable>portname</replaceable> requests to install files outside the common directory structure!</screen>
2990
2991          <para>This means that the port installed files outside of their
2992          normal locations in <varname>${prefix}</varname>. These could be
2993          files totally outside of <varname>${prefix}</varname>, which could
2994          cause problems on your computer, or files inside of
2995          <varname>${prefix}</varname> that are not in a standard location.
2996          Use <literal>port contents
2997          <replaceable>portname</replaceable></literal> to see the location
2998          for all files that were installed by a given port.</para>
2999
3000          <itemizedlist>
3001            <listitem>
3002              <para>Default: <option>no</option></para>
3003            </listitem>
3004
3005            <listitem>
3006              <para>Example:</para>
3007
3008              <programlisting>destroot.violate_mtree      yes</programlisting>
3009            </listitem>
3010          </itemizedlist>
3011        </listitem>
3012      </varlistentry>
3013    </variablelist>
3014  </section>
3015</section>
Note: See TracBrowser for help on using the repository browser.