source: trunk/doc/guide/new/xml/portfileref.xml @ 28584

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

One more section ID addition for startupitems section.

File size: 67.0 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4<chapter id="reference">
5  <title>Portfile Reference</title>
6
7  <para>This chapter serves as a reference for the major elements of a
8  <filename>Portfile</filename>: port phases, variants, StartupItems,
9  variables, keywords, and Tcl extensions.</para>
10
11  <section id="reference.phases">
12    <title>Port Phases</title>
13
14    <para>A MacPorts port has ten distinct phases. The MacPorts base is set to
15    perform default steps for applications that use the standard
16    <command>configure</command>, <command>make</command>, and <command>make
17    install</command> steps, but for applications that do not conform to this
18    behavior, installation phases may be declared in a Portfile to <link
19    linkend="development.examples.pre-post">augment</link> or <link
20    linkend="development.examples.override">override</link> the default
21    behavior as described in the <link linkend="development">Portfile
22    Development</link> chapter.</para>
23
24    <section id="reference.phases.fetch">
25      <title>Fetch</title>
26
27      <para>Overview: Fetch the <varname>${distfiles}</varname> from
28      <varname>${master_sites}</varname> and place it in
29      <filename>${prefix}/var/macports/distfiles</filename>.</para>
30    </section>
31
32    <section id="reference.phases.checksum">
33      <title>Checksum</title>
34
35      <para>Overview: Compare <varname>${checksums}</varname> specified in a
36      <filename>Portfile</filename> to the checksums of the fetched
37      ${distfiles}.</para>
38    </section>
39
40    <section id="reference.phases.extract">
41      <title>Extract</title>
42
43      <para>Overview: Unzip and untar the <varname>${distfiles}</varname> into
44      the path ${prefix}/var/macports/build/..../work</para>
45    </section>
46
47    <section id="reference.phases.patch">
48      <title>Patch</title>
49
50      <para>Overview: Apply optional <ulink
51      url="http://en.wikipedia.org/wiki/Patch_(Unix)">patch</ulink> files
52      specified in <varname>${patchfiles}</varname> to modify a port's source
53      code file(s).</para>
54
55      <para>Details: Patch files are made using the <ulink
56      url="http://en.wikipedia.org/wiki/Diff">diff</ulink> command, and
57      MacPorts patches should be created as <ulink
58      url="http://en.wikipedia.org/wiki/Diff#Unified_format">unified
59      diffs</ulink>.</para>
60    </section>
61
62    <section id="reference.phases.configure">
63      <title>Configure</title>
64
65      <para>Overview: Execute the command "configure" in
66      <varname>${workpath}</varname>.</para>
67    </section>
68
69    <section id="reference.phases.build">
70      <title>Build</title>
71
72      <para>Overview: Execute the command "make" in
73      <varname>${workpath}</varname>.</para>
74    </section>
75
76    <section id="reference.phases.destroot">
77      <title>Destroot</title>
78
79      <para>Overview: Execute the command <command>make install
80      DESTDIR=${destroot}</command> in <varname>${workpath}</varname>.</para>
81
82      <para>Details: Understanding the destroot phase is critical to
83      understanding MacPorts, because, unlike some port systems, MacPorts
84      "stages" an installation into an intermediate location —not the final
85      file destination. There are two main advantages to this method.</para>
86
87      <orderedlist>
88        <listitem>
89          <para>A port's files may be cleanly uninstalled because all files
90          and locations are tracked.</para>
91        </listitem>
92
93        <listitem>
94          <para>Since a port's files are not installed into MacPorts directory
95          structure until an activation phase, a port may be deactivated
96          through MacPorts to allow activation of a different version of the
97          same port, thus allowing two versions of a port to be present,
98          though not both active, on a given host.</para>
99        </listitem>
100      </orderedlist>
101
102      <note>
103        <para>The <varname>$(DESTDIR)</varname> variable must be supported in
104        an application's Makefile for the MacPorts destroot phase to work
105        properly. Urge developers to fully support
106        <varname>$(DESTDIR)</varname> in their Makefiles.</para>
107      </note>
108
109      <para>At the beginning of the destroot phase, all the directories in the
110      file <filename>${prefix}/etc/macports/prefix.mtree</filename> are
111      created. Any directories still empty upon completion of the destroot
112      phase are removed unless a directory is listed using a destroot.keepdirs
113      keyword.</para>
114    </section>
115
116    <section id="reference.phases.archive">
117      <title>Archive</title>
118
119      <para>Overview: Use tar to create a tarball of a port's destrooted files
120      and copy it to
121      <filename>${prefix}/var/macports/packages/</filename>.</para>
122    </section>
123
124    <section id="reference.phases.install">
125      <title>Install</title>
126
127      <para>Overview: Copy a port's destrooted files into
128      <filename>${prefix}/var/macports/software</filename>. See <link
129      linkend="internals.images">Port Images</link> in the <link
130      linkend="internals">MacPorts Internals</link> chapter for
131      details.</para>
132    </section>
133
134    <section id="reference.phases.activate">
135      <title>Activate</title>
136
137      <para>Overview: Set <ulink
138      url="http://en.wikipedia.org/wiki/Hard_link">hardlinks</ulink> pointing
139      to <filename>${prefix}/var/macports/software</filename> to point to
140      ${prefix}.</para>
141    </section>
142  </section>
143
144  <section id="reference.dependencies">
145    <title>Dependencies</title>
146
147    <para>Free and open source software is highly modular, and MacPorts ports
148    often require modules not provided in a port's distribution to be
149    installed before a port may be installed, compiled, or run. These support
150    modules are generally other MacPorts ports, and the ports required to
151    satisfy prerequistes for a given port are called a port's
152    "dependencies".</para>
153
154    <para>There are three types of dependencies in MacPorts: library, build,
155    and run dependencies. The dependency type is important for proper port
156    upgrade and uninstall behavior. For example, you may not uninstall a port
157    that is a library dependency for another port, though you may remove one
158    with a build dependency; likewise, upgrading a port will upgrade its
159    library and build dependencies also, but not its run dependencies.</para>
160
161    <section id="reference.dependencies.dependslib">
162      <title>depends_lib</title>
163
164      <para>The list of dependencies to check before phases
165      <option>configure</option>, <option>build</option>,
166      <option>destroot</option>, <option>install</option>, and
167      <option>package</option>. Library dependencies are needed both at build
168      time (for headers and libraries to link against) and at run time.</para>
169
170      <programlisting>depends_lib         port:rrdtool</programlisting>
171    </section>
172
173    <section id="reference.dependencies.dependsbuild">
174      <title>depends_build</title>
175
176      <para>The list of dependencies to check before phases
177      <option>build</option>, <option>destroot</option>,
178      <option>install</option>, and <option>package</option>. Build
179      dependencies are needed when software is compiled, but not needed at all
180      once the software is compiled and installed.</para>
181
182      <programlisting>depends_build       port:gcc42</programlisting>
183    </section>
184
185    <section id="reference.dependencies.dependsrun">
186      <title>depends_run</title>
187
188      <para>The list of dependencies to check before phases
189      <option>destroot</option>, <option>install</option>, and
190      <option>package</option>. Run dependencies are needed when the software
191      is run, but not to compile it.</para>
192
193      <programlisting>depends_run         port:apache2</programlisting>
194    </section>
195
196    <section id="reference.dependencies.nonport">
197      <title>Non-Port Dependencies</title>
198
199      <para>Port dependencies should refer to other MacPorts ports whenever
200      possible. However, if satisfying a dependency with a port is not
201      practical or desirable for a special reason, you may specify
202      dependencies by having MacPorts test for an individual file by replacing
203      <literal>port:</literal> with one of the options <literal>lib: bin: or
204      path:</literal>.</para>
205
206      <para>In this lib style dependency, if the file
207      <filename>libX11.6.x.dylib</filename> is not found in the library path
208      the XFree86 port will be installed to satisfy it.</para>
209
210      <programlisting>depends_lib         lib:libX11.6:XFree86</programlisting>
211
212      <para>In this bin style dependency, if the <filename>python</filename>
213      binary is not found in the shell's binary path the port python24 will be
214      installed.</para>
215
216      <programlisting>depends_build       bin:python:python24</programlisting>
217
218      <para>In this path style dependency, if the file
219      <filename>/usr/bin/nano</filename> is not found the nano port will be
220      installed.</para>
221
222      <programlisting>depends_run         path:/usr/bin/nano:nano</programlisting>
223    </section>
224  </section>
225
226  <section id="reference.startupitems">
227    <title>StartupItems</title>
228
229    <para>StartupItems are keywords that create Mac OS X startup scripts for
230    <ulink
231    url="http://developer.apple.com/macosx/launchd.html">launchd</ulink>, the
232    facility intoduced by Apple beginning with OS X 10.4, that starts, stops,
233    and manages daemons, programs and scripts. Port authors use StartupItem
234    keywords within Portfiles to instruct MacPorts to generate and install
235    <command>launchd</command> scripts for ports when they are
236    installed.</para>
237
238    <para>There are two types of StartupItems, executable and wrapper, but
239    first we'll list the StartupItem keywords common to both types.</para>
240
241    <section id="reference.startupitems.common">
242      <title>Common StartupItem Keywords</title>
243
244      <para>The keywords in this section may be used with executable or
245      wrapper StartupItems.</para>
246
247      <variablelist>
248        <varlistentry>
249          <term>startupitem.create</term>
250
251          <listitem>
252            <para>Trigger the creation of a StartupItem.</para>
253
254            <simplelist>
255              <member>Type: optional</member>
256
257              <member>Default: <option>no</option></member>
258
259              <member>Values: <option>yes no</option></member>
260            </simplelist>
261
262            <programlisting>startupitem.create  yes</programlisting>
263          </listitem>
264        </varlistentry>
265
266        <varlistentry>
267          <term>startupitem.name</term>
268
269          <listitem>
270            <para>Sets the name for the StartupItem.</para>
271
272            <simplelist>
273              <member>Type: required</member>
274
275              <member>Default: none</member>
276
277              <member>Values:</member>
278            </simplelist>
279
280            <programlisting>startupitem.name  OpenSSH</programlisting>
281          </listitem>
282        </varlistentry>
283
284        <varlistentry>
285          <term>startupitem.logfile</term>
286
287          <listitem>
288            <para>Path to a logfile for logging events about the lifetime of
289            the startupitem. Depending on the type of startupitem, and the
290            manner in which it is started, standard output from the daemon may
291            also be directed to the logfile.</para>
292
293            <simplelist>
294              <member>Type: optional</member>
295
296              <member>Default: <option>/dev/null</option></member>
297
298              <member>Values: <replaceable>/file/path/</replaceable></member>
299            </simplelist>
300
301            <programlisting>startupitem.logfile  ${prefix}/var/log/mydaemon.log</programlisting>
302          </listitem>
303        </varlistentry>
304
305        <varlistentry>
306          <term>startupitem.logevents</term>
307
308          <listitem>
309            <para>Control whether or not to log events to the log file. If
310            logevents is set, events with timestamps are logged to the
311            logfile.</para>
312
313            <simplelist>
314              <member>Type: optional</member>
315
316              <member>Default: <option>no</option></member>
317
318              <member>Values: <option>yes no</option></member>
319            </simplelist>
320
321            <programlisting>startupitem.logevents   yes</programlisting>
322          </listitem>
323        </varlistentry>
324      </variablelist>
325    </section>
326
327    <section id="reference.startupitems.executable">
328      <title>Executable StartupItems</title>
329
330      <para>The executable StartupItem is the preferred type —it merely
331      specify the name of the daemon to be run in the background.
332      <command>launchd</command> monitors the daemon to make sure it stays
333      running. Executable StartupItem keywords may not be used together with
334      any of the wrapper StartupItem keywords.</para>
335
336      <variablelist>
337        <varlistentry>
338          <term>startupitem.executable</term>
339
340          <listitem>
341            <para>Specifies the name of the daemon to be run in the
342            background. It may have multiple arguments, but they must be
343            appropriate for a call to exec; arbitrary shell code may not be
344            used.</para>
345
346            <simplelist>
347              <member>Type: optional</member>
348
349              <member>Default: <option>no</option></member>
350
351              <member>Values: <option>yes no</option></member>
352            </simplelist>
353
354            <programlisting>startupitem.executable  "${prefix}/bin/nmicmpd"</programlisting>
355          </listitem>
356        </varlistentry>
357
358        <varlistentry>
359          <term>startupitem.pidfile</term>
360
361          <listitem>
362            <para>A specification for process id (PID) file handling that may
363            be used in conjunction with the startupitem.executable key to
364            inform the startupitem how to track the executable. This keyword
365            specifies whether the daemon is not to use a pidfile
366            (<option>none</option>), generates its own pidfile
367            (<option>auto</option>), never generates one (so the startupitem
368            should manage the pidfile on its own (<option>manual</option>), or
369            generates its own but will not delete it (so the startupitem
370            should delete it using <option>clean</option>).</para>
371
372            <simplelist>
373              <member>Type: optional</member>
374
375              <member>Default: <option>none</option> |
376              <filename>${prefix}/var/run/${name}.pid</filename></member>
377
378              <member>Values: <option>none auto manual clean</option>
379              [<replaceable>/path/to/pidfile</replaceable>]</member>
380            </simplelist>
381
382            <programlisting>startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile</programlisting>
383          </listitem>
384        </varlistentry>
385      </variablelist>
386    </section>
387
388    <section id="reference.startupitems.wrapper">
389      <title>Wrapper StartupItems</title>
390
391      <para>Wrapper StartupItems use <command>daemondo</command>, a wrapper
392      program provided by MacPorts base made to execute startup scripts for
393      daemons. <command>daemondo</command> works as an adapter between OS X's
394      launchd and daemons that are normally started via traditional rc.d style
395      scripts.</para>
396
397      <variablelist>
398        <varlistentry>
399          <term>startupitem.init</term>
400
401          <listitem>
402            <para>Shell code that will be executed prior to any of the options
403            startupitem.start, startupitem.stop and
404            startupitem.restart.</para>
405
406            <simplelist>
407              <member>Type: optional</member>
408
409              <member>Default: <option>no</option></member>
410
411              <member>Values: <literal>shell script</literal></member>
412            </simplelist>
413
414            <programlisting>startupitem.init  "PID=/var/run/dhcpd.pid"</programlisting>
415          </listitem>
416        </varlistentry>
417
418        <varlistentry>
419          <term>startupitem.start</term>
420
421          <listitem>
422            <para>Specify a shell script to start the daemon.</para>
423
424            <simplelist>
425              <member>Type: optional</member>
426
427              <member>Default: none</member>
428
429              <member>Values: <literal>shell script</literal></member>
430            </simplelist>
431
432            <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server start</programlisting>
433          </listitem>
434        </varlistentry>
435
436        <varlistentry>
437          <term>startupitem.stop</term>
438
439          <listitem>
440            <para>Specify a shell script to stop the daemon.</para>
441
442            <simplelist>
443              <member>Type: optional</member>
444
445              <member>Default: none</member>
446
447              <member>Values: <literal>shell script</literal></member>
448            </simplelist>
449
450            <programlisting>startupitem.start ${prefix}/share/mysql/mysql.server stop</programlisting>
451          </listitem>
452        </varlistentry>
453
454        <varlistentry>
455          <term>startupitem.restart</term>
456
457          <listitem>
458            <para>Specify a shell script to restart the daemon. In the absence
459            of this key, the daemon will be restarted by taking the stop
460            action, followed by taking the start action.</para>
461
462            <simplelist>
463              <member>Type: optional</member>
464
465              <member>Default: none</member>
466
467              <member>Values: <literal>shell script</literal></member>
468            </simplelist>
469
470            <programlisting>startupitem.start  ${prefix}/share/mysql/mysql.server restart</programlisting>
471          </listitem>
472        </varlistentry>
473      </variablelist>
474    </section>
475  </section>
476
477  <section id="reference.variables">
478    <title>Variables</title>
479
480    <para>This section describes the MacPorts preset variables that may be
481    used within Portfiles.</para>
482
483    <section id="reference.variables.general">
484      <title>General</title>
485
486      <para>These are the variables available to any
487      <filename>Portfile</filename>.</para>
488
489      <para><variablelist>
490          <varlistentry>
491            <term>prefix</term>
492
493            <listitem>
494              <para>Installation prefix, set in the system-wide configuration
495              file <filename>${prefix}/etc/macports/macports.conf</filename>
496              —may be overridden on a per port basis. For example, aqua
497              applications are installed in
498              <filename>/Applications/MacPorts</filename>.</para>
499            </listitem>
500          </varlistentry>
501
502          <varlistentry>
503            <term>binpath</term>
504
505            <listitem>
506              <para>Default PATH to use in finding executables. Read
507              only.</para>
508            </listitem>
509          </varlistentry>
510
511          <varlistentry>
512            <term>libpath</term>
513
514            <listitem>
515              <para>Path to the MacPorts TCL libraries. Read only.</para>
516            </listitem>
517          </varlistentry>
518
519          <varlistentry>
520            <term>portpath</term>
521
522            <listitem>
523              <para>Path to the directory containing the downloaded Read
524              only.</para>
525            </listitem>
526          </varlistentry>
527
528          <varlistentry>
529            <term>filesdir</term>
530
531            <listitem>
532              <para>Path to port files relative to
533              <varname>${portpath}</varname>. Read only.</para>
534            </listitem>
535          </varlistentry>
536
537          <varlistentry>
538            <term>workpath</term>
539
540            <listitem>
541              <para>Full path to work directory. Read only.</para>
542            </listitem>
543          </varlistentry>
544
545          <varlistentry>
546            <term>worksrcpath</term>
547
548            <listitem>
549              <para>Full path to extracted source code. Equivalent to
550              <varname>${workpath}/${worksrcdir}</varname>.</para>
551            </listitem>
552          </varlistentry>
553
554          <varlistentry>
555            <term>destroot</term>
556
557            <listitem>
558              <para>Full path into which software will be destrooted.
559              Equivalent to <filename>${workpath}/destroot</filename>. Read
560              only.</para>
561            </listitem>
562          </varlistentry>
563
564          <varlistentry>
565            <term>distpath</term>
566
567            <listitem>
568              <para>Location to store downloaded distfiles. Read only.</para>
569            </listitem>
570          </varlistentry>
571
572          <varlistentry>
573            <term>install.user</term>
574
575            <listitem>
576              <para>The Unix user at the time of port installation.</para>
577            </listitem>
578          </varlistentry>
579
580          <varlistentry>
581            <term>install.group</term>
582
583            <listitem>
584              <para>The Unix group at the time of port installation.</para>
585            </listitem>
586          </varlistentry>
587
588          <varlistentry>
589            <term>os.platform</term>
590
591            <listitem>
592              <para>Identifies platform type (ie, "darwin", "freebsd", etc).
593              Read only.</para>
594            </listitem>
595          </varlistentry>
596
597          <varlistentry>
598            <term>os.arch</term>
599
600            <listitem>
601              <para>Identifies hardware type (ie, "powerpc", "intel"). Read
602              only.</para>
603            </listitem>
604          </varlistentry>
605
606          <varlistentry>
607            <term>os.version</term>
608
609            <listitem>
610              <para>The version number of the host operating system (ie "8.0"
611              for Darwin 8.0). Read only.</para>
612            </listitem>
613          </varlistentry>
614
615          <varlistentry>
616            <term>os.major</term>
617
618            <listitem>
619              <para>The major version number of the host operating system (ie
620              "8" for Darwin 8.0). Read only.</para>
621            </listitem>
622          </varlistentry>
623        </variablelist></para>
624    </section>
625
626    <section id="reference.variables.portgroup">
627      <title>PortGroup Variables</title>
628
629      <para>In addition to the general <filename>Portfile</filename> type for
630      standard Unix applications and libraries, there are six optional
631      PortGroup types that provide special <filename>Portfile</filename>
632      handling to make creating <filename>a Portfile</filename> easier.</para>
633
634      <itemizedlist>
635        <listitem>
636          <para>perl5</para>
637        </listitem>
638
639        <listitem>
640          <para>python24 and python25</para>
641        </listitem>
642
643        <listitem>
644          <para>ruby</para>
645        </listitem>
646
647        <listitem>
648          <para>xcode</para>
649        </listitem>
650
651        <listitem>
652          <para>gnustep</para>
653        </listitem>
654
655        <listitem>
656          <para>zope</para>
657        </listitem>
658      </itemizedlist>
659
660      <para>Some PortGroups provide additional variables when they are
661      declared within a Portfile. The additional variables provided by
662      PortGroups perl5, python, and ruby are listed below. You may view the
663      port Tcl code for each group in the directory<filename>
664      ${prefix}/share/macports/resources/port1.0/group</filename>.</para>
665
666      <variablelist>
667        <varlistentry>
668          <term>PortGroup perl5</term>
669
670          <listitem>
671            <para>Description: The variables available to a
672            <filename>Portfile</filename> when the <literal>PortGroup
673            perl5</literal> keyword is declared.</para>
674
675            <variablelist>
676              <varlistentry>
677                <term>perl5.version</term>
678
679                <listitem>
680                  <para>The MacPorts Perl version.</para>
681                </listitem>
682              </varlistentry>
683            </variablelist>
684
685            <variablelist>
686              <varlistentry>
687                <term>perl5.bin</term>
688
689                <listitem>
690                  <para>The Perl binary path (ie,
691                  <filename>${prefix}/bin/perl</filename>).</para>
692                </listitem>
693              </varlistentry>
694            </variablelist>
695
696            <variablelist>
697              <varlistentry>
698                <term>perl5.lib</term>
699
700                <listitem>
701                  <para>Path to the Perl vendor directory.</para>
702                </listitem>
703              </varlistentry>
704            </variablelist>
705
706            <variablelist>
707              <varlistentry>
708                <term>perl5.archlib</term>
709
710                <listitem>
711                  <para>Path to the Perl architecture-dependent modules
712                  directory.</para>
713                </listitem>
714              </varlistentry>
715            </variablelist>
716          </listitem>
717        </varlistentry>
718      </variablelist>
719
720      <variablelist>
721        <varlistentry>
722          <term>PortGroup python2x</term>
723
724          <listitem>
725            <para>Description: The variables available to a
726            <filename>Portfile</filename> when the <literal>PortGroup
727            python2x</literal> keyword is declared.</para>
728
729            <variablelist>
730              <varlistentry>
731                <term>python.bin</term>
732
733                <listitem>
734                  <para>The MacPorts Python binary location.</para>
735                </listitem>
736              </varlistentry>
737            </variablelist>
738
739            <variablelist>
740              <varlistentry>
741                <term>python.lib</term>
742
743                <listitem>
744                  <para>The Python dynamic library and path (ie,
745                  <filename>${prefix}/lib/libpython2.x.dylib</filename>).</para>
746                </listitem>
747              </varlistentry>
748            </variablelist>
749
750            <variablelist>
751              <varlistentry>
752                <term>python.include</term>
753
754                <listitem>
755                  <para>Path to the Python include directory.</para>
756                </listitem>
757              </varlistentry>
758            </variablelist>
759
760            <variablelist>
761              <varlistentry>
762                <term>python.pkgd</term>
763
764                <listitem>
765                  <para>Path to the Python site-packages directory. (ie,
766                  <filename>${prefix}/lib/python2.4/site-packages</filename>).</para>
767                </listitem>
768              </varlistentry>
769            </variablelist>
770          </listitem>
771        </varlistentry>
772      </variablelist>
773
774      <variablelist>
775        <varlistentry>
776          <term>PortGroup ruby</term>
777
778          <listitem>
779            <para>Description: The variables available to a
780            <filename>Portfile</filename> when the <literal>PortGroup
781            ruby</literal> keyword is declared.</para>
782
783            <variablelist>
784              <varlistentry>
785                <term>ruby.version</term>
786
787                <listitem>
788                  <para>The MacPorts Ruby version.</para>
789                </listitem>
790              </varlistentry>
791            </variablelist>
792
793            <variablelist>
794              <varlistentry>
795                <term>ruby.bin</term>
796
797                <listitem>
798                  <para>The Ruby binary location.</para>
799                </listitem>
800              </varlistentry>
801            </variablelist>
802
803            <variablelist>
804              <varlistentry>
805                <term>ruby.lib</term>
806
807                <listitem>
808                  <para>Path to the Ruby vendorlibdir directory (ie,
809                  <filename>${prefix}/lib/ruby/vendor_ruby/${ruby.version}</filename>)</para>
810                </listitem>
811              </varlistentry>
812
813              <varlistentry>
814                <term>ruby.arch</term>
815
816                <listitem>
817                  <para>The name for the Ruby architecture-dependent directory
818                  name (ie, <literal>i686-darwin8.10.1</literal>).</para>
819                </listitem>
820              </varlistentry>
821            </variablelist>
822
823            <variablelist>
824              <varlistentry>
825                <term>ruby.archlib</term>
826
827                <listitem>
828                  <para>Path to the Ruby vendor archdir (ie,
829                  <filename>${ruby.lib}/${ruby.arch}</filename>).</para>
830                </listitem>
831              </varlistentry>
832            </variablelist>
833          </listitem>
834        </varlistentry>
835      </variablelist>
836    </section>
837  </section>
838
839  <section id="reference.keywords">
840    <title>Keywords</title>
841
842    <para>MacPorts keywords are used to specify required or optional items
843    within a <filename>Portfile</filename>, or to override default options
844    used by MacPorts base for individual ports when necessary. Keywords are to
845    be used within the "global" and "variant" sections of Portfiles, and not
846    within optional port phase declarations. In other words, port phase
847    keywords are not located within port phase declarations, but rather they
848    <emphasis>refer</emphasis> to port phases and set options for those
849    phases, and they take affect whether or not phase declarations have been
850    explicitly defined by a port author.</para>
851
852    <para>The keywords listed below in category "global" specify information
853    for ports as a whole, whereas the keywords listed under a port phase
854    specify information to be used during a particular installation
855    phase.</para>
856
857    <section id="reference.keywords.append-delete">
858      <title>Using -append and -delete Keywords</title>
859
860      <para>It is often necessary to add to a list of keyword values
861      previously set by MacPorts base or set by a prior Portfile keyword. In
862      these cases we generally don't want to replace the current list, but
863      rather to add or delete values from the list. For this purpose there are
864      "-append" and "-delete" keywords; they are listed below according to
865      keyword category. The three most common uses for these keywords are
866      given below.</para>
867
868      <itemizedlist>
869        <listitem>
870          <para>Preserve default configure arguments.</para>
871
872          <para>MacPorts base sets the gcc compiler flags CFLAGS and LDFLAGS
873          for all ports using <literal>configure.cflags</literal> and
874          <literal>configure.ldflags</literal>, therefore to keep from
875          overwriting the default compiler flags use:</para>
876
877          <itemizedlist>
878            <listitem>
879              <para><literal>configure.cflags-append</literal></para>
880            </listitem>
881
882            <listitem>
883              <para><literal>configure.ldflags-append</literal></para>
884            </listitem>
885          </itemizedlist>
886        </listitem>
887
888        <listitem>
889          <para>Preserve default dependencies within a PortGroup.</para>
890
891          <para>Ports in a PortGroup have default library dependencies set by
892          MacPorts base. Therefore, never use <literal>depends_lib</literal>
893          in ports belonging to a PortGroup or it will overwrite the default
894          library dependencies. Instead, use:</para>
895
896          <itemizedlist>
897            <listitem>
898              <para><literal>depends_lib-append</literal></para>
899            </listitem>
900          </itemizedlist>
901        </listitem>
902
903        <listitem>
904          <para>Add or delete port dependencies, distfiles, patchfiles, etc.
905          for port variants.</para>
906
907          <para>When a variant requires more or fewer dependencies, distfiles,
908          or patchfiles, you want to add or remove items to the list of
909          dependency keyword values that were set in the global section of the
910          Portfile. Use the appropriate keywords, for example:</para>
911
912          <itemizedlist>
913            <listitem>
914              <para><literal>depends_lib-append</literal> or
915              <literal>depends_lib-delete</literal></para>
916            </listitem>
917
918            <listitem>
919              <para><literal>distfiles-append</literal> or
920              <literal>distfiles-delete</literal></para>
921            </listitem>
922
923            <listitem>
924              <para><literal>patchfiles-append</literal> or
925              <literal>patchfiles-delete</literal></para>
926            </listitem>
927          </itemizedlist>
928        </listitem>
929      </itemizedlist>
930    </section>
931
932    <section id="reference.keywords.global">
933      <title>Global Keywords</title>
934
935      <para>The list of global keywords.</para>
936
937      <variablelist>
938        <varlistentry>
939          <term>PortSystem</term>
940
941          <listitem>
942            <para>The top line of every Portfile; it must be followed by a
943            blank line. It defines which version of the Portfile interpreter
944            will be used.</para>
945
946            <programlisting>PortSystem   1.0
947
948</programlisting>
949          </listitem>
950        </varlistentry>
951
952        <varlistentry>
953          <term>name</term>
954
955          <listitem>
956            <para>The name of the Port; it should be lowercase.</para>
957
958            <simplelist>
959              <member>Type: required</member>
960
961              <member>Default: none</member>
962            </simplelist>
963
964            <programlisting>name         foo</programlisting>
965          </listitem>
966        </varlistentry>
967
968        <varlistentry>
969          <term>version</term>
970
971          <listitem>
972            <para>The version of the ported software.</para>
973
974            <programlisting>version      1.23.45</programlisting>
975          </listitem>
976        </varlistentry>
977
978        <varlistentry>
979          <term>revision</term>
980
981          <listitem>
982            <para>Optional keyword (default is 0) that is used to track port
983            revisions. It should not be incremented for port revisions unless
984            it would benefit users to upgrade an installed port, and cleared
985            when the port is updated to a newer version.</para>
986
987            <programlisting>revision     1</programlisting>
988          </listitem>
989        </varlistentry>
990
991        <varlistentry>
992          <term>categories</term>
993
994          <listitem>
995            <para>The category under which the ported software falls. The
996            first category should be the same as the directory within which
997            the Portfile is stored; secondary and tertiary categories may be
998            selected.</para>
999
1000            <programlisting>categories     net security</programlisting>
1001          </listitem>
1002        </varlistentry>
1003
1004        <varlistentry>
1005          <term>maintainers</term>
1006
1007          <listitem>
1008            <para>A port's maintainer is a person or persons who take
1009            responsibility for keeping the port up-to-date, and the maintainer
1010            keyword lists maintainer email addresses(s). However, many
1011            maintainers wish to hide these addresses from spambots; to do so
1012            follow these conventions:</para>
1013
1014            <itemizedlist>
1015              <listitem>
1016                <para>For addresses in domain @macports.org, simply omit the
1017                domain name.</para>
1018              </listitem>
1019
1020              <listitem>
1021                <para>For addresses in other domains, say
1022                <email>account@example.org</email>, use the convention
1023                example.org:account to specify the address.</para>
1024              </listitem>
1025            </itemizedlist>
1026
1027            <para>In the example below, the maintainer email addresses
1028            <email>jdoe@macports.org</email> and
1029            <email>julesverne@example.org</email> are hidden using these
1030            conventions.</para>
1031
1032            <programlisting>maintainers       jdoe \
1033                  example.org:julesverne</programlisting>
1034          </listitem>
1035        </varlistentry>
1036
1037        <varlistentry>
1038          <term>description</term>
1039
1040          <listitem>
1041            <para>A one-sentence description of the ported software.</para>
1042
1043            <programlisting>description    A clasic shooter arcade game.</programlisting>
1044          </listitem>
1045        </varlistentry>
1046
1047        <varlistentry>
1048          <term>long_description</term>
1049
1050          <listitem>
1051            <para>A long description of the ported software. Break long lines
1052            with escaped newlines.</para>
1053
1054            <programlisting>description    A classic shooter arcade game derived from \
1055               the game alien-munchers.  Not suitable for \
1056               children under two years old.      </programlisting>
1057          </listitem>
1058        </varlistentry>
1059
1060        <varlistentry>
1061          <term>homepage</term>
1062
1063          <listitem>
1064            <para>Port application's homepage.</para>
1065
1066            <programlisting>homepage       http://www.somesite.org/apps</programlisting>
1067          </listitem>
1068        </varlistentry>
1069
1070        <varlistentry>
1071          <term>platforms</term>
1072
1073          <listitem>
1074            <para>The platforms on which the port has been tested.</para>
1075
1076            <programlisting>platforms      darwin freebsd</programlisting>
1077          </listitem>
1078        </varlistentry>
1079
1080        <varlistentry>
1081          <term>depends_lib</term>
1082
1083          <listitem>
1084            <para>Library dependencies are needed both at build time (for
1085            headers and libraries to link against) and at run time.</para>
1086
1087            <programlisting>depends_lib     port:rrdtool</programlisting>
1088
1089            <simplelist>
1090              <member>depends_lib-append</member>
1091
1092              <member>depends_lib-delete</member>
1093            </simplelist>
1094          </listitem>
1095        </varlistentry>
1096
1097        <varlistentry>
1098          <term>depends_build</term>
1099
1100          <listitem>
1101            <para>Build dependencies are needed when software is compiled, but
1102            not needed at all once the software is compiled and
1103            installed.</para>
1104
1105            <programlisting>depends_build    port:gcc42</programlisting>
1106
1107            <simplelist>
1108              <member>depends_build-append</member>
1109
1110              <member>depends_build-delete</member>
1111            </simplelist>
1112          </listitem>
1113        </varlistentry>
1114
1115        <varlistentry>
1116          <term>depends_run</term>
1117
1118          <listitem>
1119            <para>Run dependencies are needed when the software is run, but
1120            not to compile it.</para>
1121
1122            <programlisting>depends_run      port:apache2</programlisting>
1123
1124            <simplelist>
1125              <member>depends_run-append</member>
1126
1127              <member>depends_run-delete</member>
1128            </simplelist>
1129          </listitem>
1130        </varlistentry>
1131      </variablelist>
1132    </section>
1133
1134    <section id="reference.keywords.fetch">
1135      <title>Fetch</title>
1136
1137      <para>The list of keywords related to the fetch phase.</para>
1138
1139      <variablelist>
1140        <varlistentry>
1141          <term>master_sites</term>
1142
1143          <listitem>
1144            <para>A list of urls from which a port's download file(s) may be
1145            retrieved.</para>
1146
1147            <para>For ports that require only one download file, the list is
1148            searched in order until a file matching
1149            ${distname}${extract.suffix} is found.</para>
1150
1151            <programlisting>master_sites   http://www.somesite.org/files/ \
1152               http://www.somemirror.org/somesite_org/files/</programlisting>
1153
1154            <para>You may also use mirror sites predefined by MacPorts. Here
1155            the sourceforge and gnu mirrors are used.</para>
1156
1157            <programlisting>master_sites   sourceforge gnu</programlisting>
1158
1159            <para>When using mirror master_sites, the subdirectory
1160            <varname>${name}</varname> is checked on every mirror. If the
1161            mirror subdirectory does not match ${name}, then you may specify
1162            it using after the mirror separated by a colon.</para>
1163
1164            <programlisting>master_sites   sourceforge:widget \
1165               gnu:widget</programlisting>
1166
1167            <para>For ports that must fetch multiple download files from
1168            different locations, you may label the files with tags and match
1169            the tags in a distfiles statement. The format is
1170            <literal>mirror:subdirectory:tag</literal>.</para>
1171
1172            <para>In the example below, file_one.tar.gz is fetched from
1173            sourceforge mirrors in subdirectory <varname>${name}</varname>;
1174            file tagtwo.tar.gz is fetched from the gnu mirrors in subdirectory
1175            sources.</para>
1176
1177            <programlisting>distfiles       file_one.tar.gz:tagone \
1178                file_two.tar.gz:tagtwo \
1179                file_three.tar.gz
1180
1181master_sites    sourceforge::tagone \
1182                gnu:sources:tagtwo</programlisting>
1183          </listitem>
1184        </varlistentry>
1185
1186        <varlistentry>
1187          <term>patch_sites</term>
1188
1189          <listitem>
1190            <para>A list of sites from which a port's patchfiles may be
1191            downloaded, where applicable.</para>
1192
1193            <programlisting>patch_sites    ftp://ftp.patchcityrepo.com/pub/magic/patches</programlisting>
1194          </listitem>
1195        </varlistentry>
1196
1197        <varlistentry>
1198          <term>distname</term>
1199
1200          <listitem>
1201            <para>The default distname is
1202            <varname>${name}-${version}</varname>. This keyword is used to
1203            specify download files that do not meet this standard (excluding
1204            the extract.suffix).</para>
1205
1206            <programlisting>distname     ${name}</programlisting>
1207          </listitem>
1208        </varlistentry>
1209
1210        <varlistentry>
1211          <term>distfiles</term>
1212
1213          <listitem>
1214            <para>The default distfile name is
1215            <varname>${distname}${extract.suffix}</varname>. This keyword is
1216            used when a download file for a port is not
1217            <varname>${distname}${extract.suffix}</varname> or to used to
1218            specify multiple download files.</para>
1219
1220            <programlisting>distfiles    ${name}-dev_src.tgz</programlisting>
1221          </listitem>
1222        </varlistentry>
1223
1224        <varlistentry>
1225          <term>extract.suffix</term>
1226
1227          <listitem>
1228            <para>The default value is .tar.gz, so is normally used to specify
1229            file suffixes other than .tar.gz.</para>
1230
1231            <programlisting>extract.suffix   .tar.gz</programlisting>
1232          </listitem>
1233        </varlistentry>
1234
1235        <varlistentry>
1236          <term>use_bzip2</term>
1237
1238          <listitem>
1239            <para>This keyword is for downloads that are tarred and bzipped.
1240            It automatically sets these variables:</para>
1241
1242            <simplelist>
1243              <member>extract_suffix = .tar.bz2</member>
1244
1245              <member>extract.cmd = bzip</member>
1246            </simplelist>
1247
1248            <programlisting>use_bzip2     yes</programlisting>
1249          </listitem>
1250        </varlistentry>
1251
1252        <varlistentry>
1253          <term>use_zip</term>
1254
1255          <listitem>
1256            <para>This keyword is for downloads are zipped. It automatically
1257            sets these variables:</para>
1258
1259            <simplelist>
1260              <member>extract.suffix = .zip</member>
1261
1262              <member>extract.cmd = unzip</member>
1263
1264              <member>extract.pre_args = -q</member>
1265
1266              <member>extract.post_args = "-d $portpath/$workdir"</member>
1267            </simplelist>
1268
1269            <programlisting>use_zip       yes</programlisting>
1270          </listitem>
1271        </varlistentry>
1272      </variablelist>
1273    </section>
1274
1275    <section id="reference.keywords.checksum">
1276      <title>Checksum</title>
1277
1278      <para>The list of keywords related to the checksum phase.</para>
1279
1280      <variablelist>
1281        <varlistentry>
1282          <term>checksums</term>
1283
1284          <listitem>
1285            <para>Checksum(s) of the distribution files.</para>
1286
1287            <programlisting>checksums     md5 65b89365a65dcad71d4402b48</programlisting>
1288
1289            <para>To download multiple files for a port, you must associate
1290            the files with their checksums by including the filename.</para>
1291
1292            <programlisting>checksums     ${distname}${extract.suffix} md5 65b89365a65dcad71d4402b44 \
1293              hobbit.tar.gz md5 65b89365a65dcad71d4402b48</programlisting>
1294          </listitem>
1295        </varlistentry>
1296      </variablelist>
1297    </section>
1298
1299    <section id="reference.keywords.extract">
1300      <title>Extract</title>
1301
1302      <para>The list of keywords related to the extract phase.</para>
1303
1304      <variablelist>
1305        <varlistentry>
1306          <term>extract.only</term>
1307
1308          <listitem>
1309            <para>List of files to extract into
1310            <varname>${worksrcpath}</varname>; the default is
1311            <varname>${distfiles}</varname>. Only use if default extract
1312            behavior is not correct for your port.</para>
1313
1314            <programlisting>extract.only     foo.tar.gz bar.tar.gz</programlisting>
1315
1316            <simplelist>
1317              <member>extract.only-append</member>
1318
1319              <member>extract.only-delete</member>
1320            </simplelist>
1321          </listitem>
1322        </varlistentry>
1323
1324        <varlistentry>
1325          <term>extract.cmd</term>
1326
1327          <listitem>
1328            <para>Command to perform extraction; the default is "gzip".</para>
1329
1330            <programlisting>extract.cmd     gunzip</programlisting>
1331          </listitem>
1332        </varlistentry>
1333
1334        <varlistentry>
1335          <term>extract.pre_args</term>
1336
1337          <listitem>
1338            <para>Arguments added to extract.cmd before a file name; the
1339            default is "-dc".</para>
1340
1341            <programlisting>extract.pre_args    -cd</programlisting>
1342
1343            <simplelist>
1344              <member>extract.pre_args-append</member>
1345
1346              <member>extract.pre_args-delete</member>
1347            </simplelist>
1348          </listitem>
1349        </varlistentry>
1350
1351        <varlistentry>
1352          <term>extract.args</term>
1353
1354          <listitem>
1355            <para>Arguments to extract.cmd; the default is
1356            <varname>${distpath}/${distfile}</varname>.</para>
1357
1358            <programlisting>extract.args      </programlisting>
1359
1360            <simplelist>
1361              <member>extract.args-append</member>
1362
1363              <member>extract.args-delete</member>
1364            </simplelist>
1365          </listitem>
1366        </varlistentry>
1367
1368        <varlistentry>
1369          <term>extract.post_args</term>
1370
1371          <listitem>
1372            <para>Arguments added to extract.cmd after a file name; the
1373            default is "| tar -xf".</para>
1374
1375            <programlisting>extract.post_args     "| tar -xf - --exclude 'CVS'"</programlisting>
1376
1377            <simplelist>
1378              <member>extract.post_args-append</member>
1379
1380              <member>extract.post_args-delete</member>
1381            </simplelist>
1382          </listitem>
1383        </varlistentry>
1384      </variablelist>
1385    </section>
1386
1387    <section id="reference.keywords.patch">
1388      <title>Patch</title>
1389
1390      <para>The list of keywords related to the patch phase.</para>
1391
1392      <variablelist>
1393        <varlistentry>
1394          <term>patchfiles</term>
1395
1396          <listitem>
1397            <para>Specify patch files to be applied for a port.</para>
1398
1399            <programlisting>patchfiles     patch-Makefile.in patch-source.c</programlisting>
1400
1401            <simplelist>
1402              <member>patchfiles-append</member>
1403
1404              <member>patchfiles-delete</member>
1405            </simplelist>
1406          </listitem>
1407        </varlistentry>
1408      </variablelist>
1409    </section>
1410
1411    <section id="reference.keywords.configure">
1412      <title>Configure</title>
1413
1414      <para>The list of keywords related to the configure phase.</para>
1415
1416      <para>MacPorts base sets some important default configure options, so
1417      should use the -append version of most configure keywords so you don't
1418      overwrite them. For example, MacPorts base sets default
1419      <literal>configure.ldflags</literal> so you should always use
1420      <literal>configure.cflags-append</literal> to set additional CFLAGS in
1421      Portfiles.</para>
1422
1423      <variablelist>
1424        <varlistentry>
1425          <term>configure.env</term>
1426
1427          <listitem>
1428            <para>Set environment variables for configure.</para>
1429
1430            <programlisting>configure.env     CFLAGS=-I${prefix}/include</programlisting>
1431
1432            <simplelist>
1433              <member>configure.env-append</member>
1434
1435              <member>configure.env-delete</member>
1436            </simplelist>
1437          </listitem>
1438        </varlistentry>
1439
1440        <varlistentry>
1441          <term>configure.pre_args</term>
1442
1443          <listitem>
1444            <para>Arguments added to configure.cmd before
1445            <varname>${configure.args}</varname>; the default is
1446            --prefix=${prefix}.</para>
1447
1448            <programlisting>configure.pre_args     --prefix=${prefix}/apache2</programlisting>
1449
1450            <simplelist>
1451              <member>configure.pre_args-append</member>
1452
1453              <member>configure.pre_args-delete</member>
1454            </simplelist>
1455          </listitem>
1456        </varlistentry>
1457
1458        <varlistentry>
1459          <term>configure.args</term>
1460
1461          <listitem>
1462            <para>Arguments to pass to configure.</para>
1463
1464            <programlisting>configure.args         --etcdir=${prefix}/etc</programlisting>
1465
1466            <simplelist>
1467              <member>configure.args-append</member>
1468
1469              <member>configure.args-delete</member>
1470            </simplelist>
1471          </listitem>
1472        </varlistentry>
1473
1474        <varlistentry>
1475          <term>configure.cflags</term>
1476
1477          <listitem>
1478            <para>Set CFLAGS compiler flags.</para>
1479
1480            <programlisting>configure.cflags      -I/usr/X11R6/include</programlisting>
1481
1482            <simplelist>
1483              <member>configure.cflags-append</member>
1484
1485              <member>configure.cflags-delete</member>
1486            </simplelist>
1487          </listitem>
1488        </varlistentry>
1489
1490        <varlistentry>
1491          <term>configure.ldflags</term>
1492
1493          <listitem>
1494            <para>Set LDFLAGS for the linker.</para>
1495
1496            <programlisting>configure.ldflags     -L${prefix}/lib/db44</programlisting>
1497
1498            <simplelist>
1499              <member>configure.ldflags-append</member>
1500
1501              <member>configure.ldflags-delete</member>
1502            </simplelist>
1503          </listitem>
1504        </varlistentry>
1505
1506        <varlistentry>
1507          <term>configure.cppflags</term>
1508
1509          <listitem>
1510            <para>Set CPPFLAGS for passing to the C processor.</para>
1511
1512            <programlisting>configure.cppflags    -I${prefix}/include/db4</programlisting>
1513
1514            <simplelist>
1515              <member>configure.cppflags-append</member>
1516
1517              <member>configure.cppflags-delete</member>
1518            </simplelist>
1519          </listitem>
1520        </varlistentry>
1521      </variablelist>
1522
1523      <section id="reference.keywords.configure.automake-autoconf">
1524        <title>Automake and Autoconf</title>
1525
1526        <para>The list of configure keywords available for ports that need
1527        automake and/or autoconf.</para>
1528
1529        <para><variablelist>
1530            <varlistentry>
1531              <term>use_automake</term>
1532
1533              <listitem>
1534                <para>Whether or not to use automake; the default is
1535                "no".</para>
1536
1537                <programlisting>use_automake      yes</programlisting>
1538              </listitem>
1539            </varlistentry>
1540
1541            <varlistentry>
1542              <term>automake.env</term>
1543
1544              <listitem>
1545                <para>Environment variables to pass to automake.</para>
1546
1547                <programlisting>automake.env      CFLAGS=-I${prefix}/include</programlisting>
1548              </listitem>
1549            </varlistentry>
1550
1551            <varlistentry>
1552              <term>automake.args</term>
1553
1554              <listitem>
1555                <para>Arguments to pass to automake.</para>
1556
1557                <programlisting>automake.args     --foreign</programlisting>
1558              </listitem>
1559            </varlistentry>
1560
1561            <varlistentry>
1562              <term>automake.dir</term>
1563
1564              <listitem>
1565                <para>Directory in which to run
1566                <varname>${automake.cmd}</varname>; the default is
1567                <varname>${worksrcpath}</varname>.</para>
1568
1569                <programlisting>automake.dir      ./src</programlisting>
1570              </listitem>
1571            </varlistentry>
1572
1573            <varlistentry>
1574              <term>use_autoconf</term>
1575
1576              <listitem>
1577                <para>Whether or not to use autoconf; the default is
1578                "no".</para>
1579
1580                <programlisting>use_autoconf      yes</programlisting>
1581              </listitem>
1582            </varlistentry>
1583
1584            <varlistentry>
1585              <term>autoconf.env</term>
1586
1587              <listitem>
1588                <para>Environmental variables to pass to autoconf.</para>
1589
1590                <programlisting>autoconf.env      CFLAGS=-I${prefix}/include/gtk12</programlisting>
1591              </listitem>
1592            </varlistentry>
1593
1594            <varlistentry>
1595              <term>autoconf.args</term>
1596
1597              <listitem>
1598                <para>Arguments to pass to autoconf.</para>
1599
1600                <programlisting>autoconf.args     -l src/aclocaldir</programlisting>
1601              </listitem>
1602            </varlistentry>
1603
1604            <varlistentry>
1605              <term>autoconf.dir</term>
1606
1607              <listitem>
1608                <para>Directory in which to run
1609                <varname>${autoconf.cmd}</varname>; the default is
1610                <varname>${worksrcpath}</varname>.</para>
1611
1612                <programlisting>autoconf.dir      src</programlisting>
1613              </listitem>
1614            </varlistentry>
1615          </variablelist></para>
1616      </section>
1617    </section>
1618
1619    <section id="reference.keywords.build">
1620      <title>Build</title>
1621
1622      <para>The list of keywords related to the build phase.</para>
1623
1624      <variablelist>
1625        <varlistentry>
1626          <term>build.cmd</term>
1627
1628          <listitem>
1629            <para>Make command to run in <varname>${worksrcdir}</varname>; the
1630            default is "make".</para>
1631
1632            <programlisting>build.cmd      pbxbuild</programlisting>
1633          </listitem>
1634        </varlistentry>
1635
1636        <varlistentry>
1637          <term>build.type</term>
1638
1639          <listitem>
1640            <para>Defines which "make" is required: "gnu" or "bsd". Sets
1641            build.cmd to either "gnumake" or "bsdmake" accordingly.</para>
1642
1643            <programlisting>build.type     gnu</programlisting>
1644          </listitem>
1645        </varlistentry>
1646
1647        <varlistentry>
1648          <term>build.pre_args</term>
1649
1650          <listitem>
1651            <para>Arguments to pass to <varname>${build.cmd}</varname> before
1652            <varname>${build.args}</varname>; the default is
1653            <varname>${build.target.current}</varname>.</para>
1654
1655            <programlisting>build.pre_args      -project AudioSlicer.xcode</programlisting>
1656
1657            <simplelist>
1658              <member>build.pre_args-append</member>
1659
1660              <member>build.pre_args-delete</member>
1661            </simplelist>
1662          </listitem>
1663        </varlistentry>
1664
1665        <varlistentry>
1666          <term>build.args</term>
1667
1668          <listitem>
1669            <para>Arguments to pass to <varname>${build.cmd}</varname>.</para>
1670
1671            <programlisting>build.args          -DNOWARN</programlisting>
1672          </listitem>
1673        </varlistentry>
1674
1675        <varlistentry>
1676          <term>build.target</term>
1677
1678          <listitem>
1679            <para>Target to pass to make for building everything; default is
1680            "all".</para>
1681
1682            <programlisting>build.target.all    all-src</programlisting>
1683          </listitem>
1684        </varlistentry>
1685      </variablelist>
1686    </section>
1687
1688    <section id="reference.keywords.destroot">
1689      <title>Destroot</title>
1690
1691      <para>The list of keywords related to the destroot phase.</para>
1692
1693      <variablelist>
1694        <varlistentry>
1695          <term>destroot.cmd</term>
1696
1697          <listitem>
1698            <para>Install command to run relative to
1699            <varname>${worksrcdir}</varname>; defaults is
1700            <varname>${build.cmd}</varname>.</para>
1701
1702            <programlisting>destroot.cmd         pbxbuild</programlisting>
1703          </listitem>
1704        </varlistentry>
1705
1706        <varlistentry>
1707          <term>destroot.type</term>
1708
1709          <listitem>
1710            <para>Defines which "make" is required: either "gnu" or "bsd".
1711            Sets install.cmd to either "gnumake" or "bsdmake"
1712            accordingly.</para>
1713
1714            <programlisting>destroot.type        gnu</programlisting>
1715          </listitem>
1716        </varlistentry>
1717
1718        <varlistentry>
1719          <term>destroot.pre_args</term>
1720
1721          <listitem>
1722            <para>Arguments to pass to <varname>${destroot.cmd}</varname>
1723            before <varname>${destroot.args}</varname>; default is
1724            ${destroot.target}.</para>
1725
1726            <programlisting>destroot.pre_args    -project AudioSlicer.xcode</programlisting>
1727
1728            <simplelist>
1729              <member>destroot.pre_args-append</member>
1730
1731              <member>destroot.pre_args-delete</member>
1732            </simplelist>
1733          </listitem>
1734        </varlistentry>
1735
1736        <varlistentry>
1737          <term>destroot.target</term>
1738
1739          <listitem>
1740            <para>Install target to pass to
1741            <varname>${destroot.cmd}</varname>.</para>
1742
1743            <programlisting>destroot.target     install-src</programlisting>
1744
1745            <simplelist>
1746              <member>destroot.target-append</member>
1747
1748              <member>destroot.target-delete</member>
1749            </simplelist>
1750          </listitem>
1751        </varlistentry>
1752
1753        <varlistentry>
1754          <term>destroot.destdir</term>
1755
1756          <listitem>
1757            <para>Arguments passed to ${destroot.cmd} to install correctly
1758            into the destroot.</para>
1759
1760            <programlisting>destroot.destdir     prefix=${destroot}${prefix}</programlisting>
1761
1762            <note>
1763              <para>If an application's Makefile properly supports the DESTDIR
1764              variable, MacPorts will automatically destroot the port
1765              properly. A port must destroot properly or the port will not
1766              install correctly, upgrade, or uninstall. If not, you may need
1767              to set this variable, or even patch the application's
1768              Makefile.</para>
1769            </note>
1770          </listitem>
1771        </varlistentry>
1772
1773        <varlistentry>
1774          <term>destroot.keepdirs</term>
1775
1776          <listitem>
1777            <para>A list of directories that should not be removed if empty
1778            upon destroot completion.</para>
1779
1780            <programlisting>destroot.keepdirs \
1781                ${destroot}${prefix}/var/run \
1782                ${destroot}${prefix}/var/log \
1783                ${destroot}${prefix}/var/cache/mrtg</programlisting>
1784          </listitem>
1785        </varlistentry>
1786
1787        <varlistentry>
1788          <term>destroot.violate_mtree</term>
1789
1790          <listitem>
1791            <para>MacPorts tests for compliance to the common directory
1792            structure in ${prefix}; the default is "no". If a port is not
1793            compliant with the standard, set it to "yes".</para>
1794
1795            <programlisting>destroot.violate_mtree    yes</programlisting>
1796          </listitem>
1797        </varlistentry>
1798      </variablelist>
1799    </section>
1800  </section>
1801
1802  <section id="reference.tcl-extensions">
1803    <title>Tcl Extensions</title>
1804
1805    <para>A MacPorts Portfile is a Tcl script, so it may contain any arbitrary
1806    Tcl code you may learn about in a <ulink
1807    url="http://tmml.sourceforge.net/doc/tcl/">Tcl reference manual</ulink>.
1808    However, few authors will use arbitrary Tcl code; the vast majority will
1809    use Tcl extensions that are coded within MacPorts for performing the most
1810    common tasks needed for Portfiles. The list below is a list of Tcl
1811    extensions provided by MacPorts base.</para>
1812
1813    <para><variablelist>
1814        <varlistentry>
1815          <term>file</term>
1816
1817          <listitem>
1818            <para>Description.</para>
1819
1820            <variablelist>
1821              <varlistentry>
1822                <term>file copy</term>
1823
1824                <listitem>
1825                  <para></para>
1826                </listitem>
1827              </varlistentry>
1828            </variablelist>
1829
1830            <variablelist>
1831              <varlistentry>
1832                <term>file move</term>
1833
1834                <listitem>
1835                  <para></para>
1836                </listitem>
1837              </varlistentry>
1838            </variablelist>
1839
1840            <variablelist>
1841              <varlistentry>
1842                <term>file rename</term>
1843
1844                <listitem>
1845                  <para></para>
1846                </listitem>
1847              </varlistentry>
1848            </variablelist>
1849
1850            <variablelist>
1851              <varlistentry>
1852                <term>file delete [-force]</term>
1853
1854                <listitem>
1855                  <para></para>
1856                </listitem>
1857              </varlistentry>
1858            </variablelist>
1859
1860            <variablelist>
1861              <varlistentry>
1862                <term>file mkdir</term>
1863
1864                <listitem>
1865                  <para></para>
1866                </listitem>
1867              </varlistentry>
1868            </variablelist>
1869          </listitem>
1870        </varlistentry>
1871
1872        <varlistentry>
1873          <term>macros</term>
1874
1875          <listitem>
1876            <para>Description.</para>
1877
1878            <variablelist>
1879              <varlistentry>
1880                <term>copy</term>
1881
1882                <listitem>
1883                  <para>Shorthand alternative to "file copy".</para>
1884                </listitem>
1885              </varlistentry>
1886            </variablelist>
1887
1888            <variablelist>
1889              <varlistentry>
1890                <term>move</term>
1891
1892                <listitem>
1893                  <para>Shorthand alternative to "file rename".</para>
1894                </listitem>
1895              </varlistentry>
1896
1897              <varlistentry>
1898                <term>delete file ...</term>
1899
1900                <listitem>
1901                  <para>Deletes each of the given files/directories. Behaves
1902                  similarly to file delete -force except that file delete
1903                  -force will fail to delete directories properly on 10.3
1904                  systems.</para>
1905                </listitem>
1906              </varlistentry>
1907
1908              <varlistentry>
1909                <term>touch</term>
1910
1911                <listitem>
1912                  <para>Mimicks the BSD touch command.</para>
1913                </listitem>
1914              </varlistentry>
1915
1916              <varlistentry>
1917                <term>ln</term>
1918
1919                <listitem>
1920                  <para>Mimickes the BSD ln command.</para>
1921                </listitem>
1922              </varlistentry>
1923            </variablelist>
1924          </listitem>
1925        </varlistentry>
1926
1927        <varlistentry>
1928          <term>xinstall</term>
1929
1930          <listitem>
1931            <para>xinstall copies files and creates directories; it is
1932            intended to be compatible with install(1).</para>
1933
1934            <variablelist>
1935              <varlistentry>
1936                <term>xinstall [-o owner] [-g group] [-m mode] [file1 file2
1937                ...] directory</term>
1938
1939                <listitem>
1940                  <para>Install the specified file(s) to a destination
1941                  directory.</para>
1942                </listitem>
1943              </varlistentry>
1944            </variablelist>
1945
1946            <variablelist>
1947              <varlistentry>
1948                <term>xinstall [-o owner] [-g group] [-m mode] [-W dir] [file1
1949                file2 ...] directory</term>
1950
1951                <listitem>
1952                  <para>Change to <option>dir</option> and install file(s) to
1953                  a destination directory.</para>
1954                </listitem>
1955              </varlistentry>
1956            </variablelist>
1957
1958            <variablelist>
1959              <varlistentry>
1960                <term>eval xinstall [-o owner] [-g group] [-m mode] [glob
1961                regexp] directory</term>
1962
1963                <listitem>
1964                  <para>Install the file(s) matching the glob expression to a
1965                  destination directory.</para>
1966                </listitem>
1967              </varlistentry>
1968            </variablelist>
1969
1970            <variablelist>
1971              <varlistentry>
1972                <term>xinstall -d [-o owner] [-g group] [-m mode]
1973                directory</term>
1974
1975                <listitem>
1976                  <para>Create a directory.</para>
1977                </listitem>
1978              </varlistentry>
1979            </variablelist>
1980
1981            <para>Defaults:</para>
1982
1983            <itemizedlist>
1984              <listitem>
1985                <para>owner -</para>
1986              </listitem>
1987
1988              <listitem>
1989                <para>group -</para>
1990              </listitem>
1991
1992              <listitem>
1993                <para>mode -</para>
1994              </listitem>
1995            </itemizedlist>
1996
1997            <para>Examples:</para>
1998
1999            <programlisting>xinstall -m 640 ${worksrcpath}/doc README \
2000       ${destroot}${prefix}/share/doc/${name}</programlisting>
2001
2002            <programlisting>xinstall -m 640 -W ${worksrcpath}/doc README INSTALL COPY \
2003       ${destroot}${prefix}/share/doc/${name}</programlisting>
2004
2005            <programlisting>eval xinstall -m 640 [glob ${worksrcpath}/doc/*] \
2006       ${destroot}${prefix}/share/doc/${name}</programlisting>
2007
2008            <programlisting>xinstall -d ${destroot}${prefix}/share/doc/${name}</programlisting>
2009          </listitem>
2010        </varlistentry>
2011
2012        <varlistentry>
2013          <term>reinplace</term>
2014
2015          <listitem>
2016            <para>Description.</para>
2017
2018            <para>Examples:</para>
2019
2020            <programlisting>example 1</programlisting>
2021
2022            <programlisting>example 2</programlisting>
2023
2024            <programlisting>example 3</programlisting>
2025          </listitem>
2026        </varlistentry>
2027
2028        <varlistentry>
2029          <term>user/group</term>
2030
2031          <listitem>
2032            <para></para>
2033
2034            <variablelist>
2035              <varlistentry>
2036                <term>adduser username [uid=uid] [gid=gid] [passwd=passwd]
2037                [realname=realname] [home=home] [shell=shell]</term>
2038
2039                <listitem>
2040                  <para>Add a new local user to the system with the specified
2041                  uid, gid, password, real name, home directory and login
2042                  shell.</para>
2043                </listitem>
2044              </varlistentry>
2045            </variablelist>
2046
2047            <variablelist>
2048              <varlistentry>
2049                <term>existsuser username</term>
2050
2051                <listitem>
2052                  <para>Check if a local user exists.</para>
2053                </listitem>
2054              </varlistentry>
2055            </variablelist>
2056
2057            <variablelist>
2058              <varlistentry>
2059                <term>nextuid</term>
2060
2061                <listitem>
2062                  <para>Returns the highest used uid plus one.</para>
2063                </listitem>
2064              </varlistentry>
2065            </variablelist>
2066
2067            <variablelist>
2068              <varlistentry>
2069                <term>addgroup group [gid=gid] [passwd=passwd]
2070                [realname=realname] [users=users]</term>
2071
2072                <listitem>
2073                  <para>Add a new local group to the system, with the
2074                  specified gid, password, real name, and with a list users as
2075                  members.</para>
2076                </listitem>
2077              </varlistentry>
2078            </variablelist>
2079
2080            <variablelist>
2081              <varlistentry>
2082                <term>existsgroup group</term>
2083
2084                <listitem>
2085                  <para>Check if a local group exists and return the
2086                  corresponding gid. This can be used with adduser:</para>
2087
2088                  <programlisting>addgroup foo
2089adduser foo gid=[existsgroup foo]</programlisting>
2090                </listitem>
2091              </varlistentry>
2092            </variablelist>
2093
2094            <variablelist>
2095              <varlistentry>
2096                <term>nextgid</term>
2097
2098                <listitem>
2099                  <para>Returns the highest used gid plus one.</para>
2100                </listitem>
2101              </varlistentry>
2102            </variablelist>
2103          </listitem>
2104        </varlistentry>
2105
2106        <varlistentry>
2107          <term>External program execution</term>
2108
2109          <listitem>
2110            <para>Use only when ....</para>
2111          </listitem>
2112        </varlistentry>
2113      </variablelist></para>
2114
2115    <para></para>
2116  </section>
2117</chapter>
Note: See TracBrowser for help on using the repository browser.