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

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

doc-new: All portfile man pages are now generated automatically.

File size: 26.0 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4<refentry>
5  <refmeta>
6    <refentrytitle>PORTFILE-GLOBAL</refentrytitle>
7
8    <manvolnum>7</manvolnum>
9  </refmeta>
10
11  <refnamediv>
12    <refname>portfile-global</refname>
13
14    <refpurpose>MacPorts Portfile reference</refpurpose>
15  </refnamediv>
16
17  <refsection>
18    <title>Description</title>
19
20    <para>A reference of all available Portfile global variables and keywords.
21    Portfiles consist of valid TCL and are encoded in UTF-8. They usually
22    contain only simple keyword/value combinations and Tcl extensions as
23    described below, though they may also contain arbitrary TCL code. Every
24    port has a corresponding Portfile, but Portfiles do not completely define
25    a port's installation behavior since the MacPorts base has default port
26    installation characteristics coded within it. Therefore Portfiles need
27    only specify required options and, if necessary, non-default
28    characteristics for a port.</para>
29  </refsection>
30
31  <refsection>
32    <title>Global Variables</title>
33
34    <para>Global variables are variables available to any Portfile. For a list
35    of additional variables available to ports that are assigned to a MacPorts
36    Portgroup, see portgroup(7).</para>
37
38    <variablelist>
39      <varlistentry>
40        <term>prefix</term>
41
42        <listitem>
43          <para>Installation prefix, set in
44          <filename>${prefix}/etc/macports/macports.conf</filename> —may be
45          overridden on a per port basis. For example, aqua applications are
46          installed in <filename>/Applications/MacPorts</filename>.</para>
47
48          <para>Default: /opt/local</para>
49        </listitem>
50      </varlistentry>
51
52      <varlistentry>
53        <term>binpath</term>
54
55        <listitem>
56          <para>Default PATH to use in finding executables.</para>
57        </listitem>
58      </varlistentry>
59
60      <varlistentry>
61        <term>libpath</term>
62
63        <listitem>
64          <para>Path to the MacPorts TCL libraries.</para>
65        </listitem>
66      </varlistentry>
67
68      <varlistentry>
69        <term>portpath</term>
70
71        <listitem>
72          <para>Full path to the Portfile location.</para>
73        </listitem>
74      </varlistentry>
75
76      <varlistentry>
77        <term>filesdir</term>
78
79        <listitem>
80          <para>Path to port files relative to
81          <varname>${portpath}</varname>.</para>
82        </listitem>
83      </varlistentry>
84
85      <varlistentry>
86        <term>workpath</term>
87
88        <listitem>
89          <para>Full path to work directory.</para>
90        </listitem>
91      </varlistentry>
92
93      <varlistentry>
94        <term>worksrcpath</term>
95
96        <listitem>
97          <para>Full path to extracted source code. Equivalent to
98          <varname>${workpath}/${worksrcdir}</varname>.</para>
99        </listitem>
100      </varlistentry>
101
102      <varlistentry>
103        <term>destroot</term>
104
105        <listitem>
106          <para>Full path into which software will be destrooted. Equivalent
107          to <filename>${workpath}/destroot</filename>.</para>
108        </listitem>
109      </varlistentry>
110
111      <varlistentry>
112        <term>distpath</term>
113
114        <listitem>
115          <para>Location to store downloaded distfiles.</para>
116        </listitem>
117      </varlistentry>
118
119      <varlistentry>
120        <term>install.user</term>
121
122        <listitem>
123          <para>The Unix user at the time of port installation.</para>
124        </listitem>
125      </varlistentry>
126
127      <varlistentry>
128        <term>install.group</term>
129
130        <listitem>
131          <para>The Unix group at the time of port installation.</para>
132        </listitem>
133      </varlistentry>
134
135      <varlistentry>
136        <term>os.platform</term>
137
138        <listitem>
139          <para>Identifies platform type (ie, "darwin", "freebsd",
140          etc).</para>
141        </listitem>
142      </varlistentry>
143
144      <varlistentry>
145        <term>os.arch</term>
146
147        <listitem>
148          <para>Identifies hardware type (ie, "powerpc", "intel").</para>
149        </listitem>
150      </varlistentry>
151
152      <varlistentry>
153        <term>os.version</term>
154
155        <listitem>
156          <para>The version number of the host operating system (ie "8.0" for
157          Darwin 8.0).</para>
158        </listitem>
159      </varlistentry>
160
161      <varlistentry>
162        <term>os.major</term>
163
164        <listitem>
165          <para>The major version number of the host operating system (ie "8"
166          for Darwin 8.0).</para>
167        </listitem>
168      </varlistentry>
169    </variablelist>
170  </refsection>
171
172  <refsection>
173    <title>Global Keywords</title>
174
175    <para>MacPorts keywords are used to specify required or optional items
176    within a Portfile, or to override default options used by MacPorts base
177    for individual ports. Keywords are to be used within the "global" and
178    "variant" sections of Portfiles, and not within optional port phase
179    declarations.</para>
180
181    <para>The global keywords listed below specify information for ports as a
182    whole, whereas the keywords listed under a port phase specify information
183    to be used during a particular installation phase.</para>
184
185    <refsection>
186      <title>General</title>
187
188      <para>The list of global keywords.</para>
189
190      <variablelist>
191        <varlistentry>
192          <term>PortSystem</term>
193
194          <listitem>
195            <para>The top line of every Portfile; it must be followed by a
196            blank line. It defines which version of the Portfile interpreter
197            will be used.</para>
198
199            <programlisting>PortSystem   1.0
200
201</programlisting>
202          </listitem>
203        </varlistentry>
204
205        <varlistentry>
206          <term>name</term>
207
208          <listitem>
209            <para>The name of the Port; it should be lowercase.</para>
210
211            <programlisting>name         foo</programlisting>
212          </listitem>
213        </varlistentry>
214
215        <varlistentry>
216          <term>version</term>
217
218          <listitem>
219            <para>The version of the ported software.</para>
220
221            <programlisting>version      1.23.45</programlisting>
222          </listitem>
223        </varlistentry>
224
225        <varlistentry>
226          <term>revision</term>
227
228          <listitem>
229            <para>Optional keyword (default is 0) that is used to track port
230            revisions. It should not be incremented for port revisions unless
231            it would benefit users to upgrade an installed port, and cleared
232            when the port is updated to a newer version.</para>
233
234            <programlisting>revision     1</programlisting>
235          </listitem>
236        </varlistentry>
237
238        <varlistentry>
239          <term>epoch</term>
240
241          <listitem>
242            <para>Optional keyword (default is 0) that is used if the new port
243            version looks older than the previous version (for example 1.10
244            -&gt; 1.2). Often the epoch is formatted like a date, but it can
245            simple a number like 1.</para>
246
247            <programlisting>epoch        20070924</programlisting>
248
249            <programlisting>epoch        1</programlisting>
250          </listitem>
251        </varlistentry>
252
253        <varlistentry>
254          <term>categories</term>
255
256          <listitem>
257            <para>The category under which the ported software falls. The
258            first category should be the same as the directory within which
259            the Portfile is stored; secondary and tertiary categories may be
260            selected.</para>
261
262            <programlisting>categories     net security</programlisting>
263          </listitem>
264        </varlistentry>
265
266        <varlistentry>
267          <term>maintainers</term>
268
269          <listitem>
270            <para>A port's maintainer is a person or persons who take
271            responsibility for keeping the port up-to-date, and the maintainer
272            keyword lists maintainer email addresses(s). However, many
273            maintainers wish to hide these addresses from spambots; to do so
274            follow these conventions:</para>
275
276            <itemizedlist>
277              <listitem>
278                <para>For addresses in domain @macports.org, simply omit the
279                domain name.</para>
280              </listitem>
281
282              <listitem>
283                <para>For addresses in other domains, say
284                <email>account@example.org</email>, use the convention
285                example.org:account to specify the address.</para>
286              </listitem>
287            </itemizedlist>
288
289            <para>In the example below, the maintainer email addresses
290            <email>jdoe@macports.org</email> and
291            <email>julesverne@example.org</email> are hidden using these
292            conventions.</para>
293
294            <programlisting>maintainers       jdoe \
295                  example.org:julesverne</programlisting>
296          </listitem>
297        </varlistentry>
298
299        <varlistentry>
300          <term>description</term>
301
302          <listitem>
303            <para>A one-sentence description of the ported software.</para>
304
305            <programlisting>description    A classic shooter arcade game.</programlisting>
306          </listitem>
307        </varlistentry>
308
309        <varlistentry>
310          <term>long_description</term>
311
312          <listitem>
313            <para>A long description of the ported software. Break long lines
314            with escaped newlines.</para>
315
316            <programlisting>description    A classic shooter arcade game derived from \
317               the game alien-munchers.  Not suitable for \
318               children under two years old.      </programlisting>
319          </listitem>
320        </varlistentry>
321
322        <varlistentry>
323          <term>homepage</term>
324
325          <listitem>
326            <para>Port application's homepage.</para>
327
328            <programlisting>homepage       http://www.somesite.org/apps</programlisting>
329          </listitem>
330        </varlistentry>
331
332        <varlistentry>
333          <term>platforms</term>
334
335          <listitem>
336            <para>The platforms on which the port has been tested.</para>
337
338            <programlisting>platforms      darwin freebsd</programlisting>
339          </listitem>
340        </varlistentry>
341      </variablelist>
342    </refsection>
343
344    <refsection>
345      <title>Dependencies</title>
346
347      <para>Free and open source software is highly modular, and MacPorts
348      ports often require that other ports be installed beforehand; these
349      prerequisites for a given port are called a port's
350      <quote>dependencies</quote>.</para>
351
352      <para>There are three types of MacPorts dependencies: library, build,
353      and run dependencies. Dependency types are important for proper port
354      upgrade and uninstall behavior. For example, you may not uninstall a
355      port that is a library dependency for another port, though you may
356      remove one with a build dependency; likewise, upgrading a port will
357      upgrade its library and build dependencies also, but not its run
358      dependencies.</para>
359
360      <variablelist>
361        <varlistentry>
362          <term>depends_lib</term>
363
364          <term>depends_lib-append</term>
365
366          <term>depends_lib-delete</term>
367
368          <listitem>
369            <para>The list of dependencies to check before phases
370            <option>configure</option>, <option>build</option>,
371            <option>destroot</option>, <option>install</option>, and
372            <option>package</option>. Library dependencies are needed both at
373            build time (for headers and libraries to link against) and at run
374            time.</para>
375          </listitem>
376        </varlistentry>
377
378        <varlistentry>
379          <term>depends_build</term>
380
381          <term>depends_build-append</term>
382
383          <term>depends_build-delete</term>
384
385          <listitem>
386            <para>The list of dependencies to check before phases
387            <option>build</option>, <option>destroot</option>,
388            <option>install</option>, and <option>package</option>. Build
389            dependencies are needed when software is compiled, but not needed
390            at all once the software is compiled and installed.</para>
391          </listitem>
392        </varlistentry>
393
394        <varlistentry>
395          <term>depends_run</term>
396
397          <term>depends_run-append</term>
398
399          <term>depends_run-delete</term>
400
401          <listitem>
402            <para>The list of dependencies to check before phases
403            <option>destroot</option>, <option>install</option>, and
404            <option>package</option>. Run dependencies are needed when the
405            software is run, but not to compile it.</para>
406          </listitem>
407        </varlistentry>
408      </variablelist>
409
410      <refsection>
411        <title>Port and Non-Port Dependencies</title>
412
413        <para>Port dependencies should be provided by MacPorts ports whenever
414        possible, however dependencies may be provided by vendor-supplied
415        software when satisfying a dependency by a port is not practical or
416        desirable for a special reason. Dependencies of this type are called
417        non-port dependencies.</para>
418
419        <para>Port dependencies, the preferred type, are specified as shown in
420        these examples:</para>
421
422        <programlisting>depends_lib        port:rrdtool port:apache2
423
424depends_build      port:apache2 port:php5</programlisting>
425
426        <para>Non-port dependencies are specified as shown in these
427        examples:</para>
428
429        <programlisting>depends_lib        lib:libX11.6:xorg
430
431depends_build      bin:rrdtool</programlisting>
432      </refsection>
433    </refsection>
434
435    <refsection>
436      <title>Variants</title>
437
438      <para>MacPorts variants are conditional modifications of port
439      installation behavior that may be invoked by a user at the time of port
440      install.</para>
441
442      <variablelist>
443        <varlistentry>
444          <term>variant [requires variant] [conflicts variant] [description
445          description]</term>
446
447          <listitem>
448            <para>The variant declaration may contain any keywords that can be
449            placed in a Portfile's global section. If you wish to execute
450            system (shell) calls or Tcl extensions during the execution of a
451            port phase, you should place those statements within a
452            <literal>variant_isset</literal> conditional within a phase
453            declaration and not within the variant declaration itself.
454            Dependencies and conflicts with other variants in the same port
455            can be expressed with requires and conflicts. See the isset Tcl
456            extension.</para>
457
458            <itemizedlist>
459              <listitem>
460                <para>Default: no</para>
461              </listitem>
462
463              <listitem>
464                <para>Example:</para>
465
466                <programlisting>variant gnome requires glib {
467      configure.args-append --with-gnome
468      depends_lib-append port:gnome-session
469}</programlisting>
470              </listitem>
471            </itemizedlist>
472          </listitem>
473        </varlistentry>
474
475        <varlistentry>
476          <term>default_variants</term>
477
478          <listitem>
479            <para>If variants are defined, then the default_variants value
480            lists which variants are enabled by default. This allows for
481            Portfile modularity and also allows users to suppress default
482            variants if they wish.</para>
483
484            <itemizedlist>
485              <listitem>
486                <para>Default: none</para>
487              </listitem>
488
489              <listitem>
490                <para>Example:</para>
491
492                <programlisting>default_variants +ssl +tcpd
493
494</programlisting>
495              </listitem>
496            </itemizedlist>
497          </listitem>
498
499          <listitem>
500            <para>Default variants may be suppressed by preceding a variant
501            name with a "-" as shown in this example.</para>
502
503            <programlisting><prompt>%%</prompt> <userinput>port install foo -ssl</userinput></programlisting>
504          </listitem>
505        </varlistentry>
506
507        <varlistentry>
508          <term>universal_variant</term>
509
510          <listitem>
511            <para>When using MacPorts on Mac OS X, a universal variant is
512            defined by default to configure ports with universal flags. The
513            variant can be overridden if the default code does not work (see
514            the Configure Universal section below), or suppressed if a
515            universal variant is not possible for the port with this
516            keyword.</para>
517
518            <itemizedlist>
519              <listitem>
520                <para>Default: yes</para>
521              </listitem>
522
523              <listitem>
524                <para>Example:</para>
525
526                <programlisting>universal_variant  no</programlisting>
527              </listitem>
528            </itemizedlist>
529          </listitem>
530        </varlistentry>
531      </variablelist>
532    </refsection>
533
534    <refsection>
535      <title>Livecheck / Distcheck</title>
536
537      <para>Options livecheck and distcheck are especially useful for port
538      maintainers, but others may also find this information valuable.</para>
539
540      <para>Livecheck checks to see if MacPorts can query the developer's
541      download site to determine if a newer version of the software has become
542      available since the port was installed.</para>
543
544      <variablelist>
545        <varlistentry>
546          <term>livecheck.check</term>
547
548          <listitem>
549            <para>Specify what kind of update check to perform.</para>
550
551            <para>Open source mirror site options are to use the project's
552            latest file release from <option>sourceforge</option> or
553            <option>googlecode</option>, or the project's
554            <literal>date_updated</literal> XML tag for
555            <option>freshmeat</option>.</para>
556
557            <para>Generic download site options are to specify a
558            <option>moddate</option> (modification date) of a URL resource), a
559            <option>regex</option> (retrieve the version by applying a regex
560            to a URL resource), <option>regexm</option> (retrieve the version
561            by applying a multi-line regex to a URL resource),
562            <option>md5</option> (compares the md5 sum of a URL resource) or
563            <option>none</option> (no check).</para>
564
565            <itemizedlist>
566              <listitem>
567                <para>Default: sourceforge or googlecode if the master_sites
568                is one of these, else freshmeat.</para>
569              </listitem>
570
571              <listitem>
572                <para>Values: freshmeat sourceforge googlecode moddate regex
573                regexm md5 none</para>
574              </listitem>
575
576              <listitem>
577                <para>Examples:</para>
578
579                <programlisting>livecheck.check     regex
580livecheck.url       http://dev.mysql.com/
581livecheck.regex     "Generally Available (${major_version}\\.\[0-9.\]+)"
582</programlisting>
583              </listitem>
584            </itemizedlist>
585          </listitem>
586        </varlistentry>
587
588        <varlistentry>
589          <term>livecheck.name</term>
590
591          <listitem>
592            <para>Name of the project for live checks; only used with
593            freshmeat, sourceforge, and googlecode livechecks.</para>
594
595            <itemizedlist>
596              <listitem>
597                <para>Default: <varname>${name}</varname> or the
598                sourceforge/freshmeat/googlecode project name if it can be
599                guessed from <literal>master_sites</literal>.</para>
600              </listitem>
601
602              <listitem>
603                <para>Values:
604                <replaceable>any_project_name</replaceable></para>
605              </listitem>
606
607              <listitem>
608                <para>Example:</para>
609
610                <programlisting>livecheck.name   hibernate</programlisting>
611              </listitem>
612            </itemizedlist>
613          </listitem>
614        </varlistentry>
615
616        <varlistentry>
617          <term>livecheck.distname</term>
618
619          <listitem>
620            <para>Name of the file release for sourceforge and googlecode
621            checks. You may use this keyword without livecheck.version if you
622            replace the version part of the name with "(.*)".</para>
623
624            <itemizedlist>
625              <listitem>
626                <para>Default: SourceForge:
627                <varname>${livecheck.name}</varname> ; GoogleCode: first
628                ${distfiles} item</para>
629              </listitem>
630
631              <listitem>
632                <para>Values: <replaceable>filename</replaceable></para>
633              </listitem>
634
635              <listitem>
636                <para>Example:</para>
637
638                <programlisting>livecheck.distname  faad2.src</programlisting>
639              </listitem>
640            </itemizedlist>
641          </listitem>
642        </varlistentry>
643
644        <varlistentry>
645          <term>livecheck.version</term>
646
647          <listitem>
648            <para>Version of the project for a check; used for regex-based
649            checks.</para>
650
651            <itemizedlist>
652              <listitem>
653                <para>Default: <varname>${version}</varname></para>
654              </listitem>
655
656              <listitem>
657                <para>Values: <replaceable>any_version</replaceable></para>
658              </listitem>
659
660              <listitem>
661                <para>Example:</para>
662
663                <programlisting>livecheck.version   ${name}-${version}</programlisting>
664              </listitem>
665            </itemizedlist>
666          </listitem>
667        </varlistentry>
668
669        <varlistentry>
670          <term>livecheck.url</term>
671
672          <listitem>
673            <para>URL to query for a check.</para>
674
675            <itemizedlist>
676              <listitem>
677                <para>Default:</para>
678
679                <itemizedlist>
680                  <listitem>
681                    <para>homepage or the first hit among the following
682                    sites</para>
683                  </listitem>
684
685                  <listitem>
686                    <para>http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml</para>
687                  </listitem>
688
689                  <listitem>
690                    <para>http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}</para>
691                  </listitem>
692
693                  <listitem>
694                    <para>http://code.google.com/p/${livecheck.name}/downloads/list</para>
695                  </listitem>
696                </itemizedlist>
697              </listitem>
698
699              <listitem>
700                <para>Values: <replaceable>any_url</replaceable></para>
701              </listitem>
702
703              <listitem>
704                <para>Example:</para>
705
706                <programlisting>livecheck.url  http://ftp.gnu.org/gnu/bison/</programlisting>
707              </listitem>
708            </itemizedlist>
709          </listitem>
710        </varlistentry>
711
712        <varlistentry>
713          <term>livecheck.regex</term>
714
715          <listitem>
716            <para>Regular expression to parse the resource for regex checks.
717            Be sure to use a regular expression grouping around the version
718            component.</para>
719
720            <itemizedlist>
721              <listitem>
722                <para>Default: none</para>
723              </listitem>
724
725              <listitem>
726                <para>Values: <replaceable>any_regex</replaceable></para>
727              </listitem>
728
729              <listitem>
730                <para>Example:</para>
731
732                <programlisting>livecheck.regex  4th-([a-z0-9.]+)-unix.tar.gz</programlisting>
733              </listitem>
734            </itemizedlist>
735          </listitem>
736        </varlistentry>
737
738        <varlistentry>
739          <term>livecheck.md5</term>
740
741          <listitem>
742            <para>md5 checksum to use for an md5 comparison.</para>
743
744            <itemizedlist>
745              <listitem>
746                <para>Default: none</para>
747              </listitem>
748
749              <listitem>
750                <para>Values:
751                <replaceable>any_md5_checksum</replaceable></para>
752              </listitem>
753
754              <listitem>
755                <para>Example:</para>
756
757                <programlisting>livecheck  md5 37e6a5b6516a680c7178b72021d3b706</programlisting>
758              </listitem>
759            </itemizedlist>
760          </listitem>
761        </varlistentry>
762      </variablelist>
763
764      <para>Distcheck reports whether or not the distfile(s) specified in a
765      Portfile are still available on the developer's download site. Examples
766      are given below.</para>
767
768      <variablelist>
769        <varlistentry>
770          <term>distcheck.check</term>
771
772          <listitem>
773            <para>This option can be used to disable distcheck. It specifies
774            what kind of check should be performed on distfiles: moddate
775            (check if the Portfile is older than the distfile) or none (no
776            check).</para>
777
778            <itemizedlist>
779              <listitem>
780                <para>Default: moddate</para>
781              </listitem>
782
783              <listitem>
784                <para>Values: moddate none</para>
785              </listitem>
786
787              <listitem>
788                <para>Example:</para>
789
790                <programlisting>distcheck.check  none</programlisting>
791              </listitem>
792            </itemizedlist>
793          </listitem>
794        </varlistentry>
795      </variablelist>
796    </refsection>
797  </refsection>
798
799  <refsection>
800    <title>SEE ALSO</title>
801
802    <para><citerefentry>
803        <refentrytitle>portfile-phase</refentrytitle>
804
805        <manvolnum>7</manvolnum>
806      </citerefentry>, <citerefentry>
807        <refentrytitle>portfile-startupitem</refentrytitle>
808
809        <manvolnum>7</manvolnum>
810      </citerefentry>, <citerefentry>
811        <refentrytitle>portfile-tcl</refentrytitle>
812
813        <manvolnum>7</manvolnum>
814      </citerefentry></para>
815  </refsection>
816
817  <refsection>
818    <title>AUTHORS</title>
819
820    <para>Landon Fuller <email>landonf@macports.org</email></para>
821
822    <para>Juan Manuel Palacios <email>jmpp@macports.org</email></para>
823
824    <para>Mark Duling <email>markd@macports.org</email></para>
825
826    <para>Kevin Van Vechten <email>kevin@opendarwin.org</email></para>
827
828    <para>Jordan K. Hubbard <email>jkh@macports.org</email></para>
829
830    <para>Chris Ridd <email>cjr@opendarwin.org</email></para>
831
832    <para>Kevin Ballard <email>eridius@macports.org</email></para>
833
834    <para>Markus W. Weissmann <email>mww@macports.org</email></para>
835  </refsection>
836</refentry>
Note: See TracBrowser for help on using the repository browser.