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

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

doc-new: Fixed some spelling mistakes and other minor errors in portfile.7.xml.

File size: 83.3 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/</programlisting>
1385
1386                <para>You may also use mirror site lists predefined by
1387                MacPorts. Here the sourceforge and gnu mirrors are
1388                used.</para>
1389
1390                <programlisting>master_sites   sourceforge gnu</programlisting>
1391
1392                <para>When using mirror master_sites, the subdirectory
1393                <varname>${name}</varname> is checked on every mirror. If the
1394                mirror subdirectory does not match ${name}, then you may
1395                specify it using after the mirror separated by a colon.</para>
1396
1397                <programlisting>master_sites   sourceforge:widget \
1398               gnu:widget</programlisting>
1399
1400                <para>For ports that must fetch multiple download files from
1401                different locations, you must label the files with tags and
1402                match the tags in a distfiles statement. The format is
1403                <literal>mirror:subdirectory:tag</literal>.</para>
1404
1405                <para>In the example below, file_one.tar.gz is fetched from
1406                sourceforge mirrors in subdirectory
1407                <varname>${name}</varname>; file tagtwo.tar.gz is fetched from
1408                the gnu mirrors in subdirectory sources.</para>
1409
1410                <programlisting>master_sites    sourceforge::tagone \
1411                gnu:sources:tagtwo
1412
1413distfiles       file_one.tar.gz:tagone \
1414                file_two.tar.gz:tagtwo</programlisting>
1415              </listitem>
1416            </itemizedlist>
1417          </listitem>
1418        </varlistentry>
1419
1420        <varlistentry>
1421          <term>patch_sites</term>
1422
1423          <listitem>
1424            <para>A list of sites from which a port's patchfiles may be
1425            downloaded, where applicable.</para>
1426
1427            <itemizedlist>
1428              <listitem>
1429                <para>Default: <varname>${master_sites}</varname></para>
1430              </listitem>
1431
1432              <listitem>
1433                <para>Example:</para>
1434
1435                <programlisting>patch_sites    ftp://ftp.patchcityrepo.com/pub/magic/patches</programlisting>
1436              </listitem>
1437            </itemizedlist>
1438          </listitem>
1439        </varlistentry>
1440
1441        <varlistentry>
1442          <term>distname</term>
1443
1444          <listitem>
1445            <para>The name of the distribution filename, not including the
1446            extract suffix.</para>
1447
1448            <itemizedlist>
1449              <listitem>
1450                <para>Default: <varname>${name}-${version}</varname></para>
1451              </listitem>
1452
1453              <listitem>
1454                <para>Example:</para>
1455
1456                <programlisting>distname     ${name}</programlisting>
1457              </listitem>
1458            </itemizedlist>
1459          </listitem>
1460        </varlistentry>
1461
1462        <varlistentry>
1463          <term>distfiles</term>
1464
1465          <listitem>
1466            <para>The full distribution filename, including the extract
1467            suffix. Used to specify non-default distribution filenames; this
1468            keyword must be specified (and tags used) when a port has multiple
1469            download files (see master_sites).</para>
1470
1471            <itemizedlist>
1472              <listitem>
1473                <para>Default:
1474                <varname>${distname}${extract.suffix}</varname></para>
1475              </listitem>
1476
1477              <listitem>
1478                <para>Example:</para>
1479
1480                <programlisting>distfiles    ${name}-dev_src.tgz
1481
1482
1483distfiles       file_one.tar.gz:tagone \
1484                file_two.tar.gz:tagtwo</programlisting>
1485              </listitem>
1486            </itemizedlist>
1487          </listitem>
1488        </varlistentry>
1489
1490        <varlistentry>
1491          <term>extract.suffix</term>
1492
1493          <listitem>
1494            <para>This keyword is used to specify the extract suffix
1495            type.</para>
1496
1497            <itemizedlist>
1498              <listitem>
1499                <para>Default: <filename>.tar.gz</filename></para>
1500              </listitem>
1501
1502              <listitem>
1503                <para>Example:</para>
1504
1505                <programlisting>extract.suffix   .tgz</programlisting>
1506              </listitem>
1507            </itemizedlist>
1508          </listitem>
1509        </varlistentry>
1510
1511        <varlistentry>
1512          <term>use_bzip2</term>
1513
1514          <listitem>
1515            <para>This keyword is for downloads that are tarred and bzipped.
1516            When invoked, it automatically sets: extract.suffix =
1517            <filename>.tar.bz</filename> and extract.cmd =
1518            <command>bzip</command>.</para>
1519
1520            <itemizedlist>
1521              <listitem>
1522                <para>Default: yes</para>
1523              </listitem>
1524
1525              <listitem>
1526                <para>Example:</para>
1527
1528                <programlisting>use_bzip2     yes</programlisting>
1529              </listitem>
1530            </itemizedlist>
1531          </listitem>
1532        </varlistentry>
1533
1534        <varlistentry>
1535          <term>use_zip</term>
1536
1537          <listitem>
1538            <para>This keyword is for downloads are zipped. When invoked, it
1539            automatically sets: extract.suffix = .<filename>zip</filename>,
1540            extract.cmd = <command>unzip</command>, extract.pre_args =
1541            <option>-q</option>, extract.post_args = "<option>-d</option>
1542            <varname>${portpath}/${workdir}</varname>"</para>
1543
1544            <itemizedlist>
1545              <listitem>
1546                <para>Default: <option>yes</option></para>
1547              </listitem>
1548
1549              <listitem>
1550                <para>Example:</para>
1551
1552                <programlisting>use_zip       yes</programlisting>
1553              </listitem>
1554            </itemizedlist>
1555          </listitem>
1556        </varlistentry>
1557      </variablelist>
1558
1559      <refsection>
1560        <title>Fetch from CVS</title>
1561
1562        <para><ulink url="http://www.nongnu.org/cvs/">CVS</ulink> may be used
1563        as an alternative method of fetching distribution files using the
1564        keywords in this section. However, fetching via CVS may cause
1565        non-reproducible builds, so it is strongly discouraged.</para>
1566
1567        <variablelist>
1568          <varlistentry>
1569            <term>cvs.root</term>
1570
1571            <listitem>
1572              <para>Specify the url from which to fetch files.</para>
1573
1574              <itemizedlist>
1575                <listitem>
1576                  <para>Default: none</para>
1577                </listitem>
1578
1579                <listitem>
1580                  <para>Example:</para>
1581
1582                  <programlisting>cvs.root :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs</programlisting>
1583                </listitem>
1584              </itemizedlist>
1585            </listitem>
1586          </varlistentry>
1587
1588          <varlistentry>
1589            <term>cvs.tag</term>
1590
1591            <listitem>
1592              <para>Optional for fetching with CVS, this specifies the
1593              code revision to checkout.</para>
1594
1595              <itemizedlist>
1596                <listitem>
1597                  <para>Default: none</para>
1598                </listitem>
1599
1600                <listitem>
1601                  <para>Example:</para>
1602
1603                  <programlisting>cvs.tag  HEAD</programlisting>
1604                </listitem>
1605              </itemizedlist>
1606            </listitem>
1607          </varlistentry>
1608
1609          <varlistentry>
1610            <term>cvs.date</term>
1611
1612            <listitem>
1613              <para>A date that identifies the CVS code set to
1614              checkout.</para>
1615
1616              <itemizedlist>
1617                <listitem>
1618                  <para>Default: none</para>
1619                </listitem>
1620
1621                <listitem>
1622                  <para>Example:</para>
1623
1624                  <programlisting>cvs.date "12-April-2007"</programlisting>
1625                </listitem>
1626              </itemizedlist>
1627            </listitem>
1628          </varlistentry>
1629
1630          <varlistentry>
1631            <term>cvs.module</term>
1632
1633            <listitem>
1634              <para>A CVS module from which to check out the code.</para>
1635
1636              <itemizedlist>
1637                <listitem>
1638                  <para>Default: none</para>
1639                </listitem>
1640
1641                <listitem>
1642                  <para>Example:</para>
1643
1644                  <programlisting>cvs.module  Sources</programlisting>
1645                </listitem>
1646              </itemizedlist>
1647            </listitem>
1648          </varlistentry>
1649        </variablelist>
1650      </refsection>
1651
1652      <refsection>
1653        <title>Fetch from SVN</title>
1654
1655        <para><ulink url="http://subversion.tigris.org/">Subversion</ulink>
1656        may be used as an alternative method of fetching distribution files
1657        using the keywords in this section. However, fetching via Subversion
1658        may cause non-reproducible builds, so it is strongly
1659        discouraged.</para>
1660
1661        <variablelist>
1662          <varlistentry>
1663            <term>svn.url</term>
1664
1665            <listitem>
1666              <para>Optional for fetching with SVN, this specify the url from
1667              which to fetch files.</para>
1668
1669              <itemizedlist>
1670                <listitem>
1671                  <para>Default: none</para>
1672                </listitem>
1673
1674                <listitem>
1675                  <para>Examples:</para>
1676
1677                  <programlisting>svn.url http://www.domain.com/svn-repo/mydirectory
1678svn.url svn://www.domain.com/svn-repo/mydirectory
1679</programlisting>
1680                </listitem>
1681              </itemizedlist>
1682            </listitem>
1683          </varlistentry>
1684
1685          <varlistentry>
1686            <term>svn.tag</term>
1687
1688            <listitem>
1689              <para>Optional tag for fetching with Subversion, this specifies
1690              the code revision to checkout; it corresponds to the -r option
1691              in the svn cli. You must use backslashes to escape characters
1692              that are meaningful to the Tcl interpreter, such as braces and
1693              double quotes.</para>
1694
1695              <itemizedlist>
1696                <listitem>
1697                  <para>Default: none</para>
1698                </listitem>
1699
1700                <listitem>
1701                  <para>Examples:</para>
1702
1703                  <programlisting>svn.tag 37192
1704svn.tag \{\"2006-02-17 15:30 +0230\"\}</programlisting>
1705                </listitem>
1706              </itemizedlist>
1707            </listitem>
1708          </varlistentry>
1709        </variablelist>
1710      </refsection>
1711    </refsection>
1712
1713    <refsection>
1714      <title>Checksum Phase Keywords</title>
1715
1716      <para>The list of keywords related to the checksum phase.</para>
1717
1718      <variablelist>
1719        <varlistentry>
1720          <term>checksums</term>
1721
1722          <listitem>
1723            <para>Checksum(s) of the distribution files. For ports with
1724            multiple distribution files, filenames must be included to
1725            associate files with their checksums.</para>
1726
1727            <itemizedlist>
1728              <listitem>
1729                <para>Default: ???</para>
1730              </listitem>
1731
1732              <listitem>
1733                <para>Examples:</para>
1734
1735                <programlisting>checksums     md5 65b89365a65dcad71d4402b48</programlisting>
1736
1737                <programlisting>checksums     ${distname}${extract.suffix} md5 65b89365a65dcad71d4402b44 \
1738              hobbit.tar.gz md5 65b89365a65dcad71d4402b48</programlisting>
1739              </listitem>
1740            </itemizedlist>
1741          </listitem>
1742        </varlistentry>
1743      </variablelist>
1744    </refsection>
1745
1746    <refsection>
1747      <title>Extract Phase Keywords</title>
1748
1749      <para>The list of keywords related to the extract phase.</para>
1750
1751      <variablelist>
1752        <varlistentry>
1753          <term>extract.only</term>
1754
1755          <term>extract.only-append</term>
1756
1757          <term>extract.only-delete</term>
1758
1759          <listitem>
1760            <para>List of files to extract into
1761            <varname>${worksrcpath}</varname>; the default is
1762            <varname>${distfiles}</varname>. Only use if default extract
1763            behavior is not correct for your port.</para>
1764
1765            <itemizedlist>
1766              <listitem>
1767                <para>Default: none</para>
1768              </listitem>
1769
1770              <listitem>
1771                <para>Example:</para>
1772
1773                <programlisting>extract.only     foo.tar.gz
1774
1775</programlisting>
1776              </listitem>
1777            </itemizedlist>
1778          </listitem>
1779
1780          <listitem>
1781            <para>List modifier examples:</para>
1782
1783            <programlisting>extract.only-append  bar.tar.gz
1784extract.only-delete  foo.tar.gz</programlisting>
1785          </listitem>
1786        </varlistentry>
1787
1788        <varlistentry>
1789          <term>extract.cmd</term>
1790
1791          <listitem>
1792            <para>Command to perform extraction.</para>
1793
1794            <itemizedlist>
1795              <listitem>
1796                <para>Default: gzip</para>
1797              </listitem>
1798
1799              <listitem>
1800                <para>Example:</para>
1801
1802                <programlisting>extract.cmd     gunzip</programlisting>
1803              </listitem>
1804            </itemizedlist>
1805          </listitem>
1806        </varlistentry>
1807
1808        <varlistentry>
1809          <term>extract.args</term>
1810
1811          <term>extract.pre_args</term>
1812
1813          <term>extract.post_args</term>
1814
1815          <listitem>
1816            <para>Main arguments to extract.cmd; additional arguments passed
1817            before and after the main arguments.</para>
1818
1819            <itemizedlist>
1820              <listitem>
1821                <para>Default: ${distpath}/${distfile}</para>
1822              </listitem>
1823
1824              <listitem>
1825                <para>Example:</para>
1826
1827                <programlisting>extract.args      ${distpath}/${distfile}
1828
1829</programlisting>
1830              </listitem>
1831            </itemizedlist>
1832          </listitem>
1833
1834          <listitem>
1835            <para>The following argument modifiers are available:</para>
1836
1837            <itemizedlist>
1838              <listitem>
1839                <para>extract.pre_args default: "-dc"</para>
1840              </listitem>
1841
1842              <listitem>
1843                <para>extract.post_args default: " | tar -xf"</para>
1844              </listitem>
1845
1846              <listitem>
1847                <para>Examples:</para>
1848
1849                <programlisting>extract.pre_args     xf
1850extract.post_args    "| gnutar –x"</programlisting>
1851              </listitem>
1852            </itemizedlist>
1853          </listitem>
1854        </varlistentry>
1855      </variablelist>
1856    </refsection>
1857
1858    <refsection>
1859      <title>Patch Phase Keywords</title>
1860
1861      <para>The list of keywords related to the patch phase.</para>
1862
1863      <variablelist>
1864        <varlistentry>
1865          <term>patch.dir</term>
1866
1867          <listitem>
1868            <para>Specify the base path for patch files.</para>
1869
1870            <itemizedlist>
1871              <listitem>
1872                <para>Default: <varname>${worksrcpath}</varname></para>
1873              </listitem>
1874
1875              <listitem>
1876                <para>Example:</para>
1877
1878                <programlisting>patch.dir      ${worksrcpath}/util</programlisting>
1879              </listitem>
1880            </itemizedlist>
1881          </listitem>
1882        </varlistentry>
1883
1884        <varlistentry>
1885          <term>patch.cmd</term>
1886
1887          <listitem>
1888            <para>Specify the command to be used for patching files.</para>
1889
1890            <itemizedlist>
1891              <listitem>
1892                <para>Default: <command>patch</command></para>
1893              </listitem>
1894
1895              <listitem>
1896                <para>Example:</para>
1897
1898                <programlisting>patch.cmd      cat</programlisting>
1899              </listitem>
1900            </itemizedlist>
1901          </listitem>
1902        </varlistentry>
1903
1904        <varlistentry>
1905          <term>patchfiles</term>
1906
1907          <term>patchfiles-append</term>
1908
1909          <term>patchfiles-delete</term>
1910
1911          <listitem>
1912            <para>Specify patch files to be applied for a port; list modifiers
1913            specify patchfiles to be added or removed from a previous
1914            patchfile declaration.</para>
1915
1916            <itemizedlist>
1917              <listitem>
1918                <para>Default: none</para>
1919              </listitem>
1920
1921              <listitem>
1922                <para>Example:</para>
1923
1924                <programlisting>patchfiles     patch-Makefile.in \
1925               patch-source.c
1926
1927</programlisting>
1928              </listitem>
1929            </itemizedlist>
1930          </listitem>
1931
1932          <listitem>
1933            <para>List modifier examples:</para>
1934
1935            <programlisting>patchfiles-append   patch-configure
1936patchfiles-delete   patch-src-Makefile.in
1937</programlisting>
1938          </listitem>
1939        </varlistentry>
1940
1941        <varlistentry>
1942          <term>patch.args</term>
1943
1944          <term>patch.pre_args</term>
1945
1946          <term>patch.post_args</term>
1947
1948          <listitem>
1949            <para>Main arguments to patch.cmd; optional argument modifiers
1950            pass arguments before and after the main arguments.</para>
1951
1952            <itemizedlist>
1953              <listitem>
1954                <para>Default: none</para>
1955              </listitem>
1956
1957              <listitem>
1958                <para>Example:</para>
1959
1960                <programlisting>patch.args   ???
1961
1962</programlisting>
1963              </listitem>
1964            </itemizedlist>
1965          </listitem>
1966
1967          <listitem>
1968            <para>The following argument modifiers are available:</para>
1969
1970            <itemizedlist>
1971              <listitem>
1972                <para>patch.pre_args default: -p0</para>
1973              </listitem>
1974
1975              <listitem>
1976                <para>patch.post_args default: none</para>
1977              </listitem>
1978
1979              <listitem>
1980                <para>Examples:</para>
1981
1982                <programlisting>patch.pre_args     -p1
1983patch.post_args    ???</programlisting>
1984              </listitem>
1985            </itemizedlist>
1986          </listitem>
1987        </varlistentry>
1988      </variablelist>
1989    </refsection>
1990
1991    <refsection>
1992      <title>Configure Phase Keywords</title>
1993
1994      <para>The list of keywords related to the configure phase.</para>
1995
1996      <para>MacPorts base sets some important default configure options, so
1997      should use the -append version of most configure keywords so you don't
1998      overwrite them. For example, MacPorts base sets default
1999      <literal>configure.cflags</literal> so you should always use
2000      <literal>configure.cflags-append</literal> to set additional CFLAGS in
2001      Portfiles.</para>
2002
2003      <variablelist>
2004        <varlistentry>
2005          <term>configure.env</term>
2006
2007          <term>configure.env-append</term>
2008
2009          <term>configure.env-delete</term>
2010
2011          <listitem>
2012            <para>Set environment variables for configure; list modifiers add
2013            and delete items from a previous Portfile configure.env keyword,
2014            or a default set by MacPorts base.</para>
2015
2016            <itemizedlist>
2017              <listitem>
2018                <para>Default: <literal>CFLAGS=-I${prefix}/include
2019                LDFLAGS=-L${prefix}/lib</literal></para>
2020              </listitem>
2021
2022              <listitem>
2023                <para>Example:</para>
2024
2025                <programlisting>configure.env   CFLAGS=-I${prefix}/include/qt3</programlisting>
2026              </listitem>
2027            </itemizedlist>
2028          </listitem>
2029
2030          <listitem>
2031            <para>List modifier examples:</para>
2032
2033            <programlisting>configure.env-append   CFLAGS=-${prefix}/include/qt3
2034configure.env-delete   LDFLAGS=-L${prefix}/lib</programlisting>
2035          </listitem>
2036        </varlistentry>
2037
2038        <varlistentry>
2039          <term>configure.cflags</term>
2040
2041          <term>configure.cflags-append</term>
2042
2043          <term>configure.cflags-delete</term>
2044
2045          <listitem>
2046            <para>Set CFLAGS compiler flags; list modifiers add or delete
2047            items from a previous Portfile configure.cflags keyword or the
2048            default set by MacPorts base.</para>
2049
2050            <itemizedlist>
2051              <listitem>
2052                <para>Default:
2053                <literal>CFLAGS=-I${prefix}/include</literal></para>
2054              </listitem>
2055
2056              <listitem>
2057                <para>Example:</para>
2058
2059                <programlisting>configure.cflags    CFLAGS=-I${worksrcpath}/include
2060
2061</programlisting>
2062              </listitem>
2063            </itemizedlist>
2064          </listitem>
2065
2066          <listitem>
2067            <para>List modifier examples:</para>
2068
2069            <programlisting>configure.cflags-append   "-I/usr/X11R6/include -I${worksrcpath}"
2070configure.cflags-delete   -I${prefix}/include/db44</programlisting>
2071          </listitem>
2072        </varlistentry>
2073
2074        <varlistentry>
2075          <term>configure.ldflags</term>
2076
2077          <term>configure.ldflags-append</term>
2078
2079          <term>configure.ldflags-delete</term>
2080
2081          <listitem>
2082            <para>Set LDFLAGS compiler flags; list modifiers add or delete
2083            items from a previous Portfile configure.ldflags keyword or the
2084            default set by MacPorts base.</para>
2085
2086            <itemizedlist>
2087              <listitem>
2088                <para>Default:
2089                <literal>LDFLAGS=-L${prefix}/lib</literal></para>
2090              </listitem>
2091
2092              <listitem>
2093                <para>Example:</para>
2094
2095                <programlisting>configure.ldflags    CFLAGS=-I${worksrcpath}/include
2096
2097</programlisting>
2098              </listitem>
2099            </itemizedlist>
2100          </listitem>
2101
2102          <listitem>
2103            <para>List modifier examples:</para>
2104
2105            <programlisting>configure.ldflags-append   "-L/usr/X11R6/lib -L${worksrcpath}/lib"
2106configure.ldflags-delete   -L${prefix}/lib/db44</programlisting>
2107          </listitem>
2108        </varlistentry>
2109
2110        <varlistentry>
2111          <term>configure.cppflags</term>
2112
2113          <term>configure.cppflags-append</term>
2114
2115          <term>configure.cppflags-delete</term>
2116
2117          <listitem>
2118            <para>Set CPPFLAGS to be passed to the C processor; list modifiers
2119            add or delete items from a previous Portfile configure.cppflags
2120            keyword or the default set by MacPorts base.</para>
2121
2122            <itemizedlist>
2123              <listitem>
2124                <para>Default:
2125                <literal>CPPFLAGS=-I${prefix}/include</literal></para>
2126              </listitem>
2127
2128              <listitem>
2129                <para>Example:</para>
2130
2131                <programlisting>configure.cppflags    CPPFLAGS=-I${worksrcpath}/include
2132
2133</programlisting>
2134              </listitem>
2135            </itemizedlist>
2136          </listitem>
2137
2138          <listitem>
2139            <para>List modifier examples:</para>
2140
2141            <programlisting>configure.cppflags-append   "-I/usr/X11R6/lib -I${worksrcpath}/lib"
2142configure.cppflags-delete   -I${prefix}/lib/db44</programlisting>
2143          </listitem>
2144        </varlistentry>
2145
2146        <varlistentry>
2147          <term>configure.args</term>
2148
2149          <term>configure.pre_args</term>
2150
2151          <term>configure.post_args</term>
2152
2153          <listitem>
2154            <para>Main arguments to configure.cmd; optional argument modifiers
2155            pass arguments before and after the main arguments.</para>
2156
2157            <itemizedlist>
2158              <listitem>
2159                <para>Default: none</para>
2160              </listitem>
2161
2162              <listitem>
2163                <para>Example:</para>
2164
2165                <programlisting>configure.args    --bindir=${prefix}/bin
2166
2167</programlisting>
2168              </listitem>
2169            </itemizedlist>
2170          </listitem>
2171
2172          <listitem>
2173            <para>The following argument modifiers are available:</para>
2174
2175            <itemizedlist>
2176              <listitem>
2177                <para>configure.pre_args default: --prefix=${prefix}</para>
2178              </listitem>
2179
2180              <listitem>
2181                <para>configure.post_args default: none</para>
2182              </listitem>
2183
2184              <listitem>
2185                <para>Examples:</para>
2186
2187                <programlisting>configure.pre_args   --prefix=${prefix}/share/bro
2188configure.post_args  OPT="-D__DARWIN_UNIX03"</programlisting>
2189              </listitem>
2190            </itemizedlist>
2191          </listitem>
2192        </varlistentry>
2193      </variablelist>
2194
2195      <refsection>
2196        <title>Configure Universal</title>
2197
2198        <para>Universal keywords are used to make a port compile on the OS X
2199        platform to run on either PPC or Intel.</para>
2200
2201        <note>
2202          <para>There is a default universal variant made available to all
2203          ports by MacPorts base, so redefining universal keywords should only
2204          be done to make a given port compile if the default options fail to
2205          do so.</para>
2206        </note>
2207
2208        <variablelist>
2209          <varlistentry>
2210            <term>configure.universal_args</term>
2211
2212            <listitem>
2213              <para>Arguments used in the configure script to build the port
2214              universal.</para>
2215
2216              <itemizedlist>
2217                <listitem>
2218                  <para>Default: --disable-dependency-tracking</para>
2219                </listitem>
2220
2221                <listitem>
2222                  <para>Example:</para>
2223
2224                  <programlisting></programlisting>
2225                </listitem>
2226              </itemizedlist>
2227            </listitem>
2228          </varlistentry>
2229
2230          <varlistentry>
2231            <term>configure.universal_cflags</term>
2232
2233            <listitem>
2234              <para>Arguments appended to the configure script to build the
2235              port universal.</para>
2236
2237              <itemizedlist>
2238                <listitem>
2239                  <para>Default: -sysroot /Developer/SDKs/MacOSX10.4u.sdk
2240                  -arch i386 -arch ppc</para>
2241                </listitem>
2242
2243                <listitem>
2244                  <para>Example:</para>
2245
2246                  <programlisting></programlisting>
2247                </listitem>
2248              </itemizedlist>
2249            </listitem>
2250          </varlistentry>
2251
2252          <varlistentry>
2253            <term>configure.universal_cppflags</term>
2254
2255            <listitem>
2256              <para>Additional flags to put in the CPPFLAGS environment
2257              variable when invoking the configure script.</para>
2258
2259              <itemizedlist>
2260                <listitem>
2261                  <para>Default: ???</para>
2262                </listitem>
2263
2264                <listitem>
2265                  <para>Example:</para>
2266
2267                  <programlisting></programlisting>
2268                </listitem>
2269              </itemizedlist>
2270            </listitem>
2271          </varlistentry>
2272
2273          <varlistentry>
2274            <term>configure.universal_cxxflags</term>
2275
2276            <listitem>
2277              <para>Additional flags to put in the CXXFLAGS environment
2278              variable when invoking the configure script.</para>
2279
2280              <itemizedlist>
2281                <listitem>
2282                  <para>Default: -isysroot /Developer/SDKs/MacOSX10.4u.sdk
2283                  -arch i386 -arch ppc</para>
2284                </listitem>
2285
2286                <listitem>
2287                  <para>Example:</para>
2288
2289                  <programlisting></programlisting>
2290                </listitem>
2291              </itemizedlist>
2292            </listitem>
2293          </varlistentry>
2294
2295          <varlistentry>
2296            <term>configure.universal_ldflags</term>
2297
2298            <listitem>
2299              <para>Additional flags to put in the LDFLAGS environment
2300              variable when invoking the configure script.</para>
2301
2302              <itemizedlist>
2303                <listitem>
2304                  <para>Default: -arch i386 -arch ppc</para>
2305                </listitem>
2306
2307                <listitem>
2308                  <para>Example:</para>
2309
2310                  <programlisting></programlisting>
2311                </listitem>
2312              </itemizedlist>
2313            </listitem>
2314          </varlistentry>
2315        </variablelist>
2316      </refsection>
2317
2318      <refsection>
2319        <title>Automake and Autoconf</title>
2320
2321        <para>The list of configure keywords available for ports that need
2322        automake and/or autoconf.</para>
2323
2324        <variablelist>
2325          <varlistentry>
2326            <term>use_automake</term>
2327
2328            <listitem>
2329              <para>Whether or not to use automake; the default is
2330              "no".</para>
2331
2332              <programlisting>use_automake      yes</programlisting>
2333            </listitem>
2334          </varlistentry>
2335
2336          <varlistentry>
2337            <term>automake.env</term>
2338
2339            <listitem>
2340              <para>Environment variables to pass to automake.</para>
2341
2342              <programlisting>automake.env      CFLAGS=-I${prefix}/include</programlisting>
2343            </listitem>
2344          </varlistentry>
2345
2346          <varlistentry>
2347            <term>automake.args</term>
2348
2349            <listitem>
2350              <para>Arguments to pass to automake.</para>
2351
2352              <programlisting>automake.args     --foreign</programlisting>
2353            </listitem>
2354          </varlistentry>
2355
2356          <varlistentry>
2357            <term>automake.dir</term>
2358
2359            <listitem>
2360              <para>Directory in which to run
2361              <varname>${automake.cmd}</varname>; the default is
2362              <varname>${worksrcpath}</varname>.</para>
2363
2364              <programlisting>automake.dir      ./src</programlisting>
2365            </listitem>
2366          </varlistentry>
2367
2368          <varlistentry>
2369            <term>use_autoconf</term>
2370
2371            <listitem>
2372              <para>Whether or not to use autoconf; the default is
2373              "no".</para>
2374
2375              <programlisting>use_autoconf      yes</programlisting>
2376            </listitem>
2377          </varlistentry>
2378
2379          <varlistentry>
2380            <term>autoconf.env</term>
2381
2382            <listitem>
2383              <para>Environmental variables to pass to autoconf.</para>
2384
2385              <programlisting>autoconf.env      CFLAGS=-I${prefix}/include/gtk12</programlisting>
2386            </listitem>
2387          </varlistentry>
2388
2389          <varlistentry>
2390            <term>autoconf.args</term>
2391
2392            <listitem>
2393              <para>Arguments to pass to autoconf.</para>
2394
2395              <programlisting>autoconf.args     -l src/aclocaldir</programlisting>
2396            </listitem>
2397          </varlistentry>
2398
2399          <varlistentry>
2400            <term>autoconf.dir</term>
2401
2402            <listitem>
2403              <para>Directory in which to run
2404              <varname>${autoconf.cmd}</varname>; the default is
2405              <varname>${worksrcpath}</varname>.</para>
2406
2407              <programlisting>autoconf.dir      src</programlisting>
2408            </listitem>
2409          </varlistentry>
2410        </variablelist>
2411      </refsection>
2412    </refsection>
2413
2414    <refsection>
2415      <title>Build Phase Keywords</title>
2416
2417      <para>The list of keywords related to the build phase.</para>
2418
2419      <variablelist>
2420        <varlistentry>
2421          <term>build.cmd</term>
2422
2423          <listitem>
2424            <para>Make command to run in <varname>${worksrcdir}</varname>; the
2425            default is "make".</para>
2426
2427            <programlisting>build.cmd      pbxbuild</programlisting>
2428          </listitem>
2429        </varlistentry>
2430
2431        <varlistentry>
2432          <term>build.type</term>
2433
2434          <listitem>
2435            <para>Defines which "make" is required: "gnu" or "bsd". Sets
2436            build.cmd to either "gnumake" or "bsdmake" accordingly.</para>
2437
2438            <programlisting>build.type     gnu</programlisting>
2439          </listitem>
2440        </varlistentry>
2441
2442        <varlistentry>
2443          <term>build.args</term>
2444
2445          <term>build.pre_args</term>
2446
2447          <term>build.post_args</term>
2448
2449          <listitem>
2450            <para>Main arguments to build.cmd; optional argument modifiers
2451            pass arguments before and after the main arguments.</para>
2452
2453            <itemizedlist>
2454              <listitem>
2455                <para>Default: none</para>
2456              </listitem>
2457
2458              <listitem>
2459                <para>Example:</para>
2460
2461                <programlisting>build.args    -DNOWARN
2462
2463</programlisting>
2464              </listitem>
2465            </itemizedlist>
2466          </listitem>
2467
2468          <listitem>
2469            <para>The following argument modifiers are available:</para>
2470
2471            <itemizedlist>
2472              <listitem>
2473                <para>build.pre_args default:
2474                <varname>${build.target.current}</varname></para>
2475              </listitem>
2476
2477              <listitem>
2478                <para>build.post_args default: none</para>
2479              </listitem>
2480
2481              <listitem>
2482                <para>Examples:</para>
2483
2484                <programlisting>build.pre_args  -project AudioSlicer.xcode
2485build.post_args CFLAGS_SYS="-DUSE_FREETYPE -DPREFER_FREETYPE"</programlisting>
2486              </listitem>
2487            </itemizedlist>
2488          </listitem>
2489        </varlistentry>
2490
2491        <varlistentry>
2492          <term>build.target</term>
2493
2494          <term>build.target-append</term>
2495
2496          <term>build.target-delete</term>
2497
2498          <listitem>
2499            <para>Build target to pass to ${build.cmd}; list modifiers add or
2500            delete items from a previous Portfile build.target keyword or the
2501            default set by MacPorts base.</para>
2502
2503            <itemizedlist>
2504              <listitem>
2505                <para>Default: all</para>
2506              </listitem>
2507
2508              <listitem>
2509                <para>Example:</para>
2510
2511                <programlisting>build.target    all-src
2512
2513</programlisting>
2514              </listitem>
2515            </itemizedlist>
2516          </listitem>
2517
2518          <listitem>
2519            <para>List modifier examples:</para>
2520
2521            <programlisting>build.target-append   doc extra
2522build.target-delete   compat</programlisting>
2523          </listitem>
2524        </varlistentry>
2525      </variablelist>
2526    </refsection>
2527
2528    <refsection>
2529      <title>Destroot Phase Keywords</title>
2530
2531      <para>The list of keywords related to the destroot phase.</para>
2532
2533      <variablelist>
2534        <varlistentry>
2535          <term>destroot.cmd</term>
2536
2537          <listitem>
2538            <para>Install command to run relative to
2539            <varname>${worksrcdir}</varname>; default is
2540            <varname>${build.cmd}</varname>.</para>
2541
2542            <programlisting>destroot.cmd         pbxbuild</programlisting>
2543          </listitem>
2544        </varlistentry>
2545
2546        <varlistentry>
2547          <term>destroot.type</term>
2548
2549          <listitem>
2550            <para>Defines which "make" is required: either "gnu" or "bsd".
2551            Sets install.cmd to either "gnumake" or "bsdmake"
2552            accordingly.</para>
2553
2554            <programlisting>destroot.type        gnu</programlisting>
2555          </listitem>
2556        </varlistentry>
2557
2558        <varlistentry>
2559          <term>destroot.args</term>
2560
2561          <term>destroot.pre_args</term>
2562
2563          <term>destroot.post_args</term>
2564
2565          <listitem>
2566            <para>Main arguments to ${destroot.cmd}; optional argument
2567            modifiers pass arguments before and after the main
2568            arguments.</para>
2569
2570            <itemizedlist>
2571              <listitem>
2572                <para>Default: none</para>
2573              </listitem>
2574
2575              <listitem>
2576                <para>Example:</para>
2577
2578                <programlisting>destroot.args    BINDIR=${prefix}/bin
2579
2580</programlisting>
2581              </listitem>
2582            </itemizedlist>
2583          </listitem>
2584
2585          <listitem>
2586            <para>The following argument modifiers are available:</para>
2587
2588            <itemizedlist>
2589              <listitem>
2590                <para>destroot.pre_args default:
2591                <varname>${destroot.target}</varname></para>
2592              </listitem>
2593
2594              <listitem>
2595                <para>destroot.post_args default: none</para>
2596              </listitem>
2597
2598              <listitem>
2599                <para>Examples:</para>
2600
2601                <programlisting>destroot.pre_args  -project AudioSlicer.xcode
2602destroot.post_args INSTDIR=${destroot}${prefix}</programlisting>
2603              </listitem>
2604            </itemizedlist>
2605          </listitem>
2606        </varlistentry>
2607
2608        <varlistentry>
2609          <term>destroot.target</term>
2610
2611          <term>destroot.target-append</term>
2612
2613          <term>destroot.target-delete</term>
2614
2615          <listitem>
2616            <para>Install target to pass to ${destroot.cmd}; list modifiers add
2617            or delete items from a previous Portfile destroot.target keyword
2618            or the default set by MacPorts base.</para>
2619
2620            <itemizedlist>
2621              <listitem>
2622                <para>Default:
2623                <literal>install</literal></para>
2624              </listitem>
2625
2626              <listitem>
2627                <para>Example:</para>
2628
2629                <programlisting>destroot.target    install install-config install-commandmode
2630
2631</programlisting>
2632              </listitem>
2633            </itemizedlist>
2634          </listitem>
2635
2636          <listitem>
2637            <para>List modifier examples:</para>
2638
2639            <programlisting>destroot.target-append   install-plugins
2640destroot.target-delete   install-commandmode</programlisting>
2641          </listitem>
2642        </varlistentry>
2643
2644        <varlistentry>
2645          <term>destroot.destdir</term>
2646
2647          <listitem>
2648            <para>Arguments passed to ${destroot.cmd} to install correctly
2649            into the destroot.</para>
2650
2651            <programlisting>destroot.destdir     prefix=${destroot}${prefix}</programlisting>
2652
2653            <note>
2654              <para>If an application's Makefile properly supports the DESTDIR
2655              variable, MacPorts will automatically destroot the port
2656              properly. A port must destroot properly or the port will not
2657              install correctly, upgrade, or uninstall. If not, you may need
2658              to set this variable, or even patch the application's
2659              Makefile.</para>
2660            </note>
2661          </listitem>
2662        </varlistentry>
2663
2664        <varlistentry>
2665          <term>destroot.keepdirs</term>
2666
2667          <listitem>
2668            <para>A list of directories that should not be removed if empty
2669            upon destroot completion.</para>
2670
2671            <programlisting>destroot.keepdirs \
2672                ${destroot}${prefix}/var/run \
2673                ${destroot}${prefix}/var/log \
2674                ${destroot}${prefix}/var/cache/mrtg</programlisting>
2675          </listitem>
2676        </varlistentry>
2677
2678        <varlistentry>
2679          <term>destroot.violate_mtree</term>
2680
2681          <listitem>
2682            <para>MacPorts tests for compliance to the common directory
2683            structure in ${prefix}; the default is "no". If a port is not
2684            compliant with the standard, set it to "yes".</para>
2685
2686            <programlisting>destroot.violate_mtree    yes</programlisting>
2687          </listitem>
2688        </varlistentry>
2689      </variablelist>
2690    </refsection>
2691  </refsection>
2692
2693  <refsection>
2694    <title>TCL EXTENSIONS</title>
2695
2696    <para></para>
2697  </refsection>
2698
2699  <refsection>
2700    <title>SEE ALSO</title>
2701
2702    <para><citerefentry>
2703        <refentrytitle>port</refentrytitle>
2704
2705        <manvolnum>1</manvolnum>
2706      </citerefentry>, <citerefentry>
2707        <refentrytitle>macports.conf</refentrytitle>
2708
2709        <manvolnum>5</manvolnum>
2710      </citerefentry>, <citerefentry>
2711        <refentrytitle>portgroup</refentrytitle>
2712
2713        <manvolnum>7</manvolnum>
2714      </citerefentry>, <citerefentry>
2715        <refentrytitle>portstyle</refentrytitle>
2716
2717        <manvolnum>7</manvolnum>
2718      </citerefentry>, <citerefentry>
2719        <refentrytitle>porthier</refentrytitle>
2720
2721        <manvolnum>7</manvolnum>
2722      </citerefentry>, <citerefentry>
2723        <refentrytitle>file</refentrytitle>
2724
2725        <manvolnum>n</manvolnum>
2726      </citerefentry></para>
2727  </refsection>
2728
2729  <refsection>
2730    <title>AUTHORS</title>
2731
2732    <para>Landon Fuller <email>landonf@macports.org</email></para>
2733
2734    <para>Juan Manuel Palacios <email>jmpp@macports.org</email></para>
2735
2736    <para>Mark Duling <email>markd@macports.org</email></para>
2737
2738    <para>Kevin Van Vechten <email>kevin@opendarwin.org</email></para>
2739
2740    <para>Jordan K. Hubbard <email>jkh@macports.org</email></para>
2741
2742    <para>Chris Ridd <email>cjr@opendarwin.org</email></para>
2743
2744    <para>Kevin Ballard <email>eridius@macports.org</email></para>
2745
2746    <para>Markus W. Weissmann <email>mww@macports.org</email></para>
2747  </refsection>
2748</refentry>
Note: See TracBrowser for help on using the repository browser.