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

Last change on this file since 75235 was 75235, checked in by snc@…, 9 years ago

guide: add extract.asroot

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