source: trunk/doc-new/man/xml/portfile.7.xml @ 29357

Last change on this file since 29357 was 29357, checked in by markd@…, 13 years ago

Some minor corrections and format changes.

File size: 83.1 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4<refentry>
5  <refmeta>
6    <refentrytitle>PORTFILE</refentrytitle>
7
8    <manvolnum>7</manvolnum>
9  </refmeta>
10
11  <refnamediv>
12    <refname>portfile</refname>
13
14    <refpurpose>MacPorts Portfile reference</refpurpose>
15  </refnamediv>
16
17  <refsection>
18    <title>Description</title>
19
20    <para>A complete reference of all available Portfile variables and example
21    syntax. Portfiles consist of valid TCL and are encoded in UTF-8. They
22    usually contain only simple keyword/value combinations and Tcl extensions
23    as described below, though they may also contain arbitrary TCL code. Every
24    port has a corresponding Portfile, but Portfiles do not completely define
25    a port's installation behavior since the MacPorts base has default port
26    installation characteristics coded within it. Therefore Portfiles need
27    only specify required options and, if necessary, non-default
28    characteristics for a port.</para>
29  </refsection>
30
31  <refsection condition="guide">
32    <title>Table of Contents</title>
33
34    <para>The contents of this man page.</para>
35
36    <orderedlist>
37      <listitem>
38        <para>Global Variables</para>
39      </listitem>
40
41      <listitem>
42        <para>Global Keyword Reference</para>
43
44        <itemizedlist>
45          <listitem>
46            <para>General Global Keywords</para>
47          </listitem>
48
49          <listitem>
50            <para>Dependencies</para>
51          </listitem>
52
53          <listitem>
54            <para>Variants</para>
55          </listitem>
56
57          <listitem>
58            <para>Livecheck / Distcheck</para>
59          </listitem>
60
61          <listitem>
62            <para>StartupItems</para>
63          </listitem>
64        </itemizedlist>
65      </listitem>
66
67      <listitem>
68        <para>Installation Phase Keyword Reference</para>
69
70        <itemizedlist>
71          <listitem>
72            <para>A word about keyword list modifiers</para>
73
74            <itemizedlist>
75              <listitem>
76                <para>Common uses for keyword list modifiers</para>
77              </listitem>
78            </itemizedlist>
79          </listitem>
80
81          <listitem>
82            <para>A word about keyword argument modifiers</para>
83          </listitem>
84
85          <listitem>
86            <para>Fetch</para>
87
88            <itemizedlist>
89              <listitem>
90                <para>Fetch from CVS</para>
91              </listitem>
92
93              <listitem>
94                <para>Fetch from SVN</para>
95              </listitem>
96            </itemizedlist>
97          </listitem>
98
99          <listitem>
100            <para>Checksum</para>
101          </listitem>
102
103          <listitem>
104            <para>Extract</para>
105          </listitem>
106
107          <listitem>
108            <para>Patch</para>
109          </listitem>
110
111          <listitem>
112            <para>Automake / Autoconf</para>
113          </listitem>
114
115          <listitem>
116            <para>Configure</para>
117
118            <itemizedlist>
119              <listitem>
120                <para>Configure Universal</para>
121              </listitem>
122            </itemizedlist>
123          </listitem>
124
125          <listitem>
126            <para>Build</para>
127          </listitem>
128
129          <listitem>
130            <para>Destroot</para>
131          </listitem>
132
133          <listitem>
134            <para>Test</para>
135          </listitem>
136        </itemizedlist>
137      </listitem>
138
139      <listitem>
140        <para>Tcl Extensions</para>
141      </listitem>
142    </orderedlist>
143  </refsection>
144
145  <refsection>
146    <title>Global Variables</title>
147
148    <para>Global variables are variables available to any Portfile. For a list
149    of additional variables available to ports that are assigned to a MacPorts
150    Portgroup, see portgroup(7).</para>
151
152    <variablelist>
153      <varlistentry>
154        <term>prefix</term>
155
156        <listitem>
157          <para>Installation prefix, set in
158          <filename>${prefix}/etc/macports/macports.conf</filename> —may be
159          overridden on a per port basis. For example, aqua applications are
160          installed in <filename>/Applications/MacPorts</filename>.</para>
161
162          <para>Default: /opt/local</para>
163        </listitem>
164      </varlistentry>
165
166      <varlistentry>
167        <term>binpath</term>
168
169        <listitem>
170          <para>Default PATH to use in finding executables.</para>
171        </listitem>
172      </varlistentry>
173
174      <varlistentry>
175        <term>libpath</term>
176
177        <listitem>
178          <para>Path to the MacPorts TCL libraries.</para>
179        </listitem>
180      </varlistentry>
181
182      <varlistentry>
183        <term>portpath</term>
184
185        <listitem>
186          <para>Full path to the Portfile location.</para>
187        </listitem>
188      </varlistentry>
189
190      <varlistentry>
191        <term>filesdir</term>
192
193        <listitem>
194          <para>Path to port files relative to
195          <varname>${portpath}</varname>.</para>
196        </listitem>
197      </varlistentry>
198
199      <varlistentry>
200        <term>workpath</term>
201
202        <listitem>
203          <para>Full path to work directory.</para>
204        </listitem>
205      </varlistentry>
206
207      <varlistentry>
208        <term>worksrcpath</term>
209
210        <listitem>
211          <para>Full path to extracted source code. Equivalent to
212          <varname>${workpath}/${worksrcdir}</varname>.</para>
213        </listitem>
214      </varlistentry>
215
216      <varlistentry>
217        <term>destroot</term>
218
219        <listitem>
220          <para>Full path into which software will be destrooted. Equivalent
221          to <filename>${workpath}/destroot</filename>.</para>
222        </listitem>
223      </varlistentry>
224
225      <varlistentry>
226        <term>distpath</term>
227
228        <listitem>
229          <para>Location to store downloaded distfiles.</para>
230        </listitem>
231      </varlistentry>
232
233      <varlistentry>
234        <term>install.user</term>
235
236        <listitem>
237          <para>The Unix user at the time of port installation.</para>
238        </listitem>
239      </varlistentry>
240
241      <varlistentry>
242        <term>install.group</term>
243
244        <listitem>
245          <para>The Unix group at the time of port installation.</para>
246        </listitem>
247      </varlistentry>
248
249      <varlistentry>
250        <term>os.platform</term>
251
252        <listitem>
253          <para>Identifies platform type (ie, "darwin", "freebsd",
254          etc).</para>
255        </listitem>
256      </varlistentry>
257
258      <varlistentry>
259        <term>os.arch</term>
260
261        <listitem>
262          <para>Identifies hardware type (ie, "powerpc", "intel").</para>
263        </listitem>
264      </varlistentry>
265
266      <varlistentry>
267        <term>os.version</term>
268
269        <listitem>
270          <para>The version number of the host operating system (ie "8.0" for
271          Darwin 8.0).</para>
272        </listitem>
273      </varlistentry>
274
275      <varlistentry>
276        <term>os.major</term>
277
278        <listitem>
279          <para>The major version number of the host operating system (ie "8"
280          for Darwin 8.0).</para>
281        </listitem>
282      </varlistentry>
283    </variablelist>
284  </refsection>
285
286  <refsection>
287    <title>Global Keyword Reference</title>
288
289    <para>MacPorts keywords are used to specify required or optional items
290    within a Portfile, or to override default options used by MacPorts base
291    for individual ports. Keywords are to be used within the "global" and
292    "variant" sections of Portfiles, and not within optional port phase
293    declarations.</para>
294
295    <para>The global keywords listed below specify information for ports as a
296    whole, whereas the keywords listed under a port phase specify information
297    to be used during a particular installation phase.</para>
298
299    <refsection>
300      <title>General Global Keywords</title>
301
302      <para>The list of global keywords.</para>
303
304      <variablelist>
305        <varlistentry>
306          <term>PortSystem</term>
307
308          <listitem>
309            <para>The top line of every Portfile; it must be followed by a
310            blank line. It defines which version of the Portfile interpreter
311            will be used.</para>
312
313            <programlisting>PortSystem   1.0
314
315</programlisting>
316          </listitem>
317        </varlistentry>
318
319        <varlistentry>
320          <term>name</term>
321
322          <listitem>
323            <para>The name of the Port; it should be lowercase.</para>
324
325            <programlisting>name         foo</programlisting>
326          </listitem>
327        </varlistentry>
328
329        <varlistentry>
330          <term>version</term>
331
332          <listitem>
333            <para>The version of the ported software.</para>
334
335            <programlisting>version      1.23.45</programlisting>
336          </listitem>
337        </varlistentry>
338
339        <varlistentry>
340          <term>revision</term>
341
342          <listitem>
343            <para>Optional keyword (default is 0) that is used to track port
344            revisions. It should not be incremented for port revisions unless
345            it would benefit users to upgrade an installed port, and cleared
346            when the port is updated to a newer version.</para>
347
348            <programlisting>revision     1</programlisting>
349          </listitem>
350        </varlistentry>
351
352        <varlistentry>
353          <term>categories</term>
354
355          <listitem>
356            <para>The category under which the ported software falls. The
357            first category should be the same as the directory within which
358            the Portfile is stored; secondary and tertiary categories may be
359            selected.</para>
360
361            <programlisting>categories     net security</programlisting>
362          </listitem>
363        </varlistentry>
364
365        <varlistentry>
366          <term>maintainers</term>
367
368          <listitem>
369            <para>A port's maintainer is a person or persons who take
370            responsibility for keeping the port up-to-date, and the maintainer
371            keyword lists maintainer email addresses(s). However, many
372            maintainers wish to hide these addresses from spambots; to do so
373            follow these conventions:</para>
374
375            <itemizedlist>
376              <listitem>
377                <para>For addresses in domain @macports.org, simply omit the
378                domain name.</para>
379              </listitem>
380
381              <listitem>
382                <para>For addresses in other domains, say
383                <email>account@example.org</email>, use the convention
384                example.org:account to specify the address.</para>
385              </listitem>
386            </itemizedlist>
387
388            <para>In the example below, the maintainer email addresses
389            <email>jdoe@macports.org</email> and
390            <email>julesverne@example.org</email> are hidden using these
391            conventions.</para>
392
393            <programlisting>maintainers       jdoe \
394                  example.org:julesverne</programlisting>
395          </listitem>
396        </varlistentry>
397
398        <varlistentry>
399          <term>description</term>
400
401          <listitem>
402            <para>A one-sentence description of the ported software.</para>
403
404            <programlisting>description    A classic shooter arcade game.</programlisting>
405          </listitem>
406        </varlistentry>
407
408        <varlistentry>
409          <term>long_description</term>
410
411          <listitem>
412            <para>A long description of the ported software. Break long lines
413            with escaped newlines.</para>
414
415            <programlisting>description    A classic shooter arcade game derived from \
416               the game alien-munchers.  Not suitable for \
417               children under two years old.      </programlisting>
418          </listitem>
419        </varlistentry>
420
421        <varlistentry>
422          <term>homepage</term>
423
424          <listitem>
425            <para>Port application's homepage.</para>
426
427            <programlisting>homepage       http://www.somesite.org/apps</programlisting>
428          </listitem>
429        </varlistentry>
430
431        <varlistentry>
432          <term>platforms</term>
433
434          <listitem>
435            <para>The platforms on which the port has been tested.</para>
436
437            <programlisting>platforms      darwin freebsd</programlisting>
438          </listitem>
439        </varlistentry>
440      </variablelist>
441    </refsection>
442
443    <refsection>
444      <title>Dependencies</title>
445
446      <para>Free and open source software is highly modular, and MacPorts
447      ports often require that other ports be installed beforehand; these
448      prerequisites for a given port are called a port's
449      <quote>dependencies</quote>.</para>
450
451      <para>There are three types of MacPorts dependencies: library, build,
452      and run dependencies. Dependency types are important for proper port
453      upgrade and uninstall behavior. For example, you may not uninstall a
454      port that is a library dependency for another port, though you may
455      remove one with a build dependency; likewise, upgrading a port will
456      upgrade its library and build dependencies also, but not its run
457      dependencies.</para>
458
459      <variablelist>
460        <varlistentry>
461          <term>depends_lib</term>
462
463          <term>depends_lib-append</term>
464
465          <term>depends_lib-delete</term>
466
467          <listitem>
468            <para>The list of dependencies to check before phases
469            <option>configure</option>, <option>build</option>,
470            <option>destroot</option>, <option>install</option>, and
471            <option>package</option>. Library dependencies are needed both at
472            build time (for headers and libraries to link against) and at run
473            time.</para>
474          </listitem>
475        </varlistentry>
476
477        <varlistentry>
478          <term>depends_build</term>
479
480          <term>depends_build-append</term>
481
482          <term>depends_build-delete</term>
483
484          <listitem>
485            <para>The list of dependencies to check before phases
486            <option>build</option>, <option>destroot</option>,
487            <option>install</option>, and <option>package</option>. Build
488            dependencies are needed when software is compiled, but not needed
489            at all once the software is compiled and installed.</para>
490          </listitem>
491        </varlistentry>
492
493        <varlistentry>
494          <term>depends_run</term>
495
496          <term>depends_run-append</term>
497
498          <term>depends_run-delete</term>
499
500          <listitem>
501            <para>The list of dependencies to check before phases
502            <option>destroot</option>, <option>install</option>, and
503            <option>package</option>. Run dependencies are needed when the
504            software is run, but not to compile it.</para>
505          </listitem>
506        </varlistentry>
507      </variablelist>
508
509      <refsection>
510        <title>Port and Non-Port Dependencies</title>
511
512        <para>Port dependencies should be provided by MacPorts ports whenever
513        possible, however dependencies may be provided by vendor-supplied
514        software when satisfying a dependency by a port is not practical or
515        desirable for a special reason. Dependencies of this type are called
516        non-port dependencies.</para>
517
518        <para>Port dependencies, the preferred type, are specified as shown in
519        these examples:</para>
520
521        <programlisting>depends_lib        port:rrdtool port:apache2
522
523depends_build      port:apache2 port:php5</programlisting>
524
525        <para>Non-port dependencies are specified as shown in these
526        examples:</para>
527
528        <programlisting>depends_lib        lib:libX11.6:xorg
529
530depends_build      bin:rrdtool</programlisting>
531      </refsection>
532    </refsection>
533
534    <refsection>
535      <title>Variants</title>
536
537      <para>MacPorts variants are conditional modifications of port
538      installation behavior that may be invoked by a user at the time of port
539      install.</para>
540
541      <variablelist>
542        <varlistentry>
543          <term>variant [requires variant] [conflicts variant] [description
544          description]</term>
545
546          <listitem>
547            <para>The variant declaration may contain any keywords that can be
548            placed in a Portfile's global section. If you wish to execute
549            system (shell) calls or Tcl extensions during the execution of a
550            port phase, you should place those statements within a
551            <literal>variant_isset</literal> conditional within a phase
552            declaration and not within the variant declaration itself.
553            Dependencies and conflicts with other variants in the same port
554            can be expressed with requires and conflicts. See the isset Tcl
555            extension.</para>
556
557            <itemizedlist>
558              <listitem>
559                <para>Default: no</para>
560              </listitem>
561
562              <listitem>
563                <para>Example:</para>
564
565                <programlisting>variant gnome requires glib {
566      configure.args-append --with-gnome
567      depends_lib-append port:gnome-session
568}</programlisting>
569              </listitem>
570            </itemizedlist>
571          </listitem>
572        </varlistentry>
573
574        <varlistentry>
575          <term>default_variants</term>
576
577          <listitem>
578            <para>If variants are defined, then the default_variants value
579            lists which variants are enabled by default. This allows for
580            Portfile modularity and also allows users to suppress default
581            variants if they wish.</para>
582
583            <itemizedlist>
584              <listitem>
585                <para>Default: none</para>
586              </listitem>
587
588              <listitem>
589                <para>Example:</para>
590
591                <programlisting>default_variants +ssl +tcpd
592
593</programlisting>
594              </listitem>
595            </itemizedlist>
596          </listitem>
597
598          <listitem>
599            <para>Default variants may be suppressed by preceding a variant
600            name with a "-" as shown in this example.</para>
601
602            <programlisting><prompt>%%</prompt> <userinput>port install foo -ssl</userinput></programlisting>
603          </listitem>
604        </varlistentry>
605
606        <varlistentry>
607          <term>universal_variant</term>
608
609          <listitem>
610            <para>When using MacPorts on Mac OS X, a universal variant is
611            defined by default to configure ports with universal flags. The
612            variant can be overridden if the default code does not work (see
613            the Configure Universal section below), or suppressed if a
614            universal variant is not possible for the port with this
615            keyword.</para>
616
617            <itemizedlist>
618              <listitem>
619                <para>Default: yes</para>
620              </listitem>
621
622              <listitem>
623                <para>Example:</para>
624
625                <programlisting>universal_variant  no</programlisting>
626              </listitem>
627            </itemizedlist>
628          </listitem>
629        </varlistentry>
630      </variablelist>
631    </refsection>
632
633    <refsection>
634      <title>Livecheck / Distcheck</title>
635
636      <para>Options livecheck and distcheck are especially useful for port
637      maintainers, but others may also find this information valuable.</para>
638
639      <para>Livecheck checks to see if MacPorts can query the developer's
640      download site to determine if a newer version of the software has become
641      available since the port was installed.</para>
642
643      <variablelist>
644        <varlistentry>
645          <term>livecheck.check</term>
646
647          <listitem>
648            <para>Specify what kind of update check to perform.</para>
649
650            <para>Open source mirror site options are to use the project's
651            latest file release from <option>sourceforge</option> or
652            <option>googlecode</option>, or the project's
653            <literal>date_updated</literal> XML tag for
654            <option>freshmeat</option>.</para>
655
656            <para>Generic download site options are to specify a
657            <option>moddate</option> (modification date) of a URL resource), a
658            <option>regex</option> (retrieve the version by applying a regex
659            to a URL resource), <option>regexm</option> (retrieve the version
660            by applying a multi-line regex to a URL resource),
661            <option>md5</option> (compares the md5 sum of a URL resource) or
662            <option>none</option> (no check).</para>
663
664            <itemizedlist>
665              <listitem>
666                <para>Default: sourceforge or googlecode if the master_sites
667                is one of these, else freshmeat.</para>
668              </listitem>
669
670              <listitem>
671                <para>Values: freshmeat sourceforge googlecode moddate regex
672                regexm md5 none</para>
673              </listitem>
674
675              <listitem>
676                <para>Examples:</para>
677
678                <programlisting>livecheck.check     regex
679livecheck.url       http://dev.mysql.com/
680livecheck.regex     "Generally Available (${major_version}\\.\[0-9.\]+)"
681</programlisting>
682              </listitem>
683            </itemizedlist>
684          </listitem>
685        </varlistentry>
686
687        <varlistentry>
688          <term>livecheck.name</term>
689
690          <listitem>
691            <para>Name of the project for live checks; only used with
692            freshmeat, sourceforge, and googlecode livechecks.</para>
693
694            <itemizedlist>
695              <listitem>
696                <para>Default: <varname>${name}</varname> or the
697                sourceforge/freshmeat/googlecode project name if it can be
698                guessed from <literal>master_sites</literal>.</para>
699              </listitem>
700
701              <listitem>
702                <para>Values:
703                <replaceable>any_project_name</replaceable></para>
704              </listitem>
705
706              <listitem>
707                <para>Example:</para>
708
709                <programlisting>livecheck.name   hibernate</programlisting>
710              </listitem>
711            </itemizedlist>
712          </listitem>
713        </varlistentry>
714
715        <varlistentry>
716          <term>livecheck.distname</term>
717
718          <listitem>
719            <para>Name of the file release for sourceforge and googlecode
720            checks. You may use this keyword without livecheck.version if you
721            replace the version part of the name with "(.*)".</para>
722
723            <itemizedlist>
724              <listitem>
725                <para>Default: SourceForge:
726                <varname>${livecheck.name}</varname> ; GoogleCode: first
727                ${distfiles} item</para>
728              </listitem>
729
730              <listitem>
731                <para>Values: <replaceable>filename</replaceable></para>
732              </listitem>
733
734              <listitem>
735                <para>Example:</para>
736
737                <programlisting>livecheck.distname  faad2.src</programlisting>
738              </listitem>
739            </itemizedlist>
740          </listitem>
741        </varlistentry>
742
743        <varlistentry>
744          <term>livecheck.version</term>
745
746          <listitem>
747            <para>Version of the project for a check; used for regex-based
748            checks.</para>
749
750            <itemizedlist>
751              <listitem>
752                <para>Default: <varname>${version}</varname></para>
753              </listitem>
754
755              <listitem>
756                <para>Values: <replaceable>any_version</replaceable></para>
757              </listitem>
758
759              <listitem>
760                <para>Example:</para>
761
762                <programlisting>livecheck.version   ${name}-${version}</programlisting>
763              </listitem>
764            </itemizedlist>
765          </listitem>
766        </varlistentry>
767
768        <varlistentry>
769          <term>livecheck.url</term>
770
771          <listitem>
772            <para>URL to query for a check.</para>
773
774            <itemizedlist>
775              <listitem>
776                <para>Default:</para>
777
778                <itemizedlist>
779                  <listitem>
780                    <para>homepage or the first hit among the following
781                    sites</para>
782                  </listitem>
783
784                  <listitem>
785                    <para>http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml</para>
786                  </listitem>
787
788                  <listitem>
789                    <para>http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}</para>
790                  </listitem>
791
792                  <listitem>
793                    <para>http://code.google.com/p/${livecheck.name}/downloads/list</para>
794                  </listitem>
795                </itemizedlist>
796              </listitem>
797
798              <listitem>
799                <para>Values: <replaceable>any_url</replaceable></para>
800              </listitem>
801
802              <listitem>
803                <para>Example:</para>
804
805                <programlisting>livecheck.url  http://ftp.gnu.org/gnu/bison/</programlisting>
806              </listitem>
807            </itemizedlist>
808          </listitem>
809        </varlistentry>
810
811        <varlistentry>
812          <term>livecheck.regex</term>
813
814          <listitem>
815            <para>Regular expression to parse the resource for regex checks.
816            Be sure to use a regular expression grouping around the version
817            component.</para>
818
819            <itemizedlist>
820              <listitem>
821                <para>Default: none</para>
822              </listitem>
823
824              <listitem>
825                <para>Values: <replaceable>any_regex</replaceable></para>
826              </listitem>
827
828              <listitem>
829                <para>Example:</para>
830
831                <programlisting>livecheck.regex  4th-([a-z0-9.]+)-unix.tar.gz</programlisting>
832              </listitem>
833            </itemizedlist>
834          </listitem>
835        </varlistentry>
836
837        <varlistentry>
838          <term>livecheck.md5</term>
839
840          <listitem>
841            <para>md5 checksum to use for an md5 comparison.</para>
842
843            <itemizedlist>
844              <listitem>
845                <para>Default: none</para>
846              </listitem>
847
848              <listitem>
849                <para>Values:
850                <replaceable>any_md5_checksum</replaceable></para>
851              </listitem>
852
853              <listitem>
854                <para>Example:</para>
855
856                <programlisting>livecheck  md5 37e6a5b6516a680c7178b72021d3b706</programlisting>
857              </listitem>
858            </itemizedlist>
859          </listitem>
860        </varlistentry>
861      </variablelist>
862
863      <para>Distcheck reports whether or not the distfile(s) specified in a
864      Portfile are still available on the developer's download site. Examples
865      are given below.</para>
866
867      <variablelist>
868        <varlistentry>
869          <term>distcheck.check</term>
870
871          <listitem>
872            <para>This option can be used to disable distcheck. It specifies
873            what kind of check should be performed on distfiles: moddate
874            (check if the Portfile is older than the distfile) or none (no
875            check).</para>
876
877            <itemizedlist>
878              <listitem>
879                <para>Default: moddate</para>
880              </listitem>
881
882              <listitem>
883                <para>Values: moddate none</para>
884              </listitem>
885
886              <listitem>
887                <para>Example:</para>
888
889                <programlisting>distcheck.check  none</programlisting>
890              </listitem>
891            </itemizedlist>
892          </listitem>
893        </varlistentry>
894      </variablelist>
895    </refsection>
896
897    <refsection>
898      <title>StartupItems</title>
899
900      <para>StartupItems are keywords that create Mac OS X startup scripts for
901      <ulink
902      url="http://developer.apple.com/macosx/launchd.html">launchd</ulink>,
903      the facility introduced by Apple beginning with OS X 10.4, that starts,
904      stops, and manages daemons, programs and scripts. Port authors use
905      StartupItem keywords within Portfiles to instruct MacPorts to generate
906      and install <command>launchd</command> scripts for daemons during port
907      installation. To support launchd, a wrapper program named
908      <command>daemondo</command> is provided by MacPorts base that serves as
909      an adapter between OS X's <command>launchd</command> and daemons that
910      are normally started via traditional rc.d style scripts.</para>
911
912      <para>There are three categories of StartupItem keywords. Those that
913      trigger StartupItem creation and setup logging, those that specify
914      attributes of <quote>executable</quote> StartupItems, and those that
915      specify attributes of <quote>script</quote> StartupItems.</para>
916
917      <refsection>
918        <title>StartupIem Creation &amp; Logging</title>
919
920        <para>The keywords in this section may be used with either
921        <quote>executable</quote> or <quote>script</quote> StartupItems (see
922        below).</para>
923
924        <variablelist>
925          <varlistentry>
926            <term>startupitem.create</term>
927
928            <listitem>
929              <para>Trigger the creation of a StartupItem.</para>
930
931              <itemizedlist>
932                <listitem>
933                  <para>Type: optional</para>
934                </listitem>
935
936                <listitem>
937                  <para>Default: no</para>
938                </listitem>
939
940                <listitem>
941                  <para>Values: yes no</para>
942                </listitem>
943
944                <listitem>
945                  <para>Example:</para>
946
947                  <programlisting>startupitem.create  yes</programlisting>
948                </listitem>
949              </itemizedlist>
950            </listitem>
951          </varlistentry>
952
953          <varlistentry>
954            <term>startupitem.name</term>
955
956            <listitem>
957              <para>Sets the name for the StartupItem.</para>
958
959              <itemizedlist>
960                <listitem>
961                  <para>Type: required</para>
962                </listitem>
963
964                <listitem>
965                  <para>Default: none</para>
966                </listitem>
967
968                <listitem>
969                  <para>Values: <replaceable>any_name</replaceable></para>
970                </listitem>
971
972                <listitem>
973                  <para>Example:</para>
974
975                  <programlisting>startupitem.name  OpenSSH</programlisting>
976                </listitem>
977              </itemizedlist>
978            </listitem>
979          </varlistentry>
980
981          <varlistentry>
982            <term>startupitem.logfile</term>
983
984            <listitem>
985              <para>Path to a logfile for logging events about the lifetime of
986              the StartupItem. Depending on the type of StartupItem, and the
987              manner in which it is started, standard output from the daemon
988              may also be directed to the logfile.</para>
989
990              <itemizedlist>
991                <listitem>
992                  <para>Type: optional</para>
993                </listitem>
994
995                <listitem>
996                  <para>Default: <filename>/dev/null</filename></para>
997                </listitem>
998
999                <listitem>
1000                  <para>Values: <replaceable>/file/path</replaceable></para>
1001                </listitem>
1002
1003                <listitem>
1004                  <para>Example:</para>
1005
1006                  <programlisting>startupitem.logfile  ${prefix}/var/log/mydaemon.log</programlisting>
1007                </listitem>
1008              </itemizedlist>
1009            </listitem>
1010          </varlistentry>
1011
1012          <varlistentry>
1013            <term>startupitem.logevents</term>
1014
1015            <listitem>
1016              <para>Control whether or not to log events to the log file. If
1017              logevents is set, events with timestamps are logged to the
1018              logfile.</para>
1019
1020              <itemizedlist>
1021                <listitem>
1022                  <para>Type: optional</para>
1023                </listitem>
1024
1025                <listitem>
1026                  <para>Default: no</para>
1027                </listitem>
1028
1029                <listitem>
1030                  <para>Values: yes no</para>
1031                </listitem>
1032
1033                <listitem>
1034                  <para>Example:</para>
1035
1036                  <programlisting>startupitem.logevents   yes</programlisting>
1037                </listitem>
1038              </itemizedlist>
1039            </listitem>
1040          </varlistentry>
1041        </variablelist>
1042      </refsection>
1043
1044      <refsection>
1045        <title>Executable StartupItems</title>
1046
1047        <para><quote>Executable</quote> StartupItems are slightly preferred
1048        over <quote>script</quote> StartupItems because
1049        <command>daemondo</command> launches the daemon directly, rather than
1050        indirectly via a startup script, and therefore it automatically knows
1051        how to monitor the daemon to restart it if it dies. The
1052        <quote>executable</quote> StartupItem specifies the path and name of
1053        the daemon to be run in the background.</para>
1054
1055        <note>
1056          <para>For a given port, the <quote>executable</quote> StartupItem
1057          keyword may not be used with any keywords in the
1058          <quote>script</quote> StartupItem category.</para>
1059        </note>
1060
1061        <variablelist>
1062          <varlistentry>
1063            <term>startupitem.executable</term>
1064
1065            <listitem>
1066              <para>Specifies the name of the daemon to be run in the
1067              background. It may have multiple arguments, but they must be
1068              appropriate for a call to exec; arbitrary shell code may not be
1069              used.</para>
1070
1071              <itemizedlist>
1072                <listitem>
1073                  <para>Type: optional</para>
1074                </listitem>
1075
1076                <listitem>
1077                  <para>Default: no</para>
1078                </listitem>
1079
1080                <listitem>
1081                  <para>Values:
1082                  <replaceable>/path/to/executable</replaceable></para>
1083                </listitem>
1084
1085                <listitem>
1086                  <para>Example:</para>
1087
1088                  <programlisting>startupitem.executable  "${prefix}/bin/nmicmpd"</programlisting>
1089                </listitem>
1090              </itemizedlist>
1091            </listitem>
1092          </varlistentry>
1093        </variablelist>
1094      </refsection>
1095
1096      <refsection>
1097        <title>Script StartupItems</title>
1098
1099        <para>StartupItems of type <quote>script</quote> use
1100        <command>daemondo</command> to launch a daemon via a startup script
1101        provided in port distributions containing daemons. When using this
1102        type of StartupItem, the <code>startupitem.pidfile</code> keyword may
1103        be used so <command>daemondo</command> can monitor the daemon's PID
1104        and restart it if it dies.</para>
1105
1106        <note>
1107          <para>For a given port, StartupItem keywords in category
1108          <quote>script</quote> may not be used with an
1109          <quote>executable</quote> StartupItem keyword.</para>
1110        </note>
1111
1112        <variablelist>
1113          <varlistentry>
1114            <term>startupitem.start</term>
1115
1116            <term>startupitem.stop</term>
1117
1118            <term>startupitem.restart</term>
1119
1120            <listitem>
1121              <para>Specify a shell script to start, stop, and restart the
1122              daemon. In the absence of a restart key, the daemon will be
1123              restarted by taking the stop action, followed by the start
1124              action.</para>
1125
1126              <itemizedlist>
1127                <listitem>
1128                  <para>Type: optional</para>
1129                </listitem>
1130
1131                <listitem>
1132                  <para>Default: none</para>
1133                </listitem>
1134
1135                <listitem>
1136                  <para>Values: <replaceable>shell_script</replaceable></para>
1137                </listitem>
1138
1139                <listitem>
1140                  <para>Examples:</para>
1141
1142                  <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server start
1143startupitem.stop ${prefix}/share/mysql/mysql.server stop
1144startupitem.restart ${prefix}/share/mysql/mysql.server restart</programlisting>
1145                </listitem>
1146              </itemizedlist>
1147            </listitem>
1148          </varlistentry>
1149
1150          <varlistentry>
1151            <term>startupitem.init</term>
1152
1153            <listitem>
1154              <para>Shell code that will be executed prior to any of the
1155              options <code>startupitem.start</code>,
1156              <code>startupitem.stop</code> and
1157              <code>startupitem.restart</code>.</para>
1158
1159              <itemizedlist>
1160                <listitem>
1161                  <para>Type: optional</para>
1162                </listitem>
1163
1164                <listitem>
1165                  <para>Default: no</para>
1166                </listitem>
1167
1168                <listitem>
1169                  <para>Values: <replaceable>shell_script</replaceable></para>
1170                </listitem>
1171
1172                <listitem>
1173                  <para>Example:</para>
1174
1175                  <programlisting>startupitem.init  "PID=/var/run/dhcpd.pid"</programlisting>
1176                </listitem>
1177              </itemizedlist>
1178            </listitem>
1179          </varlistentry>
1180
1181          <varlistentry>
1182            <term>startupitem.pidfile</term>
1183
1184            <listitem>
1185              <para>This keyword must be defined properly for
1186              <command>daemondo</command> to be able to monitor daemons
1187              launched via <quote>script</quote> StartupItems and restart them
1188              if they die. It specifies two things: a process id (PID) file
1189              handling method, and a pidfile name and path.</para>
1190
1191              <itemizedlist>
1192                <listitem>
1193                  <para>Type: optional</para>
1194                </listitem>
1195
1196                <listitem>
1197                  <para>Default: [none] |
1198                  [<filename>${prefix}/var/run/${name}.pid</filename>]</para>
1199                </listitem>
1200
1201                <listitem>
1202                  <para>Values [none auto manual clean]
1203                  [<replaceable>/path/to/pidfile</replaceable>]</para>
1204                </listitem>
1205
1206                <listitem>
1207                  <para>Example:</para>
1208
1209                  <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
1210                </listitem>
1211              </itemizedlist>
1212
1213              <para>Pidfile handling options:</para>
1214
1215              <itemizedlist>
1216                <listitem>
1217                  <para><option>none</option> - The daemon is not to use a
1218                  pidfile.</para>
1219                </listitem>
1220
1221                <listitem>
1222                  <para><option>auto</option> - The daemon generates its own
1223                  pidfile.</para>
1224                </listitem>
1225
1226                <listitem>
1227                  <para><option>manual</option> - The daemon never generates a
1228                  pidfile; the StartupItem must manage the pidfile on its
1229                  own.</para>
1230                </listitem>
1231
1232                <listitem>
1233                  <para><option>clean</option> - The daemon generates its own
1234                  but will not delete it; the StartupItem must delete
1235                  it.</para>
1236                </listitem>
1237              </itemizedlist>
1238            </listitem>
1239          </varlistentry>
1240        </variablelist>
1241      </refsection>
1242    </refsection>
1243  </refsection>
1244
1245  <refsection>
1246    <title>Installation Phase Keyword Reference</title>
1247
1248    <para>MacPorts keywords are used to specify required or optional items
1249    within a Portfile, or to override default options used by MacPorts base
1250    for individual ports. Keywords are to be used within the "global" and
1251    "variant" sections of Portfiles, and not within optional port phase
1252    declarations.</para>
1253
1254    <para>In other words, port phase keywords are not located within port
1255    phase declarations, but rather they <emphasis>refer</emphasis> to port
1256    phases and set options for those phases, and they take affect whether or
1257    not phase declarations have been explicitly defined in a Portfile.</para>
1258
1259    <refsection>
1260      <title>A Word about Keyword List Modifiers (-append / -delete)</title>
1261
1262      <para>It is often necessary to add to a list of keyword values
1263      previously set by a previously executed Portfile keyword or by MacPorts
1264      base. To keep from overwriting a previous keyword list, use a keyword
1265      list modifier. Keywords that support list modifiers are identified under
1266      appropriate reference sections below.</para>
1267
1268      <para>The three most common uses for keyword list modifiers are to
1269      preserve configure defaults, to preserve PortGroup dependencies, and to
1270      add or delete items for variants.</para>
1271
1272      <refsection>
1273        <title>Common Uses for Keyword List Modifiers</title>
1274
1275        <para>The three most common uses for keyword list modifiers are to
1276        preserve configure defaults, to preserve PortGroup dependencies, and
1277        to add or delete items for variants.</para>
1278
1279        <variablelist>
1280          <varlistentry>
1281            <term>Preserve configure Defaults</term>
1282
1283            <listitem>
1284              <para>MacPorts base sets the gcc compiler flags CFLAGS and
1285              LDFLAGS for all ports using <literal>configure.cflags</literal>
1286              and <literal>configure.ldflags</literal>, therefore to keep from
1287              overwriting the default compiler flags use
1288              <literal>configure.cflags-append</literal> and
1289              <literal>configure.ldflags-append</literal>.</para>
1290
1291              <itemizedlist>
1292                <listitem>
1293                  <para><code>configure.cflags-append</code></para>
1294                </listitem>
1295
1296                <listitem>
1297                  <para><code>configure.ldflags-append</code></para>
1298                </listitem>
1299              </itemizedlist>
1300            </listitem>
1301          </varlistentry>
1302
1303          <varlistentry>
1304            <term>Preserve PortGroup Dependencies</term>
1305
1306            <listitem>
1307              <para>Ports in a PortGroup have default library dependencies set
1308              by MacPorts base. Therefore, never use
1309              <literal>depends_lib</literal> in ports belonging to a PortGroup
1310              or it will overwrite the default library dependencies. Instead,
1311              use <literal>depends_lib-append</literal>.</para>
1312            </listitem>
1313          </varlistentry>
1314
1315          <varlistentry>
1316            <term>Add or Delete Items for Variants</term>
1317
1318            <listitem>
1319              <para>When a variant requires more or fewer dependencies,
1320              distfiles, or patchfiles, when the variant is invoked you want
1321              to add or remove items to the appropriate keyword values list
1322              set in the global section of the Portfile. Use the appropriate
1323              keywords, for example:</para>
1324
1325              <itemizedlist>
1326                <listitem>
1327                  <para><code>depends_lib-append</code> or
1328                  <code>depends_lib-delete</code></para>
1329                </listitem>
1330
1331                <listitem>
1332                  <para><code>distfiles-append</code> or
1333                  <code>distfile-delete</code></para>
1334                </listitem>
1335
1336                <listitem>
1337                  <para><code>patchfiles-append</code> or
1338                  <code>patchfiles-delete</code></para>
1339                </listitem>
1340              </itemizedlist>
1341            </listitem>
1342          </varlistentry>
1343        </variablelist>
1344      </refsection>
1345    </refsection>
1346
1347    <refsection>
1348      <title>A Word about Keyword Argument Modifiers (.pre_args /
1349      .post_args)</title>
1350
1351      <para>Keywords that support pre_args and post_args are used to assemble
1352      command strings together in a row, as described in the reference
1353      sections below. But it should be noted that all keyword argument
1354      modifiers implicitly support keyword list modifiers. For example, the
1355      keyword <literal>configure.pre_args</literal> also supports
1356      <literal>configure.pre_args-append</literal> and
1357      <literal>configure.pre_args-delete</literal>.</para>
1358    </refsection>
1359
1360    <refsection>
1361      <title>Fetch Phase Keywords</title>
1362
1363      <para>The list of keywords related to the fetch phase.</para>
1364
1365      <variablelist>
1366        <varlistentry>
1367          <term>master_sites</term>
1368
1369          <listitem>
1370            <para>A list of URLs from which a port's download file(s) may be
1371            retrieved. For multiple master_sites, they are searched in order
1372            until a file matching <varname>${distfile}</varname> is
1373            found.</para>
1374
1375            <itemizedlist>
1376              <listitem>
1377                <para>Default: ???</para>
1378              </listitem>
1379
1380              <listitem>
1381                <para>Examples:</para>
1382
1383                <programlisting>master_sites   http://www.somesite.org/files/ \
1384               http://www.somemirror.org/somesite_org/files/
1385
1386</programlisting>
1387
1388                <para>You may also use mirror site lists predefined by
1389                MacPorts. Here the sourceforge and gnu mirrors are
1390                used.</para>
1391
1392                <programlisting>master_sites   sourceforge gnu
1393
1394</programlisting>
1395
1396                <para>When using mirror master_sites, the subdirectory
1397                <varname>${name}</varname> is checked on every mirror. If the
1398                mirror subdirectory does not match ${name}, then you may
1399                specify it using after the mirror separated by a colon.</para>
1400
1401                <programlisting>master_sites   sourceforge:widget \
1402               gnu:widget
1403
1404</programlisting>
1405
1406                <para>For ports that must fetch multiple download files from
1407                different locations, you must label the files with tags and
1408                match the tags in a distfiles statement. The format is
1409                <literal>mirror:subdirectory:tag</literal>.</para>
1410
1411                <para>In the example below, file_one.tar.gz is fetched from
1412                sourceforge mirrors in subdirectory
1413                <varname>${name}</varname>; file tagtwo.tar.gz is fetched from
1414                the gnu mirrors in subdirectory sources.</para>
1415
1416                <programlisting>master_sites    sourceforge::tagone \
1417                gnu:sources:tagtwo
1418
1419distfiles       file_one.tar.gz:tagone \
1420                file_two.tar.gz:tagtwo</programlisting>
1421              </listitem>
1422            </itemizedlist>
1423          </listitem>
1424        </varlistentry>
1425
1426        <varlistentry>
1427          <term>patch_sites</term>
1428
1429          <listitem>
1430            <para>A list of sites from which a port's patchfiles may be
1431            downloaded, where applicable.</para>
1432
1433            <itemizedlist>
1434              <listitem>
1435                <para>Default: <varname>${master_sites}</varname></para>
1436              </listitem>
1437
1438              <listitem>
1439                <para>Example:</para>
1440
1441                <programlisting>patch_sites    ftp://ftp.patchcityrepo.com/pub/magic/patches</programlisting>
1442              </listitem>
1443            </itemizedlist>
1444          </listitem>
1445        </varlistentry>
1446
1447        <varlistentry>
1448          <term>distname</term>
1449
1450          <listitem>
1451            <para>The name of the distribution filename, not including the
1452            extract suffix.</para>
1453
1454            <itemizedlist>
1455              <listitem>
1456                <para>Default: <varname>${name}-${version}</varname></para>
1457              </listitem>
1458
1459              <listitem>
1460                <para>Example:</para>
1461
1462                <programlisting>distname     ${name}</programlisting>
1463              </listitem>
1464            </itemizedlist>
1465          </listitem>
1466        </varlistentry>
1467
1468        <varlistentry>
1469          <term>distfiles</term>
1470
1471          <listitem>
1472            <para>The full distribution filename, including the extract
1473            suffix. Used to specify non-default distribution filenames; this
1474            keyword must be specified (and tags used) when a port has multiple
1475            download files (see master_sites).</para>
1476
1477            <itemizedlist>
1478              <listitem>
1479                <para>Default:
1480                <varname>${distname}${extract.suffix}</varname></para>
1481              </listitem>
1482
1483              <listitem>
1484                <para>Example:</para>
1485
1486                <programlisting>distfiles    ${name}-dev_src.tgz
1487
1488
1489distfiles       file_one.tar.gz:tagone \
1490                file_two.tar.gz:tagtwo</programlisting>
1491              </listitem>
1492            </itemizedlist>
1493          </listitem>
1494        </varlistentry>
1495
1496        <varlistentry>
1497          <term>extract.suffix</term>
1498
1499          <listitem>
1500            <para>This keyword is used to specify the extract suffix
1501            type.</para>
1502
1503            <itemizedlist>
1504              <listitem>
1505                <para>Default: <filename>.tar.gz</filename></para>
1506              </listitem>
1507
1508              <listitem>
1509                <para>Example:</para>
1510
1511                <programlisting>extract.suffix   .tgz</programlisting>
1512              </listitem>
1513            </itemizedlist>
1514          </listitem>
1515        </varlistentry>
1516
1517        <varlistentry>
1518          <term>use_bzip2</term>
1519
1520          <listitem>
1521            <para>This keyword is for downloads that are tarred and bzipped.
1522            When invoked, it automatically sets:</para>
1523
1524            <literallayout>extract.suffix = .tar.bz
1525extract.cmd = bzip
1526
1527</literallayout>
1528
1529            <itemizedlist>
1530              <listitem>
1531                <para>Default: yes</para>
1532              </listitem>
1533
1534              <listitem>
1535                <para>Example:</para>
1536
1537                <programlisting>use_bzip2     yes</programlisting>
1538              </listitem>
1539            </itemizedlist>
1540          </listitem>
1541        </varlistentry>
1542
1543        <varlistentry>
1544          <term>use_zip</term>
1545
1546          <listitem>
1547            <para>This keyword is for downloads are zipped. When invoked, it
1548            automatically sets:</para>
1549
1550            <literallayout>extract.suffix = .zip
1551extract.cmd = unzip
1552extract.pre_args = -q
1553extract.post_args = "-d ${portpath}/${workdir}"
1554
1555</literallayout>
1556
1557            <itemizedlist>
1558              <listitem>
1559                <para>Default: <option>yes</option></para>
1560              </listitem>
1561
1562              <listitem>
1563                <para>Example:</para>
1564
1565                <programlisting>use_zip       yes</programlisting>
1566              </listitem>
1567            </itemizedlist>
1568          </listitem>
1569        </varlistentry>
1570      </variablelist>
1571
1572      <refsection>
1573        <title>Fetch from CVS</title>
1574
1575        <para><ulink url="http://www.nongnu.org/cvs/">CVS</ulink> may be used
1576        as an alternative method of fetching distribution files using the
1577        keywords in this section. However, fetching via CVS may cause
1578        non-reproducible builds, so it is strongly discouraged.</para>
1579
1580        <variablelist>
1581          <varlistentry>
1582            <term>cvs.root</term>
1583
1584            <listitem>
1585              <para>Specify the url from which to fetch files.</para>
1586
1587              <itemizedlist>
1588                <listitem>
1589                  <para>Default: none</para>
1590                </listitem>
1591
1592                <listitem>
1593                  <para>Example:</para>
1594
1595                  <programlisting>cvs.root :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs</programlisting>
1596                </listitem>
1597              </itemizedlist>
1598            </listitem>
1599          </varlistentry>
1600
1601          <varlistentry>
1602            <term>cvs.tag</term>
1603
1604            <listitem>
1605              <para>Optional for fetching with CVS, this specifies the code
1606              revision to checkout.</para>
1607
1608              <itemizedlist>
1609                <listitem>
1610                  <para>Default: none</para>
1611                </listitem>
1612
1613                <listitem>
1614                  <para>Example:</para>
1615
1616                  <programlisting>cvs.tag  HEAD</programlisting>
1617                </listitem>
1618              </itemizedlist>
1619            </listitem>
1620          </varlistentry>
1621
1622          <varlistentry>
1623            <term>cvs.date</term>
1624
1625            <listitem>
1626              <para>A date that identifies the CVS code set to
1627              checkout.</para>
1628
1629              <itemizedlist>
1630                <listitem>
1631                  <para>Default: none</para>
1632                </listitem>
1633
1634                <listitem>
1635                  <para>Example:</para>
1636
1637                  <programlisting>cvs.date "12-April-2007"</programlisting>
1638                </listitem>
1639              </itemizedlist>
1640            </listitem>
1641          </varlistentry>
1642
1643          <varlistentry>
1644            <term>cvs.module</term>
1645
1646            <listitem>
1647              <para>A CVS module from which to check out the code.</para>
1648
1649              <itemizedlist>
1650                <listitem>
1651                  <para>Default: none</para>
1652                </listitem>
1653
1654                <listitem>
1655                  <para>Example:</para>
1656
1657                  <programlisting>cvs.module  Sources</programlisting>
1658                </listitem>
1659              </itemizedlist>
1660            </listitem>
1661          </varlistentry>
1662        </variablelist>
1663      </refsection>
1664
1665      <refsection>
1666        <title>Fetch from Subversion</title>
1667
1668        <para><ulink url="http://subversion.tigris.org/">Subversion</ulink>
1669        may be used as an alternative method of fetching distribution files
1670        using the keywords in this section. However, fetching via Subversion
1671        may cause non-reproducible builds, so it is strongly
1672        discouraged.</para>
1673
1674        <variablelist>
1675          <varlistentry>
1676            <term>svn.url</term>
1677
1678            <listitem>
1679              <para>This specifies the url from which to fetch files.</para>
1680
1681              <itemizedlist>
1682                <listitem>
1683                  <para>Default: none</para>
1684                </listitem>
1685
1686                <listitem>
1687                  <para>Examples:</para>
1688
1689                  <programlisting>svn.url http://www.domain.com/svn-repo/mydirectory
1690svn.url svn://www.domain.com/svn-repo/mydirectory
1691</programlisting>
1692                </listitem>
1693              </itemizedlist>
1694            </listitem>
1695          </varlistentry>
1696
1697          <varlistentry>
1698            <term>svn.tag</term>
1699
1700            <listitem>
1701              <para>Optional tag for fetching with Subversion, this specifies
1702              the code revision to checkout; it corresponds to the -r option
1703              in the svn cli. You must use backslashes to escape characters
1704              that are meaningful to the Tcl interpreter, such as braces and
1705              double quotes.</para>
1706
1707              <itemizedlist>
1708                <listitem>
1709                  <para>Default: none</para>
1710                </listitem>
1711
1712                <listitem>
1713                  <para>Examples:</para>
1714
1715                  <programlisting>svn.tag 37192
1716svn.tag \{\"2006-02-17 15:30 +0230\"\}</programlisting>
1717                </listitem>
1718              </itemizedlist>
1719            </listitem>
1720          </varlistentry>
1721        </variablelist>
1722      </refsection>
1723    </refsection>
1724
1725    <refsection>
1726      <title>Checksum Phase Keywords</title>
1727
1728      <para>The list of keywords related to the checksum phase.</para>
1729
1730      <variablelist>
1731        <varlistentry>
1732          <term>checksums</term>
1733
1734          <listitem>
1735            <para>Checksum(s) of the distribution files. For ports with
1736            multiple distribution files, filenames must be included to
1737            associate files with their checksums.</para>
1738
1739            <itemizedlist>
1740              <listitem>
1741                <para>Default: ???</para>
1742              </listitem>
1743
1744              <listitem>
1745                <para>Examples:</para>
1746
1747                <programlisting>checksums     md5 65b89365a65dcad71d4402b48</programlisting>
1748
1749                <programlisting>checksums     ${distname}${extract.suffix} md5 65b89365a65dcad71d4402b44 \
1750              hobbit.tar.gz md5 65b89365a65dcad71d4402b48</programlisting>
1751              </listitem>
1752            </itemizedlist>
1753          </listitem>
1754        </varlistentry>
1755      </variablelist>
1756    </refsection>
1757
1758    <refsection>
1759      <title>Extract Phase Keywords</title>
1760
1761      <para>The list of keywords related to the extract phase.</para>
1762
1763      <variablelist>
1764        <varlistentry>
1765          <term>extract.only</term>
1766
1767          <term>extract.only-append</term>
1768
1769          <term>extract.only-delete</term>
1770
1771          <listitem>
1772            <para>List of files to extract into
1773            <varname>${worksrcpath}</varname>; the default is
1774            <varname>${distfiles}</varname>. Only use if default extract
1775            behavior is not correct for your port.</para>
1776
1777            <itemizedlist>
1778              <listitem>
1779                <para>Default: none</para>
1780              </listitem>
1781
1782              <listitem>
1783                <para>Example:</para>
1784
1785                <programlisting>extract.only     foo.tar.gz
1786
1787</programlisting>
1788              </listitem>
1789            </itemizedlist>
1790          </listitem>
1791
1792          <listitem>
1793            <para>List modifier examples:</para>
1794
1795            <programlisting>extract.only-append  bar.tar.gz
1796extract.only-delete  foo.tar.gz</programlisting>
1797          </listitem>
1798        </varlistentry>
1799
1800        <varlistentry>
1801          <term>extract.cmd</term>
1802
1803          <listitem>
1804            <para>Command to perform extraction.</para>
1805
1806            <itemizedlist>
1807              <listitem>
1808                <para>Default: gzip</para>
1809              </listitem>
1810
1811              <listitem>
1812                <para>Example:</para>
1813
1814                <programlisting>extract.cmd     gunzip</programlisting>
1815              </listitem>
1816            </itemizedlist>
1817          </listitem>
1818        </varlistentry>
1819
1820        <varlistentry>
1821          <term>extract.args</term>
1822
1823          <term>extract.pre_args</term>
1824
1825          <term>extract.post_args</term>
1826
1827          <listitem>
1828            <para>Main arguments to extract.cmd; additional arguments passed
1829            before and after the main arguments.</para>
1830
1831            <itemizedlist>
1832              <listitem>
1833                <para>Default: ${distpath}/${distfile}</para>
1834              </listitem>
1835
1836              <listitem>
1837                <para>Example:</para>
1838
1839                <programlisting>extract.args      ${distpath}/${distfile}
1840
1841</programlisting>
1842              </listitem>
1843            </itemizedlist>
1844          </listitem>
1845
1846          <listitem>
1847            <para>The following argument modifiers are available:</para>
1848
1849            <itemizedlist>
1850              <listitem>
1851                <para>extract.pre_args default: "-dc"</para>
1852              </listitem>
1853
1854              <listitem>
1855                <para>extract.post_args default: " | tar -xf"</para>
1856              </listitem>
1857
1858              <listitem>
1859                <para>Examples:</para>
1860
1861                <programlisting>extract.pre_args     xf
1862extract.post_args    "| gnutar –x"</programlisting>
1863              </listitem>
1864            </itemizedlist>
1865          </listitem>
1866        </varlistentry>
1867      </variablelist>
1868    </refsection>
1869
1870    <refsection>
1871      <title>Patch Phase Keywords</title>
1872
1873      <para>The list of keywords related to the patch phase.</para>
1874
1875      <variablelist>
1876        <varlistentry>
1877          <term>patch.dir</term>
1878
1879          <listitem>
1880            <para>Specify the base path for patch files.</para>
1881
1882            <itemizedlist>
1883              <listitem>
1884                <para>Default: <varname>${worksrcpath}</varname></para>
1885              </listitem>
1886
1887              <listitem>
1888                <para>Example:</para>
1889
1890                <programlisting>patch.dir      ${worksrcpath}/util</programlisting>
1891              </listitem>
1892            </itemizedlist>
1893          </listitem>
1894        </varlistentry>
1895
1896        <varlistentry>
1897          <term>patch.cmd</term>
1898
1899          <listitem>
1900            <para>Specify the command to be used for patching files.</para>
1901
1902            <itemizedlist>
1903              <listitem>
1904                <para>Default: <command>patch</command></para>
1905              </listitem>
1906
1907              <listitem>
1908                <para>Example:</para>
1909
1910                <programlisting>patch.cmd      cat</programlisting>
1911              </listitem>
1912            </itemizedlist>
1913          </listitem>
1914        </varlistentry>
1915
1916        <varlistentry>
1917          <term>patchfiles</term>
1918
1919          <term>patchfiles-append</term>
1920
1921          <term>patchfiles-delete</term>
1922
1923          <listitem>
1924            <para>Specify patch files to be applied for a port; list modifiers
1925            specify patchfiles to be added or removed from a previous
1926            patchfile declaration.</para>
1927
1928            <itemizedlist>
1929              <listitem>
1930                <para>Default: none</para>
1931              </listitem>
1932
1933              <listitem>
1934                <para>Example:</para>
1935
1936                <programlisting>patchfiles     patch-Makefile.in \
1937               patch-source.c
1938
1939</programlisting>
1940              </listitem>
1941            </itemizedlist>
1942          </listitem>
1943
1944          <listitem>
1945            <para>List modifier examples:</para>
1946
1947            <programlisting>patchfiles-append   patch-configure
1948patchfiles-delete   patch-src-Makefile.in
1949</programlisting>
1950          </listitem>
1951        </varlistentry>
1952
1953        <varlistentry>
1954          <term>patch.args</term>
1955
1956          <term>patch.pre_args</term>
1957
1958          <term>patch.post_args</term>
1959
1960          <listitem>
1961            <para>Main arguments to patch.cmd; optional argument modifiers
1962            pass arguments before and after the main arguments.</para>
1963
1964            <itemizedlist>
1965              <listitem>
1966                <para>Default: none</para>
1967              </listitem>
1968
1969              <listitem>
1970                <para>Example:</para>
1971
1972                <programlisting>patch.args   ???
1973
1974</programlisting>
1975              </listitem>
1976            </itemizedlist>
1977          </listitem>
1978
1979          <listitem>
1980            <para>The following argument modifiers are available:</para>
1981
1982            <itemizedlist>
1983              <listitem>
1984                <para>patch.pre_args default: -p0</para>
1985              </listitem>
1986
1987              <listitem>
1988                <para>patch.post_args default: none</para>
1989              </listitem>
1990
1991              <listitem>
1992                <para>Examples:</para>
1993
1994                <programlisting>patch.pre_args     -p1
1995patch.post_args    ???</programlisting>
1996              </listitem>
1997            </itemizedlist>
1998          </listitem>
1999        </varlistentry>
2000      </variablelist>
2001    </refsection>
2002
2003    <refsection>
2004      <title>Configure Phase Keywords</title>
2005
2006      <para>The list of keywords related to the configure phase.</para>
2007
2008      <para>MacPorts base sets some important default configure options, so
2009      should use the -append version of most configure keywords so you don't
2010      overwrite them. For example, MacPorts base sets default
2011      <literal>configure.cflags</literal> so you should always use
2012      <literal>configure.cflags-append</literal> to set additional CFLAGS in
2013      Portfiles.</para>
2014
2015      <variablelist>
2016        <varlistentry>
2017          <term>configure.env</term>
2018
2019          <term>configure.env-append</term>
2020
2021          <term>configure.env-delete</term>
2022
2023          <listitem>
2024            <para>Set environment variables for configure; list modifiers add
2025            and delete items from a previous Portfile configure.env keyword,
2026            or a default set by MacPorts base.</para>
2027
2028            <itemizedlist>
2029              <listitem>
2030                <para>Default: <literal>CFLAGS=-I${prefix}/include
2031                LDFLAGS=-L${prefix}/lib</literal></para>
2032              </listitem>
2033
2034              <listitem>
2035                <para>Example:</para>
2036
2037                <programlisting>configure.env   CFLAGS=-I${prefix}/include/qt3
2038</programlisting>
2039              </listitem>
2040            </itemizedlist>
2041          </listitem>
2042
2043          <listitem>
2044            <para>List modifier examples:</para>
2045
2046            <programlisting>configure.env-append   CFLAGS=-${prefix}/include/qt3
2047configure.env-delete   LDFLAGS=-L${prefix}/lib</programlisting>
2048          </listitem>
2049        </varlistentry>
2050
2051        <varlistentry>
2052          <term>configure.cflags</term>
2053
2054          <term>configure.cflags-append</term>
2055
2056          <term>configure.cflags-delete</term>
2057
2058          <listitem>
2059            <para>Set CFLAGS compiler flags; list modifiers add or delete
2060            items from a previous Portfile configure.cflags keyword or the
2061            default set by MacPorts base.</para>
2062
2063            <itemizedlist>
2064              <listitem>
2065                <para>Default:
2066                <literal>CFLAGS=-I${prefix}/include</literal></para>
2067              </listitem>
2068
2069              <listitem>
2070                <para>Example:</para>
2071
2072                <programlisting>configure.cflags    CFLAGS=-I${worksrcpath}/include
2073
2074</programlisting>
2075              </listitem>
2076            </itemizedlist>
2077          </listitem>
2078
2079          <listitem>
2080            <para>List modifier examples:</para>
2081
2082            <programlisting>configure.cflags-append   "-I/usr/X11R6/include -I${worksrcpath}"
2083configure.cflags-delete   -I${prefix}/include/db44</programlisting>
2084          </listitem>
2085        </varlistentry>
2086
2087        <varlistentry>
2088          <term>configure.ldflags</term>
2089
2090          <term>configure.ldflags-append</term>
2091
2092          <term>configure.ldflags-delete</term>
2093
2094          <listitem>
2095            <para>Set LDFLAGS compiler flags; list modifiers add or delete
2096            items from a previous Portfile configure.ldflags keyword or the
2097            default set by MacPorts base.</para>
2098
2099            <itemizedlist>
2100              <listitem>
2101                <para>Default:
2102                <literal>LDFLAGS=-L${prefix}/lib</literal></para>
2103              </listitem>
2104
2105              <listitem>
2106                <para>Example:</para>
2107
2108                <programlisting>configure.ldflags    CFLAGS=-I${worksrcpath}/include
2109
2110</programlisting>
2111              </listitem>
2112            </itemizedlist>
2113          </listitem>
2114
2115          <listitem>
2116            <para>List modifier examples:</para>
2117
2118            <programlisting>configure.ldflags-append   "-L/usr/X11R6/lib -L${worksrcpath}/lib"
2119configure.ldflags-delete   -L${prefix}/lib/db44</programlisting>
2120          </listitem>
2121        </varlistentry>
2122
2123        <varlistentry>
2124          <term>configure.cppflags</term>
2125
2126          <term>configure.cppflags-append</term>
2127
2128          <term>configure.cppflags-delete</term>
2129
2130          <listitem>
2131            <para>Set CPPFLAGS to be passed to the C processor; list modifiers
2132            add or delete items from a previous Portfile configure.cppflags
2133            keyword or the default set by MacPorts base.</para>
2134
2135            <itemizedlist>
2136              <listitem>
2137                <para>Default:
2138                <literal>CPPFLAGS=-I${prefix}/include</literal></para>
2139              </listitem>
2140
2141              <listitem>
2142                <para>Example:</para>
2143
2144                <programlisting>configure.cppflags    CPPFLAGS=-I${worksrcpath}/include
2145
2146</programlisting>
2147              </listitem>
2148            </itemizedlist>
2149          </listitem>
2150
2151          <listitem>
2152            <para>List modifier examples:</para>
2153
2154            <programlisting>configure.cppflags-append   "-I/usr/X11R6/lib -I${worksrcpath}/lib"
2155configure.cppflags-delete   -I${prefix}/lib/db44</programlisting>
2156          </listitem>
2157        </varlistentry>
2158
2159        <varlistentry>
2160          <term>configure.args</term>
2161
2162          <term>configure.pre_args</term>
2163
2164          <term>configure.post_args</term>
2165
2166          <listitem>
2167            <para>Main arguments to configure.cmd; optional argument modifiers
2168            pass arguments before and after the main arguments.</para>
2169
2170            <itemizedlist>
2171              <listitem>
2172                <para>Default: none</para>
2173              </listitem>
2174
2175              <listitem>
2176                <para>Example:</para>
2177
2178                <programlisting>configure.args    --bindir=${prefix}/bin
2179
2180</programlisting>
2181              </listitem>
2182            </itemizedlist>
2183          </listitem>
2184
2185          <listitem>
2186            <para>The following argument modifiers are available:</para>
2187
2188            <itemizedlist>
2189              <listitem>
2190                <para>configure.pre_args default: --prefix=${prefix}</para>
2191              </listitem>
2192
2193              <listitem>
2194                <para>configure.post_args default: none</para>
2195              </listitem>
2196
2197              <listitem>
2198                <para>Examples:</para>
2199
2200                <programlisting>configure.pre_args   --prefix=${prefix}/share/bro
2201configure.post_args  OPT="-D__DARWIN_UNIX03"</programlisting>
2202              </listitem>
2203            </itemizedlist>
2204          </listitem>
2205        </varlistentry>
2206      </variablelist>
2207
2208      <refsection>
2209        <title>Configure Universal</title>
2210
2211        <para>Universal keywords are used to make a port compile on the OS X
2212        platform to run on either PPC or Intel.</para>
2213
2214        <note>
2215          <para>There is a default universal variant made available to all
2216          ports by MacPorts base, so redefining universal keywords should only
2217          be done to make a given port compile if the default options fail to
2218          do so.</para>
2219        </note>
2220
2221        <variablelist>
2222          <varlistentry>
2223            <term>configure.universal_args</term>
2224
2225            <listitem>
2226              <para>Arguments used in the configure script to build the port
2227              universal.</para>
2228
2229              <itemizedlist>
2230                <listitem>
2231                  <para>Default: --disable-dependency-tracking</para>
2232                </listitem>
2233
2234                <listitem>
2235                  <para>Example:</para>
2236
2237                  <programlisting></programlisting>
2238                </listitem>
2239              </itemizedlist>
2240            </listitem>
2241          </varlistentry>
2242
2243          <varlistentry>
2244            <term>configure.universal_cflags</term>
2245
2246            <listitem>
2247              <para>Arguments appended to the configure script to build the
2248              port universal.</para>
2249
2250              <itemizedlist>
2251                <listitem>
2252                  <para>Default: -sysroot /Developer/SDKs/MacOSX10.4u.sdk
2253                  -arch i386 -arch ppc</para>
2254                </listitem>
2255
2256                <listitem>
2257                  <para>Example:</para>
2258
2259                  <programlisting></programlisting>
2260                </listitem>
2261              </itemizedlist>
2262            </listitem>
2263          </varlistentry>
2264
2265          <varlistentry>
2266            <term>configure.universal_cppflags</term>
2267
2268            <listitem>
2269              <para>Additional flags to put in the CPPFLAGS environment
2270              variable when invoking the configure script.</para>
2271
2272              <itemizedlist>
2273                <listitem>
2274                  <para>Default: ???</para>
2275                </listitem>
2276
2277                <listitem>
2278                  <para>Example:</para>
2279
2280                  <programlisting></programlisting>
2281                </listitem>
2282              </itemizedlist>
2283            </listitem>
2284          </varlistentry>
2285
2286          <varlistentry>
2287            <term>configure.universal_cxxflags</term>
2288
2289            <listitem>
2290              <para>Additional flags to put in the CXXFLAGS environment
2291              variable when invoking the configure script.</para>
2292
2293              <itemizedlist>
2294                <listitem>
2295                  <para>Default: -isysroot /Developer/SDKs/MacOSX10.4u.sdk
2296                  -arch i386 -arch ppc</para>
2297                </listitem>
2298
2299                <listitem>
2300                  <para>Example:</para>
2301
2302                  <programlisting></programlisting>
2303                </listitem>
2304              </itemizedlist>
2305            </listitem>
2306          </varlistentry>
2307
2308          <varlistentry>
2309            <term>configure.universal_ldflags</term>
2310
2311            <listitem>
2312              <para>Additional flags to put in the LDFLAGS environment
2313              variable when invoking the configure script.</para>
2314
2315              <itemizedlist>
2316                <listitem>
2317                  <para>Default: -arch i386 -arch ppc</para>
2318                </listitem>
2319
2320                <listitem>
2321                  <para>Example:</para>
2322
2323                  <programlisting></programlisting>
2324                </listitem>
2325              </itemizedlist>
2326            </listitem>
2327          </varlistentry>
2328        </variablelist>
2329      </refsection>
2330
2331      <refsection>
2332        <title>Automake and Autoconf</title>
2333
2334        <para>The list of configure keywords available for ports that need
2335        automake and/or autoconf.</para>
2336
2337        <variablelist>
2338          <varlistentry>
2339            <term>use_automake</term>
2340
2341            <listitem>
2342              <para>Whether or not to use automake; the default is
2343              "no".</para>
2344
2345              <programlisting>use_automake      yes</programlisting>
2346            </listitem>
2347          </varlistentry>
2348
2349          <varlistentry>
2350            <term>automake.env</term>
2351
2352            <listitem>
2353              <para>Environment variables to pass to automake.</para>
2354
2355              <programlisting>automake.env      CFLAGS=-I${prefix}/include</programlisting>
2356            </listitem>
2357          </varlistentry>
2358
2359          <varlistentry>
2360            <term>automake.args</term>
2361
2362            <listitem>
2363              <para>Arguments to pass to automake.</para>
2364
2365              <programlisting>automake.args     --foreign</programlisting>
2366            </listitem>
2367          </varlistentry>
2368
2369          <varlistentry>
2370            <term>automake.dir</term>
2371
2372            <listitem>
2373              <para>Directory in which to run
2374              <varname>${automake.cmd}</varname>; the default is
2375              <varname>${worksrcpath}</varname>.</para>
2376
2377              <programlisting>automake.dir      ./src</programlisting>
2378            </listitem>
2379          </varlistentry>
2380
2381          <varlistentry>
2382            <term>use_autoconf</term>
2383
2384            <listitem>
2385              <para>Whether or not to use autoconf; the default is
2386              "no".</para>
2387
2388              <programlisting>use_autoconf      yes</programlisting>
2389            </listitem>
2390          </varlistentry>
2391
2392          <varlistentry>
2393            <term>autoconf.env</term>
2394
2395            <listitem>
2396              <para>Environmental variables to pass to autoconf.</para>
2397
2398              <programlisting>autoconf.env      CFLAGS=-I${prefix}/include/gtk12</programlisting>
2399            </listitem>
2400          </varlistentry>
2401
2402          <varlistentry>
2403            <term>autoconf.args</term>
2404
2405            <listitem>
2406              <para>Arguments to pass to autoconf.</para>
2407
2408              <programlisting>autoconf.args     -l src/aclocaldir</programlisting>
2409            </listitem>
2410          </varlistentry>
2411
2412          <varlistentry>
2413            <term>autoconf.dir</term>
2414
2415            <listitem>
2416              <para>Directory in which to run
2417              <varname>${autoconf.cmd}</varname>; the default is
2418              <varname>${worksrcpath}</varname>.</para>
2419
2420              <programlisting>autoconf.dir      src</programlisting>
2421            </listitem>
2422          </varlistentry>
2423        </variablelist>
2424      </refsection>
2425    </refsection>
2426
2427    <refsection>
2428      <title>Build Phase Keywords</title>
2429
2430      <para>The list of keywords related to the build phase.</para>
2431
2432      <variablelist>
2433        <varlistentry>
2434          <term>build.cmd</term>
2435
2436          <listitem>
2437            <para>Make command to run in <varname>${worksrcdir}</varname>; the
2438            default is "make".</para>
2439
2440            <programlisting>build.cmd      pbxbuild</programlisting>
2441          </listitem>
2442        </varlistentry>
2443
2444        <varlistentry>
2445          <term>build.type</term>
2446
2447          <listitem>
2448            <para>Defines which "make" is required: "gnu" or "bsd". Sets
2449            build.cmd to either "gnumake" or "bsdmake" accordingly.</para>
2450
2451            <programlisting>build.type     gnu</programlisting>
2452          </listitem>
2453        </varlistentry>
2454
2455        <varlistentry>
2456          <term>build.args</term>
2457
2458          <term>build.pre_args</term>
2459
2460          <term>build.post_args</term>
2461
2462          <listitem>
2463            <para>Main arguments to build.cmd; optional argument modifiers
2464            pass arguments before and after the main arguments.</para>
2465
2466            <itemizedlist>
2467              <listitem>
2468                <para>Default: none</para>
2469              </listitem>
2470
2471              <listitem>
2472                <para>Example:</para>
2473
2474                <programlisting>build.args    -DNOWARN
2475
2476</programlisting>
2477              </listitem>
2478            </itemizedlist>
2479          </listitem>
2480
2481          <listitem>
2482            <para>The following argument modifiers are available:</para>
2483
2484            <itemizedlist>
2485              <listitem>
2486                <para>build.pre_args default:
2487                <varname>${build.target.current}</varname></para>
2488              </listitem>
2489
2490              <listitem>
2491                <para>build.post_args default: none</para>
2492              </listitem>
2493
2494              <listitem>
2495                <para>Examples:</para>
2496
2497                <programlisting>build.pre_args  -project AudioSlicer.xcode
2498build.post_args CFLAGS_SYS="-DUSE_FREETYPE -DPREFER_FREETYPE"</programlisting>
2499              </listitem>
2500            </itemizedlist>
2501          </listitem>
2502        </varlistentry>
2503
2504        <varlistentry>
2505          <term>build.target</term>
2506
2507          <term>build.target-append</term>
2508
2509          <term>build.target-delete</term>
2510
2511          <listitem>
2512            <para>Build target to pass to ${build.cmd}; list modifiers add or
2513            delete items from a previous Portfile build.target keyword or the
2514            default set by MacPorts base.</para>
2515
2516            <itemizedlist>
2517              <listitem>
2518                <para>Default: all</para>
2519              </listitem>
2520
2521              <listitem>
2522                <para>Example:</para>
2523
2524                <programlisting>build.target    all-src
2525
2526</programlisting>
2527              </listitem>
2528            </itemizedlist>
2529          </listitem>
2530
2531          <listitem>
2532            <para>List modifier examples:</para>
2533
2534            <programlisting>build.target-append   doc extra
2535build.target-delete   compat</programlisting>
2536          </listitem>
2537        </varlistentry>
2538      </variablelist>
2539    </refsection>
2540
2541    <refsection>
2542      <title>Destroot Phase Keywords</title>
2543
2544      <para>The list of keywords related to the destroot phase.</para>
2545
2546      <variablelist>
2547        <varlistentry>
2548          <term>destroot.cmd</term>
2549
2550          <listitem>
2551            <para>Install command to run relative to
2552            <varname>${worksrcdir}</varname>; default is
2553            <varname>${build.cmd}</varname>.</para>
2554
2555            <programlisting>destroot.cmd         pbxbuild</programlisting>
2556          </listitem>
2557        </varlistentry>
2558
2559        <varlistentry>
2560          <term>destroot.type</term>
2561
2562          <listitem>
2563            <para>Defines which "make" is required: either "gnu" or "bsd".
2564            Sets install.cmd to either "gnumake" or "bsdmake"
2565            accordingly.</para>
2566
2567            <programlisting>destroot.type        gnu</programlisting>
2568          </listitem>
2569        </varlistentry>
2570
2571        <varlistentry>
2572          <term>destroot.args</term>
2573
2574          <term>destroot.pre_args</term>
2575
2576          <term>destroot.post_args</term>
2577
2578          <listitem>
2579            <para>Main arguments to ${destroot.cmd}; optional argument
2580            modifiers pass arguments before and after the main
2581            arguments.</para>
2582
2583            <itemizedlist>
2584              <listitem>
2585                <para>Default: none</para>
2586              </listitem>
2587
2588              <listitem>
2589                <para>Example:</para>
2590
2591                <programlisting>destroot.args    BINDIR=${prefix}/bin
2592
2593</programlisting>
2594              </listitem>
2595            </itemizedlist>
2596          </listitem>
2597
2598          <listitem>
2599            <para>The following argument modifiers are available:</para>
2600
2601            <itemizedlist>
2602              <listitem>
2603                <para>destroot.pre_args default:
2604                <varname>${destroot.target}</varname></para>
2605              </listitem>
2606
2607              <listitem>
2608                <para>destroot.post_args default: none</para>
2609              </listitem>
2610
2611              <listitem>
2612                <para>Examples:</para>
2613
2614                <programlisting>destroot.pre_args  -project AudioSlicer.xcode
2615destroot.post_args INSTDIR=${destroot}${prefix}</programlisting>
2616              </listitem>
2617            </itemizedlist>
2618          </listitem>
2619        </varlistentry>
2620
2621        <varlistentry>
2622          <term>destroot.target</term>
2623
2624          <term>destroot.target-append</term>
2625
2626          <term>destroot.target-delete</term>
2627
2628          <listitem>
2629            <para>Install target to pass to ${destroot.cmd}; list modifiers
2630            add or delete items from a previous Portfile destroot.target
2631            keyword or the default set by MacPorts base.</para>
2632
2633            <itemizedlist>
2634              <listitem>
2635                <para>Default: <literal>install</literal></para>
2636              </listitem>
2637
2638              <listitem>
2639                <para>Example:</para>
2640
2641                <programlisting>destroot.target    install install-config install-commandmode
2642
2643</programlisting>
2644              </listitem>
2645            </itemizedlist>
2646          </listitem>
2647
2648          <listitem>
2649            <para>List modifier examples:</para>
2650
2651            <programlisting>destroot.target-append   install-plugins
2652destroot.target-delete   install-commandmode</programlisting>
2653          </listitem>
2654        </varlistentry>
2655
2656        <varlistentry>
2657          <term>destroot.destdir</term>
2658
2659          <listitem>
2660            <para>Arguments passed to ${destroot.cmd} to install correctly
2661            into the destroot.</para>
2662
2663            <programlisting>destroot.destdir     prefix=${destroot}${prefix}</programlisting>
2664
2665            <note>
2666              <para>If an application's Makefile properly supports the DESTDIR
2667              variable, MacPorts will automatically destroot the port
2668              properly. A port must destroot properly or the port will not
2669              install correctly, upgrade, or uninstall. If not, you may need
2670              to set this variable, or even patch the application's
2671              Makefile.</para>
2672            </note>
2673          </listitem>
2674        </varlistentry>
2675
2676        <varlistentry>
2677          <term>destroot.keepdirs</term>
2678
2679          <listitem>
2680            <para>A list of directories that should not be removed if empty
2681            upon destroot completion.</para>
2682
2683            <programlisting>destroot.keepdirs \
2684                ${destroot}${prefix}/var/run \
2685                ${destroot}${prefix}/var/log \
2686                ${destroot}${prefix}/var/cache/mrtg</programlisting>
2687          </listitem>
2688        </varlistentry>
2689
2690        <varlistentry>
2691          <term>destroot.violate_mtree</term>
2692
2693          <listitem>
2694            <para>MacPorts tests for compliance to the common directory
2695            structure in ${prefix}; the default is "no". If a port is not
2696            compliant with the standard, set it to "yes".</para>
2697
2698            <programlisting>destroot.violate_mtree    yes</programlisting>
2699          </listitem>
2700        </varlistentry>
2701      </variablelist>
2702    </refsection>
2703  </refsection>
2704
2705  <refsection>
2706    <title>TCL EXTENSIONS</title>
2707
2708    <para></para>
2709  </refsection>
2710
2711  <refsection>
2712    <title>SEE ALSO</title>
2713
2714    <para><citerefentry>
2715        <refentrytitle>port</refentrytitle>
2716
2717        <manvolnum>1</manvolnum>
2718      </citerefentry>, <citerefentry>
2719        <refentrytitle>macports.conf</refentrytitle>
2720
2721        <manvolnum>5</manvolnum>
2722      </citerefentry>, <citerefentry>
2723        <refentrytitle>portgroup</refentrytitle>
2724
2725        <manvolnum>7</manvolnum>
2726      </citerefentry>, <citerefentry>
2727        <refentrytitle>portstyle</refentrytitle>
2728
2729        <manvolnum>7</manvolnum>
2730      </citerefentry>, <citerefentry>
2731        <refentrytitle>porthier</refentrytitle>
2732
2733        <manvolnum>7</manvolnum>
2734      </citerefentry>, <citerefentry>
2735        <refentrytitle>file</refentrytitle>
2736
2737        <manvolnum>n</manvolnum>
2738      </citerefentry></para>
2739  </refsection>
2740
2741  <refsection>
2742    <title>AUTHORS</title>
2743
2744    <para>Landon Fuller <email>landonf@macports.org</email></para>
2745
2746    <para>Juan Manuel Palacios <email>jmpp@macports.org</email></para>
2747
2748    <para>Mark Duling <email>markd@macports.org</email></para>
2749
2750    <para>Kevin Van Vechten <email>kevin@opendarwin.org</email></para>
2751
2752    <para>Jordan K. Hubbard <email>jkh@macports.org</email></para>
2753
2754    <para>Chris Ridd <email>cjr@opendarwin.org</email></para>
2755
2756    <para>Kevin Ballard <email>eridius@macports.org</email></para>
2757
2758    <para>Markus W. Weissmann <email>mww@macports.org</email></para>
2759  </refsection>
2760</refentry>
Note: See TracBrowser for help on using the repository browser.