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

Last change on this file was 143864, checked in by dstrubbe@…, 5 years ago

doc-new: Further information about the test phase.

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