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

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

add configure-options for fortran compiler flags

File size: 97.5 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>StartupIem Creation &amp; Logging</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        </variablelist>
1059      </refsection>
1060
1061      <refsection>
1062        <title>Executable StartupItems</title>
1063
1064        <para>Daemons run continuously, so monitoring the health of daemon
1065        processes and restarting them if they die is an important
1066        StartupItems' feature. <quote>Executable</quote> StartupItems are
1067        preferred over <quote>script</quote> StartupItems because
1068        <command>daemondo</command> launches the daemon
1069        <emphasis>directly</emphasis>, rather than
1070        <emphasis>indirectly</emphasis> via a script, and therefore it
1071        automatically knows how to monitor a daemon process and restart it if
1072        it dies. Daemons used with <quote>executable</quote> StartupItems may
1073        be programs or scripts (shell, perl, python, etc.), but when a script
1074        the script <emphasis>itself</emphasis> must be the daemon, rather than
1075        a script that launches a daemon. <quote>Script</quote> StartupItems
1076        are to be used for the latter.</para>
1077
1078        <note>
1079          <para>For a given port, the <quote>executable</quote> StartupItem
1080          keyword may not be used with any keywords in the
1081          <quote>script</quote> StartupItem category.</para>
1082        </note>
1083
1084        <variablelist>
1085          <varlistentry>
1086            <term>startupitem.executable</term>
1087
1088            <listitem>
1089              <para>Specifies the name of the daemon to be run in the
1090              background. It may have multiple arguments, but they must be
1091              appropriate for a call to exec; arbitrary shell code may not be
1092              used.</para>
1093
1094              <itemizedlist>
1095                <listitem>
1096                  <para>Type: optional</para>
1097                </listitem>
1098
1099                <listitem>
1100                  <para>Default: no</para>
1101                </listitem>
1102
1103                <listitem>
1104                  <para>Values:
1105                  <replaceable>/path/to/executable</replaceable></para>
1106                </listitem>
1107
1108                <listitem>
1109                  <para>Example:</para>
1110
1111                  <programlisting>startupitem.executable  "${prefix}/bin/nmicmpd"</programlisting>
1112                </listitem>
1113              </itemizedlist>
1114            </listitem>
1115          </varlistentry>
1116        </variablelist>
1117      </refsection>
1118
1119      <refsection>
1120        <title>Script StartupItems</title>
1121
1122        <para>StartupItems of type <quote>script</quote> use
1123        <command>daemondo</command> to launch a daemon
1124        <emphasis>indirectly</emphasis> via a startup script. A typical
1125        snippet of a startup script that may be used with a
1126        <quote>script</quote> StartupItem is shown below. Notice that the
1127        script is not a daemon; rather the script indirectly launches the
1128        vm-pop3d daemon.</para>
1129
1130        <programlisting>#!/bin/sh
1131#
1132case "$1" in
1133  start)
1134       echo -n "Starting vm-pop3d: "
1135       /opt/local/sbin/vm-pop3d -d 10 -t 600
1136
1137
1138[... trimmed ...]</programlisting>
1139
1140        <para>But if a script itself is a daemon, use the executable
1141        StartupItem type since that way it will be launched directly and its
1142        health tracked automatically. When using <quote>script</quote>
1143        StartupItems, the <code>startupitem.pidfile</code> keyword must be
1144        used if you want <command>daemondo</command> to monitor a daemon
1145        process and restart it if it dies.</para>
1146
1147        <note>
1148          <para>For a given port, StartupItem keywords in category
1149          <quote>script</quote> may not be used with an
1150          <quote>executable</quote> StartupItem keyword.</para>
1151        </note>
1152
1153        <variablelist>
1154          <varlistentry>
1155            <term>startupitem.start</term>
1156
1157            <term>startupitem.stop</term>
1158
1159            <term>startupitem.restart</term>
1160
1161            <listitem>
1162              <para>Specify a shell script to start, stop, and restart the
1163              daemon. In the absence of a restart key, the daemon will be
1164              restarted by taking the stop action, followed by the start
1165              action.</para>
1166
1167              <itemizedlist>
1168                <listitem>
1169                  <para>Type: optional</para>
1170                </listitem>
1171
1172                <listitem>
1173                  <para>Default: none</para>
1174                </listitem>
1175
1176                <listitem>
1177                  <para>Values: <replaceable>shell_script</replaceable></para>
1178                </listitem>
1179
1180                <listitem>
1181                  <para>Examples:</para>
1182
1183                  <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server start
1184startupitem.stop ${prefix}/share/mysql/mysql.server stop
1185startupitem.restart ${prefix}/share/mysql/mysql.server restart</programlisting>
1186                </listitem>
1187              </itemizedlist>
1188            </listitem>
1189          </varlistentry>
1190
1191          <varlistentry>
1192            <term>startupitem.init</term>
1193
1194            <listitem>
1195              <para>Shell code that will be executed prior to any of the
1196              options <code>startupitem.start</code>,
1197              <code>startupitem.stop</code> and
1198              <code>startupitem.restart</code>.</para>
1199
1200              <itemizedlist>
1201                <listitem>
1202                  <para>Type: optional</para>
1203                </listitem>
1204
1205                <listitem>
1206                  <para>Default: no</para>
1207                </listitem>
1208
1209                <listitem>
1210                  <para>Values: <replaceable>shell_script</replaceable></para>
1211                </listitem>
1212
1213                <listitem>
1214                  <para>Example:</para>
1215
1216                  <programlisting>startupitem.init  "PID=/var/run/dhcpd.pid"</programlisting>
1217                </listitem>
1218              </itemizedlist>
1219            </listitem>
1220          </varlistentry>
1221
1222          <varlistentry>
1223            <term>startupitem.pidfile</term>
1224
1225            <listitem>
1226              <para>This keyword must be defined properly for
1227              <command>daemondo</command> to be able to monitor daemons
1228              launched via <quote>script</quote> StartupItems and restart them
1229              if they die. It specifies two things: a process id (PID) file
1230              handling method, and a pidfile name and path.</para>
1231
1232              <itemizedlist>
1233                <listitem>
1234                  <para>Type: optional</para>
1235                </listitem>
1236
1237                <listitem>
1238                  <para>Default: [none] |
1239                  [<filename>${prefix}/var/run/${name}.pid</filename>]</para>
1240                </listitem>
1241
1242                <listitem>
1243                  <para>Values [none auto manual clean]
1244                  [<replaceable>/path/to/pidfile</replaceable>]</para>
1245                </listitem>
1246
1247                <listitem>
1248                  <para>Example:</para>
1249
1250                  <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
1251                </listitem>
1252              </itemizedlist>
1253
1254              <para>PID file handling options:</para>
1255
1256              <itemizedlist>
1257                <listitem>
1258                  <para><option>none</option> - daemondo will not create or
1259                  track a PID file, so it won't know when a daemon
1260                  dies.</para>
1261                </listitem>
1262
1263                <listitem>
1264                  <para><option>auto</option> - The started process is
1265                  expected to create a PID file that contains the PID of the
1266                  running daemon; daemondo then reads the PID from the file
1267                  and tracks the process. The started process must delete the
1268                  PID file if this is necessary.</para>
1269                </listitem>
1270
1271                <listitem>
1272                  <para><option>clean</option> - The started process is
1273                  expected to create a PID file that contains the PID of the
1274                  running daemon; daemondo then reads the PID from the file
1275                  and tracks the process, and deletes the PID file if it
1276                  detects the daemon has died.</para>
1277                </listitem>
1278
1279                <listitem>
1280                  <para><option>manual</option> - This option should only be
1281                  used if an <quote>executable</quote> StartupItem could be
1282                  used (daemondo launches a daemon directly)
1283                  <emphasis>and</emphasis> a port author wants a PID file
1284                  written for some special use. A PID file is not needed to
1285                  detect process death for daemons launched directly by
1286                  daemondo. As with executale StartupItems, daemondo remembers
1287                  the PID of the launched process and tracks it
1288                  automatically.</para>
1289                </listitem>
1290              </itemizedlist>
1291            </listitem>
1292          </varlistentry>
1293        </variablelist>
1294      </refsection>
1295
1296      <refsection>
1297        <title>Loading / Unloading StartupItems into launchd</title>
1298
1299        <para>A port with a StartupItem places a link to a .plist file for the
1300        port's daemon within <filename>/Library/LaunchDaemons/</filename>. A
1301        .plist file is an XML file; MacPorts installs .plist files tagged as
1302        <quote>disabled</quote> for the sake of security. You may enable a
1303        startup script (tag the.plist file as <quote>enabled</quote>) and load
1304        it into <command>launchd</command> with a single command as
1305        shown.</para>
1306
1307        <programlisting><prompt>%%</prompt> <userinput>sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
1308
1309        <para>You may stop a running startup script, disable it (tag the.plist
1310        file as <quote>disabled</quote>), and unload it from
1311        <command>launchd</command> with a single command as shown.</para>
1312
1313        <programlisting><prompt>%%</prompt> <userinput>sudo launchctl unload -w /Library/LaunchDaemons/org.macports.mysql5.plist</userinput></programlisting>
1314      </refsection>
1315
1316      <refsection>
1317        <title>StartupItem Internals</title>
1318
1319        <para>During port installation a MacPorts StartupItem creates a .plist
1320        file in <filename>${prefix}/etc/LaunchDaemons/</filename>, and places
1321        a symbolic link to the .plist file within
1322        <filename>/Library/LaunchDaemons/</filename>.</para>
1323
1324        <para>For example, the StartupItem for the mysql5 port is
1325        <filename>org.macports.mysql5.plist</filename>, and it is linked as
1326        shown.</para>
1327
1328        <programlisting><prompt>%%</prompt> <userinput>ls -l /Library/LaunchDaemons</userinput></programlisting>
1329
1330        <screen>org.macports.mysql5.plist -&gt;
1331     /opt/local/etc/LaunchDaemons/org.macports.mysql5/org.macports.mysql5.plist</screen>
1332
1333        <para>For <quote>script</quote> StartupItems, in addition to a .plist
1334        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
1335-rw-r--r--   2 root  wheel  975 Aug  2 14:16 org.macports.mysql5.plist</screen>The
1336        wrapper manipulates the script as specified in the startupitem.start
1337        and startupitem.stop keywords. An example wrapper script snippet is
1338        shown below.</para>
1339
1340        <programlisting>#!/bin/sh
1341#
1342# MacPorts generated daemondo support script
1343
1344# Start
1345Start()
1346{
1347        /opt/local/share/mysql5/mysql/mysql.server start
1348}
1349
1350# Stop
1351Stop()
1352{
1353        /opt/local/share/mysql5/mysql/mysql.server stop
1354}
1355
1356[... trimmed ...]</programlisting>
1357      </refsection>
1358    </refsection>
1359  </refsection>
1360
1361  <refsection>
1362    <title>Installation Phase Keyword Reference</title>
1363
1364    <para>MacPorts keywords are used to specify required or optional items
1365    within a Portfile, or to override default options used by MacPorts base
1366    for individual ports. Keywords are to be used within the "global" and
1367    "variant" sections of Portfiles, and not within optional port phase
1368    declarations.</para>
1369
1370    <para>In other words, port phase keywords are not located within port
1371    phase declarations, but rather they <emphasis>refer</emphasis> to port
1372    phases and set options for those phases, and they take affect whether or
1373    not phase declarations have been explicitly defined in a Portfile.</para>
1374
1375    <refsection>
1376      <title>A Word about Keyword List Modifiers (-append / -delete)</title>
1377
1378      <para>It is often necessary to add to a list of keyword values
1379      previously set by a previously executed Portfile keyword or by MacPorts
1380      base. To keep from overwriting a previous keyword list, use a keyword
1381      list modifier. Keywords that support list modifiers are identified under
1382      appropriate reference sections below.</para>
1383
1384      <para>The three most common uses for keyword list modifiers are to
1385      preserve configure defaults, to preserve PortGroup dependencies, and to
1386      add or delete items for variants.</para>
1387
1388      <refsection>
1389        <title>Common Uses for Keyword List Modifiers</title>
1390
1391        <para>The three most common uses for keyword list modifiers are to
1392        preserve configure defaults, to preserve PortGroup dependencies, and
1393        to add or delete items for variants.</para>
1394
1395        <variablelist>
1396          <varlistentry>
1397            <term>Preserve configure Defaults</term>
1398
1399            <listitem>
1400              <para>MacPorts base sets the gcc compiler flags CFLAGS and
1401              LDFLAGS for all ports using <literal>configure.cflags</literal>
1402              and <literal>configure.ldflags</literal>, therefore to keep from
1403              overwriting the default compiler flags use
1404              <literal>configure.cflags-append</literal> and
1405              <literal>configure.ldflags-append</literal>.</para>
1406
1407              <itemizedlist>
1408                <listitem>
1409                  <para><code>configure.cflags-append</code></para>
1410                </listitem>
1411
1412                <listitem>
1413                  <para><code>configure.ldflags-append</code></para>
1414                </listitem>
1415              </itemizedlist>
1416            </listitem>
1417          </varlistentry>
1418
1419          <varlistentry>
1420            <term>Preserve PortGroup Dependencies</term>
1421
1422            <listitem>
1423              <para>Ports in a PortGroup have default library dependencies set
1424              by MacPorts base. Therefore, never use
1425              <literal>depends_lib</literal> in ports belonging to a PortGroup
1426              or it will overwrite the default library dependencies. Instead,
1427              use <literal>depends_lib-append</literal>.</para>
1428            </listitem>
1429          </varlistentry>
1430
1431          <varlistentry>
1432            <term>Add or Delete Items for Variants</term>
1433
1434            <listitem>
1435              <para>When a variant requires more or fewer dependencies,
1436              distfiles, or patchfiles, when the variant is invoked you want
1437              to add or remove items to the appropriate keyword values list
1438              set in the global section of the Portfile. Use the appropriate
1439              keywords, for example:</para>
1440
1441              <itemizedlist>
1442                <listitem>
1443                  <para><code>depends_lib-append</code> or
1444                  <code>depends_lib-delete</code></para>
1445                </listitem>
1446
1447                <listitem>
1448                  <para><code>distfiles-append</code> or
1449                  <code>distfile-delete</code></para>
1450                </listitem>
1451
1452                <listitem>
1453                  <para><code>patchfiles-append</code> or
1454                  <code>patchfiles-delete</code></para>
1455                </listitem>
1456              </itemizedlist>
1457            </listitem>
1458          </varlistentry>
1459        </variablelist>
1460      </refsection>
1461    </refsection>
1462
1463    <refsection>
1464      <title>A Word about Keyword Argument Modifiers (.pre_args /
1465      .post_args)</title>
1466
1467      <para>Keywords that support pre_args and post_args are used to assemble
1468      command strings together in a row, as described in the reference
1469      sections below. But it should be noted that all keyword argument
1470      modifiers implicitly support keyword list modifiers. For example, the
1471      keyword <literal>configure.pre_args</literal> also supports
1472      <literal>configure.pre_args-append</literal> and
1473      <literal>configure.pre_args-delete</literal>.</para>
1474    </refsection>
1475
1476    <refsection>
1477      <title>Fetch Phase Keywords</title>
1478
1479      <para>The list of keywords related to the fetch phase.</para>
1480
1481      <variablelist>
1482        <varlistentry>
1483          <term>master_sites</term>
1484
1485          <listitem>
1486            <para>A list of URLs from which a port's download file(s) may be
1487            retrieved. For multiple master_sites, they are searched in order
1488            until a file matching <varname>${distfile}</varname> is
1489            found.</para>
1490
1491            <itemizedlist>
1492              <listitem>
1493                <para>Default: ???</para>
1494              </listitem>
1495
1496              <listitem>
1497                <para>Examples:</para>
1498
1499                <programlisting>master_sites   http://www.somesite.org/files/ \
1500               http://www.somemirror.org/somesite_org/files/
1501
1502</programlisting>
1503
1504                <para>You may also use mirror site lists predefined by
1505                MacPorts. Here the sourceforge and gnu mirrors are
1506                used.</para>
1507
1508                <programlisting>master_sites   sourceforge gnu
1509
1510</programlisting>
1511
1512                <para>When using mirror master_sites, the subdirectory
1513                <varname>${name}</varname> is checked on every mirror. If the
1514                mirror subdirectory does not match ${name}, then you may
1515                specify it using after the mirror separated by a colon.</para>
1516
1517                <programlisting>master_sites   sourceforge:widget \
1518               gnu:widget
1519
1520</programlisting>
1521
1522                <para>For ports that must fetch multiple download files from
1523                different locations, you must label the files with tags and
1524                match the tags in a distfiles statement. The format is
1525                <literal>mirror:subdirectory:tag</literal>.</para>
1526
1527                <para>In the example below, file_one.tar.gz is fetched from
1528                sourceforge mirrors in subdirectory
1529                <varname>${name}</varname>; file tagtwo.tar.gz is fetched from
1530                the gnu mirrors in subdirectory sources.</para>
1531
1532                <programlisting>master_sites    sourceforge::tagone \
1533                gnu:sources:tagtwo
1534
1535distfiles       file_one.tar.gz:tagone \
1536                file_two.tar.gz:tagtwo</programlisting>
1537              </listitem>
1538            </itemizedlist>
1539          </listitem>
1540        </varlistentry>
1541
1542        <varlistentry>
1543          <term>patch_sites</term>
1544
1545          <listitem>
1546            <para>A list of sites from which a port's patchfiles may be
1547            downloaded, where applicable.</para>
1548
1549            <itemizedlist>
1550              <listitem>
1551                <para>Default: <varname>${master_sites}</varname></para>
1552              </listitem>
1553
1554              <listitem>
1555                <para>Example:</para>
1556
1557                <programlisting>patch_sites    ftp://ftp.patchcityrepo.com/pub/magic/patches</programlisting>
1558              </listitem>
1559            </itemizedlist>
1560          </listitem>
1561        </varlistentry>
1562
1563        <varlistentry>
1564          <term>distname</term>
1565
1566          <listitem>
1567            <para>The name of the distribution filename, not including the
1568            extract suffix.</para>
1569
1570            <itemizedlist>
1571              <listitem>
1572                <para>Default: <varname>${name}-${version}</varname></para>
1573              </listitem>
1574
1575              <listitem>
1576                <para>Example:</para>
1577
1578                <programlisting>distname     ${name}</programlisting>
1579              </listitem>
1580            </itemizedlist>
1581          </listitem>
1582        </varlistentry>
1583
1584        <varlistentry>
1585          <term>distfiles</term>
1586
1587          <listitem>
1588            <para>The full distribution filename, including the extract
1589            suffix. Used to specify non-default distribution filenames; this
1590            keyword must be specified (and tags used) when a port has multiple
1591            download files (see master_sites).</para>
1592
1593            <itemizedlist>
1594              <listitem>
1595                <para>Default:
1596                <varname>${distname}${extract.suffix}</varname></para>
1597              </listitem>
1598
1599              <listitem>
1600                <para>Example:</para>
1601
1602                <programlisting>distfiles    ${name}-dev_src.tgz
1603
1604
1605distfiles       file_one.tar.gz:tagone \
1606                file_two.tar.gz:tagtwo</programlisting>
1607              </listitem>
1608            </itemizedlist>
1609          </listitem>
1610        </varlistentry>
1611
1612        <varlistentry>
1613          <term>extract.suffix</term>
1614
1615          <listitem>
1616            <para>This keyword is used to specify the extract suffix
1617            type.</para>
1618
1619            <itemizedlist>
1620              <listitem>
1621                <para>Default: <filename>.tar.gz</filename></para>
1622              </listitem>
1623
1624              <listitem>
1625                <para>Example:</para>
1626
1627                <programlisting>extract.suffix   .tgz</programlisting>
1628              </listitem>
1629            </itemizedlist>
1630          </listitem>
1631        </varlistentry>
1632
1633        <varlistentry>
1634          <term>use_bzip2</term>
1635
1636          <listitem>
1637            <para>This keyword is for downloads that are tarred and bzipped.
1638            When invoked, it automatically sets:</para>
1639
1640            <literallayout>extract.suffix = .tar.bz
1641extract.cmd = bzip
1642
1643</literallayout>
1644
1645            <itemizedlist>
1646              <listitem>
1647                <para>Default: yes</para>
1648              </listitem>
1649
1650              <listitem>
1651                <para>Example:</para>
1652
1653                <programlisting>use_bzip2     yes</programlisting>
1654              </listitem>
1655            </itemizedlist>
1656          </listitem>
1657        </varlistentry>
1658
1659        <varlistentry>
1660          <term>use_zip</term>
1661
1662          <listitem>
1663            <para>This keyword is for downloads are zipped. When invoked, it
1664            automatically sets:</para>
1665
1666            <literallayout>extract.suffix = .zip
1667extract.cmd = unzip
1668extract.pre_args = -q
1669extract.post_args = "-d ${portpath}/${workdir}"
1670
1671</literallayout>
1672
1673            <itemizedlist>
1674              <listitem>
1675                <para>Default: <option>yes</option></para>
1676              </listitem>
1677
1678              <listitem>
1679                <para>Example:</para>
1680
1681                <programlisting>use_zip       yes</programlisting>
1682              </listitem>
1683            </itemizedlist>
1684          </listitem>
1685        </varlistentry>
1686      </variablelist>
1687
1688      <refsection>
1689        <title>Fetch from CVS</title>
1690
1691        <para><ulink url="http://www.nongnu.org/cvs/">CVS</ulink> may be used
1692        as an alternative method of fetching distribution files using the
1693        keywords in this section. However, fetching via CVS may cause
1694        non-reproducible builds, so it is strongly discouraged.</para>
1695
1696        <variablelist>
1697          <varlistentry>
1698            <term>cvs.root</term>
1699
1700            <listitem>
1701              <para>Specify the url from which to fetch files.</para>
1702
1703              <itemizedlist>
1704                <listitem>
1705                  <para>Default: none</para>
1706                </listitem>
1707
1708                <listitem>
1709                  <para>Example:</para>
1710
1711                  <programlisting>cvs.root :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs</programlisting>
1712                </listitem>
1713              </itemizedlist>
1714            </listitem>
1715          </varlistentry>
1716
1717          <varlistentry>
1718            <term>cvs.tag</term>
1719
1720            <listitem>
1721              <para>Optional for fetching with CVS, this specifies the code
1722              revision to checkout.</para>
1723
1724              <itemizedlist>
1725                <listitem>
1726                  <para>Default: none</para>
1727                </listitem>
1728
1729                <listitem>
1730                  <para>Example:</para>
1731
1732                  <programlisting>cvs.tag  HEAD</programlisting>
1733                </listitem>
1734              </itemizedlist>
1735            </listitem>
1736          </varlistentry>
1737
1738          <varlistentry>
1739            <term>cvs.date</term>
1740
1741            <listitem>
1742              <para>A date that identifies the CVS code set to
1743              checkout.</para>
1744
1745              <itemizedlist>
1746                <listitem>
1747                  <para>Default: none</para>
1748                </listitem>
1749
1750                <listitem>
1751                  <para>Example:</para>
1752
1753                  <programlisting>cvs.date "12-April-2007"</programlisting>
1754                </listitem>
1755              </itemizedlist>
1756            </listitem>
1757          </varlistentry>
1758
1759          <varlistentry>
1760            <term>cvs.module</term>
1761
1762            <listitem>
1763              <para>A CVS module from which to check out the code.</para>
1764
1765              <itemizedlist>
1766                <listitem>
1767                  <para>Default: none</para>
1768                </listitem>
1769
1770                <listitem>
1771                  <para>Example:</para>
1772
1773                  <programlisting>cvs.module  Sources</programlisting>
1774                </listitem>
1775              </itemizedlist>
1776            </listitem>
1777          </varlistentry>
1778        </variablelist>
1779      </refsection>
1780
1781      <refsection>
1782        <title>Fetch from Subversion</title>
1783
1784        <para><ulink url="http://subversion.tigris.org/">Subversion</ulink>
1785        may be used as an alternative method of fetching distribution files
1786        using the keywords in this section. However, fetching via Subversion
1787        may cause non-reproducible builds, so it is strongly
1788        discouraged.</para>
1789
1790        <variablelist>
1791          <varlistentry>
1792            <term>svn.url</term>
1793
1794            <listitem>
1795              <para>This specifies the url from which to fetch files.</para>
1796
1797              <itemizedlist>
1798                <listitem>
1799                  <para>Default: none</para>
1800                </listitem>
1801
1802                <listitem>
1803                  <para>Examples:</para>
1804
1805                  <programlisting>svn.url http://www.domain.com/svn-repo/mydirectory
1806svn.url svn://www.domain.com/svn-repo/mydirectory
1807</programlisting>
1808                </listitem>
1809              </itemizedlist>
1810            </listitem>
1811          </varlistentry>
1812
1813          <varlistentry>
1814            <term>svn.tag</term>
1815
1816            <listitem>
1817              <para>Optional tag for fetching with Subversion, this specifies
1818              the code revision to checkout; it corresponds to the -r option
1819              in the svn cli. You must use backslashes to escape characters
1820              that are meaningful to the Tcl interpreter, such as braces and
1821              double quotes.</para>
1822
1823              <itemizedlist>
1824                <listitem>
1825                  <para>Default: none</para>
1826                </listitem>
1827
1828                <listitem>
1829                  <para>Examples:</para>
1830
1831                  <programlisting>svn.tag 37192
1832svn.tag \{\"2006-02-17 15:30 +0230\"\}</programlisting>
1833                </listitem>
1834              </itemizedlist>
1835            </listitem>
1836          </varlistentry>
1837        </variablelist>
1838      </refsection>
1839    </refsection>
1840
1841    <refsection>
1842      <title>Checksum Phase Keywords</title>
1843
1844      <para>The list of keywords related to the checksum phase.</para>
1845
1846      <variablelist>
1847        <varlistentry>
1848          <term>checksums</term>
1849
1850          <listitem>
1851            <para>Checksum(s) of the distribution files. For ports with
1852            multiple distribution files, filenames must be included to
1853            associate files with their checksums.</para>
1854
1855            <itemizedlist>
1856              <listitem>
1857                <para>Default: ???</para>
1858              </listitem>
1859
1860              <listitem>
1861                <para>Examples:</para>
1862
1863                <programlisting>checksums     md5 dafa161bc9c61e57636a6085c87c1fe8 \
1864              sha1 5da610e1c8bc01b80abc21ab9e98e004363b429c \
1865              rmd160 0c1147242adf476f5e93f4d59b553ee3ea378b23</programlisting>
1866
1867                <programlisting>checksums     ${distname}${extract.suffix} md5 dafa161bc9c61e57636a6085c87c1fe8 \
1868                  sha1 5da610e1c8bc01b80abc21ab9e98e004363b429c \
1869                  rmd160 0c1147242adf476f5e93f4d59b553ee3ea378b23 \
1870              hobbit.tar.gz md5 3b8d02c6cf6239b9bdadbc6543c5a683 \
1871                  sha1 27874638b23e66d39ed94fe716ca25c967f6e993 \
1872                  rmd160 82b9991f3bf0ceedbf74c188c5fa44b98b5e40c9</programlisting>
1873              </listitem>
1874            </itemizedlist>
1875          </listitem>
1876        </varlistentry>
1877      </variablelist>
1878    </refsection>
1879
1880    <refsection>
1881      <title>Extract Phase Keywords</title>
1882
1883      <para>The list of keywords related to the extract phase.</para>
1884
1885      <variablelist>
1886        <varlistentry>
1887          <term>extract.only</term>
1888
1889          <term>extract.only-append</term>
1890
1891          <term>extract.only-delete</term>
1892
1893          <listitem>
1894            <para>List of files to extract into
1895            <varname>${worksrcpath}</varname>; the default is
1896            <varname>${distfiles}</varname>. Only use if default extract
1897            behavior is not correct for your port.</para>
1898
1899            <itemizedlist>
1900              <listitem>
1901                <para>Default: none</para>
1902              </listitem>
1903
1904              <listitem>
1905                <para>Example:</para>
1906
1907                <programlisting>extract.only     foo.tar.gz
1908
1909</programlisting>
1910              </listitem>
1911            </itemizedlist>
1912          </listitem>
1913
1914          <listitem>
1915            <para>List modifier examples:</para>
1916
1917            <programlisting>extract.only-append  bar.tar.gz
1918extract.only-delete  foo.tar.gz</programlisting>
1919          </listitem>
1920        </varlistentry>
1921
1922        <varlistentry>
1923          <term>extract.cmd</term>
1924
1925          <listitem>
1926            <para>Command to perform extraction.</para>
1927
1928            <itemizedlist>
1929              <listitem>
1930                <para>Default: gzip</para>
1931              </listitem>
1932
1933              <listitem>
1934                <para>Example:</para>
1935
1936                <programlisting>extract.cmd     gunzip</programlisting>
1937              </listitem>
1938            </itemizedlist>
1939          </listitem>
1940        </varlistentry>
1941
1942        <varlistentry>
1943          <term>extract.args</term>
1944
1945          <term>extract.pre_args</term>
1946
1947          <term>extract.post_args</term>
1948
1949          <listitem>
1950            <para>Main arguments to extract.cmd; additional arguments passed
1951            before and after the main arguments.</para>
1952
1953            <itemizedlist>
1954              <listitem>
1955                <para>Default: ${distpath}/${distfile}</para>
1956              </listitem>
1957
1958              <listitem>
1959                <para>Example:</para>
1960
1961                <programlisting>extract.args      ${distpath}/${distfile}
1962
1963</programlisting>
1964              </listitem>
1965            </itemizedlist>
1966          </listitem>
1967
1968          <listitem>
1969            <para>The following argument modifiers are available:</para>
1970
1971            <itemizedlist>
1972              <listitem>
1973                <para>extract.pre_args default: "-dc"</para>
1974              </listitem>
1975
1976              <listitem>
1977                <para>extract.post_args default: " | tar -xf"</para>
1978              </listitem>
1979
1980              <listitem>
1981                <para>Examples:</para>
1982
1983                <programlisting>extract.pre_args     xf
1984extract.post_args    "| gnutar –x"</programlisting>
1985              </listitem>
1986            </itemizedlist>
1987          </listitem>
1988        </varlistentry>
1989      </variablelist>
1990    </refsection>
1991
1992    <refsection>
1993      <title>Patch Phase Keywords</title>
1994
1995      <para>The list of keywords related to the patch phase.</para>
1996
1997      <variablelist>
1998        <varlistentry>
1999          <term>patch.dir</term>
2000
2001          <listitem>
2002            <para>Specify the base path for patch files.</para>
2003
2004            <itemizedlist>
2005              <listitem>
2006                <para>Default: <varname>${worksrcpath}</varname></para>
2007              </listitem>
2008
2009              <listitem>
2010                <para>Example:</para>
2011
2012                <programlisting>patch.dir      ${worksrcpath}/util</programlisting>
2013              </listitem>
2014            </itemizedlist>
2015          </listitem>
2016        </varlistentry>
2017
2018        <varlistentry>
2019          <term>patch.cmd</term>
2020
2021          <listitem>
2022            <para>Specify the command to be used for patching files.</para>
2023
2024            <itemizedlist>
2025              <listitem>
2026                <para>Default: <command>patch</command></para>
2027              </listitem>
2028
2029              <listitem>
2030                <para>Example:</para>
2031
2032                <programlisting>patch.cmd      cat</programlisting>
2033              </listitem>
2034            </itemizedlist>
2035          </listitem>
2036        </varlistentry>
2037
2038        <varlistentry>
2039          <term>patchfiles</term>
2040
2041          <term>patchfiles-append</term>
2042
2043          <term>patchfiles-delete</term>
2044
2045          <listitem>
2046            <para>Specify patch files to be applied for a port; list modifiers
2047            specify patchfiles to be added or removed from a previous
2048            patchfile declaration.</para>
2049
2050            <itemizedlist>
2051              <listitem>
2052                <para>Default: none</para>
2053              </listitem>
2054
2055              <listitem>
2056                <para>Example:</para>
2057
2058                <programlisting>patchfiles     patch-Makefile.in \
2059               patch-source.c
2060
2061</programlisting>
2062              </listitem>
2063            </itemizedlist>
2064          </listitem>
2065
2066          <listitem>
2067            <para>List modifier examples:</para>
2068
2069            <programlisting>patchfiles-append   patch-configure
2070patchfiles-delete   patch-src-Makefile.in
2071</programlisting>
2072          </listitem>
2073        </varlistentry>
2074
2075        <varlistentry>
2076          <term>patch.args</term>
2077
2078          <term>patch.pre_args</term>
2079
2080          <term>patch.post_args</term>
2081
2082          <listitem>
2083            <para>Main arguments to patch.cmd; optional argument modifiers
2084            pass arguments before and after the main arguments.</para>
2085
2086            <itemizedlist>
2087              <listitem>
2088                <para>Default: none</para>
2089              </listitem>
2090
2091              <listitem>
2092                <para>Example:</para>
2093
2094                <programlisting>patch.args   ???
2095
2096</programlisting>
2097              </listitem>
2098            </itemizedlist>
2099          </listitem>
2100
2101          <listitem>
2102            <para>The following argument modifiers are available:</para>
2103
2104            <itemizedlist>
2105              <listitem>
2106                <para>patch.pre_args default: -p0</para>
2107              </listitem>
2108
2109              <listitem>
2110                <para>patch.post_args default: none</para>
2111              </listitem>
2112
2113              <listitem>
2114                <para>Examples:</para>
2115
2116                <programlisting>patch.pre_args     -p1
2117patch.post_args    ???</programlisting>
2118              </listitem>
2119            </itemizedlist>
2120          </listitem>
2121        </varlistentry>
2122      </variablelist>
2123    </refsection>
2124
2125    <refsection>
2126      <title>Configure Phase Keywords</title>
2127
2128      <para>The list of keywords related to the configure phase.</para>
2129
2130      <para>MacPorts base sets some important default configure options, so
2131      should use the -append version of most configure keywords so you don't
2132      overwrite them. For example, MacPorts base sets default
2133      <literal>configure.cflags</literal> so you should always use
2134      <literal>configure.cflags-append</literal> to set additional CFLAGS in
2135      Portfiles.</para>
2136
2137      <variablelist>
2138        <varlistentry>
2139          <term>configure.env</term>
2140
2141          <term>configure.env-append</term>
2142
2143          <term>configure.env-delete</term>
2144
2145          <listitem>
2146            <para>Set environment variables for configure; list modifiers add
2147            and delete items from a previous Portfile configure.env keyword,
2148            or a default set by MacPorts base. If available, it is encouraged to
2149            use the predefined options (like configure.cflags) instead of
2150            modifying configure.env directly</para>
2151
2152            <itemizedlist>
2153              <listitem>
2154                <para>Default: <literal>CFLAGS=-I${prefix}/include
2155                LDFLAGS=-L${prefix}/lib</literal></para>
2156              </listitem>
2157
2158              <listitem>
2159                <para>Example:</para>
2160
2161                <programlisting>configure.env   QTDIR=${prefix}/lib/qt3
2162</programlisting>
2163              </listitem>
2164            </itemizedlist>
2165          </listitem>
2166
2167          <listitem>
2168            <para>List modifier examples:</para>
2169
2170            <programlisting>configure.env-append   ABI=32
2171configure.env-delete   TCLROOT=${prefix}</programlisting>
2172          </listitem>
2173        </varlistentry>
2174
2175        <varlistentry>
2176          <term>configure.cflags</term>
2177
2178          <term>configure.cflags-append</term>
2179
2180          <term>configure.cflags-delete</term>
2181
2182          <listitem>
2183            <para>Set CFLAGS compiler flags; list modifiers add or delete
2184            items from a previous Portfile configure.cflags keyword or the
2185            default set by MacPorts base.</para>
2186
2187            <itemizedlist>
2188              <listitem>
2189                <para>Default:
2190                <literal>-O2</literal></para>
2191              </listitem>
2192
2193              <listitem>
2194                <para>Example:</para>
2195
2196                <programlisting>configure.cflags    -Os -flat_namespace
2197
2198</programlisting>
2199              </listitem>
2200            </itemizedlist>
2201          </listitem>
2202
2203          <listitem>
2204            <para>List modifier examples:</para>
2205
2206            <programlisting>configure.cflags-append   "-undefined suppress"
2207configure.cflags-delete   -O2</programlisting>
2208          </listitem>
2209        </varlistentry>
2210
2211        <varlistentry>
2212          <term>configure.ldflags</term>
2213
2214          <term>configure.ldflags-append</term>
2215
2216          <term>configure.ldflags-delete</term>
2217
2218          <listitem>
2219            <para>Set LDFLAGS compiler flags; list modifiers add or delete
2220            items from a previous Portfile configure.ldflags keyword or the
2221            default set by MacPorts base.</para>
2222
2223            <itemizedlist>
2224              <listitem>
2225                <para>Default:
2226                <literal>-L${prefix}/lib</literal></para>
2227              </listitem>
2228
2229              <listitem>
2230                <para>Example:</para>
2231
2232                <programlisting>configure.ldflags    -L${worksrcpath}/zlib -lz
2233
2234</programlisting>
2235              </listitem>
2236            </itemizedlist>
2237          </listitem>
2238
2239          <listitem>
2240            <para>List modifier examples:</para>
2241
2242            <programlisting>configure.ldflags-append   "-L/usr/X11R6/lib -L${worksrcpath}/lib"
2243configure.ldflags-delete   -L${prefix}/lib/db44</programlisting>
2244          </listitem>
2245        </varlistentry>
2246
2247        <varlistentry>
2248          <term>configure.cppflags</term>
2249
2250          <term>configure.cppflags-append</term>
2251
2252          <term>configure.cppflags-delete</term>
2253
2254          <listitem>
2255            <para>Set CPPFLAGS to be passed to the C processor; list modifiers
2256            add or delete items from a previous Portfile configure.cppflags
2257            keyword or the default set by MacPorts base.</para>
2258
2259            <itemizedlist>
2260              <listitem>
2261                <para>Default:
2262                <literal>-I${prefix}/include</literal></para>
2263              </listitem>
2264
2265              <listitem>
2266                <para>Example:</para>
2267
2268                <programlisting>configure.cppflags    -I${worksrcpath}/include
2269
2270</programlisting>
2271              </listitem>
2272            </itemizedlist>
2273          </listitem>
2274
2275          <listitem>
2276            <para>List modifier examples:</para>
2277
2278            <programlisting>configure.cppflags-append   "-I/usr/X11R6/lib -I${worksrcpath}/lib -DHAVE_RRD_12X"
2279configure.cppflags-delete   -I${prefix}/lib/db44</programlisting>
2280          </listitem>
2281        </varlistentry>
2282
2283<!-- fortran compiler options -->
2284        <varlistentry>
2285          <term>configure.fflags</term>
2286
2287          <term>configure.fflags-append</term>
2288
2289          <term>configure.fflags-delete</term>
2290
2291          <listitem>
2292            <para>Set FFLAGS to be passed to the Fortran compiler; list modifiers
2293            add or delete items from a previous Portfile configure.fflags
2294            keyword or the default set by MacPorts base.</para>
2295
2296            <itemizedlist>
2297              <listitem>
2298                <para>Default:
2299                <literal>-O2</literal></para>
2300              </listitem>
2301
2302              <listitem>
2303                <para>Example:</para>
2304
2305                <programlisting>configure.fflags    -Os
2306
2307</programlisting>
2308              </listitem>
2309            </itemizedlist>
2310          </listitem>
2311        </varlistentry>
2312
2313        <varlistentry>
2314          <term>configure.fcflags</term>
2315
2316          <term>configure.fcflags-append</term>
2317
2318          <term>configure.fcflags-delete</term>
2319
2320          <listitem>
2321            <para>Set FCFLAGS to be passed to the Fortran compiler; list modifiers
2322            add or delete items from a previous Portfile configure.fcflags
2323            keyword or the default set by MacPorts base.</para>
2324
2325            <itemizedlist>
2326              <listitem>
2327                <para>Default:
2328                <literal>-O2</literal></para>
2329              </listitem>
2330
2331              <listitem>
2332                <para>Example:</para>
2333
2334                <programlisting>configure.fcflags    -Os
2335
2336</programlisting>
2337              </listitem>
2338            </itemizedlist>
2339          </listitem>
2340        </varlistentry>
2341
2342        <varlistentry>
2343          <term>configure.f90flags</term>
2344
2345          <term>configure.f90flags-append</term>
2346
2347          <term>configure.f90flags-delete</term>
2348
2349          <listitem>
2350            <para>Set F90FLAGS to be passed to the Fortran 90 compiler; list modifiers
2351            add or delete items from a previous Portfile configure.f90flags
2352            keyword or the default set by MacPorts base.</para>
2353
2354            <itemizedlist>
2355              <listitem>
2356                <para>Default:
2357                <literal>-O2</literal></para>
2358              </listitem>
2359
2360              <listitem>
2361                <para>Example:</para>
2362
2363                <programlisting>configure.f90flags    -Os
2364
2365</programlisting>
2366              </listitem>
2367            </itemizedlist>
2368          </listitem>
2369        </varlistentry>
2370<!-- fortran compiler options end -->
2371
2372<!-- compiler selection arguments -->
2373        <varlistentry>
2374          <term>configure.cc</term>
2375
2376          <listitem>
2377            <para>Set CC compiler flags for selecting a C compiler;</para>
2378
2379            <itemizedlist>
2380              <listitem>
2381                <para>Default:
2382                <literal></literal></para>
2383              </listitem>
2384
2385              <listitem>
2386                <para>Example:</para>
2387
2388                <programlisting>configure.cc    ${prefix}/bin/gcc-mp-4.2</programlisting>
2389              </listitem>
2390            </itemizedlist>
2391          </listitem>
2392        </varlistentry>
2393
2394        <varlistentry>
2395          <term>configure.cpp</term>
2396
2397          <listitem>
2398            <para>Set CPP compiler flags for selecting a C preprocessor;</para>
2399
2400            <itemizedlist>
2401              <listitem>
2402                <para>Default:
2403                <literal></literal></para>
2404              </listitem>
2405
2406              <listitem>
2407                <para>Example:</para>
2408
2409                <programlisting>configure.cpp    /usr/bin/cpp-3.3</programlisting>
2410              </listitem>
2411            </itemizedlist>
2412          </listitem>
2413        </varlistentry>
2414
2415        <varlistentry>
2416          <term>configure.cxx</term>
2417
2418          <listitem>
2419            <para>Set CXX compiler flags for selecting a C++ compiler;</para>
2420
2421            <itemizedlist>
2422              <listitem>
2423                <para>Default:
2424                <literal></literal></para>
2425              </listitem>
2426
2427              <listitem>
2428                <para>Example:</para>
2429
2430                <programlisting>configure.cpp    /usr/bin/g++-4.0</programlisting>
2431              </listitem>
2432            </itemizedlist>
2433          </listitem>
2434        </varlistentry>
2435
2436        <varlistentry>
2437          <term>configure.objc</term>
2438
2439          <listitem>
2440            <para>Set OBJC compiler flags for selecting an Objective-C compiler;</para>
2441
2442            <itemizedlist>
2443              <listitem>
2444                <para>Default:
2445                <literal></literal></para>
2446              </listitem>
2447
2448              <listitem>
2449                <para>Example:</para>
2450
2451                <programlisting>configure.objc    /usr/bin/gcc-4.0</programlisting>
2452              </listitem>
2453            </itemizedlist>
2454          </listitem>
2455        </varlistentry>
2456
2457        <varlistentry>
2458          <term>configure.fc</term>
2459
2460          <listitem>
2461            <para>Set FC compiler flags for selecting a Fortran compiler;</para>
2462
2463            <itemizedlist>
2464              <listitem>
2465                <para>Default:
2466                <literal></literal></para>
2467              </listitem>
2468
2469              <listitem>
2470                <para>Example:</para>
2471
2472                <programlisting>configure.fc    ${prefix}/bin/gfortran-mp-4.2</programlisting>
2473              </listitem>
2474            </itemizedlist>
2475          </listitem>
2476        </varlistentry>
2477
2478        <varlistentry>
2479          <term>configure.f77</term>
2480
2481          <listitem>
2482            <para>Set F77 compiler flags for selecting a Fortran 77 compiler;</para>
2483
2484            <itemizedlist>
2485              <listitem>
2486                <para>Default:
2487                <literal></literal></para>
2488              </listitem>
2489
2490              <listitem>
2491                <para>Example:</para>
2492
2493                <programlisting>configure.f77    ${prefix}/bin/gfortran-mp-4.2</programlisting>
2494              </listitem>
2495            </itemizedlist>
2496          </listitem>
2497        </varlistentry>
2498
2499        <varlistentry>
2500          <term>configure.f90</term>
2501
2502          <listitem>
2503            <para>Set F90 compiler flags for selecting a Fortran 90 compiler;</para>
2504
2505            <itemizedlist>
2506              <listitem>
2507                <para>Default:
2508                <literal></literal></para>
2509              </listitem>
2510
2511              <listitem>
2512                <para>Example:</para>
2513
2514                <programlisting>configure.f90    ${prefix}/bin/gfortran-mp-4.2</programlisting>
2515              </listitem>
2516            </itemizedlist>
2517          </listitem>
2518        </varlistentry>
2519
2520        <varlistentry>
2521          <term>configure.javac</term>
2522
2523          <listitem>
2524            <para>Set JAVAC compiler flags for selecting a Java compiler;</para>
2525
2526            <itemizedlist>
2527              <listitem>
2528                <para>Default:
2529                <literal></literal></para>
2530              </listitem>
2531
2532              <listitem>
2533                <para>Example:</para>
2534
2535                <programlisting>configure.javac    ${prefix}/bin/jikes</programlisting>
2536              </listitem>
2537            </itemizedlist>
2538          </listitem>
2539        </varlistentry>
2540<!-- compiler selection arguments end -->
2541<!-- interpreter selection arguments -->
2542        <varlistentry>
2543          <term>configure.perl</term>
2544
2545          <listitem>
2546            <para>Set PERL flag for selecting a Perl interpreter;</para>
2547
2548            <itemizedlist>
2549              <listitem>
2550                <para>Default:
2551                <literal></literal></para>
2552              </listitem>
2553
2554              <listitem>
2555                <para>Example:</para>
2556
2557                <programlisting>configure.perl    ${prefix}/bin/perl5.8</programlisting>
2558              </listitem>
2559            </itemizedlist>
2560          </listitem>
2561        </varlistentry>
2562
2563        <varlistentry>
2564          <term>configure.python</term>
2565
2566          <listitem>
2567            <para>Set PYTHON flag for selecting a Python interpreter;</para>
2568
2569            <itemizedlist>
2570              <listitem>
2571                <para>Default:
2572                <literal></literal></para>
2573              </listitem>
2574
2575              <listitem>
2576                <para>Example:</para>
2577
2578                <programlisting>configure.python    ${prefix}/bin/python3.0</programlisting>
2579              </listitem>
2580            </itemizedlist>
2581          </listitem>
2582        </varlistentry>
2583
2584        <varlistentry>
2585          <term>configure.ruby</term>
2586
2587          <listitem>
2588            <para>Set RUBY flag for selecting a Ruby interpreter;</para>
2589
2590            <itemizedlist>
2591              <listitem>
2592                <para>Default:
2593                <literal></literal></para>
2594              </listitem>
2595
2596              <listitem>
2597                <para>Example:</para>
2598
2599                <programlisting>configure.ruby    ${prefix}/bin/ruby</programlisting>
2600              </listitem>
2601            </itemizedlist>
2602          </listitem>
2603        </varlistentry>
2604<!-- interpreter selection arguments end -->
2605
2606        <varlistentry>
2607          <term>configure.args</term>
2608
2609          <term>configure.pre_args</term>
2610
2611          <term>configure.post_args</term>
2612
2613          <listitem>
2614            <para>Main arguments to configure.cmd; optional argument modifiers
2615            pass arguments before and after the main arguments.</para>
2616
2617            <itemizedlist>
2618              <listitem>
2619                <para>Default: none</para>
2620              </listitem>
2621
2622              <listitem>
2623                <para>Example:</para>
2624
2625                <programlisting>configure.args    --bindir=${prefix}/bin
2626
2627</programlisting>
2628              </listitem>
2629            </itemizedlist>
2630          </listitem>
2631
2632          <listitem>
2633            <para>The following argument modifiers are available:</para>
2634
2635            <itemizedlist>
2636              <listitem>
2637                <para>configure.pre_args default: --prefix=${prefix}</para>
2638              </listitem>
2639
2640              <listitem>
2641                <para>configure.post_args default: none</para>
2642              </listitem>
2643
2644              <listitem>
2645                <para>Examples:</para>
2646
2647                <programlisting>configure.pre_args   --prefix=${prefix}/share/bro
2648configure.post_args  OPT="-D__DARWIN_UNIX03"</programlisting>
2649              </listitem>
2650            </itemizedlist>
2651          </listitem>
2652        </varlistentry>
2653      </variablelist>
2654
2655      <refsection>
2656        <title>Configure Universal</title>
2657
2658        <para>Universal keywords are used to make a port compile on the OS X
2659        platform to run on either PPC or Intel.</para>
2660
2661        <note>
2662          <para>There is a default universal variant made available to all
2663          ports by MacPorts base, so redefining universal keywords should only
2664          be done to make a given port compile if the default options fail to
2665          do so.</para>
2666        </note>
2667
2668        <variablelist>
2669          <varlistentry>
2670            <term>configure.universal_args</term>
2671
2672            <listitem>
2673              <para>Arguments used in the configure script to build the port
2674              universal.</para>
2675
2676              <itemizedlist>
2677                <listitem>
2678                  <para>Default: --disable-dependency-tracking</para>
2679                </listitem>
2680
2681                <listitem>
2682                  <para>Example:</para>
2683
2684                  <programlisting></programlisting>
2685                </listitem>
2686              </itemizedlist>
2687            </listitem>
2688          </varlistentry>
2689
2690          <varlistentry>
2691            <term>configure.universal_cflags</term>
2692
2693            <listitem>
2694              <para>Arguments appended to the configure script to build the
2695              port universal.</para>
2696
2697              <itemizedlist>
2698                <listitem>
2699                  <para>Default: -sysroot /Developer/SDKs/MacOSX10.4u.sdk
2700                  -arch i386 -arch ppc</para>
2701                </listitem>
2702
2703                <listitem>
2704                  <para>Example:</para>
2705
2706                  <programlisting></programlisting>
2707                </listitem>
2708              </itemizedlist>
2709            </listitem>
2710          </varlistentry>
2711
2712          <varlistentry>
2713            <term>configure.universal_cppflags</term>
2714
2715            <listitem>
2716              <para>Additional flags to put in the CPPFLAGS environment
2717              variable when invoking the configure script.</para>
2718
2719              <itemizedlist>
2720                <listitem>
2721                  <para>Default: ???</para>
2722                </listitem>
2723
2724                <listitem>
2725                  <para>Example:</para>
2726
2727                  <programlisting></programlisting>
2728                </listitem>
2729              </itemizedlist>
2730            </listitem>
2731          </varlistentry>
2732
2733          <varlistentry>
2734            <term>configure.universal_cxxflags</term>
2735
2736            <listitem>
2737              <para>Additional flags to put in the CXXFLAGS environment
2738              variable when invoking the configure script.</para>
2739
2740              <itemizedlist>
2741                <listitem>
2742                  <para>Default: -isysroot /Developer/SDKs/MacOSX10.4u.sdk
2743                  -arch i386 -arch ppc</para>
2744                </listitem>
2745
2746                <listitem>
2747                  <para>Example:</para>
2748
2749                  <programlisting></programlisting>
2750                </listitem>
2751              </itemizedlist>
2752            </listitem>
2753          </varlistentry>
2754
2755          <varlistentry>
2756            <term>configure.universal_ldflags</term>
2757
2758            <listitem>
2759              <para>Additional flags to put in the LDFLAGS environment
2760              variable when invoking the configure script.</para>
2761
2762              <itemizedlist>
2763                <listitem>
2764                  <para>Default: -arch i386 -arch ppc</para>
2765                </listitem>
2766
2767                <listitem>
2768                  <para>Example:</para>
2769
2770                  <programlisting></programlisting>
2771                </listitem>
2772              </itemizedlist>
2773            </listitem>
2774          </varlistentry>
2775        </variablelist>
2776      </refsection>
2777
2778      <refsection>
2779        <title>Automake and Autoconf</title>
2780
2781        <para>The list of configure keywords available for ports that need
2782        automake and/or autoconf.</para>
2783
2784        <variablelist>
2785          <varlistentry>
2786            <term>use_automake</term>
2787
2788            <listitem>
2789              <para>Whether or not to use automake; the default is
2790              "no".</para>
2791
2792              <programlisting>use_automake      yes</programlisting>
2793            </listitem>
2794          </varlistentry>
2795
2796          <varlistentry>
2797            <term>automake.env</term>
2798
2799            <listitem>
2800              <para>Environment variables to pass to automake.</para>
2801
2802              <programlisting>automake.env      CFLAGS=-I${prefix}/include</programlisting>
2803            </listitem>
2804          </varlistentry>
2805
2806          <varlistentry>
2807            <term>automake.args</term>
2808
2809            <listitem>
2810              <para>Arguments to pass to automake.</para>
2811
2812              <programlisting>automake.args     --foreign</programlisting>
2813            </listitem>
2814          </varlistentry>
2815
2816          <varlistentry>
2817            <term>automake.dir</term>
2818
2819            <listitem>
2820              <para>Directory in which to run
2821              <varname>${automake.cmd}</varname>; the default is
2822              <varname>${worksrcpath}</varname>.</para>
2823
2824              <programlisting>automake.dir      ./src</programlisting>
2825            </listitem>
2826          </varlistentry>
2827
2828          <varlistentry>
2829            <term>use_autoconf</term>
2830
2831            <listitem>
2832              <para>Whether or not to use autoconf; the default is
2833              "no".</para>
2834
2835              <programlisting>use_autoconf      yes</programlisting>
2836            </listitem>
2837          </varlistentry>
2838
2839          <varlistentry>
2840            <term>autoconf.env</term>
2841
2842            <listitem>
2843              <para>Environmental variables to pass to autoconf.</para>
2844
2845              <programlisting>autoconf.env      CFLAGS=-I${prefix}/include/gtk12</programlisting>
2846            </listitem>
2847          </varlistentry>
2848
2849          <varlistentry>
2850            <term>autoconf.args</term>
2851
2852            <listitem>
2853              <para>Arguments to pass to autoconf.</para>
2854
2855              <programlisting>autoconf.args     -l src/aclocaldir</programlisting>
2856            </listitem>
2857          </varlistentry>
2858
2859          <varlistentry>
2860            <term>autoconf.dir</term>
2861
2862            <listitem>
2863              <para>Directory in which to run
2864              <varname>${autoconf.cmd}</varname>; the default is
2865              <varname>${worksrcpath}</varname>.</para>
2866
2867              <programlisting>autoconf.dir      src</programlisting>
2868            </listitem>
2869          </varlistentry>
2870        </variablelist>
2871      </refsection>
2872    </refsection>
2873
2874    <refsection>
2875      <title>Build Phase Keywords</title>
2876
2877      <para>The list of keywords related to the build phase.</para>
2878
2879      <variablelist>
2880        <varlistentry>
2881          <term>build.cmd</term>
2882
2883          <listitem>
2884            <para>Make command to run in <varname>${worksrcdir}</varname>; the
2885            default is "make".</para>
2886
2887            <programlisting>build.cmd      pbxbuild</programlisting>
2888          </listitem>
2889        </varlistentry>
2890
2891        <varlistentry>
2892          <term>build.type</term>
2893
2894          <listitem>
2895            <para>Defines which "make" is required: "gnu" or "bsd". Sets
2896            build.cmd to either "gnumake" or "bsdmake" accordingly.</para>
2897
2898            <programlisting>build.type     gnu</programlisting>
2899          </listitem>
2900        </varlistentry>
2901
2902        <varlistentry>
2903          <term>build.args</term>
2904
2905          <term>build.pre_args</term>
2906
2907          <term>build.post_args</term>
2908
2909          <listitem>
2910            <para>Main arguments to build.cmd; optional argument modifiers
2911            pass arguments before and after the main arguments.</para>
2912
2913            <itemizedlist>
2914              <listitem>
2915                <para>Default: none</para>
2916              </listitem>
2917
2918              <listitem>
2919                <para>Example:</para>
2920
2921                <programlisting>build.args    -DNOWARN
2922
2923</programlisting>
2924              </listitem>
2925            </itemizedlist>
2926          </listitem>
2927
2928          <listitem>
2929            <para>The following argument modifiers are available:</para>
2930
2931            <itemizedlist>
2932              <listitem>
2933                <para>build.pre_args default:
2934                <varname>${build.target.current}</varname></para>
2935              </listitem>
2936
2937              <listitem>
2938                <para>build.post_args default: none</para>
2939              </listitem>
2940
2941              <listitem>
2942                <para>Examples:</para>
2943
2944                <programlisting>build.pre_args  -project AudioSlicer.xcode
2945build.post_args CFLAGS_SYS="-DUSE_FREETYPE -DPREFER_FREETYPE"</programlisting>
2946              </listitem>
2947            </itemizedlist>
2948          </listitem>
2949        </varlistentry>
2950
2951        <varlistentry>
2952          <term>build.target</term>
2953
2954          <term>build.target-append</term>
2955
2956          <term>build.target-delete</term>
2957
2958          <listitem>
2959            <para>Build target to pass to ${build.cmd}; list modifiers add or
2960            delete items from a previous Portfile build.target keyword or the
2961            default set by MacPorts base.</para>
2962
2963            <itemizedlist>
2964              <listitem>
2965                <para>Default: all</para>
2966              </listitem>
2967
2968              <listitem>
2969                <para>Example:</para>
2970
2971                <programlisting>build.target    all-src
2972
2973</programlisting>
2974              </listitem>
2975            </itemizedlist>
2976          </listitem>
2977
2978          <listitem>
2979            <para>List modifier examples:</para>
2980
2981            <programlisting>build.target-append   doc extra
2982build.target-delete   compat</programlisting>
2983          </listitem>
2984        </varlistentry>
2985      </variablelist>
2986    </refsection>
2987
2988    <refsection>
2989      <title>Destroot Phase Keywords</title>
2990
2991      <para>The list of keywords related to the destroot phase.</para>
2992
2993      <variablelist>
2994        <varlistentry>
2995          <term>destroot.cmd</term>
2996
2997          <listitem>
2998            <para>Install command to run relative to
2999            <varname>${worksrcdir}</varname>; default is
3000            <varname>${build.cmd}</varname>.</para>
3001
3002            <programlisting>destroot.cmd         pbxbuild</programlisting>
3003          </listitem>
3004        </varlistentry>
3005
3006        <varlistentry>
3007          <term>destroot.type</term>
3008
3009          <listitem>
3010            <para>Defines which "make" is required: either "gnu" or "bsd".
3011            Sets install.cmd to either "gnumake" or "bsdmake"
3012            accordingly.</para>
3013
3014            <programlisting>destroot.type        gnu</programlisting>
3015          </listitem>
3016        </varlistentry>
3017
3018        <varlistentry>
3019          <term>destroot.args</term>
3020
3021          <term>destroot.pre_args</term>
3022
3023          <term>destroot.post_args</term>
3024
3025          <listitem>
3026            <para>Main arguments to ${destroot.cmd}; optional argument
3027            modifiers pass arguments before and after the main
3028            arguments.</para>
3029
3030            <itemizedlist>
3031              <listitem>
3032                <para>Default: none</para>
3033              </listitem>
3034
3035              <listitem>
3036                <para>Example:</para>
3037
3038                <programlisting>destroot.args    BINDIR=${prefix}/bin
3039
3040</programlisting>
3041              </listitem>
3042            </itemizedlist>
3043          </listitem>
3044
3045          <listitem>
3046            <para>The following argument modifiers are available:</para>
3047
3048            <itemizedlist>
3049              <listitem>
3050                <para>destroot.pre_args default:
3051                <varname>${destroot.target}</varname></para>
3052              </listitem>
3053
3054              <listitem>
3055                <para>destroot.post_args default: none</para>
3056              </listitem>
3057
3058              <listitem>
3059                <para>Examples:</para>
3060
3061                <programlisting>destroot.pre_args  -project AudioSlicer.xcode
3062destroot.post_args INSTDIR=${destroot}${prefix}</programlisting>
3063              </listitem>
3064            </itemizedlist>
3065          </listitem>
3066        </varlistentry>
3067
3068        <varlistentry>
3069          <term>destroot.target</term>
3070
3071          <term>destroot.target-append</term>
3072
3073          <term>destroot.target-delete</term>
3074
3075          <listitem>
3076            <para>Install target to pass to ${destroot.cmd}; list modifiers
3077            add or delete items from a previous Portfile destroot.target
3078            keyword or the default set by MacPorts base.</para>
3079
3080            <itemizedlist>
3081              <listitem>
3082                <para>Default: <literal>install</literal></para>
3083              </listitem>
3084
3085              <listitem>
3086                <para>Example:</para>
3087
3088                <programlisting>destroot.target    install install-config install-commandmode
3089
3090</programlisting>
3091              </listitem>
3092            </itemizedlist>
3093          </listitem>
3094
3095          <listitem>
3096            <para>List modifier examples:</para>
3097
3098            <programlisting>destroot.target-append   install-plugins
3099destroot.target-delete   install-commandmode</programlisting>
3100          </listitem>
3101        </varlistentry>
3102
3103        <varlistentry>
3104          <term>destroot.destdir</term>
3105
3106          <listitem>
3107            <para>Arguments passed to ${destroot.cmd} to install correctly
3108            into the destroot.</para>
3109
3110            <programlisting>destroot.destdir     prefix=${destroot}${prefix}</programlisting>
3111
3112            <note>
3113              <para>If an application's Makefile properly supports the DESTDIR
3114              variable, MacPorts will automatically destroot the port
3115              properly. A port must destroot properly or the port will not
3116              install correctly, upgrade, or uninstall. If not, you may need
3117              to set this variable, or even patch the application's
3118              Makefile.</para>
3119            </note>
3120          </listitem>
3121        </varlistentry>
3122
3123        <varlistentry>
3124          <term>destroot.keepdirs</term>
3125
3126          <listitem>
3127            <para>A list of directories that should not be removed if empty
3128            upon destroot completion.</para>
3129
3130            <programlisting>destroot.keepdirs \
3131                ${destroot}${prefix}/var/run \
3132                ${destroot}${prefix}/var/log \
3133                ${destroot}${prefix}/var/cache/mrtg</programlisting>
3134          </listitem>
3135        </varlistentry>
3136
3137        <varlistentry>
3138          <term>destroot.violate_mtree</term>
3139
3140          <listitem>
3141            <para>MacPorts tests for compliance to the common directory
3142            structure in ${prefix}; the default is "no". If a port is not
3143            compliant with the standard, set it to "yes".</para>
3144
3145            <programlisting>destroot.violate_mtree    yes</programlisting>
3146          </listitem>
3147        </varlistentry>
3148      </variablelist>
3149    </refsection>
3150  </refsection>
3151
3152  <refsection>
3153    <title>TCL EXTENSIONS</title>
3154
3155    <para></para>
3156  </refsection>
3157
3158  <refsection>
3159    <title>SEE ALSO</title>
3160
3161    <para><citerefentry>
3162        <refentrytitle>port</refentrytitle>
3163
3164        <manvolnum>1</manvolnum>
3165      </citerefentry>, <citerefentry>
3166        <refentrytitle>macports.conf</refentrytitle>
3167
3168        <manvolnum>5</manvolnum>
3169      </citerefentry>, <citerefentry>
3170        <refentrytitle>portgroup</refentrytitle>
3171
3172        <manvolnum>7</manvolnum>
3173      </citerefentry>, <citerefentry>
3174        <refentrytitle>portstyle</refentrytitle>
3175
3176        <manvolnum>7</manvolnum>
3177      </citerefentry>, <citerefentry>
3178        <refentrytitle>porthier</refentrytitle>
3179
3180        <manvolnum>7</manvolnum>
3181      </citerefentry>, <citerefentry>
3182        <refentrytitle>file</refentrytitle>
3183
3184        <manvolnum>n</manvolnum>
3185      </citerefentry></para>
3186  </refsection>
3187
3188  <refsection>
3189    <title>AUTHORS</title>
3190
3191    <para>Landon Fuller <email>landonf@macports.org</email></para>
3192
3193    <para>Juan Manuel Palacios <email>jmpp@macports.org</email></para>
3194
3195    <para>Mark Duling <email>markd@macports.org</email></para>
3196
3197    <para>Kevin Van Vechten <email>kevin@opendarwin.org</email></para>
3198
3199    <para>Jordan K. Hubbard <email>jkh@macports.org</email></para>
3200
3201    <para>Chris Ridd <email>cjr@opendarwin.org</email></para>
3202
3203    <para>Kevin Ballard <email>eridius@macports.org</email></para>
3204
3205    <para>Markus W. Weissmann <email>mww@macports.org</email></para>
3206  </refsection>
3207</refentry>
Note: See TracBrowser for help on using the repository browser.