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

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

Refine the terms and language in the StartupItems section.

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