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

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

Add startupitem.netchange and startupitem.inetdcompat; the latter is not implemented yet, but
hopefully soon.

File size: 101.6 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>epoch</term>
354
355          <listitem>
356            <para>Optional keyword (default is 0) that is used if the new port
357            version looks older than the previous version (for example 1.10
358            -&gt; 1.2). Often the epoch is formatted like a date, but it can
359            simple a number like 1.</para>
360
361            <programlisting>epoch        20070924</programlisting>
362
363            <programlisting>epoch        1</programlisting>
364          </listitem>
365        </varlistentry>
366
367        <varlistentry>
368          <term>categories</term>
369
370          <listitem>
371            <para>The category under which the ported software falls. The
372            first category should be the same as the directory within which
373            the Portfile is stored; secondary and tertiary categories may be
374            selected.</para>
375
376            <programlisting>categories     net security</programlisting>
377          </listitem>
378        </varlistentry>
379
380        <varlistentry>
381          <term>maintainers</term>
382
383          <listitem>
384            <para>A port's maintainer is a person or persons who take
385            responsibility for keeping the port up-to-date, and the maintainer
386            keyword lists maintainer email addresses(s). However, many
387            maintainers wish to hide these addresses from spambots; to do so
388            follow these conventions:</para>
389
390            <itemizedlist>
391              <listitem>
392                <para>For addresses in domain @macports.org, simply omit the
393                domain name.</para>
394              </listitem>
395
396              <listitem>
397                <para>For addresses in other domains, say
398                <email>account@example.org</email>, use the convention
399                example.org:account to specify the address.</para>
400              </listitem>
401            </itemizedlist>
402
403            <para>In the example below, the maintainer email addresses
404            <email>jdoe@macports.org</email> and
405            <email>julesverne@example.org</email> are hidden using these
406            conventions.</para>
407
408            <programlisting>maintainers       jdoe \
409                  example.org:julesverne</programlisting>
410          </listitem>
411        </varlistentry>
412
413        <varlistentry>
414          <term>description</term>
415
416          <listitem>
417            <para>A one-sentence description of the ported software.</para>
418
419            <programlisting>description    A classic shooter arcade game.</programlisting>
420          </listitem>
421        </varlistentry>
422
423        <varlistentry>
424          <term>long_description</term>
425
426          <listitem>
427            <para>A long description of the ported software. Break long lines
428            with escaped newlines.</para>
429
430            <programlisting>description    A classic shooter arcade game derived from \
431               the game alien-munchers.  Not suitable for \
432               children under two years old.      </programlisting>
433          </listitem>
434        </varlistentry>
435
436        <varlistentry>
437          <term>homepage</term>
438
439          <listitem>
440            <para>Port application's homepage.</para>
441
442            <programlisting>homepage       http://www.somesite.org/apps</programlisting>
443          </listitem>
444        </varlistentry>
445
446        <varlistentry>
447          <term>platforms</term>
448
449          <listitem>
450            <para>The platforms on which the port has been tested.</para>
451
452            <programlisting>platforms      darwin freebsd</programlisting>
453          </listitem>
454        </varlistentry>
455      </variablelist>
456    </refsection>
457
458    <refsection>
459      <title>Dependencies</title>
460
461      <para>Free and open source software is highly modular, and MacPorts
462      ports often require that other ports be installed beforehand; these
463      prerequisites for a given port are called a port's
464      <quote>dependencies</quote>.</para>
465
466      <para>There are three types of MacPorts dependencies: library, build,
467      and run dependencies. Dependency types are important for proper port
468      upgrade and uninstall behavior. For example, you may not uninstall a
469      port that is a library dependency for another port, though you may
470      remove one with a build dependency; likewise, upgrading a port will
471      upgrade its library and build dependencies also, but not its run
472      dependencies.</para>
473
474      <variablelist>
475        <varlistentry>
476          <term>depends_lib</term>
477
478          <term>depends_lib-append</term>
479
480          <term>depends_lib-delete</term>
481
482          <listitem>
483            <para>The list of dependencies to check before phases
484            <option>configure</option>, <option>build</option>,
485            <option>destroot</option>, <option>install</option>, and
486            <option>package</option>. Library dependencies are needed both at
487            build time (for headers and libraries to link against) and at run
488            time.</para>
489          </listitem>
490        </varlistentry>
491
492        <varlistentry>
493          <term>depends_build</term>
494
495          <term>depends_build-append</term>
496
497          <term>depends_build-delete</term>
498
499          <listitem>
500            <para>The list of dependencies to check before phases
501            <option>build</option>, <option>destroot</option>,
502            <option>install</option>, and <option>package</option>. Build
503            dependencies are needed when software is compiled, but not needed
504            at all once the software is compiled and installed.</para>
505          </listitem>
506        </varlistentry>
507
508        <varlistentry>
509          <term>depends_run</term>
510
511          <term>depends_run-append</term>
512
513          <term>depends_run-delete</term>
514
515          <listitem>
516            <para>The list of dependencies to check before phases
517            <option>destroot</option>, <option>install</option>, and
518            <option>package</option>. Run dependencies are needed when the
519            software is run, but not to compile it.</para>
520          </listitem>
521        </varlistentry>
522      </variablelist>
523
524      <refsection>
525        <title>Port and Non-Port Dependencies</title>
526
527        <para>Port dependencies should be provided by MacPorts ports whenever
528        possible, however dependencies may be provided by vendor-supplied
529        software when satisfying a dependency by a port is not practical or
530        desirable for a special reason. Dependencies of this type are called
531        non-port dependencies.</para>
532
533        <para>Port dependencies, the preferred type, are specified as shown in
534        these examples:</para>
535
536        <programlisting>depends_lib        port:rrdtool port:apache2
537
538depends_build      port:apache2 port:php5</programlisting>
539
540        <para>Non-port dependencies are specified as shown in these
541        examples:</para>
542
543        <programlisting>depends_lib        lib:libX11.6:xorg
544
545depends_build      bin:rrdtool</programlisting>
546      </refsection>
547    </refsection>
548
549    <refsection>
550      <title>Variants</title>
551
552      <para>MacPorts variants are conditional modifications of port
553      installation behavior that may be invoked by a user at the time of port
554      install.</para>
555
556      <variablelist>
557        <varlistentry>
558          <term>variant [requires variant] [conflicts variant] [description
559          description]</term>
560
561          <listitem>
562            <para>The variant declaration may contain any keywords that can be
563            placed in a Portfile's global section. If you wish to execute
564            system (shell) calls or Tcl extensions during the execution of a
565            port phase, you should place those statements within a
566            <literal>variant_isset</literal> conditional within a phase
567            declaration and not within the variant declaration itself.
568            Dependencies and conflicts with other variants in the same port
569            can be expressed with requires and conflicts. See the isset Tcl
570            extension.</para>
571
572            <itemizedlist>
573              <listitem>
574                <para>Default: no</para>
575              </listitem>
576
577              <listitem>
578                <para>Example:</para>
579
580                <programlisting>variant gnome requires glib {
581      configure.args-append --with-gnome
582      depends_lib-append port:gnome-session
583}</programlisting>
584              </listitem>
585            </itemizedlist>
586          </listitem>
587        </varlistentry>
588
589        <varlistentry>
590          <term>default_variants</term>
591
592          <listitem>
593            <para>If variants are defined, then the default_variants value
594            lists which variants are enabled by default. This allows for
595            Portfile modularity and also allows users to suppress default
596            variants if they wish.</para>
597
598            <itemizedlist>
599              <listitem>
600                <para>Default: none</para>
601              </listitem>
602
603              <listitem>
604                <para>Example:</para>
605
606                <programlisting>default_variants +ssl +tcpd
607
608</programlisting>
609              </listitem>
610            </itemizedlist>
611          </listitem>
612
613          <listitem>
614            <para>Default variants may be suppressed by preceding a variant
615            name with a "-" as shown in this example.</para>
616
617            <programlisting><prompt>%%</prompt> <userinput>port install foo -ssl</userinput></programlisting>
618          </listitem>
619        </varlistentry>
620
621        <varlistentry>
622          <term>universal_variant</term>
623
624          <listitem>
625            <para>When using MacPorts on Mac OS X, a universal variant is
626            defined by default to configure ports with universal flags. The
627            variant can be overridden if the default code does not work (see
628            the Configure Universal section below), or suppressed if a
629            universal variant is not possible for the port with this
630            keyword.</para>
631
632            <itemizedlist>
633              <listitem>
634                <para>Default: yes</para>
635              </listitem>
636
637              <listitem>
638                <para>Example:</para>
639
640                <programlisting>universal_variant  no</programlisting>
641              </listitem>
642            </itemizedlist>
643          </listitem>
644        </varlistentry>
645      </variablelist>
646    </refsection>
647
648    <refsection>
649      <title>Livecheck / Distcheck</title>
650
651      <para>Options livecheck and distcheck are especially useful for port
652      maintainers, but others may also find this information valuable.</para>
653
654      <para>Livecheck checks to see if MacPorts can query the developer's
655      download site to determine if a newer version of the software has become
656      available since the port was installed.</para>
657
658      <variablelist>
659        <varlistentry>
660          <term>livecheck.check</term>
661
662          <listitem>
663            <para>Specify what kind of update check to perform.</para>
664
665            <para>Open source mirror site options are to use the project's
666            latest file release from <option>sourceforge</option> or
667            <option>googlecode</option>, or the project's
668            <literal>date_updated</literal> XML tag for
669            <option>freshmeat</option>.</para>
670
671            <para>Generic download site options are to specify a
672            <option>moddate</option> (modification date) of a URL resource), a
673            <option>regex</option> (retrieve the version by applying a regex
674            to a URL resource), <option>regexm</option> (retrieve the version
675            by applying a multi-line regex to a URL resource),
676            <option>md5</option> (compares the md5 sum of a URL resource) or
677            <option>none</option> (no check).</para>
678
679            <itemizedlist>
680              <listitem>
681                <para>Default: sourceforge or googlecode if the master_sites
682                is one of these, else freshmeat.</para>
683              </listitem>
684
685              <listitem>
686                <para>Values: freshmeat sourceforge googlecode moddate regex
687                regexm md5 none</para>
688              </listitem>
689
690              <listitem>
691                <para>Examples:</para>
692
693                <programlisting>livecheck.check     regex
694livecheck.url       http://dev.mysql.com/
695livecheck.regex     "Generally Available (${major_version}\\.\[0-9.\]+)"
696</programlisting>
697              </listitem>
698            </itemizedlist>
699          </listitem>
700        </varlistentry>
701
702        <varlistentry>
703          <term>livecheck.name</term>
704
705          <listitem>
706            <para>Name of the project for live checks; only used with
707            freshmeat, sourceforge, and googlecode livechecks.</para>
708
709            <itemizedlist>
710              <listitem>
711                <para>Default: <varname>${name}</varname> or the
712                sourceforge/freshmeat/googlecode project name if it can be
713                guessed from <literal>master_sites</literal>.</para>
714              </listitem>
715
716              <listitem>
717                <para>Values:
718                <replaceable>any_project_name</replaceable></para>
719              </listitem>
720
721              <listitem>
722                <para>Example:</para>
723
724                <programlisting>livecheck.name   hibernate</programlisting>
725              </listitem>
726            </itemizedlist>
727          </listitem>
728        </varlistentry>
729
730        <varlistentry>
731          <term>livecheck.distname</term>
732
733          <listitem>
734            <para>Name of the file release for sourceforge and googlecode
735            checks. You may use this keyword without livecheck.version if you
736            replace the version part of the name with "(.*)".</para>
737
738            <itemizedlist>
739              <listitem>
740                <para>Default: SourceForge:
741                <varname>${livecheck.name}</varname> ; GoogleCode: first
742                ${distfiles} item</para>
743              </listitem>
744
745              <listitem>
746                <para>Values: <replaceable>filename</replaceable></para>
747              </listitem>
748
749              <listitem>
750                <para>Example:</para>
751
752                <programlisting>livecheck.distname  faad2.src</programlisting>
753              </listitem>
754            </itemizedlist>
755          </listitem>
756        </varlistentry>
757
758        <varlistentry>
759          <term>livecheck.version</term>
760
761          <listitem>
762            <para>Version of the project for a check; used for regex-based
763            checks.</para>
764
765            <itemizedlist>
766              <listitem>
767                <para>Default: <varname>${version}</varname></para>
768              </listitem>
769
770              <listitem>
771                <para>Values: <replaceable>any_version</replaceable></para>
772              </listitem>
773
774              <listitem>
775                <para>Example:</para>
776
777                <programlisting>livecheck.version   ${name}-${version}</programlisting>
778              </listitem>
779            </itemizedlist>
780          </listitem>
781        </varlistentry>
782
783        <varlistentry>
784          <term>livecheck.url</term>
785
786          <listitem>
787            <para>URL to query for a check.</para>
788
789            <itemizedlist>
790              <listitem>
791                <para>Default:</para>
792
793                <itemizedlist>
794                  <listitem>
795                    <para>homepage or the first hit among the following
796                    sites</para>
797                  </listitem>
798
799                  <listitem>
800                    <para>http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml</para>
801                  </listitem>
802
803                  <listitem>
804                    <para>http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}</para>
805                  </listitem>
806
807                  <listitem>
808                    <para>http://code.google.com/p/${livecheck.name}/downloads/list</para>
809                  </listitem>
810                </itemizedlist>
811              </listitem>
812
813              <listitem>
814                <para>Values: <replaceable>any_url</replaceable></para>
815              </listitem>
816
817              <listitem>
818                <para>Example:</para>
819
820                <programlisting>livecheck.url  http://ftp.gnu.org/gnu/bison/</programlisting>
821              </listitem>
822            </itemizedlist>
823          </listitem>
824        </varlistentry>
825
826        <varlistentry>
827          <term>livecheck.regex</term>
828
829          <listitem>
830            <para>Regular expression to parse the resource for regex checks.
831            Be sure to use a regular expression grouping around the version
832            component.</para>
833
834            <itemizedlist>
835              <listitem>
836                <para>Default: none</para>
837              </listitem>
838
839              <listitem>
840                <para>Values: <replaceable>any_regex</replaceable></para>
841              </listitem>
842
843              <listitem>
844                <para>Example:</para>
845
846                <programlisting>livecheck.regex  4th-([a-z0-9.]+)-unix.tar.gz</programlisting>
847              </listitem>
848            </itemizedlist>
849          </listitem>
850        </varlistentry>
851
852        <varlistentry>
853          <term>livecheck.md5</term>
854
855          <listitem>
856            <para>md5 checksum to use for an md5 comparison.</para>
857
858            <itemizedlist>
859              <listitem>
860                <para>Default: none</para>
861              </listitem>
862
863              <listitem>
864                <para>Values:
865                <replaceable>any_md5_checksum</replaceable></para>
866              </listitem>
867
868              <listitem>
869                <para>Example:</para>
870
871                <programlisting>livecheck  md5 37e6a5b6516a680c7178b72021d3b706</programlisting>
872              </listitem>
873            </itemizedlist>
874          </listitem>
875        </varlistentry>
876      </variablelist>
877
878      <para>Distcheck reports whether or not the distfile(s) specified in a
879      Portfile are still available on the developer's download site. Examples
880      are given below.</para>
881
882      <variablelist>
883        <varlistentry>
884          <term>distcheck.check</term>
885
886          <listitem>
887            <para>This option can be used to disable distcheck. It specifies
888            what kind of check should be performed on distfiles: moddate
889            (check if the Portfile is older than the distfile) or none (no
890            check).</para>
891
892            <itemizedlist>
893              <listitem>
894                <para>Default: moddate</para>
895              </listitem>
896
897              <listitem>
898                <para>Values: moddate none</para>
899              </listitem>
900
901              <listitem>
902                <para>Example:</para>
903
904                <programlisting>distcheck.check  none</programlisting>
905              </listitem>
906            </itemizedlist>
907          </listitem>
908        </varlistentry>
909      </variablelist>
910    </refsection>
911
912    <refsection>
913      <title>StartupItems</title>
914
915      <para>A StartupItem is a MacPort facility to run "daemons," a Unix term
916      for programs that run continuously in the background, rather than under
917      the direct control of a user; for example, mail servers, network
918      listeners, etc. Ports that use StartupItem keywords create Mac OS X
919      scripts for <ulink
920      url="http://developer.apple.com/macosx/launchd.html">launchd</ulink>,
921      which is the Apple facility introduced with OS X 10.4 to replace xinetd
922      for starting and managing daemons. To support
923      <command>launchd</command>, a program named <command>daemondo</command>
924      is provided by MacPorts base that serves as an adapter between OS X's
925      <command>launchd</command> and daemons (<quote>executable</quote>
926      StartupItems) or traditional Unix startup scripts that start daemons
927      (<quote>script</quote> StartupItems).</para>
928
929      <para>There are three categories of StartupItem keywords. Those that
930      trigger StartupItem creation and logging, those that specify attributes
931      of <quote>executable</quote> StartupItems, and those that specify
932      attributes of <quote>script</quote> StartupItems.</para>
933
934      <refsection>
935        <title>StartupItem Attributes</title>
936
937        <para>The keywords in this section may be used with either
938        <quote>executable</quote> or <quote>script</quote> StartupItems (see
939        below).</para>
940
941        <variablelist>
942          <varlistentry>
943            <term>startupitem.create</term>
944
945            <listitem>
946              <para>Trigger the creation of a StartupItem.</para>
947
948              <itemizedlist>
949                <listitem>
950                  <para>Type: optional</para>
951                </listitem>
952
953                <listitem>
954                  <para>Default: no</para>
955                </listitem>
956
957                <listitem>
958                  <para>Values: yes no</para>
959                </listitem>
960
961                <listitem>
962                  <para>Example:</para>
963
964                  <programlisting>startupitem.create  yes</programlisting>
965                </listitem>
966              </itemizedlist>
967            </listitem>
968          </varlistentry>
969
970          <varlistentry>
971            <term>startupitem.name</term>
972
973            <listitem>
974              <para>Sets the name for the StartupItem.</para>
975
976              <itemizedlist>
977                <listitem>
978                  <para>Type: required</para>
979                </listitem>
980
981                <listitem>
982                  <para>Default: none</para>
983                </listitem>
984
985                <listitem>
986                  <para>Values: <replaceable>any_name</replaceable></para>
987                </listitem>
988
989                <listitem>
990                  <para>Example:</para>
991
992                  <programlisting>startupitem.name  OpenSSH</programlisting>
993                </listitem>
994              </itemizedlist>
995            </listitem>
996          </varlistentry>
997
998          <varlistentry>
999            <term>startupitem.logfile</term>
1000
1001            <listitem>
1002              <para>Path to a logfile for logging events about the lifetime of
1003              the StartupItem. Depending on the type of StartupItem, and the
1004              manner in which it is started, standard output from the daemon
1005              may also be directed to the logfile.</para>
1006
1007              <itemizedlist>
1008                <listitem>
1009                  <para>Type: optional</para>
1010                </listitem>
1011
1012                <listitem>
1013                  <para>Default: <filename>/dev/null</filename></para>
1014                </listitem>
1015
1016                <listitem>
1017                  <para>Values: <replaceable>/file/path</replaceable></para>
1018                </listitem>
1019
1020                <listitem>
1021                  <para>Example:</para>
1022
1023                  <programlisting>startupitem.logfile  ${prefix}/var/log/mydaemon.log</programlisting>
1024                </listitem>
1025              </itemizedlist>
1026            </listitem>
1027          </varlistentry>
1028
1029          <varlistentry>
1030            <term>startupitem.logevents</term>
1031
1032            <listitem>
1033              <para>Control whether or not to log events to the log file. If
1034              logevents is set, events with timestamps are logged to the
1035              logfile.</para>
1036
1037              <itemizedlist>
1038                <listitem>
1039                  <para>Type: optional</para>
1040                </listitem>
1041
1042                <listitem>
1043                  <para>Default: no</para>
1044                </listitem>
1045
1046                <listitem>
1047                  <para>Values: yes no</para>
1048                </listitem>
1049
1050                <listitem>
1051                  <para>Example:</para>
1052
1053                  <programlisting>startupitem.logevents   yes</programlisting>
1054                </listitem>
1055              </itemizedlist>
1056            </listitem>
1057          </varlistentry>
1058
1059          <varlistentry>
1060            <term>startupitem.netchange</term>
1061
1062            <listitem>
1063              <para>Cause the daemon to be restarted when a change in network
1064              state is detected.</para>
1065
1066              <itemizedlist>
1067                <listitem>
1068                  <para>Type: optional</para>
1069                </listitem>
1070
1071                <listitem>
1072                  <para>Default: no</para>
1073                </listitem>
1074
1075                <listitem>
1076                  <para>Values: yes no</para>
1077                </listitem>
1078
1079                <listitem>
1080                  <para>Example:</para>
1081
1082                  <programlisting>startupitem.netchange  yes</programlisting>
1083                </listitem>
1084              </itemizedlist>
1085            </listitem>
1086          </varlistentry>
1087        </variablelist>
1088      </refsection>
1089
1090      <refsection>
1091        <title>Executable StartupItems</title>
1092
1093        <para>Daemons run continuously, so monitoring the health of daemon
1094        processes and restarting them if they die is an important
1095        StartupItems' feature. <quote>Executable</quote> StartupItems are
1096        preferred over <quote>script</quote> StartupItems because
1097        <command>daemondo</command> launches the daemon
1098        <emphasis>directly</emphasis>, rather than
1099        <emphasis>indirectly</emphasis> via a script, and therefore it
1100        automatically knows how to monitor a daemon process and restart it if
1101        it dies. Daemons used with <quote>executable</quote> StartupItems may
1102        be programs or scripts (shell, perl, python, etc.), but when a script
1103        the script <emphasis>itself</emphasis> must be the daemon, rather than
1104        a script that launches a daemon. <quote>Script</quote> StartupItems
1105        are to be used for the latter.</para>
1106
1107        <note>
1108          <para>For a given port, the <quote>executable</quote> StartupItem
1109          keyword may not be used with any keywords in the
1110          <quote>script</quote> StartupItem category.</para>
1111        </note>
1112
1113        <variablelist>
1114          <varlistentry>
1115            <term>startupitem.executable</term>
1116
1117            <listitem>
1118              <para>Specifies the name of the daemon to be run in the
1119              background. It may have multiple arguments, but they must be
1120              appropriate for a call to exec; arbitrary shell code may not be
1121              used.</para>
1122
1123              <itemizedlist>
1124                <listitem>
1125                  <para>Type: optional</para>
1126                </listitem>
1127
1128                <listitem>
1129                  <para>Default: no</para>
1130                </listitem>
1131
1132                <listitem>
1133                  <para>Values:
1134                  <replaceable>/path/to/executable</replaceable></para>
1135                </listitem>
1136
1137                <listitem>
1138                  <para>Example:</para>
1139
1140                  <programlisting>startupitem.executable  "${prefix}/bin/nmicmpd"</programlisting>
1141                </listitem>
1142              </itemizedlist>
1143            </listitem>
1144          </varlistentry>
1145
1146          <varlistentry>
1147            <term>startupitem.inetdcompat</term>
1148
1149            <listitem>
1150              <para>This keyword can only be used with startupitem.executable
1151              and sets inetdCompatibility option.</para>
1152
1153              <itemizedlist>
1154                <listitem>
1155                  <para>Type: optional</para>
1156                </listitem>
1157
1158                <listitem>
1159                  <para>Default: no</para>
1160                </listitem>
1161
1162                <listitem>
1163                  <para>Values: yes no</para>
1164                </listitem>
1165
1166                <listitem>
1167                  <para>Example:</para>
1168
1169                  <programlisting>startupitem.inetdcompat   yes</programlisting>
1170                </listitem>
1171              </itemizedlist>
1172            </listitem>
1173          </varlistentry>
1174
1175          <varlistentry>
1176            <term>startupitem.inetdsockname</term>
1177
1178            <listitem>
1179              <para>Specify the xinetd socket servicename given in
1180              <filename>/etc/services</filename>; this is mandatory when using
1181              startupitem.inetdcompat, otherwise an invalid plist file
1182              results.</para>
1183
1184              <itemizedlist>
1185                <listitem>
1186                  <para>Type: optional, but mandatory when using
1187                  startupitem.inetdcompat.</para>
1188                </listitem>
1189
1190                <listitem>
1191                  <para>Default: no</para>
1192                </listitem>
1193
1194                <listitem>
1195                  <para>Values: <replaceable>name</replaceable></para>
1196                </listitem>
1197
1198                <listitem>
1199                  <para>Example:</para>
1200
1201                  <programlisting>startupitem.inetdsockname   nmicmpd</programlisting>
1202                </listitem>
1203              </itemizedlist>
1204            </listitem>
1205          </varlistentry>
1206
1207          <varlistentry>
1208            <term>startupitem.inetdnowait</term>
1209
1210            <listitem>
1211              <para>This keyword can only be used with
1212              startupitem.inetdcompat, and corresponds to "wait" or "nowait"
1213              option of xinetd services.</para>
1214
1215              <itemizedlist>
1216                <listitem>
1217                  <para>Type: optional</para>
1218                </listitem>
1219
1220                <listitem>
1221                  <para>Default: no</para>
1222                </listitem>
1223
1224                <listitem>
1225                  <para>Values: yes no</para>
1226                </listitem>
1227
1228                <listitem>
1229                  <para>Example:</para>
1230
1231                  <programlisting>startupitem.inetdnowait   yes</programlisting>
1232                </listitem>
1233              </itemizedlist>
1234            </listitem>
1235          </varlistentry>
1236
1237          <varlistentry>
1238            <term>startupitem.logevents</term>
1239
1240            <listitem>
1241              <para>Control whether or not to log events to the log file. If
1242              logevents is set, events with timestamps are logged to the
1243              logfile.</para>
1244
1245              <itemizedlist>
1246                <listitem>
1247                  <para>Type: optional</para>
1248                </listitem>
1249
1250                <listitem>
1251                  <para>Default: no</para>
1252                </listitem>
1253
1254                <listitem>
1255                  <para>Values: yes no</para>
1256                </listitem>
1257
1258                <listitem>
1259                  <para>Example:</para>
1260
1261                  <programlisting>startupitem.logevents   yes</programlisting>
1262                </listitem>
1263              </itemizedlist>
1264            </listitem>
1265          </varlistentry>
1266        </variablelist>
1267      </refsection>
1268
1269      <refsection>
1270        <title>Script StartupItems</title>
1271
1272        <para>StartupItems of type <quote>script</quote> use
1273        <command>daemondo</command> to launch a daemon
1274        <emphasis>indirectly</emphasis> via a startup script. A typical
1275        snippet of a startup script that may be used with a
1276        <quote>script</quote> StartupItem is shown below. Notice that the
1277        script is not a daemon; rather the script indirectly launches the
1278        vm-pop3d daemon.</para>
1279
1280        <programlisting>#!/bin/sh
1281#
1282case "$1" in
1283  start)
1284       echo -n "Starting vm-pop3d: "
1285       /opt/local/sbin/vm-pop3d -d 10 -t 600
1286
1287
1288[... trimmed ...]</programlisting>
1289
1290        <para>But if a script itself is a daemon, use the executable
1291        StartupItem type since that way it will be launched directly and its
1292        health tracked automatically. When using <quote>script</quote>
1293        StartupItems, the <code>startupitem.pidfile</code> keyword must be
1294        used if you want <command>daemondo</command> to monitor a daemon
1295        process and restart it if it dies.</para>
1296
1297        <note>
1298          <para>For a given port, StartupItem keywords in category
1299          <quote>script</quote> may not be used with an
1300          <quote>executable</quote> StartupItem keyword.</para>
1301        </note>
1302
1303        <variablelist>
1304          <varlistentry>
1305            <term>startupitem.start</term>
1306
1307            <term>startupitem.stop</term>
1308
1309            <term>startupitem.restart</term>
1310
1311            <listitem>
1312              <para>Specify a shell script to start, stop, and restart the
1313              daemon. In the absence of a restart key, the daemon will be
1314              restarted by taking the stop action, followed by the start
1315              action.</para>
1316
1317              <itemizedlist>
1318                <listitem>
1319                  <para>Type: optional</para>
1320                </listitem>
1321
1322                <listitem>
1323                  <para>Default: none</para>
1324                </listitem>
1325
1326                <listitem>
1327                  <para>Values: <replaceable>shell_script</replaceable></para>
1328                </listitem>
1329
1330                <listitem>
1331                  <para>Examples:</para>
1332
1333                  <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server start
1334startupitem.stop ${prefix}/share/mysql/mysql.server stop
1335startupitem.restart ${prefix}/share/mysql/mysql.server restart</programlisting>
1336                </listitem>
1337              </itemizedlist>
1338            </listitem>
1339          </varlistentry>
1340
1341          <varlistentry>
1342            <term>startupitem.init</term>
1343
1344            <listitem>
1345              <para>Shell code that will be executed prior to any of the
1346              options <code>startupitem.start</code>,
1347              <code>startupitem.stop</code> and
1348              <code>startupitem.restart</code>.</para>
1349
1350              <itemizedlist>
1351                <listitem>
1352                  <para>Type: optional</para>
1353                </listitem>
1354
1355                <listitem>
1356                  <para>Default: no</para>
1357                </listitem>
1358
1359                <listitem>
1360                  <para>Values: <replaceable>shell_script</replaceable></para>
1361                </listitem>
1362
1363                <listitem>
1364                  <para>Example:</para>
1365
1366                  <programlisting>startupitem.init  "PID=/var/run/dhcpd.pid"</programlisting>
1367                </listitem>
1368              </itemizedlist>
1369            </listitem>
1370          </varlistentry>
1371
1372          <varlistentry>
1373            <term>startupitem.pidfile</term>
1374
1375            <listitem>
1376              <para>This keyword must be defined properly for
1377              <command>daemondo</command> to be able to monitor daemons
1378              launched via <quote>script</quote> StartupItems and restart them
1379              if they die. It specifies two things: a process id (PID) file
1380              handling method, and a pidfile name and path.</para>
1381
1382              <itemizedlist>
1383                <listitem>
1384                  <para>Type: optional</para>
1385                </listitem>
1386
1387                <listitem>
1388                  <para>Default: [none] |
1389                  [<filename>${prefix}/var/run/${name}.pid</filename>]</para>
1390                </listitem>
1391
1392                <listitem>
1393                  <para>Values [none auto manual clean]
1394                  [<replaceable>/path/to/pidfile</replaceable>]</para>
1395                </listitem>
1396
1397                <listitem>
1398                  <para>Example:</para>
1399
1400                  <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
1401                </listitem>
1402              </itemizedlist>
1403
1404              <para>PID file handling options:</para>
1405
1406              <itemizedlist>
1407                <listitem>
1408                  <para><option>none</option> - daemondo will not create or
1409                  track a PID file, so it won't know when a daemon
1410                  dies.</para>
1411                </listitem>
1412
1413                <listitem>
1414                  <para><option>auto</option> - The started process is
1415                  expected to create a PID file that contains the PID of the
1416                  running daemon; daemondo then reads the PID from the file
1417                  and tracks the process. The started process must delete the
1418                  PID file if this is necessary.</para>
1419                </listitem>
1420
1421                <listitem>
1422                  <para><option>clean</option> - The started process is
1423                  expected to create a PID file that contains the PID of the
1424                  running daemon; daemondo then reads the PID from the file
1425                  and tracks the process, and deletes the PID file if it
1426                  detects the daemon has died.</para>
1427                </listitem>
1428
1429                <listitem>
1430                  <para><option>manual</option> - This option should only be
1431                  used if an <quote>executable</quote> StartupItem could be
1432                  used (daemondo launches a daemon directly)
1433                  <emphasis>and</emphasis> a port author wants a PID file
1434                  written for some special use. A PID file is not needed to
1435                  detect process death for daemons launched directly by
1436                  daemondo. As with executale StartupItems, daemondo remembers
1437                  the PID of the launched process and tracks it
1438                  automatically.</para>
1439                </listitem>
1440              </itemizedlist>
1441            </listitem>
1442          </varlistentry>
1443        </variablelist>
1444      </refsection>
1445
1446      <refsection>
1447        <title>Loading / Unloading StartupItems into launchd</title>
1448
1449        <para>A port with a StartupItem places a link to a .plist file for the
1450        port's daemon within <filename>/Library/LaunchDaemons/</filename>. A
1451        .plist file is an XML file; MacPorts installs .plist files tagged as
1452        <quote>disabled</quote> for the sake of security. You may enable a
1453        startup script (tag the.plist file as <quote>enabled</quote>) and load
1454        it into <command>launchd</command> with a single command as
1455        shown.</para>
1456
1457        <programlisting><prompt>%%</prompt> <userinput>sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
1458
1459        <para>You may stop a running startup script, disable it (tag the.plist
1460        file as <quote>disabled</quote>), and unload it from
1461        <command>launchd</command> with a single command as shown.</para>
1462
1463        <programlisting><prompt>%%</prompt> <userinput>sudo launchctl unload -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
1464      </refsection>
1465
1466      <refsection>
1467        <title>StartupItem Internals</title>
1468
1469        <para>During port installation a MacPorts StartupItem creates a .plist
1470        file in <filename>${prefix}/etc/LaunchDaemons/</filename>, and places
1471        a symbolic link to the .plist file within
1472        <filename>/Library/LaunchDaemons/</filename>.</para>
1473
1474        <para>For example, the StartupItem for the mysql5 port is
1475        <filename>org.macports.mysql5.plist</filename>, and it is linked as
1476        shown.</para>
1477
1478        <programlisting><prompt>%%</prompt> <userinput>ls -l /Library/LaunchDaemons</userinput></programlisting>
1479
1480        <screen>org.macports.mysql5.plist -&gt;
1481     /opt/local/etc/LaunchDaemons/org.macports.mysql5/org.macports.mysql5.plist</screen>
1482
1483        <para>For <quote>script</quote> StartupItems, in addition to a .plist
1484        file, a wrapper is also created.<programlisting><prompt>%%</prompt> <userinput>ls -l /opt/local/etc/LaunchDaemons/org.macports.mysql5/</userinput></programlisting><screen>-rwxr-xr-x   2 root  wheel  475 Aug  2 14:16 mysql5.wrapper
1485-rw-r--r--   2 root  wheel  975 Aug  2 14:16 org.macports.mysql5.plist</screen>The
1486        wrapper manipulates the script as specified in the startupitem.start
1487        and startupitem.stop keywords. An example wrapper script snippet is
1488        shown below.</para>
1489
1490        <programlisting>#!/bin/sh
1491#
1492# MacPorts generated daemondo support script
1493
1494# Start
1495Start()
1496{
1497        /opt/local/share/mysql5/mysql/mysql.server start
1498}
1499
1500# Stop
1501Stop()
1502{
1503        /opt/local/share/mysql5/mysql/mysql.server stop
1504}
1505
1506[... trimmed ...]</programlisting>
1507      </refsection>
1508    </refsection>
1509  </refsection>
1510
1511  <refsection>
1512    <title>Installation Phase Keyword Reference</title>
1513
1514    <para>MacPorts keywords are used to specify required or optional items
1515    within a Portfile, or to override default options used by MacPorts base
1516    for individual ports. Keywords are to be used within the "global" and
1517    "variant" sections of Portfiles, and not within optional port phase
1518    declarations.</para>
1519
1520    <para>In other words, port phase keywords are not located within port
1521    phase declarations, but rather they <emphasis>refer</emphasis> to port
1522    phases and set options for those phases, and they take affect whether or
1523    not phase declarations have been explicitly defined in a Portfile.</para>
1524
1525    <refsection>
1526      <title>A Word about Keyword List Modifiers (-append / -delete)</title>
1527
1528      <para>It is often necessary to add to a list of keyword values
1529      previously set by a previously executed Portfile keyword or by MacPorts
1530      base. To keep from overwriting a previous keyword list, use a keyword
1531      list modifier. Keywords that support list modifiers are identified under
1532      appropriate reference sections below.</para>
1533
1534      <para>The three most common uses for keyword list modifiers are to
1535      preserve configure defaults, to preserve PortGroup dependencies, and to
1536      add or delete items for variants.</para>
1537
1538      <refsection>
1539        <title>Common Uses for Keyword List Modifiers</title>
1540
1541        <para>The three most common uses for keyword list modifiers are to
1542        preserve configure defaults, to preserve PortGroup dependencies, and
1543        to add or delete items for variants.</para>
1544
1545        <variablelist>
1546          <varlistentry>
1547            <term>Preserve configure Defaults</term>
1548
1549            <listitem>
1550              <para>MacPorts base sets the gcc compiler flags CFLAGS and
1551              LDFLAGS for all ports using <literal>configure.cflags</literal>
1552              and <literal>configure.ldflags</literal>, therefore to keep from
1553              overwriting the default compiler flags use
1554              <literal>configure.cflags-append</literal> and
1555              <literal>configure.ldflags-append</literal>.</para>
1556
1557              <itemizedlist>
1558                <listitem>
1559                  <para><code>configure.cflags-append</code></para>
1560                </listitem>
1561
1562                <listitem>
1563                  <para><code>configure.ldflags-append</code></para>
1564                </listitem>
1565              </itemizedlist>
1566            </listitem>
1567          </varlistentry>
1568
1569          <varlistentry>
1570            <term>Preserve PortGroup Dependencies</term>
1571
1572            <listitem>
1573              <para>Ports in a PortGroup have default library dependencies set
1574              by MacPorts base. Therefore, never use
1575              <literal>depends_lib</literal> in ports belonging to a PortGroup
1576              or it will overwrite the default library dependencies. Instead,
1577              use <literal>depends_lib-append</literal>.</para>
1578            </listitem>
1579          </varlistentry>
1580
1581          <varlistentry>
1582            <term>Add or Delete Items for Variants</term>
1583
1584            <listitem>
1585              <para>When a variant requires more or fewer dependencies,
1586              distfiles, or patchfiles, when the variant is invoked you want
1587              to add or remove items to the appropriate keyword values list
1588              set in the global section of the Portfile. Use the appropriate
1589              keywords, for example:</para>
1590
1591              <itemizedlist>
1592                <listitem>
1593                  <para><code>depends_lib-append</code> or
1594                  <code>depends_lib-delete</code></para>
1595                </listitem>
1596
1597                <listitem>
1598                  <para><code>distfiles-append</code> or
1599                  <code>distfile-delete</code></para>
1600                </listitem>
1601
1602                <listitem>
1603                  <para><code>patchfiles-append</code> or
1604                  <code>patchfiles-delete</code></para>
1605                </listitem>
1606              </itemizedlist>
1607            </listitem>
1608          </varlistentry>
1609        </variablelist>
1610      </refsection>
1611    </refsection>
1612
1613    <refsection>
1614      <title>A Word about Keyword Argument Modifiers (.pre_args /
1615      .post_args)</title>
1616
1617      <para>Keywords that support pre_args and post_args are used to assemble
1618      command strings together in a row, as described in the reference
1619      sections below. But it should be noted that all keyword argument
1620      modifiers implicitly support keyword list modifiers. For example, the
1621      keyword <literal>configure.pre_args</literal> also supports
1622      <literal>configure.pre_args-append</literal> and
1623      <literal>configure.pre_args-delete</literal>.</para>
1624    </refsection>
1625
1626    <refsection>
1627      <title>Fetch Phase Keywords</title>
1628
1629      <para>The list of keywords related to the fetch phase.</para>
1630
1631      <variablelist>
1632        <varlistentry>
1633          <term>master_sites</term>
1634
1635          <listitem>
1636            <para>A list of URLs from which a port's download file(s) may be
1637            retrieved. For multiple master_sites, they are searched in order
1638            until a file matching <varname>${distfile}</varname> is
1639            found.</para>
1640
1641            <itemizedlist>
1642              <listitem>
1643                <para>Default: ???</para>
1644              </listitem>
1645
1646              <listitem>
1647                <para>Examples:</para>
1648
1649                <programlisting>master_sites   http://www.somesite.org/files/ \
1650               http://www.somemirror.org/somesite_org/files/
1651
1652</programlisting>
1653
1654                <para>You may also use mirror site lists predefined by
1655                MacPorts. Here the sourceforge and gnu mirrors are
1656                used.</para>
1657
1658                <programlisting>master_sites   sourceforge gnu
1659
1660</programlisting>
1661
1662                <para>When using mirror master_sites, the subdirectory
1663                <varname>${name}</varname> is checked on every mirror. If the
1664                mirror subdirectory does not match ${name}, then you may
1665                specify it using after the mirror separated by a colon.</para>
1666
1667                <programlisting>master_sites   sourceforge:widget \
1668               gnu:widget
1669
1670</programlisting>
1671
1672                <para>For ports that must fetch multiple download files from
1673                different locations, you must label the files with tags and
1674                match the tags in a distfiles statement. The format is
1675                <literal>mirror:subdirectory:tag</literal>.</para>
1676
1677                <para>In the example below, file_one.tar.gz is fetched from
1678                sourceforge mirrors in subdirectory
1679                <varname>${name}</varname>; file tagtwo.tar.gz is fetched from
1680                the gnu mirrors in subdirectory sources.</para>
1681
1682                <programlisting>master_sites    sourceforge::tagone \
1683                gnu:sources:tagtwo
1684
1685distfiles       file_one.tar.gz:tagone \
1686                file_two.tar.gz:tagtwo</programlisting>
1687              </listitem>
1688            </itemizedlist>
1689          </listitem>
1690        </varlistentry>
1691
1692        <varlistentry>
1693          <term>patch_sites</term>
1694
1695          <listitem>
1696            <para>A list of sites from which a port's patchfiles may be
1697            downloaded, where applicable.</para>
1698
1699            <itemizedlist>
1700              <listitem>
1701                <para>Default: <varname>${master_sites}</varname></para>
1702              </listitem>
1703
1704              <listitem>
1705                <para>Example:</para>
1706
1707                <programlisting>patch_sites    ftp://ftp.patchcityrepo.com/pub/magic/patches</programlisting>
1708              </listitem>
1709            </itemizedlist>
1710          </listitem>
1711        </varlistentry>
1712
1713        <varlistentry>
1714          <term>distname</term>
1715
1716          <listitem>
1717            <para>The name of the distribution filename, not including the
1718            extract suffix.</para>
1719
1720            <itemizedlist>
1721              <listitem>
1722                <para>Default: <varname>${name}-${version}</varname></para>
1723              </listitem>
1724
1725              <listitem>
1726                <para>Example:</para>
1727
1728                <programlisting>distname     ${name}</programlisting>
1729              </listitem>
1730            </itemizedlist>
1731          </listitem>
1732        </varlistentry>
1733
1734        <varlistentry>
1735          <term>distfiles</term>
1736
1737          <listitem>
1738            <para>The full distribution filename, including the extract
1739            suffix. Used to specify non-default distribution filenames; this
1740            keyword must be specified (and tags used) when a port has multiple
1741            download files (see master_sites).</para>
1742
1743            <itemizedlist>
1744              <listitem>
1745                <para>Default:
1746                <varname>${distname}${extract.suffix}</varname></para>
1747              </listitem>
1748
1749              <listitem>
1750                <para>Example:</para>
1751
1752                <programlisting>distfiles    ${name}-dev_src.tgz
1753
1754
1755distfiles       file_one.tar.gz:tagone \
1756                file_two.tar.gz:tagtwo</programlisting>
1757              </listitem>
1758            </itemizedlist>
1759          </listitem>
1760        </varlistentry>
1761
1762        <varlistentry>
1763          <term>extract.suffix</term>
1764
1765          <listitem>
1766            <para>This keyword is used to specify the extract suffix
1767            type.</para>
1768
1769            <itemizedlist>
1770              <listitem>
1771                <para>Default: <filename>.tar.gz</filename></para>
1772              </listitem>
1773
1774              <listitem>
1775                <para>Example:</para>
1776
1777                <programlisting>extract.suffix   .tgz</programlisting>
1778              </listitem>
1779            </itemizedlist>
1780          </listitem>
1781        </varlistentry>
1782
1783        <varlistentry>
1784          <term>use_bzip2</term>
1785
1786          <listitem>
1787            <para>This keyword is for downloads that are tarred and bzipped.
1788            When invoked, it automatically sets:</para>
1789
1790            <literallayout>extract.suffix = .tar.bz
1791extract.cmd = bzip
1792
1793</literallayout>
1794
1795            <itemizedlist>
1796              <listitem>
1797                <para>Default: yes</para>
1798              </listitem>
1799
1800              <listitem>
1801                <para>Example:</para>
1802
1803                <programlisting>use_bzip2     yes</programlisting>
1804              </listitem>
1805            </itemizedlist>
1806          </listitem>
1807        </varlistentry>
1808
1809        <varlistentry>
1810          <term>use_zip</term>
1811
1812          <listitem>
1813            <para>This keyword is for downloads are zipped. When invoked, it
1814            automatically sets:</para>
1815
1816            <literallayout>extract.suffix = .zip
1817extract.cmd = unzip
1818extract.pre_args = -q
1819extract.post_args = "-d ${portpath}/${workdir}"
1820
1821</literallayout>
1822
1823            <itemizedlist>
1824              <listitem>
1825                <para>Default: <option>yes</option></para>
1826              </listitem>
1827
1828              <listitem>
1829                <para>Example:</para>
1830
1831                <programlisting>use_zip       yes</programlisting>
1832              </listitem>
1833            </itemizedlist>
1834          </listitem>
1835        </varlistentry>
1836      </variablelist>
1837
1838      <refsection>
1839        <title>Fetch from CVS</title>
1840
1841        <para><ulink url="http://www.nongnu.org/cvs/">CVS</ulink> may be used
1842        as an alternative method of fetching distribution files using the
1843        keywords in this section. However, fetching via CVS may cause
1844        non-reproducible builds, so it is strongly discouraged.</para>
1845
1846        <variablelist>
1847          <varlistentry>
1848            <term>cvs.root</term>
1849
1850            <listitem>
1851              <para>Specify the url from which to fetch files.</para>
1852
1853              <itemizedlist>
1854                <listitem>
1855                  <para>Default: none</para>
1856                </listitem>
1857
1858                <listitem>
1859                  <para>Example:</para>
1860
1861                  <programlisting>cvs.root :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs</programlisting>
1862                </listitem>
1863              </itemizedlist>
1864            </listitem>
1865          </varlistentry>
1866
1867          <varlistentry>
1868            <term>cvs.tag</term>
1869
1870            <listitem>
1871              <para>Optional for fetching with CVS, this specifies the code
1872              revision to checkout.</para>
1873
1874              <itemizedlist>
1875                <listitem>
1876                  <para>Default: none</para>
1877                </listitem>
1878
1879                <listitem>
1880                  <para>Example:</para>
1881
1882                  <programlisting>cvs.tag  HEAD</programlisting>
1883                </listitem>
1884              </itemizedlist>
1885            </listitem>
1886          </varlistentry>
1887
1888          <varlistentry>
1889            <term>cvs.date</term>
1890
1891            <listitem>
1892              <para>A date that identifies the CVS code set to
1893              checkout.</para>
1894
1895              <itemizedlist>
1896                <listitem>
1897                  <para>Default: none</para>
1898                </listitem>
1899
1900                <listitem>
1901                  <para>Example:</para>
1902
1903                  <programlisting>cvs.date "12-April-2007"</programlisting>
1904                </listitem>
1905              </itemizedlist>
1906            </listitem>
1907          </varlistentry>
1908
1909          <varlistentry>
1910            <term>cvs.module</term>
1911
1912            <listitem>
1913              <para>A CVS module from which to check out the code.</para>
1914
1915              <itemizedlist>
1916                <listitem>
1917                  <para>Default: none</para>
1918                </listitem>
1919
1920                <listitem>
1921                  <para>Example:</para>
1922
1923                  <programlisting>cvs.module  Sources</programlisting>
1924                </listitem>
1925              </itemizedlist>
1926            </listitem>
1927          </varlistentry>
1928        </variablelist>
1929      </refsection>
1930
1931      <refsection>
1932        <title>Fetch from Subversion</title>
1933
1934        <para><ulink url="http://subversion.tigris.org/">Subversion</ulink>
1935        may be used as an alternative method of fetching distribution files
1936        using the keywords in this section. However, fetching via Subversion
1937        may cause non-reproducible builds, so it is strongly
1938        discouraged.</para>
1939
1940        <variablelist>
1941          <varlistentry>
1942            <term>svn.url</term>
1943
1944            <listitem>
1945              <para>This specifies the url from which to fetch files.</para>
1946
1947              <itemizedlist>
1948                <listitem>
1949                  <para>Default: none</para>
1950                </listitem>
1951
1952                <listitem>
1953                  <para>Examples:</para>
1954
1955                  <programlisting>svn.url http://www.domain.com/svn-repo/mydirectory
1956svn.url svn://www.domain.com/svn-repo/mydirectory
1957</programlisting>
1958                </listitem>
1959              </itemizedlist>
1960            </listitem>
1961          </varlistentry>
1962
1963          <varlistentry>
1964            <term>svn.tag</term>
1965
1966            <listitem>
1967              <para>Optional tag for fetching with Subversion, this specifies
1968              the code revision to checkout; it corresponds to the -r option
1969              in the svn cli. You must use backslashes to escape characters
1970              that are meaningful to the Tcl interpreter, such as braces and
1971              double quotes.</para>
1972
1973              <itemizedlist>
1974                <listitem>
1975                  <para>Default: none</para>
1976                </listitem>
1977
1978                <listitem>
1979                  <para>Examples:</para>
1980
1981                  <programlisting>svn.tag 37192
1982svn.tag \{\"2006-02-17 15:30 +0230\"\}</programlisting>
1983                </listitem>
1984              </itemizedlist>
1985            </listitem>
1986          </varlistentry>
1987        </variablelist>
1988      </refsection>
1989    </refsection>
1990
1991    <refsection>
1992      <title>Checksum Phase Keywords</title>
1993
1994      <para>The list of keywords related to the checksum phase.</para>
1995
1996      <variablelist>
1997        <varlistentry>
1998          <term>checksums</term>
1999
2000          <listitem>
2001            <para>Checksum(s) of the distribution files. For ports with
2002            multiple distribution files, filenames must be included to
2003            associate files with their checksums.</para>
2004
2005            <itemizedlist>
2006              <listitem>
2007                <para>Default: ???</para>
2008              </listitem>
2009
2010              <listitem>
2011                <para>Examples:</para>
2012
2013                <programlisting>checksums     md5 dafa161bc9c61e57636a6085c87c1fe8 \
2014              sha1 5da610e1c8bc01b80abc21ab9e98e004363b429c \
2015              rmd160 0c1147242adf476f5e93f4d59b553ee3ea378b23</programlisting>
2016
2017                <programlisting>checksums     ${distname}${extract.suffix} md5 dafa161bc9c61e57636a6085c87c1fe8 \
2018                  sha1 5da610e1c8bc01b80abc21ab9e98e004363b429c \
2019                  rmd160 0c1147242adf476f5e93f4d59b553ee3ea378b23 \
2020              hobbit.tar.gz md5 3b8d02c6cf6239b9bdadbc6543c5a683 \
2021                  sha1 27874638b23e66d39ed94fe716ca25c967f6e993 \
2022                  rmd160 82b9991f3bf0ceedbf74c188c5fa44b98b5e40c9</programlisting>
2023              </listitem>
2024            </itemizedlist>
2025          </listitem>
2026        </varlistentry>
2027      </variablelist>
2028    </refsection>
2029
2030    <refsection>
2031      <title>Extract Phase Keywords</title>
2032
2033      <para>The list of keywords related to the extract phase.</para>
2034
2035      <variablelist>
2036        <varlistentry>
2037          <term>extract.only</term>
2038
2039          <term>extract.only-append</term>
2040
2041          <term>extract.only-delete</term>
2042
2043          <listitem>
2044            <para>List of files to extract into
2045            <varname>${worksrcpath}</varname>; the default is
2046            <varname>${distfiles}</varname>. Only use if default extract
2047            behavior is not correct for your port.</para>
2048
2049            <itemizedlist>
2050              <listitem>
2051                <para>Default: none</para>
2052              </listitem>
2053
2054              <listitem>
2055                <para>Example:</para>
2056
2057                <programlisting>extract.only     foo.tar.gz
2058
2059</programlisting>
2060              </listitem>
2061            </itemizedlist>
2062          </listitem>
2063
2064          <listitem>
2065            <para>List modifier examples:</para>
2066
2067            <programlisting>extract.only-append  bar.tar.gz
2068extract.only-delete  foo.tar.gz</programlisting>
2069          </listitem>
2070        </varlistentry>
2071
2072        <varlistentry>
2073          <term>extract.cmd</term>
2074
2075          <listitem>
2076            <para>Command to perform extraction.</para>
2077
2078            <itemizedlist>
2079              <listitem>
2080                <para>Default: gzip</para>
2081              </listitem>
2082
2083              <listitem>
2084                <para>Example:</para>
2085
2086                <programlisting>extract.cmd     gunzip</programlisting>
2087              </listitem>
2088            </itemizedlist>
2089          </listitem>
2090        </varlistentry>
2091
2092        <varlistentry>
2093          <term>extract.args</term>
2094
2095          <term>extract.pre_args</term>
2096
2097          <term>extract.post_args</term>
2098
2099          <listitem>
2100            <para>Main arguments to extract.cmd; additional arguments passed
2101            before and after the main arguments.</para>
2102
2103            <itemizedlist>
2104              <listitem>
2105                <para>Default: ${distpath}/${distfile}</para>
2106              </listitem>
2107
2108              <listitem>
2109                <para>Example:</para>
2110
2111                <programlisting>extract.args      ${distpath}/${distfile}
2112
2113</programlisting>
2114              </listitem>
2115            </itemizedlist>
2116          </listitem>
2117
2118          <listitem>
2119            <para>The following argument modifiers are available:</para>
2120
2121            <itemizedlist>
2122              <listitem>
2123                <para>extract.pre_args default: "-dc"</para>
2124              </listitem>
2125
2126              <listitem>
2127                <para>extract.post_args default: " | tar -xf"</para>
2128              </listitem>
2129
2130              <listitem>
2131                <para>Examples:</para>
2132
2133                <programlisting>extract.pre_args     xf
2134extract.post_args    "| gnutar –x"</programlisting>
2135              </listitem>
2136            </itemizedlist>
2137          </listitem>
2138        </varlistentry>
2139      </variablelist>
2140    </refsection>
2141
2142    <refsection>
2143      <title>Patch Phase Keywords</title>
2144
2145      <para>The list of keywords related to the patch phase.</para>
2146
2147      <variablelist>
2148        <varlistentry>
2149          <term>patch.dir</term>
2150
2151          <listitem>
2152            <para>Specify the base path for patch files.</para>
2153
2154            <itemizedlist>
2155              <listitem>
2156                <para>Default: <varname>${worksrcpath}</varname></para>
2157              </listitem>
2158
2159              <listitem>
2160                <para>Example:</para>
2161
2162                <programlisting>patch.dir      ${worksrcpath}/util</programlisting>
2163              </listitem>
2164            </itemizedlist>
2165          </listitem>
2166        </varlistentry>
2167
2168        <varlistentry>
2169          <term>patch.cmd</term>
2170
2171          <listitem>
2172            <para>Specify the command to be used for patching files.</para>
2173
2174            <itemizedlist>
2175              <listitem>
2176                <para>Default: <command>patch</command></para>
2177              </listitem>
2178
2179              <listitem>
2180                <para>Example:</para>
2181
2182                <programlisting>patch.cmd      cat</programlisting>
2183              </listitem>
2184            </itemizedlist>
2185          </listitem>
2186        </varlistentry>
2187
2188        <varlistentry>
2189          <term>patchfiles</term>
2190
2191          <term>patchfiles-append</term>
2192
2193          <term>patchfiles-delete</term>
2194
2195          <listitem>
2196            <para>Specify patch files to be applied for a port; list modifiers
2197            specify patchfiles to be added or removed from a previous
2198            patchfile declaration.</para>
2199
2200            <itemizedlist>
2201              <listitem>
2202                <para>Default: none</para>
2203              </listitem>
2204
2205              <listitem>
2206                <para>Example:</para>
2207
2208                <programlisting>patchfiles     patch-Makefile.in \
2209               patch-source.c
2210
2211</programlisting>
2212              </listitem>
2213            </itemizedlist>
2214          </listitem>
2215
2216          <listitem>
2217            <para>List modifier examples:</para>
2218
2219            <programlisting>patchfiles-append   patch-configure
2220patchfiles-delete   patch-src-Makefile.in
2221</programlisting>
2222          </listitem>
2223        </varlistentry>
2224
2225        <varlistentry>
2226          <term>patch.args</term>
2227
2228          <term>patch.pre_args</term>
2229
2230          <term>patch.post_args</term>
2231
2232          <listitem>
2233            <para>Main arguments to patch.cmd; optional argument modifiers
2234            pass arguments before and after the main arguments.</para>
2235
2236            <itemizedlist>
2237              <listitem>
2238                <para>Default: none</para>
2239              </listitem>
2240
2241              <listitem>
2242                <para>Example:</para>
2243
2244                <programlisting>patch.args   ???
2245
2246</programlisting>
2247              </listitem>
2248            </itemizedlist>
2249          </listitem>
2250
2251          <listitem>
2252            <para>The following argument modifiers are available:</para>
2253
2254            <itemizedlist>
2255              <listitem>
2256                <para>patch.pre_args default: -p0</para>
2257              </listitem>
2258
2259              <listitem>
2260                <para>patch.post_args default: none</para>
2261              </listitem>
2262
2263              <listitem>
2264                <para>Examples:</para>
2265
2266                <programlisting>patch.pre_args     -p1
2267patch.post_args    ???</programlisting>
2268              </listitem>
2269            </itemizedlist>
2270          </listitem>
2271        </varlistentry>
2272      </variablelist>
2273    </refsection>
2274
2275    <refsection>
2276      <title>Configure Phase Keywords</title>
2277
2278      <para>The list of keywords related to the configure phase.</para>
2279
2280      <para>MacPorts base sets some important default configure options, so
2281      should use the -append version of most configure keywords so you don't
2282      overwrite them. For example, MacPorts base sets default
2283      <literal>configure.cflags</literal> so you should always use
2284      <literal>configure.cflags-append</literal> to set additional CFLAGS in
2285      Portfiles.</para>
2286
2287      <variablelist>
2288        <varlistentry>
2289          <term>configure.env</term>
2290
2291          <term>configure.env-append</term>
2292
2293          <term>configure.env-delete</term>
2294
2295          <listitem>
2296            <para>Set environment variables for configure; list modifiers add
2297            and delete items from a previous Portfile configure.env keyword,
2298            or a default set by MacPorts base. If available, it is encouraged
2299            to use the predefined options (like configure.cflags) instead of
2300            modifying configure.env directly</para>
2301
2302            <itemizedlist>
2303              <listitem>
2304                <para>Default: <literal>CFLAGS=-I${prefix}/include
2305                LDFLAGS=-L${prefix}/lib</literal></para>
2306              </listitem>
2307
2308              <listitem>
2309                <para>Example:</para>
2310
2311                <programlisting>configure.env   QTDIR=${prefix}/lib/qt3
2312</programlisting>
2313              </listitem>
2314            </itemizedlist>
2315          </listitem>
2316
2317          <listitem>
2318            <para>List modifier examples:</para>
2319
2320            <programlisting>configure.env-append   ABI=32
2321configure.env-delete   TCLROOT=${prefix}</programlisting>
2322          </listitem>
2323        </varlistentry>
2324
2325        <varlistentry>
2326          <term>configure.cflags</term>
2327
2328          <term>configure.cflags-append</term>
2329
2330          <term>configure.cflags-delete</term>
2331
2332          <listitem>
2333            <para>Set CFLAGS compiler flags; list modifiers add or delete
2334            items from a previous Portfile configure.cflags keyword or the
2335            default set by MacPorts base.</para>
2336
2337            <itemizedlist>
2338              <listitem>
2339                <para>Default: <literal>-O2</literal></para>
2340              </listitem>
2341
2342              <listitem>
2343                <para>Example:</para>
2344
2345                <programlisting>configure.cflags    -Os -flat_namespace
2346
2347</programlisting>
2348              </listitem>
2349            </itemizedlist>
2350          </listitem>
2351
2352          <listitem>
2353            <para>List modifier examples:</para>
2354
2355            <programlisting>configure.cflags-append   "-undefined suppress"
2356configure.cflags-delete   -O2</programlisting>
2357          </listitem>
2358        </varlistentry>
2359
2360        <varlistentry>
2361          <term>configure.ldflags</term>
2362
2363          <term>configure.ldflags-append</term>
2364
2365          <term>configure.ldflags-delete</term>
2366
2367          <listitem>
2368            <para>Set LDFLAGS compiler flags; list modifiers add or delete
2369            items from a previous Portfile configure.ldflags keyword or the
2370            default set by MacPorts base.</para>
2371
2372            <itemizedlist>
2373              <listitem>
2374                <para>Default: <literal>-L${prefix}/lib</literal></para>
2375              </listitem>
2376
2377              <listitem>
2378                <para>Example:</para>
2379
2380                <programlisting>configure.ldflags    -L${worksrcpath}/zlib -lz
2381
2382</programlisting>
2383              </listitem>
2384            </itemizedlist>
2385          </listitem>
2386
2387          <listitem>
2388            <para>List modifier examples:</para>
2389
2390            <programlisting>configure.ldflags-append   "-L/usr/X11R6/lib -L${worksrcpath}/lib"
2391configure.ldflags-delete   -L${prefix}/lib/db44</programlisting>
2392          </listitem>
2393        </varlistentry>
2394
2395        <varlistentry>
2396          <term>configure.cppflags</term>
2397
2398          <term>configure.cppflags-append</term>
2399
2400          <term>configure.cppflags-delete</term>
2401
2402          <listitem>
2403            <para>Set CPPFLAGS to be passed to the C processor; list modifiers
2404            add or delete items from a previous Portfile configure.cppflags
2405            keyword or the default set by MacPorts base.</para>
2406
2407            <itemizedlist>
2408              <listitem>
2409                <para>Default: <literal>-I${prefix}/include</literal></para>
2410              </listitem>
2411
2412              <listitem>
2413                <para>Example:</para>
2414
2415                <programlisting>configure.cppflags    -I${worksrcpath}/include
2416
2417</programlisting>
2418              </listitem>
2419            </itemizedlist>
2420          </listitem>
2421
2422          <listitem>
2423            <para>List modifier examples:</para>
2424
2425            <programlisting>configure.cppflags-append   "-I/usr/X11R6/lib -I${worksrcpath}/lib -DHAVE_RRD_12X"
2426configure.cppflags-delete   -I${prefix}/lib/db44</programlisting>
2427          </listitem>
2428        </varlistentry>
2429
2430        <!-- fortran compiler options -->
2431
2432        <varlistentry>
2433          <term>configure.fflags</term>
2434
2435          <term>configure.fflags-append</term>
2436
2437          <term>configure.fflags-delete</term>
2438
2439          <listitem>
2440            <para>Set FFLAGS to be passed to the Fortran compiler; list
2441            modifiers add or delete items from a previous Portfile
2442            configure.fflags keyword or the default set by MacPorts
2443            base.</para>
2444
2445            <itemizedlist>
2446              <listitem>
2447                <para>Default: <literal>-O2</literal></para>
2448              </listitem>
2449
2450              <listitem>
2451                <para>Example:</para>
2452
2453                <programlisting>configure.fflags    -Os
2454
2455</programlisting>
2456              </listitem>
2457            </itemizedlist>
2458          </listitem>
2459        </varlistentry>
2460
2461        <varlistentry>
2462          <term>configure.fcflags</term>
2463
2464          <term>configure.fcflags-append</term>
2465
2466          <term>configure.fcflags-delete</term>
2467
2468          <listitem>
2469            <para>Set FCFLAGS to be passed to the Fortran compiler; list
2470            modifiers add or delete items from a previous Portfile
2471            configure.fcflags keyword or the default set by MacPorts
2472            base.</para>
2473
2474            <itemizedlist>
2475              <listitem>
2476                <para>Default: <literal>-O2</literal></para>
2477              </listitem>
2478
2479              <listitem>
2480                <para>Example:</para>
2481
2482                <programlisting>configure.fcflags    -Os
2483
2484</programlisting>
2485              </listitem>
2486            </itemizedlist>
2487          </listitem>
2488        </varlistentry>
2489
2490        <varlistentry>
2491          <term>configure.f90flags</term>
2492
2493          <term>configure.f90flags-append</term>
2494
2495          <term>configure.f90flags-delete</term>
2496
2497          <listitem>
2498            <para>Set F90FLAGS to be passed to the Fortran 90 compiler; list
2499            modifiers add or delete items from a previous Portfile
2500            configure.f90flags keyword or the default set by MacPorts
2501            base.</para>
2502
2503            <itemizedlist>
2504              <listitem>
2505                <para>Default: <literal>-O2</literal></para>
2506              </listitem>
2507
2508              <listitem>
2509                <para>Example:</para>
2510
2511                <programlisting>configure.f90flags    -Os
2512
2513</programlisting>
2514              </listitem>
2515            </itemizedlist>
2516          </listitem>
2517        </varlistentry>
2518
2519        <!-- fortran compiler options end -->
2520
2521        <!-- compiler selection arguments -->
2522
2523        <varlistentry>
2524          <term>configure.cc</term>
2525
2526          <listitem>
2527            <para>Set CC compiler flags for selecting a C compiler;</para>
2528
2529            <itemizedlist>
2530              <listitem>
2531                <para>Default: <literal></literal></para>
2532              </listitem>
2533
2534              <listitem>
2535                <para>Example:</para>
2536
2537                <programlisting>configure.cc    ${prefix}/bin/gcc-mp-4.2</programlisting>
2538              </listitem>
2539            </itemizedlist>
2540          </listitem>
2541        </varlistentry>
2542
2543        <varlistentry>
2544          <term>configure.cpp</term>
2545
2546          <listitem>
2547            <para>Set CPP compiler flags for selecting a C
2548            preprocessor;</para>
2549
2550            <itemizedlist>
2551              <listitem>
2552                <para>Default: <literal></literal></para>
2553              </listitem>
2554
2555              <listitem>
2556                <para>Example:</para>
2557
2558                <programlisting>configure.cpp    /usr/bin/cpp-3.3</programlisting>
2559              </listitem>
2560            </itemizedlist>
2561          </listitem>
2562        </varlistentry>
2563
2564        <varlistentry>
2565          <term>configure.cxx</term>
2566
2567          <listitem>
2568            <para>Set CXX compiler flags for selecting a C++ compiler;</para>
2569
2570            <itemizedlist>
2571              <listitem>
2572                <para>Default: <literal></literal></para>
2573              </listitem>
2574
2575              <listitem>
2576                <para>Example:</para>
2577
2578                <programlisting>configure.cpp    /usr/bin/g++-4.0</programlisting>
2579              </listitem>
2580            </itemizedlist>
2581          </listitem>
2582        </varlistentry>
2583
2584        <varlistentry>
2585          <term>configure.objc</term>
2586
2587          <listitem>
2588            <para>Set OBJC compiler flags for selecting an Objective-C
2589            compiler;</para>
2590
2591            <itemizedlist>
2592              <listitem>
2593                <para>Default: <literal></literal></para>
2594              </listitem>
2595
2596              <listitem>
2597                <para>Example:</para>
2598
2599                <programlisting>configure.objc    /usr/bin/gcc-4.0</programlisting>
2600              </listitem>
2601            </itemizedlist>
2602          </listitem>
2603        </varlistentry>
2604
2605        <varlistentry>
2606          <term>configure.fc</term>
2607
2608          <listitem>
2609            <para>Set FC compiler flags for selecting a Fortran
2610            compiler;</para>
2611
2612            <itemizedlist>
2613              <listitem>
2614                <para>Default: <literal></literal></para>
2615              </listitem>
2616
2617              <listitem>
2618                <para>Example:</para>
2619
2620                <programlisting>configure.fc    ${prefix}/bin/gfortran-mp-4.2</programlisting>
2621              </listitem>
2622            </itemizedlist>
2623          </listitem>
2624        </varlistentry>
2625
2626        <varlistentry>
2627          <term>configure.f77</term>
2628
2629          <listitem>
2630            <para>Set F77 compiler flags for selecting a Fortran 77
2631            compiler;</para>
2632
2633            <itemizedlist>
2634              <listitem>
2635                <para>Default: <literal></literal></para>
2636              </listitem>
2637
2638              <listitem>
2639                <para>Example:</para>
2640
2641                <programlisting>configure.f77    ${prefix}/bin/gfortran-mp-4.2</programlisting>
2642              </listitem>
2643            </itemizedlist>
2644          </listitem>
2645        </varlistentry>
2646
2647        <varlistentry>
2648          <term>configure.f90</term>
2649
2650          <listitem>
2651            <para>Set F90 compiler flags for selecting a Fortran 90
2652            compiler;</para>
2653
2654            <itemizedlist>
2655              <listitem>
2656                <para>Default: <literal></literal></para>
2657              </listitem>
2658
2659              <listitem>
2660                <para>Example:</para>
2661
2662                <programlisting>configure.f90    ${prefix}/bin/gfortran-mp-4.2</programlisting>
2663              </listitem>
2664            </itemizedlist>
2665          </listitem>
2666        </varlistentry>
2667
2668        <varlistentry>
2669          <term>configure.javac</term>
2670
2671          <listitem>
2672            <para>Set JAVAC compiler flags for selecting a Java
2673            compiler;</para>
2674
2675            <itemizedlist>
2676              <listitem>
2677                <para>Default: <literal></literal></para>
2678              </listitem>
2679
2680              <listitem>
2681                <para>Example:</para>
2682
2683                <programlisting>configure.javac    ${prefix}/bin/jikes</programlisting>
2684              </listitem>
2685            </itemizedlist>
2686          </listitem>
2687        </varlistentry>
2688
2689        <!-- compiler selection arguments end -->
2690
2691        <!-- interpreter selection arguments -->
2692
2693        <varlistentry>
2694          <term>configure.perl</term>
2695
2696          <listitem>
2697            <para>Set PERL flag for selecting a Perl interpreter;</para>
2698
2699            <itemizedlist>
2700              <listitem>
2701                <para>Default: <literal></literal></para>
2702              </listitem>
2703
2704              <listitem>
2705                <para>Example:</para>
2706
2707                <programlisting>configure.perl    ${prefix}/bin/perl5.8</programlisting>
2708              </listitem>
2709            </itemizedlist>
2710          </listitem>
2711        </varlistentry>
2712
2713        <varlistentry>
2714          <term>configure.python</term>
2715
2716          <listitem>
2717            <para>Set PYTHON flag for selecting a Python interpreter;</para>
2718
2719            <itemizedlist>
2720              <listitem>
2721                <para>Default: <literal></literal></para>
2722              </listitem>
2723
2724              <listitem>
2725                <para>Example:</para>
2726
2727                <programlisting>configure.python    ${prefix}/bin/python3.0</programlisting>
2728              </listitem>
2729            </itemizedlist>
2730          </listitem>
2731        </varlistentry>
2732
2733        <varlistentry>
2734          <term>configure.ruby</term>
2735
2736          <listitem>
2737            <para>Set RUBY flag for selecting a Ruby interpreter;</para>
2738
2739            <itemizedlist>
2740              <listitem>
2741                <para>Default: <literal></literal></para>
2742              </listitem>
2743
2744              <listitem>
2745                <para>Example:</para>
2746
2747                <programlisting>configure.ruby    ${prefix}/bin/ruby</programlisting>
2748              </listitem>
2749            </itemizedlist>
2750          </listitem>
2751        </varlistentry>
2752
2753        <!-- interpreter selection arguments end -->
2754
2755        <varlistentry>
2756          <term>configure.args</term>
2757
2758          <term>configure.pre_args</term>
2759
2760          <term>configure.post_args</term>
2761
2762          <listitem>
2763            <para>Main arguments to configure.cmd; optional argument modifiers
2764            pass arguments before and after the main arguments.</para>
2765
2766            <itemizedlist>
2767              <listitem>
2768                <para>Default: none</para>
2769              </listitem>
2770
2771              <listitem>
2772                <para>Example:</para>
2773
2774                <programlisting>configure.args    --bindir=${prefix}/bin
2775
2776</programlisting>
2777              </listitem>
2778            </itemizedlist>
2779          </listitem>
2780
2781          <listitem>
2782            <para>The following argument modifiers are available:</para>
2783
2784            <itemizedlist>
2785              <listitem>
2786                <para>configure.pre_args default: --prefix=${prefix}</para>
2787              </listitem>
2788
2789              <listitem>
2790                <para>configure.post_args default: none</para>
2791              </listitem>
2792
2793              <listitem>
2794                <para>Examples:</para>
2795
2796                <programlisting>configure.pre_args   --prefix=${prefix}/share/bro
2797configure.post_args  OPT="-D__DARWIN_UNIX03"</programlisting>
2798              </listitem>
2799            </itemizedlist>
2800          </listitem>
2801        </varlistentry>
2802      </variablelist>
2803
2804      <refsection>
2805        <title>Configure Universal</title>
2806
2807        <para>Universal keywords are used to make a port compile on the OS X
2808        platform to run on either PPC or Intel.</para>
2809
2810        <note>
2811          <para>There is a default universal variant made available to all
2812          ports by MacPorts base, so redefining universal keywords should only
2813          be done to make a given port compile if the default options fail to
2814          do so.</para>
2815        </note>
2816
2817        <variablelist>
2818          <varlistentry>
2819            <term>configure.universal_args</term>
2820
2821            <listitem>
2822              <para>Arguments used in the configure script to build the port
2823              universal.</para>
2824
2825              <itemizedlist>
2826                <listitem>
2827                  <para>Default: --disable-dependency-tracking</para>
2828                </listitem>
2829
2830                <listitem>
2831                  <para>Example:</para>
2832
2833                  <programlisting></programlisting>
2834                </listitem>
2835              </itemizedlist>
2836            </listitem>
2837          </varlistentry>
2838
2839          <varlistentry>
2840            <term>configure.universal_cflags</term>
2841
2842            <listitem>
2843              <para>Arguments appended to the configure script to build the
2844              port universal.</para>
2845
2846              <itemizedlist>
2847                <listitem>
2848                  <para>Default: -sysroot /Developer/SDKs/MacOSX10.4u.sdk
2849                  -arch i386 -arch ppc</para>
2850                </listitem>
2851
2852                <listitem>
2853                  <para>Example:</para>
2854
2855                  <programlisting></programlisting>
2856                </listitem>
2857              </itemizedlist>
2858            </listitem>
2859          </varlistentry>
2860
2861          <varlistentry>
2862            <term>configure.universal_cppflags</term>
2863
2864            <listitem>
2865              <para>Additional flags to put in the CPPFLAGS environment
2866              variable when invoking the configure script.</para>
2867
2868              <itemizedlist>
2869                <listitem>
2870                  <para>Default: ???</para>
2871                </listitem>
2872
2873                <listitem>
2874                  <para>Example:</para>
2875
2876                  <programlisting></programlisting>
2877                </listitem>
2878              </itemizedlist>
2879            </listitem>
2880          </varlistentry>
2881
2882          <varlistentry>
2883            <term>configure.universal_cxxflags</term>
2884
2885            <listitem>
2886              <para>Additional flags to put in the CXXFLAGS environment
2887              variable when invoking the configure script.</para>
2888
2889              <itemizedlist>
2890                <listitem>
2891                  <para>Default: -isysroot /Developer/SDKs/MacOSX10.4u.sdk
2892                  -arch i386 -arch ppc</para>
2893                </listitem>
2894
2895                <listitem>
2896                  <para>Example:</para>
2897
2898                  <programlisting></programlisting>
2899                </listitem>
2900              </itemizedlist>
2901            </listitem>
2902          </varlistentry>
2903
2904          <varlistentry>
2905            <term>configure.universal_ldflags</term>
2906
2907            <listitem>
2908              <para>Additional flags to put in the LDFLAGS environment
2909              variable when invoking the configure script.</para>
2910
2911              <itemizedlist>
2912                <listitem>
2913                  <para>Default: -arch i386 -arch ppc</para>
2914                </listitem>
2915
2916                <listitem>
2917                  <para>Example:</para>
2918
2919                  <programlisting></programlisting>
2920                </listitem>
2921              </itemizedlist>
2922            </listitem>
2923          </varlistentry>
2924        </variablelist>
2925      </refsection>
2926
2927      <refsection>
2928        <title>Automake and Autoconf</title>
2929
2930        <para>The list of configure keywords available for ports that need
2931        automake and/or autoconf.</para>
2932
2933        <variablelist>
2934          <varlistentry>
2935            <term>use_automake</term>
2936
2937            <listitem>
2938              <para>Whether or not to use automake; the default is
2939              "no".</para>
2940
2941              <programlisting>use_automake      yes</programlisting>
2942            </listitem>
2943          </varlistentry>
2944
2945          <varlistentry>
2946            <term>automake.env</term>
2947
2948            <listitem>
2949              <para>Environment variables to pass to automake.</para>
2950
2951              <programlisting>automake.env      CFLAGS=-I${prefix}/include</programlisting>
2952            </listitem>
2953          </varlistentry>
2954
2955          <varlistentry>
2956            <term>automake.args</term>
2957
2958            <listitem>
2959              <para>Arguments to pass to automake.</para>
2960
2961              <programlisting>automake.args     --foreign</programlisting>
2962            </listitem>
2963          </varlistentry>
2964
2965          <varlistentry>
2966            <term>automake.dir</term>
2967
2968            <listitem>
2969              <para>Directory in which to run
2970              <varname>${automake.cmd}</varname>; the default is
2971              <varname>${worksrcpath}</varname>.</para>
2972
2973              <programlisting>automake.dir      ./src</programlisting>
2974            </listitem>
2975          </varlistentry>
2976
2977          <varlistentry>
2978            <term>use_autoconf</term>
2979
2980            <listitem>
2981              <para>Whether or not to use autoconf; the default is
2982              "no".</para>
2983
2984              <programlisting>use_autoconf      yes</programlisting>
2985            </listitem>
2986          </varlistentry>
2987
2988          <varlistentry>
2989            <term>autoconf.env</term>
2990
2991            <listitem>
2992              <para>Environmental variables to pass to autoconf.</para>
2993
2994              <programlisting>autoconf.env      CFLAGS=-I${prefix}/include/gtk12</programlisting>
2995            </listitem>
2996          </varlistentry>
2997
2998          <varlistentry>
2999            <term>autoconf.args</term>
3000
3001            <listitem>
3002              <para>Arguments to pass to autoconf.</para>
3003
3004              <programlisting>autoconf.args     -l src/aclocaldir</programlisting>
3005            </listitem>
3006          </varlistentry>
3007
3008          <varlistentry>
3009            <term>autoconf.dir</term>
3010
3011            <listitem>
3012              <para>Directory in which to run
3013              <varname>${autoconf.cmd}</varname>; the default is
3014              <varname>${worksrcpath}</varname>.</para>
3015
3016              <programlisting>autoconf.dir      src</programlisting>
3017            </listitem>
3018          </varlistentry>
3019        </variablelist>
3020      </refsection>
3021    </refsection>
3022
3023    <refsection>
3024      <title>Build Phase Keywords</title>
3025
3026      <para>The list of keywords related to the build phase.</para>
3027
3028      <variablelist>
3029        <varlistentry>
3030          <term>build.cmd</term>
3031
3032          <listitem>
3033            <para>Make command to run in <varname>${worksrcdir}</varname>; the
3034            default is "make".</para>
3035
3036            <programlisting>build.cmd      pbxbuild</programlisting>
3037          </listitem>
3038        </varlistentry>
3039
3040        <varlistentry>
3041          <term>build.type</term>
3042
3043          <listitem>
3044            <para>Defines which "make" is required: "gnu" or "bsd". Sets
3045            build.cmd to either "gnumake" or "bsdmake" accordingly.</para>
3046
3047            <programlisting>build.type     gnu</programlisting>
3048          </listitem>
3049        </varlistentry>
3050
3051        <varlistentry>
3052          <term>build.args</term>
3053
3054          <term>build.pre_args</term>
3055
3056          <term>build.post_args</term>
3057
3058          <listitem>
3059            <para>Main arguments to build.cmd; optional argument modifiers
3060            pass arguments before and after the main arguments.</para>
3061
3062            <itemizedlist>
3063              <listitem>
3064                <para>Default: none</para>
3065              </listitem>
3066
3067              <listitem>
3068                <para>Example:</para>
3069
3070                <programlisting>build.args    -DNOWARN
3071
3072</programlisting>
3073              </listitem>
3074            </itemizedlist>
3075          </listitem>
3076
3077          <listitem>
3078            <para>The following argument modifiers are available:</para>
3079
3080            <itemizedlist>
3081              <listitem>
3082                <para>build.pre_args default:
3083                <varname>${build.target.current}</varname></para>
3084              </listitem>
3085
3086              <listitem>
3087                <para>build.post_args default: none</para>
3088              </listitem>
3089
3090              <listitem>
3091                <para>Examples:</para>
3092
3093                <programlisting>build.pre_args  -project AudioSlicer.xcode
3094build.post_args CFLAGS_SYS="-DUSE_FREETYPE -DPREFER_FREETYPE"</programlisting>
3095              </listitem>
3096            </itemizedlist>
3097          </listitem>
3098        </varlistentry>
3099
3100        <varlistentry>
3101          <term>build.target</term>
3102
3103          <term>build.target-append</term>
3104
3105          <term>build.target-delete</term>
3106
3107          <listitem>
3108            <para>Build target to pass to ${build.cmd}; list modifiers add or
3109            delete items from a previous Portfile build.target keyword or the
3110            default set by MacPorts base.</para>
3111
3112            <itemizedlist>
3113              <listitem>
3114                <para>Default: all</para>
3115              </listitem>
3116
3117              <listitem>
3118                <para>Example:</para>
3119
3120                <programlisting>build.target    all-src
3121
3122</programlisting>
3123              </listitem>
3124            </itemizedlist>
3125          </listitem>
3126
3127          <listitem>
3128            <para>List modifier examples:</para>
3129
3130            <programlisting>build.target-append   doc extra
3131build.target-delete   compat</programlisting>
3132          </listitem>
3133        </varlistentry>
3134      </variablelist>
3135    </refsection>
3136
3137    <refsection>
3138      <title>Destroot Phase Keywords</title>
3139
3140      <para>The list of keywords related to the destroot phase.</para>
3141
3142      <variablelist>
3143        <varlistentry>
3144          <term>destroot.cmd</term>
3145
3146          <listitem>
3147            <para>Install command to run relative to
3148            <varname>${worksrcdir}</varname>; default is
3149            <varname>${build.cmd}</varname>.</para>
3150
3151            <programlisting>destroot.cmd         pbxbuild</programlisting>
3152          </listitem>
3153        </varlistentry>
3154
3155        <varlistentry>
3156          <term>destroot.type</term>
3157
3158          <listitem>
3159            <para>Defines which "make" is required: either "gnu" or "bsd".
3160            Sets install.cmd to either "gnumake" or "bsdmake"
3161            accordingly.</para>
3162
3163            <programlisting>destroot.type        gnu</programlisting>
3164          </listitem>
3165        </varlistentry>
3166
3167        <varlistentry>
3168          <term>destroot.args</term>
3169
3170          <term>destroot.pre_args</term>
3171
3172          <term>destroot.post_args</term>
3173
3174          <listitem>
3175            <para>Main arguments to ${destroot.cmd}; optional argument
3176            modifiers pass arguments before and after the main
3177            arguments.</para>
3178
3179            <itemizedlist>
3180              <listitem>
3181                <para>Default: none</para>
3182              </listitem>
3183
3184              <listitem>
3185                <para>Example:</para>
3186
3187                <programlisting>destroot.args    BINDIR=${prefix}/bin
3188
3189</programlisting>
3190              </listitem>
3191            </itemizedlist>
3192          </listitem>
3193
3194          <listitem>
3195            <para>The following argument modifiers are available:</para>
3196
3197            <itemizedlist>
3198              <listitem>
3199                <para>destroot.pre_args default:
3200                <varname>${destroot.target}</varname></para>
3201              </listitem>
3202
3203              <listitem>
3204                <para>destroot.post_args default: none</para>
3205              </listitem>
3206
3207              <listitem>
3208                <para>Examples:</para>
3209
3210                <programlisting>destroot.pre_args  -project AudioSlicer.xcode
3211destroot.post_args INSTDIR=${destroot}${prefix}</programlisting>
3212              </listitem>
3213            </itemizedlist>
3214          </listitem>
3215        </varlistentry>
3216
3217        <varlistentry>
3218          <term>destroot.target</term>
3219
3220          <term>destroot.target-append</term>
3221
3222          <term>destroot.target-delete</term>
3223
3224          <listitem>
3225            <para>Install target to pass to ${destroot.cmd}; list modifiers
3226            add or delete items from a previous Portfile destroot.target
3227            keyword or the default set by MacPorts base.</para>
3228
3229            <itemizedlist>
3230              <listitem>
3231                <para>Default: <literal>install</literal></para>
3232              </listitem>
3233
3234              <listitem>
3235                <para>Example:</para>
3236
3237                <programlisting>destroot.target    install install-config install-commandmode
3238
3239</programlisting>
3240              </listitem>
3241            </itemizedlist>
3242          </listitem>
3243
3244          <listitem>
3245            <para>List modifier examples:</para>
3246
3247            <programlisting>destroot.target-append   install-plugins
3248destroot.target-delete   install-commandmode</programlisting>
3249          </listitem>
3250        </varlistentry>
3251
3252        <varlistentry>
3253          <term>destroot.destdir</term>
3254
3255          <listitem>
3256            <para>Arguments passed to ${destroot.cmd} to install correctly
3257            into the destroot.</para>
3258
3259            <programlisting>destroot.destdir     prefix=${destroot}${prefix}</programlisting>
3260
3261            <note>
3262              <para>If an application's Makefile properly supports the DESTDIR
3263              variable, MacPorts will automatically destroot the port
3264              properly. A port must destroot properly or the port will not
3265              install correctly, upgrade, or uninstall. If not, you may need
3266              to set this variable, or even patch the application's
3267              Makefile.</para>
3268            </note>
3269          </listitem>
3270        </varlistentry>
3271
3272        <varlistentry>
3273          <term>destroot.keepdirs</term>
3274
3275          <listitem>
3276            <para>A list of directories that should not be removed if empty
3277            upon destroot completion.</para>
3278
3279            <programlisting>destroot.keepdirs \
3280                ${destroot}${prefix}/var/run \
3281                ${destroot}${prefix}/var/log \
3282                ${destroot}${prefix}/var/cache/mrtg</programlisting>
3283          </listitem>
3284        </varlistentry>
3285
3286        <varlistentry>
3287          <term>destroot.violate_mtree</term>
3288
3289          <listitem>
3290            <para>MacPorts tests for compliance to the common directory
3291            structure in ${prefix}; the default is "no". If a port is not
3292            compliant with the standard, set it to "yes".</para>
3293
3294            <programlisting>destroot.violate_mtree    yes</programlisting>
3295          </listitem>
3296        </varlistentry>
3297      </variablelist>
3298    </refsection>
3299  </refsection>
3300
3301  <refsection>
3302    <title>TCL EXTENSIONS</title>
3303
3304    <para></para>
3305  </refsection>
3306
3307  <refsection>
3308    <title>SEE ALSO</title>
3309
3310    <para><citerefentry>
3311        <refentrytitle>port</refentrytitle>
3312
3313        <manvolnum>1</manvolnum>
3314      </citerefentry>, <citerefentry>
3315        <refentrytitle>macports.conf</refentrytitle>
3316
3317        <manvolnum>5</manvolnum>
3318      </citerefentry>, <citerefentry>
3319        <refentrytitle>portgroup</refentrytitle>
3320
3321        <manvolnum>7</manvolnum>
3322      </citerefentry>, <citerefentry>
3323        <refentrytitle>portstyle</refentrytitle>
3324
3325        <manvolnum>7</manvolnum>
3326      </citerefentry>, <citerefentry>
3327        <refentrytitle>porthier</refentrytitle>
3328
3329        <manvolnum>7</manvolnum>
3330      </citerefentry>, <citerefentry>
3331        <refentrytitle>file</refentrytitle>
3332
3333        <manvolnum>n</manvolnum>
3334      </citerefentry></para>
3335  </refsection>
3336
3337  <refsection>
3338    <title>AUTHORS</title>
3339
3340    <para>Landon Fuller <email>landonf@macports.org</email></para>
3341
3342    <para>Juan Manuel Palacios <email>jmpp@macports.org</email></para>
3343
3344    <para>Mark Duling <email>markd@macports.org</email></para>
3345
3346    <para>Kevin Van Vechten <email>kevin@opendarwin.org</email></para>
3347
3348    <para>Jordan K. Hubbard <email>jkh@macports.org</email></para>
3349
3350    <para>Chris Ridd <email>cjr@opendarwin.org</email></para>
3351
3352    <para>Kevin Ballard <email>eridius@macports.org</email></para>
3353
3354    <para>Markus W. Weissmann <email>mww@macports.org</email></para>
3355  </refsection>
3356</refentry>
Note: See TracBrowser for help on using the repository browser.