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

Last change on this file since 126058 was 126058, checked in by khindenburg@…, 6 years ago

guide: add info about using fetch type of bzr #25391

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