source: trunk/base/doc/portfile.7 @ 26942

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

Document filespath variable in portfile(7).

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 39.4 KB
Line 
1.\" portfile.7
2.\"
3.\" Copyright (c) 2002 Apple Computer, Inc.
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of Apple Computer, Inc. nor the names of its
15.\"    contributors may be used to endorse or promote products derived from
16.\"    this software without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
22.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.Dd February 13, 2007
31.Dt PORTFILE 7 "MacPorts"
32.Os Darwin
33.Sh NAME
34.Nm Portfile
35.Nd MacPorts description file reference
36.Sh DESCRIPTION
37A complete reference of all available
38.Nm
39variables and example syntax.
40.Nm Portfiles
41consist of valid TCL, allowing for simple key/value pair syntax as well
42as utilization of TCL's extensive functionality.
43.Nm Portfiles
44are encoded in UTF-8.
45.Pp
46The
47.Nm Macports System
48uses a target dependency system based on a
49depends/provides model, allowing for targets to be registered and
50executed in the correct order based on their individual requirements.
51.Pp
52A
53.Nm
54author needs to be aware of the various standard targets, the options
55that they require and the variables that both the targets and the port
56system provide.
57.Sh PORTSYSTEM
58Portfiles must begin with a PortSystem line that defines which version of the
59Portfile interpreter should be used.
60.br
61.Sy Synopsis:
62.Dl PortSystem 1.0
63.Sh MAIN VARIABLES
64All ports are required to set certain variables.
65.Bl -tag -width lc
66.It Ic name
67Full name of port.
68.br
69.Sy Type:
70.Em required
71.br
72.Sy Example:
73.Dl name XFree86
74.It Ic version
75Upstream version of software.
76.br
77.Sy Type:
78.Em required
79.br
80.Sy Example:
81.Dl version 4.2.1
82.It Ic epoch
83If a port's version numbering changes such that a newer version looks
84older than the previous version, the
85.Ic epoch
86should be increased. Often the
87.Ic epoch
88is formatted like a date.
89.br
90.Sy Type:
91.Em optional
92.br
93.Sy Default:
94.Em 0
95.br
96.Sy Example:
97.Dl epoch 20041231
98.It Ic description
99One line description of the software and what it does.  To appear in the
100description, brackets and semi-colons need to be escaped with a backslash (i.e.
101they must be written as "\\[", "\\]" and "\\;").  The escape sequences listed in
102.Xr re_syntax n
103may also be used, with the exception of \\n, \\r and \\f.
104.br
105.Sy Type:
106.Em required
107.br
108.Sy Example:
109.Dl description Dictionary Server Protocol (RFC2229) client
110.It Ic long_description
111A verbose description of the software and what it does.  To appear in the
112description, brackets and semi-colons need to be escaped with a backslash (i.e.
113they must be written as "\\[", "\\]" and "\\;").  The escape sequences listed in
114.Xr re_syntax n
115may also be used, with the exception of \\n, \\r and \\f.
116.br
117.Sy Type:
118.Em required
119.br
120.Sy Example:
121.Bd -literal -offset indent -compact
122long_description The GNU Image Manipulation Program \e\
123
124    (GIMP) is a powerful tool for the preparation and \e\
125
126    manipulation of digital images. The GIMP provides \e\
127
128    the user with a wide variety of image manipulation, \e\
129
130    painting, processing, and rendering tools.
131.Ed
132.It Ic revision
133Local revision number of
134.Nm .
135Increment for port revisions which would change its installation in any way.
136.br
137.Sy Type:
138.Em optional
139.br
140.Sy Default:
141.Em 0
142.br
143.Sy Example:
144.Dl revision 1
145.It Ic categories
146Categories to which this port belongs.
147.br
148.Sy Type:
149.Em required
150.br
151.Sy Example:
152.Dl categories spelling textproc
153.It Ic maintainers
154E-mail address(es) of port maintainer(s).
155.br
156.Sy Type:
157.Em required
158.br
159.Sy Example:
160.Dl maintainers landonf@macports.org
161.It Ic platforms
162Declares which platforms are supported by the port.
163.br
164.Sy Type:
165.Em required
166.br
167.Sy Values:
168.Em darwin freebsd
169.br
170.Sy Example:
171.Dl platforms darwin
172.It Ic homepage
173Project homepage for the port.
174.br
175.Sy Type:
176.Em required
177.br
178.Sy Example:
179.Dl http://wireshark.org
180.It Ic master_sites
181List of sites to fetch
182.Ic distfiles
183from or a predefined mirror site
184list. If set to a predefined mirror site, without a subdirectory being
185defined, the portname is used as the name of the subdirectory.
186.br
187.Sy Type:
188.Em required
189.br
190.Sy Example:
191.Bd -literal -offset indent -compact
192master_sites ftp://ftp.cdrom.com/pub/magic \e\
193
194    sourceforge
195.Ed
196.It Ic worksrcdir
197Path to source directory relative to
198.Ic workpath .
199.br
200.Sy Type:
201.Em optional
202.br
203.Sy Default:
204.Em ${distname}
205.br
206.Sy Example:
207.Dl worksrcdir ${distname}-src-${version}
208.It Ic distname
209Name of distribution file, without the
210.Cm extract.suffix .
211.br
212.Sy Type:
213.Em optional
214.br
215.Sy Default:
216.Em ${name}-${version}
217.br
218.Sy Example:
219.Dl distname ${name}-${version}-src
220.It Xo
221.Ic checksums Ar filename Ar type Ar checksum
222.Op Ar filename Ar type checksum ...
223.Xc
224List of checksums for the
225.Ic distfiles .
226The checksum
227.Ar type
228can currently be md5, rmd160 or sha1. The
229.Ar filename
230can be omitted if there is only one distfile.
231.br
232.Sy Type:
233.Em required
234.br
235.Sy Example:
236.Bd -literal -offset indent -compact
237checksums dictd-1.7.1.tar.gz md5 81317b86ea0a5df0163900ad2e6bb12c \e\
238        magic-words-1.7.1.tar.gz md5 897a005182928613eadd30c267ce9c5b
239.Ed
240.br
241.Sy Example (ledit 1.11):
242.Bd -literal -offset indent -compact
243checksums md5 a2d38ba641682509c1e964ad699a9dd2 \e\
244        sha1 1fb6443b5fdf3c83787953f06282d256477c1288
245.Ed
246.br
247.Sy Example (ssldump 0.9b3):
248.Bd -literal -offset indent -compact
249checksums md5 ac8c28fe87508d6bfb06344ec496b1dd \e\
250        sha1 a633a9a811a138eac5ed440d583473b644135ef5 \e\
251        rmd160 941cf8f2ef8459ec4f9ce65772e134505d46566
252.Ed
253.It Ic use_automake
254If set to yes, run the
255.Cm automake
256target to build any
257.Pa Makefile.in
258files for use by
259.Pa configure .
260.br
261.Sy Type:
262.Em optional
263.br
264.Sy Default:
265.Em no
266.br
267.Sy Example:
268.Dl use_automake yes
269.It Ic use_autoconf
270If set to yes, run the
271.Cm autoconf
272target to build any
273.Pa configure
274script required.
275.br
276.Sy Type:
277.Em optional
278.br
279.Sy Default:
280.Em no
281.br
282.Sy Example:
283.Dl use_autoconf yes
284.It Ic use_configure
285If set to yes, run the
286.Cm configure
287target to configure the build.
288.br
289.Sy Type:
290.Em optional
291.br
292.Sy Default:
293.Em yes
294.br
295.Sy Example:
296.Dl use_configure no
297.El
298.Sh TARGET HOOKS
299A number of hooks are available for customizing many of the standard
300targets that
301.Xr port 1
302executes. The targets supporting these hooks are
303.Cm fetch ,
304.Cm automake ,
305.Cm autoconf ,
306.Cm configure ,
307.Cm build ,
308.Cm destroot ,
309and
310.Cm test .
311The hooks are:
312.Bl -tag -width lc
313.It Va target Ns Ic .dir
314Directory in which to run the
315.Va target .
316.br
317.Sy Example:
318.Dl automake.dir src
319.It Va target Ns Ic .env
320Change the environment the
321.Va target
322is run in. This is often overridden on a per
323.Nm
324basis.
325.br
326.Sy Example:
327.Dl configure.env CPP=/usr/bin/cpp-4.0
328.It Va target Ns Ic .pre_args
329Additional arguments passed before the main arguments.
330.br
331.Sy Example:
332.Dl extract.pre_args -cd
333.It Va target Ns Ic .args
334Main arguments to pass to the
335.Va target .
336This is often overridden on a per
337.Nm
338basis.
339.br
340.Sy Example:
341.Dl configure.args --enable-fooble
342.It Va target Ns Ic .post_args
343Additional arguments passed after the main arguments.
344.br
345.Sy Example:
346.Dl extract.post_args | tar xf -
347.El
348.Sh RUNTIME VARIABLES
349Read-only access to the MacPorts configuration is provided.
350.Bl -tag -width lc
351.It Ic prefix
352Install prefix
353.br
354.Sy Type:
355.Em optional
356.br
357.Sy Default:
358.Em /opt/local
359.It Ic libpath
360Location of ports-specific TCL libraries.
361.br
362.Sy Type:
363.Em read-only
364.It Ic portpath
365Full path to the Portfile location.
366.br
367.Sy Type:
368.Em read-only
369.br
370.Sy Default:
371.Em work
372.It Ic workpath
373Full path to work directory.
374.br
375.Sy Type:
376.Em read-only
377.br
378.Sy Default:
379.Em ${portbuildpath}/work
380.It Ic worksrcpath
381Full path to working sources (where port has unpacked itself).
382.br
383.Sy Type:
384.Em read-only
385.br
386.Sy Default:
387.Em ${workpath}/${worksrcdir}
388.It Ic filesdir
389Path to port files relative to
390.Ic portpath .
391.br
392.Sy Type:
393.Em read-only
394.br
395.Sy Default:
396.Em files
397.It Ic filespath
398Full path to the port files location.
399.br
400.Sy Type:
401.Em read-only
402.br
403.Sy Default:
404.Em ${portpath}/${filesdir}
405.It Ic distpath
406Location to store downloaded distfiles.
407.br
408.Sy Type:
409.Em read-only
410.br
411.Sy Default:
412.Em ${sysportpath}/distfiles/${dist_subdir}/
413.It Ic os.arch
414Identifies hardware type (eg "powerpc").
415.br
416.Sy Type:
417.Em read-only
418.It Ic os.version
419Version number of operating system (eg "7.0").
420.br
421.Sy Type:
422.Em read-only
423.It Ic os.endian
424Endianness of the processor (eg "bigEndian").
425.br
426.Sy Type:
427.Em read-only
428.It Ic os.platform
429Operating system name (eg "darwin").
430.br
431.Sy Type:
432.Em read-only
433.It Ic install.user
434User for MacPorts installation (eg
435.Pa root )
436.br
437.Sy Type:
438.Em read-only
439.It Ic install.group
440Group for MacPorts installation (eg
441.Pa wheel )
442.br
443.Sy Type:
444.Em read-only
445.It Ic x11prefix
446Absolute path to X11 (eg
447.Pa /usr/X11R6 )
448.br
449.Sy Type:
450.Em read-only
451.El
452.Sh DEPENDENCY OPTIONS
453Port dependencies should refer to other MacPort ports
454whenever possible, therefore each dependency should be
455expressed in the format:
456.Bl -tag -width ls
457.It port: Ns Ao port Ac
458.El
459.Pp
460Where
461.Ao port Ac represents the name of an existing MacPorts
462.Nm port .
463If satisfying a dependency with a MacPorts port is not
464practical and it is likely that a dependency must be met
465by an Apple optional install, then the alternative dependency
466format:
467.Bl -tag -width lc
468.It Ar type Ns : Ns Ao filename Ac Ns : Ns Ao port Ac
469.El
470.Pp
471may be used. Where
472.Ar type
473is "bin" if
474.Ao filename Ac
475is a program, "lib" if it is a library, or "path" if it is a path to an
476installed file.
477.br
478.Sy Example:
479.Dl lib:libX11.6:XFree86
480.Bl -tag -width lc
481.It Ic depends_build
482List of dependencies to check before
483.Cm build ,
484.Cm destroot ,
485.Cm install ,
486and
487.Cm package
488targets.
489.br
490.Sy Type:
491.Em optional
492.br
493.Sy Example:
494.Dl depends_build port:autoconf
495.It Ic depends_run
496List of dependencies to check before
497.Cm destroot ,
498.Cm install
499and
500.Cm package
501targets.
502.br
503.Sy Type:
504.Em optional
505.br
506.Sy Example:
507.Dl depends_run port:bash
508.It Ic depends_lib
509List of dependencies to check before
510.Cm configure ,
511.Cm build ,
512.Cm destroot ,
513.Cm install ,
514and
515.Cm package
516targets.
517.br
518.Sy Type:
519.Em optional
520.br
521.Sy Example:
522.Dl depends_lib port:libfetch
523.El
524.Sh FETCH OPTIONS
525Fetch all distribution files and patches.
526.Bl -tag -width lc
527.It Ic master_sites.mirror_subdir
528Subdirectory to append to all mirror sites for any list specified in
529master_sites.
530.br
531.Sy Type:
532.Em optional
533.br
534.Sy Default:
535.Em ${name}
536.br
537.Sy Example:
538.Dl master_sites.mirror_subdir      magic
539.It Ic patch_sites
540List of sites to fetch
541.Ic patchfiles
542from or a predefined mirror site list.
543.br
544.Sy Type:
545.Em optional
546.br
547.Sy Default:
548.Em ${master_sites}
549.br
550.Sy Example:
551.Dl patch_sites ftp://ftp.patchcityrepo.com/pub/magic/patches
552.It Ic patch_sites.mirror_subdir
553Subdirectory to append to all mirror sites for any list specified in
554.Ic patch_sites .
555.br
556.Sy Type:
557.Em optional
558.br
559.Sy Default:
560.Em ${name}
561.br
562.Sy Example:
563.Dl patch_sites.mirror_subdir       magic
564.It Ic extract.suffix
565Suffix to append to
566.Ic distname .
567.br
568.Sy Type:
569.Em optional
570.br
571.Sy Default:
572.Em .tar.gz
573.br
574.Sy Example:
575.Dl extract.suffix .tgz
576.It Ic distfiles
577List of distribution files to fetch from
578.Ic master_sites .
579.br
580.Sy Type:
581.Em optional
582.br
583.Sy Default:
584.Em [suffix ${distname}]
585.br
586.Sy Example:
587.Dl distfiles magicsource.tar.gz cluebat.tar.bz2
588.It Ic patchfiles
589List of patches to fetch and apply.
590.br
591.Sy Type:
592.Em optional
593.br
594.Sy Example:
595.Dl patchfiles japanese-widechar-fix.diff japanese-localization.diff
596.It Ic use_zip
597Use zip.
598.br
599Sets extract.suffix to: .zip
600.br
601Sets extract.cmd to: unzip
602.br
603Sets extract.pre_args to: -q
604.br
605Sets extract.post_args to: "-d ${workpath}"
606.br
607.Sy Type:
608.Em optional
609.br
610.Sy Example:
611.Dl use_zip yes
612.It Ic use_bzip2
613Use bzip2.
614.br
615Sets extract.suffix to: .bzip2
616.br
617Sets extract.cmd to: bzip2
618.br
619.Sy Type:
620.Em optional
621.br
622.Sy Example:
623.Dl use_bzip2 yes
624.It Ic dist_subdir
625Create a sub-directory in
626.Ic distpath
627to store all fetched files.
628.br
629.Sy Type:
630.Em optional
631.br
632.Sy Default:
633.Em ${name}
634.br
635.Sy Example:
636.Dl dist_subdir vim${version}
637.El
638.Ss ADVANCED FETCH OPTIONS
639Some mirrors require special options for a resource to be properly
640fetched.
641.Bl -tag -width lc
642.It Ic fetch.user
643HTTP or FTP user to fetch the resource.
644.br
645.Sy Type:
646.Em optional
647.It Ic fetch.password
648HTTP or FTP password to fetch the resource.
649.br
650.Sy Type:
651.Em optional
652.It Ic fetch.use_epsv
653Whether to use EPSV command for FTP transfers.
654.br
655.Sy Type:
656.Em optional
657.br
658.Sy Default:
659.Em yes
660.br
661.It Ic fetch.ignore_sslcert
662Whether to ignore the host SSL certificate (for HTTPS).
663.br
664.Sy Type:
665.Em optional
666.br
667.Sy Default:
668.Em no
669.br
670.El
671.Ss FETCHING FROM CVS
672As an alternative to fetching distribution files, pulling the sources
673from a CVS repository is supported. Use of CVS can give rise to
674non-reproducible builds, so it is strongly discouraged.
675.Bl -tag -width lc
676.It Ic cvs.root
677Specify the address to a CVS repository from which to checkout files.
678.br
679.Sy Type:
680.Em optional
681.br
682.Sy Default:
683.Em none
684.br
685.Sy Example:
686.Dl cvs.root :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs
687.It Ic cvs.tag
688Specify a CVS tag identifying the code to checkout.
689.br
690.Sy Type:
691.Em optional
692.br
693.Sy Default
694.Em none
695.br
696.Sy Example:
697.Dl cvs.tag HEAD
698.It Ic cvs.date
699A date that identifies the CVS code set to checkout.
700.br
701.Sy Type:
702.Em optional
703.br
704.Sy Default
705.Em none
706.br
707.Sy Example:
708.Dl cvs.date \*q12-April-2005\*q
709.It Ic cvs.module
710A CVS module from which to check out the code.
711.br
712.Sy Type:
713.Em optional
714.br
715.Sy Default
716.Em none
717.br
718.Sy Example:
719.Dl cvs.module Sources
720.El
721.Ss FETCHING FROM SUBVERSION
722As an alternative to fetching distribution files, pulling the sources
723from a subversion repository is supported. Use of subversion can give
724rise to non-reproducible builds, so it is strongly discouraged.
725.Bl -tag -width lc
726.It Ic svn.url
727Specify the url from which to fetch files.
728.br
729.Sy Type:
730.Em required
731.br
732.Sy Default:
733.Em none
734.br
735.Sy Example:
736.Dl svn.url http://www.domain.com/svn-repo/mydirectory
737      svn.url svn://www.domain.com/svn-repo/mydirectory
738.It Ic svn.tag
739Specify the a tag from which svn should fetch files. This
740corresponds to the -r option to the svn cli.  Note that you
741will need to use backslashes to escape characters that have
742meaning to the Tcl interpreter, such as braces and double
743quotes.
744.br
745.Sy Type:
746.Em optional
747.br
748.Sy Default:
749.Em none
750.br
751.Sy Example:
752.Dl svn.tag 37192
753      svn.tag \\{\\"2006-02-17 15:30 +0230\\"\\}
754.El
755.Sh EXTRACT OPTIONS
756Extract all compressed/archived files.
757.Bl -tag -width lc
758.It Ic extract.only
759List of files to extract into
760.Ic workpath .
761.br
762.Sy Type:
763.Em optional
764.br
765.Sy Default:
766.Em ${distfiles}
767.br
768.Sy Example:
769.Dl extract.only worksrc-1.4.4.tar.gz
770.It Ic extract.cmd
771Command to perform the extraction.
772.br
773.Sy Type:
774.Em optional
775.br
776.Sy Default:
777.Em gzip
778.br
779.Sy Example:
780.Dl extract.cmd bzip2
781.El
782.Sh CONFIGURE OPTIONS
783MacPorts provide special support for configure flags (CFLAGS, LDFLAGS, CPPFLAGS, CXXFLAGS). Please note that the previous way to alter these flags (using configure.env) may become deprecated at some point. The following options are defined:
784.Bl -tag -width lc
785.It Ic configure.cflags
786Flags to put in the CFLAGS environment variable when invoking the configure script.
787.br
788.Sy Type:
789.Em optional
790.br
791.Sy Default:
792.Em -O2
793.br
794.Sy Example:
795.Dl configure.cflags-append -DHAS_LRINTF
796.It Ic configure.cppflags
797Flags to put in the CPPFLAGS environment variable when invoking the configure script.
798.br
799.Sy Type:
800.Em optional
801.br
802.Sy Default:
803.Em -I${prefix}/include
804.It Ic configure.cxxflags
805Flags to put in the CXXFLAGS environment variable when invoking the configure script.
806.br
807.Sy Type:
808.Em optional
809.br
810.Sy Default:
811.Em -O2
812.It Ic configure.ldflags
813Flags to put in the LDFLAGS environment variable when invoking the configure script.
814.br
815.Sy Type:
816.Em optional
817.br
818.Sy Default:
819.Em -L${prefix}/lib
820.El
821.Ss UNIVERSAL TARGET HOOKS
822For universal builds of configure-based ports, we also define specific target hooks. These can be overridden for specific ports. Please note that these hooks are used by the default universal variant and redefining the variant will make them useless.
823.Bl -tag -width lc
824.It Ic configure.universal_args
825Arguments appended to the configure script to build the port universal.
826.br
827.Sy Type:
828.Em optional
829.br
830.Sy Default:
831.Em --disable-dependency-tracking
832.It Ic configure.universal_cflags
833Additional flags to put in the CFLAGS environment variable when invoking the configure script.
834.br
835.Sy Type:
836.Em optional
837.br
838.Sy Default:
839.Em -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc
840.It Ic configure.universal_cppflags
841Additional flags to put in the CPPFLAGS environment variable when invoking the configure script.
842.br
843.Sy Type:
844.Em optional
845.It Ic configure.universal_cxxflags
846Additional flags to put in the CXXFLAGS environment variable when invoking the configure script.
847.br
848.Sy Type:
849.Em optional
850.br
851.Sy Default:
852.Em -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc
853.It Ic configure.universal_ldflags
854Additional flags to put in the LDFLAGS environment variable when invoking the configure script.
855.br
856.Sy Type:
857.Em optional
858.br
859.Sy Default:
860.Em -arch i386 -arch ppc
861.El
862.Sh BUILD OPTIONS
863Execute necessary build commands.
864.Bl -tag -width lc
865.It Ic build.cmd
866Make command to run relative to
867.Ic worksrcdir .
868.br
869.Sy Type:
870.Em optional
871.br
872.Sy Default:
873.Em make
874.br
875.Sy Example:
876.Dl build.cmd pbxbuild
877.It Ic build.type
878Defines which 'make' is required, either 'gnu' or 'bsd'.
879Sets
880.Ic build.cmd
881to either
882.Pa gnumake
883or
884.Pa bsdmake
885accordingly.
886.br
887.Sy Type:
888.Em optional
889.br
890.Sy Default:
891.Em gnu
892.br
893.Sy Example:
894.Dl build.type bsd
895.It Ic build.target
896Target passed to
897.Ic build.cmd .
898.br
899.Sy Type:
900.Em optional
901.br
902.Sy Default:
903.Em all
904.br
905.Sy Example:
906.Dl build.target all-src
907.El
908.Sh DESTROOT OPTIONS
909Execute necessary commands to install into a temporary destination root
910("destroot") staging area.
911.Bl -tag -width lc
912.It Ic destroot.cmd
913Install command to run relative to
914.Ic worksrcdir .
915.br
916.Sy Type:
917.Em optional
918.br
919.Sy Default:
920.Em ${build.cmd}
921.br
922.Sy Example:
923.Dl destroot.cmd pbxbuild
924.It Ic destroot.type
925Defines which 'make' is required, either 'gnu' or 'bsd'.
926Sets
927.Ic destroot.cmd
928to either
929.Pa gnumake
930or
931.Pa bsdmake
932accordingly.
933.br
934.Sy Type:
935.Em optional
936.br
937.Sy Default:
938.Em ${build.type}
939.br
940.Sy Example:
941.Dl destroot.type gnu
942.It Ic destroot.destdir
943Arguments passed to
944.Ic destroot.cmd
945in order to install correctly
946into the destroot.
947.br
948.Sy Type:
949.Em optional
950.br
951.Sy Default:
952.Em DESTDIR=${destroot}
953.br
954.Sy Example:
955.Dl destroot.destdir prefix=${destroot}${prefix}
956.It Ic destroot.target
957Install target to pass to
958.Ic destroot.cmd .
959.br
960.Sy Type:
961.Em optional
962.br
963.Sy Default:
964.Em install
965.br
966.Sy Example:
967.Dl destroot.target install-src
968.It Ic destroot.umask
969Umask to use during destroot.
970.br
971.Sy Type:
972.Em optional
973.br
974.Sy Default:
975.Em 022
976.br
977.Sy Example:
978.Dl destroot.umask 002
979.It Ic destroot.keepdirs
980List of directories that should not be pruned if empty upon
981.Cm destroot
982completion.
983.br
984.Sy Type:
985.Em optional
986.br
987.Sy Example:
988.Dl destroot.keepdirs ${destroot}${prefix}/var/log/mysql
989.El
990.Sh TEST OPTIONS
991Execute commands to run test suites bundled with a port.
992.Bl -tag -width lc
993.It Ic test.run
994Enable running test suites bundled with a port.
995.br
996.Sy Type:
997.Em optional
998.br
999.Sy Example:
1000.Dl test.run     yes
1001.It Ic test.cmd
1002Test command to run relative to
1003.Ic worksrcdir .
1004.br
1005.Sy Type:
1006.Em optional
1007.br
1008.Sy Default:
1009.Em ${build.cmd}
1010.br
1011.Sy Example:
1012.Dl test.cmd checks.sh
1013.It Ic test.target
1014Test target to pass to
1015.Ic test.cmd .
1016.br
1017.Sy Type:
1018.Em optional
1019.br
1020.Sy Default:
1021.Em test
1022.br
1023.Sy Example:
1024.Dl test.target checks
1025.El
1026.Sh STARTUPITEM OPTIONS
1027If a port needs to run on system startup, it can use MacPorts
1028startupitem keywords to install native OS X startup scripts.
1029Startup scripts require user interaction after port installation
1030to activate them and instructions are given during port installs.
1031.Bl -tag -width lc
1032.It Ic startupitem.create
1033Choose whether or not to generate a startup item.
1034.br
1035.Sy Type:
1036.Em optional
1037.br
1038.Sy Default:
1039.Em no
1040.br
1041.Sy Values:
1042.Em yes no
1043.br
1044.Sy Example:
1045.Dl startupitem.create yes
1046.It Ic startupitem.type
1047Select the type of startupitem to generate. By default, a startupitem
1048will be generated that is of the appropriate type for the OS. For
1049instance, launchd is used on system 10.4, while SystemStarter is used
1050on prior Mac OS X systems. A global default may be specified with the startupitem_type preference in ports.conf.
1051.br
1052.Sy Type:
1053.Em optional
1054.br
1055.Sy Default:
1056.Em default
1057.br
1058.Sy Values:
1059.Em SystemStarter launchd default rcNG
1060.br
1061.Sy Example
1062.Dl startupitem.type launchd
1063.It Ic startupitem.name
1064Displayed name of the startup item.
1065.br
1066.Sy Type:
1067.Em required
1068.br
1069.Sy Example:
1070.Dl startupitem.name OpenSSH
1071.It Ic startupitem.executable
1072The name of the daemon to be run in the background. This is
1073the preferred type of startup item rather than any of
1074startupitem.init, startupitem.start, startupitem.stop, or
1075startupitem.restart, and may not be used together with any
1076of these options.  This option may contain multiple
1077arguments, but they must be appropriate for a call to exec; they
1078may not contain arbitrary shell code.
1079.br
1080.Sy Type:
1081.Em optional
1082.br
1083.Sy Values:
1084.Em /path/to/executable <args>
1085.br
1086.Sy Example:
1087.Dl startupitem.executable ${prefix}/bin/wonka
1088.It Ic startupitem.init
1089Shell code that will be executed prior to any of the options
1090startupitem.start, startupitem.stop and startupitem.restart.
1091.br
1092.Sy Type:
1093.Em optional
1094.br
1095.Sy Values:
1096.Em sh code
1097.br
1098.Sy Example:
1099.Dl startupitem.init FOO=start
1100.It Ic startupitem.start
1101Shell code executed to start the daemon.
1102.br
1103.Sy Type:
1104.Em optional
1105.br
1106.Sy Values:
1107.Em sh code
1108.br
1109.Sy Example:
1110.Dl startupitem.start ${prefix}/share/mysql/mysql.server start
1111.It Ic startupitem.stop
1112Shell code executed to stop the daemon.
1113.br
1114.Sy Type:
1115.Em optional
1116.br
1117.Sy Values:
1118.Em sh code
1119.br
1120.Sy Example:
1121.Dl startupitem.stop ${prefix}/share/mysql/mysql.server stop
1122.It Ic startupitem.restart
1123Shell code executed to restart the daemon. In the absence
1124of this key, the daemon will be restarted by taking the
1125stop action, followed by taking the start action.
1126.br
1127.Sy Type:
1128.Em optional
1129.br
1130.Sy Values:
1131.Em sh code
1132.br
1133.Sy Example:
1134.Dl startupitem.restart ${prefix}/share/mysql/mysql.server restart
1135.It Ic startupitem.pidfile
1136Specification for pidfile handling. This is particularly useful
1137in conjunction with the startupitem.executable key, because it is
1138important that the startupitem know how to track the executable.
1139This specifies whether the daemon generates its own pidfile (auto),
1140whether it generates its own but forgets to delete it, so that the
1141startupitem should delete it (clean), or whether it never generates
1142one, in which case the startupitem should manage the pidfile on its
1143own (manual), or whether no pidfile should be used at all (none).
1144.br
1145.Sy Type:
1146.Em optional
1147.br
1148.Sy Default:
1149.Em none "${prefix}/var/run/${name}.pid"
1150.br
1151.Sy Values:
1152.Em none|auto|manual|clean [/path/to/pidfile]
1153.br
1154.Sy Example:
1155.Dl startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile
1156.It Ic startupitem.logfile
1157Path to a logfile for logging events about the lifetime of the
1158startupitem. Depending on the type of startupitem, and the manner
1159in which it is started, standard output from the daemon may also be
1160directed to the logfile.
1161.br
1162.Sy Type:
1163.Em optional
1164.br
1165.Sy Default:
1166.Em /dev/null
1167.br
1168.Sy Values:
1169.Em path
1170.br
1171.Sy Example:
1172.Dl startupitem.logfile ${prefix}/var/log/mydaemon.log
1173.It Ic startupitem.logevents
1174Control whether or not to log events to the log file. If logevents
1175is set, events with timestamps are logged to the logfile.
1176.br
1177.Sy Type:
1178.Em optional
1179.br
1180.Sy Default:
1181.Em no
1182.br
1183.Sy Values:
1184.Em yes|no
1185.br
1186.Sy Example:
1187.Dl startupitem.logevents yes
1188.El
1189.Sh DISTCHECK AND LIVECHECK OPTIONS
1190MacPorts can automatically check if the software has been updated
1191since the Portfile was modified and if some external changes require
1192an update to the Portfile. This helps maintainers have up-to-date
1193and working Portfiles.
1194.br
1195Two checks are available. With distcheck, MacPorts can check that the
1196distfile(s) are still downloadable and did not change since the portfile
1197was modified.
1198With livecheck, MacPorts can query a resource to determine if a newer
1199version of the software is available.
1200.Bl -tag -width lc
1201.It Ic distcheck.check
1202This option can be used to disable distcheck. It specifies what kind
1203of check should be performed on distfiles:
1204.Em moddate
1205(check if the Portfile is older than the distfile) or
1206.Em none
1207(no check).
1208.br
1209.Sy Type:
1210.Em optional
1211.br
1212.Sy Default:
1213.Em moddate
1214.br
1215.Sy Values:
1216.Em moddate none
1217.It Ic livecheck.check
1218What kind of check to perform to figure out if the software has been updated.
1219Can be
1220.Em freshmeat
1221(uses the date_updated tag of the freshmeat XML file),
1222.Em sourceforge
1223(uses the version of the latest file release of the project),
1224.Em googlecode
1225(uses the version of the latest file release of the project),
1226.Em moddate
1227(uses the modification date of some URL resource),
1228.Em regex
1229(retrieve the version by applying a regex to some URL resource),
1230.Em regexm
1231(retrieve the version by applying a multi-line regex to some URL resource),
1232.Em md5
1233(compares the md5 sum of some URL resource) or
1234.Em none
1235(no check).
1236.br
1237.Sy Type:
1238.Em optional
1239.br
1240.Sy Default:
1241.Em sourceforge
1242or
1243.Em googlecode
1244if the master_sites is one of these, else
1245.Em freshmeat
1246.br
1247.Sy Values:
1248.Em freshmeat sourceforge googlecode moddate regex regexm md5 none
1249.It Ic livecheck.name
1250Name of the project for live checks (used for freshmeat, sourceforge, and googlecode checks).
1251.br
1252.Sy Type:
1253.Em optional
1254.br
1255.Sy Default:
1256.Em ${name}
1257or the sourceforge/freshmeat/googlecode project name if it can be guessed by looking at the master_sites.
1258.It Ic livecheck.distname
1259Name of the file release (used for sourceforge and googlecode checks).
1260For sourceforge releases use the name of the package release.
1261For googlecode releases use the name of the file download, including extension.
1262Replace the version part of the name with "(.*)".
1263.br
1264.Sy Type:
1265.Em optional
1266.br
1267.Sy Default:
1268.Em ${livecheck.name}
1269for sourceforge projects or the first entry in
1270.Em ${distfiles}
1271for googlecode projects
1272.It Ic livecheck.version
1273Version of the project for live checks (used for regex-based checks).
1274.br
1275.Sy Type:
1276.Em optional
1277.br
1278.Sy Default:
1279.Em ${version}
1280.It Ic livecheck.url
1281URL to query for the check.
1282.br
1283.Sy Type:
1284.Em optional
1285.br
1286.Sy Default:
1287.Em ${homepage}
1288or
1289.Em http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml
1290or
1291.Em http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}
1292or
1293.Em http://code.google.com/p/${livecheck.name}/downloads/list
1294.It Ic livecheck.regex
1295Regular expression to parse the resource for regex checks.
1296Be sure to use a regular expression grouping around the version component.
1297.br
1298.Sy Type:
1299.Em optional
1300.It Ic livecheck.md5
1301md5 sum to use for md5 comparison.
1302.br
1303.Sy Type:
1304.Em optional
1305.El
1306.Sh VARIANT OPTIONS
1307MacPorts allows for conditional modification to be specified in a
1308.Nm ,
1309allowing for user-customization of a software's build-time settings.
1310.Bl -tag -width lc
1311.It Xo
1312.Ic variant
1313.Op Cm requires Ar variant
1314.Op Cm conflicts Ar variant
1315.Op Cm description Ar "description"
1316.Xc
1317The value is usually a TCL script which modifies other port's
1318.Nm
1319variables. Dependencies and conflicts with other variants in the same
1320port can be expressed with
1321.Cm requires
1322and
1323.Cm conflicts .
1324.Cm description
1325provides a means to supply a description of the variant for the user.
1326.br
1327.Sy Type:
1328.Em optional
1329.br
1330.Sy Example:
1331Add a "gnome" variant to a port.
1332.Bd -literal -offset indent -compact
1333variant gnome requires glib { configure.args-append --with-gnome \e\
1334
1335    depends_lib-append lib:gnome-session:gnome-session }
1336.Ed
1337.It Ic default_variants
1338If variants are defined, then the
1339.Ic default_variants
1340value lists which variants are enabled by default.
1341.br
1342.Sy Type:
1343.Em optional
1344.br
1345.Sy Example:
1346.Dl default_variants +ssl +tcpd
1347.It Ic universal_variant
1348When using MacPorts on Mac OS X, a universal variant is defined and
1349the default behavior is to configure ports with universal flags
1350(see the
1351.Ic UNIVERSAL TARGET HOOKS
1352section above). The variant can be
1353overridden if the default code does not work. It can also be
1354suppressed if having a universal variant for the port does not make
1355sense. To suppress it, use the
1356.Ic universal_variant
1357option.
1358.br
1359.Sy Type:
1360.Em optional
1361.br
1362.Sy Default:
1363.Em yes
1364.br
1365.Sy Example:
1366.Dl universal_variant no
1367.El
1368.Sh PLATFORM OPTIONS
1369MacPorts allows for platform-specific conditional modification to be
1370specified in a
1371.Nm ,
1372much like variants, for handling differences between platforms and
1373versions of the same platform.
1374.Bl -tag -width lc
1375.It Xo
1376.Ic platform
1377.Ar platform
1378.Op Ar version
1379.Op Ar arch
1380.Xc
1381The platform key is used to begin the darwin platform definitions as
1382shown in the examples from the databases/db4 and devel/libidl1
1383.Nm Portfiles
1384respectively.
1385.br
1386.Sy Type:
1387.Em optional
1388.br
1389.Sy Example:
1390.Bd -literal -offset indent -compact
1391platform darwin 6 { configure.args-append   --enable-tcl \e\
1392
1393        --with-tcl=/System/Library/Tcl/8.3 }
1394.Ed
1395.br
1396.Sy Example:
1397.Bd -literal -offset indent -compact
1398platform darwin powerpc { configure.args-append \e\
1399
1400        --host=${os.arch}-apple-rhapsody${os.version} }
1401platform darwin i386 { configure.args-append \e\
1402
1403        --host=i386-gnu-rhapsody${os.version} }
1404.Ed
1405.El
1406.Sh PORTGROUP
1407To factorize the work with similar ports, MacPorts provides the notion of
1408.Nm PortGroup
1409that can be used to load definitions for a given class or group of ports. See
1410.Xr portgroup 7
1411for more details on the various PortGroup classes.
1412.Sh TCL EXTENSIONS
1413A number of TCL extensions are available for use in
1414.Nm Portfiles .
1415.Pp
1416.Bl -tag -width lc
1417.Bl -tag -width lc -compact
1418.It Xo
1419.Ic xinstall
1420.Op Fl c
1421.Op Fl B Ar suffix
1422.Op Fl b
1423.Op Fl C
1424.Op Fl f Ar flags
1425.Op Fl g Ar group
1426.Op Fl M
1427.Op Fl m Ar mode
1428.Op Fl o Ar owner
1429.Op Fl p
1430.Op Fl S
1431.Op Fl s
1432.Op Fl W Ar dir
1433.Op Ar
1434.Ar destination
1435.Xc
1436.It Xo
1437.Ic xinstall
1438.Fl d
1439.Op Fl B Ar suffix
1440.Op Fl b
1441.Op Fl C
1442.Op Fl f Ar flags
1443.Op Fl g Ar group
1444.Op Fl M
1445.Op Fl m Ar mode
1446.Op Fl o Ar owner
1447.Op Fl p
1448.Op Fl S
1449.Op Fl s
1450.Op Fl W Ar dir
1451.Ar directory
1452.Xc
1453Install file(s) to a target file or directory. The options are
1454intended to be compatible with
1455.Xr install 1 :
1456.Bl -tag -width indent
1457.It Fl b
1458Backup any existing files with an
1459.Pa .old
1460extension.
1461.It Fl B
1462Specify a different backup suffix for the
1463.Fl b
1464flag.
1465.It Fl c
1466Install files (this is the default).
1467.It Fl C
1468Only copy a file if it is different.
1469.It Fl d
1470Create directories, including (if necessary) parent directories.
1471.It Fl f
1472Specify target flags, see
1473.Xr chflags 1
1474for details.
1475.It Fl g
1476Specify the group.
1477.It Fl M
1478Disable use of
1479.Xr mmap 2 .
1480.It Fl m
1481Specify an alternate mode. The default is 0755. See
1482.Xr chmod 1
1483for defails.
1484.It Fl p
1485Preserve the modification time.
1486.It Fl S
1487Copy safely, using a temporary file.
1488.It Fl s
1489Strip binaries using
1490.Xr strip 1 .
1491.It Fl W
1492Change to
1493.Ar dir
1494before working.
1495.El
1496.El
1497.It Xo
1498.Ic fs-traverse
1499.Op Fl depth
1500.Op Fl ignoreErrors
1501.Ar varname
1502.Ar target-list
1503.Ar body
1504.Xc
1505Traverse the filesystem hierarchy rooted in each element of
1506.Ar target-list
1507and execute
1508.Ar body
1509for each found file/directory.
1510.Va varname
1511is set to the path of the file/directory. If
1512.Ic break
1513is called during execution, the filesystem traversal is stopped. If
1514.Ic continue
1515is called during execution, the current file and any children are skipped
1516and traversal continues with the next file/directory.
1517.Bl -tag -width indent
1518.It Fl depth
1519Equivalent to the
1520.Fl d
1521switch to
1522.Xr find 1 .
1523Please note that using
1524.Fl depth
1525means you cannot prune a directory with
1526.Ic continue
1527as it will be processed after its children.
1528.It Fl ignoreErrors
1529Causes
1530.Ic fs-traverse
1531to ignore any permissions/read errors encountered during processing.
1532.El
1533.Pp
1534If
1535.Nm fs-traverse
1536is called directly on a symbolic link, the link will be followed. All other
1537links encountered during traversal will not be followed.
1538.Pp
1539.Nm fs-traverse
1540will not descend into directories that have a different device number than
1541the root of the descent.
1542.Pp
1543If you remove the current directory during traversal, be aware that you must call
1544.Nm continue
1545to inform
1546.Nm fs-traverse
1547that the directory should not be descended into.
1548.It Xo
1549.Ic curl fetch
1550.Ar url
1551.Ar file
1552.Xc
1553Fetch a resource at
1554.Ar url
1555and save it to
1556.Ar file .
1557.It Xo
1558.Ic curl isnewer
1559.Ar url
1560.Ar date
1561.Xc
1562Determine if resource at
1563.Ar url
1564is newer than
1565.Ar date
1566(expressed in seconds since epoch).
1567.It Xo
1568.Ic adduser
1569.Ar username
1570.Op Cm uid Ns = Ns uid
1571.Op Cm gid Ns = Ns gid
1572.Op Cm passwd Ns = Ns passwd
1573.Op Cm realname Ns = Ns realname
1574.Op Cm home Ns = Ns home
1575.Op Cm shell Ns = Ns shell
1576.Xc
1577Add a new local user to the system with the specified uid, gid,
1578password, real name, home directory and login shell.
1579.It Ic existsuser Ar username
1580Check if a local user exists.
1581.It Ic nextuid
1582Returns the highest used uid plus one.
1583.It Xo
1584.Ic addgroup
1585.Ar group
1586.Op Cm gid Ns = Ns gid
1587.Op Cm passwd Ns = Ns passwd
1588.Op Cm realname Ns = Ns realname
1589.Op Cm users Ns = Ns users
1590.Xc
1591Add a new local group to the system, with the specified gid, password,
1592real name, and with a list users as members.
1593.It Ic existsgroup Ar group
1594Check if a local group exists and return the corresponding gid. This can be used
1595with adduser:
1596.Dl addgroup foo
1597.Dl adduser foo gid=[existsgroup foo]
1598.It Ic nextgid
1599Returns the highest used gid plus one.
1600.It Xo
1601.Ic reinplace
1602.Op Fl E
1603.Ar regex
1604.Ar
1605.Xc
1606Provide in-place
1607.Xr sed 1
1608like editing of a file.
1609The -E flag does the same thing as in
1610.Xr sed 1
1611.br
1612.Sy Example:
1613.Dl reinplace \*qs|/usr/local|${prefix}|g\*q doc/manpage.1
1614.It Ic file
1615Standard TCL command to manipulate file names and attributes, recommended if you wish to preserve Mac OS
1616resource forks when destrooting ports on Mac OS X 10.3.x and Mac OS X 10.4.x . Use
1617.Nm xinstall
1618to also preserve Extended Attributes (i.e. Access Control Lists). See
1619.Xr file n
1620for more information on this command.
1621.It Ic copy
1622Built-in shorthand alternative to "file copy".
1623.It Ic move
1624Built-in shorthand alternative to "file rename".
1625.It Ic delete Ar
1626Deletes each of the given files/directories. Behaves similarly to
1627.Ic file delete -force
1628except that
1629.Ic file delete -force
1630will fail to delete directories properly on 10.3 systems.
1631.It Ic touch
1632Built-in command mimicking the BSD touch command.
1633.It Ic ln
1634.br
1635Built-in command mimicking the BSD ln command.
1636.It Ic system Ar commandline
1637Execute a program. See
1638.Xr system 3 .
1639For calls to
1640.Xr install 1
1641please use
1642.Nm xinstall .
1643For calls to
1644.Xr mv 1 ,
1645.Xr cp 1 ,
1646.Xr rm 1
1647or similar, please use the built-in commands or
1648.Nm file
1649if they don't meet your requirements.
1650.It Ic variant_isset Ar variant
1651Checks if the given
1652.Ar variant
1653is being built.
1654.It Ic variant_set Ar variant
1655Set the given
1656.Ar variant .
1657.It Ic variant_unset Ar variant
1658Unset the given
1659.Ar variant .
1660.It Va variable Ns - Ns Ic append Ar item
1661Append
1662.Ar item
1663to the
1664.Va variable .
1665.br
1666.Sy Example:
1667.Dl configure.args-append --with-gnomedb
1668.It Va variable Ns - Ns Ic delete Ar item
1669Delete
1670.Ar item
1671from the
1672.Va variable .
1673.br
1674.Sy Example:
1675.Dl configure.args-delete --with-gnomedb
1676.It Ic readdir Ar directory
1677Return the list of elements in a
1678.Ar directory ,
1679excluding
1680.Pa \&.
1681and
1682.Pa \&.. .
1683.It Ic strsed Ar string Ar pattern
1684Perform
1685.Xr ed 1 Ns / Ns
1686.Xr tr 1 Ns -like
1687search, replace, and transliteration on a string.
1688.It Ic mktemp Ar template
1689Create a temporary file using a
1690.Ar template .
1691See
1692.Xr mktemp 3 .
1693.It Ic mkstemp Ar template
1694Create a temporary file securely using a
1695.Ar template .
1696See
1697.Xr mkstemp 3 .
1698.It Ic md5 Ar
1699Compute the MD5 hashes of the file(s).
1700.It Ic rpm-vercomp Ar versionA Ar versionB
1701Compare two RPM-format versions for equality.
1702.It Ic sudo Ar password Ar command Ar \&...
1703Execute
1704.Ar command
1705using
1706.Cm sudo
1707with the provided password.
1708.It Xo
1709.Ic lpush
1710.Ar varName
1711.Op Ar value \&...
1712.Xc
1713Treats the variable given by
1714.Ar varName
1715as a list and appends each of the
1716.Ar value
1717arguments to that list as a separate element. If
1718.Ar varName
1719doesn't exist, it is created as a list with elements
1720given by the
1721.Ar value
1722arguments.
1723Really just an alias for
1724.Xr lappend n .
1725.It Ic lpop Ar varName
1726Removes the last element from the list given by
1727.Ar varName
1728and returns it. If there are no elements in the list,
1729the empty string is returned. If
1730.Ar varName
1731doesn't exist, an exception is raised.
1732.It Xo
1733.Ic lunshift
1734.Ar varName
1735.Op Ar value \&...
1736.Xc
1737Treats the variable given by
1738.Ar varName
1739as a list and prepends each of the
1740.Ar value
1741arguments to that list as a separate element. If
1742.Ar varName
1743doesn't exist, it is created as a list with elements
1744given by the
1745.Ar value
1746arguments.
1747.It Ic lshift Ar varName
1748Removes the first element from the list given by
1749.Ar varName
1750and returns it. If there are no elements in the list,
1751the empty string is returned. If
1752.Ar varName
1753doesn't exist, an exception is raised.
1754.It Xo
1755.Ic ldindex
1756.Ar varName
1757.Op Ar index \&...
1758.Xc
1759Treats the variable given by
1760.Ar varName
1761as a list and removes the element pointed to by the sequence of
1762.Ar index
1763arguments and returns it. If no
1764.Ar index
1765arguments are provided,
1766.Ar varName
1767is set to the empty string and the entire former value is returned.
1768Has the same usage semantics as
1769.Xr lindex n .
1770.It Xo
1771.Ic try
1772.Ar body
1773.Oo
1774.Nm catch Nm {
1775.Ar type-list
1776.Op Ar ecvar
1777.Op Ar msgvar
1778.Op Ar infovar
1779.Nm }
1780.Ar body Ar \&...
1781.Oc
1782.Op Nm finally Ar body
1783.Xc
1784Implements a try-catch-finally block as defined in TIP #89.
1785.br
1786.Sy Example:
1787Basic try-finally construct.
1788.Bd -literal -offset indent -compact
1789try {
1790    set fd [open $file r]
1791    # do stuff here
1792} finally {
1793    close $fd
1794}
1795.Ed
1796.Sy Example:
1797Basic try-catch construct
1798.Bd -literal -offset indent -compact
1799try {
1800    set result [expr $num / $div]
1801} catch {{ARITH DIVZERO}} {
1802    set result -1
1803}
1804.Ed
1805.Sy Example:
1806Basic try with multiple catches construct
1807.Bd -literal -offset indent -compact
1808try {
1809    set fd [open $file r]
1810    # do stuff here
1811} catch {{POSIX ENOENT} {} msgvar} {
1812    puts stderr $msgvar
1813} catch {*} {
1814    puts stderr "An error occurred while processing the file"
1815    close $fd
1816    throw
1817}
1818.Ed
1819.It Xo
1820.Ic throw
1821.Op Ar type
1822.Op Ar message
1823.Op Ar info
1824.Xc
1825Throws an exception. If given arguments, works just like
1826.Ic error
1827.Ar message
1828.Ar info
1829.Ar type .
1830If called with no arguments from within a
1831.Ic catch
1832block, re-throws the caught exception.
1833.El
1834.Pp
1835.Bl -tag -width lc -compact
1836.It Ic ui_debug Ar message
1837.It Ic ui_error Ar message
1838.It Ic ui_info Ar message
1839.It Ic ui_msg Ar message
1840.It Ic ui_warn Ar message
1841Display a
1842.Ar message
1843to the user, at various different levels.
1844.br
1845.Sy Example:
1846.Dl ui_msg \*qAdd each user to the system using the clamav command\*q
1847.El
1848.Sh SEE ALSO
1849.Xr port 1 ,
1850.Xr macports.conf 5 ,
1851.Xr portgroup 7 ,
1852.Xr portstyle 7 ,
1853.Xr porthier 7 ,
1854.Xr file n
1855.Sh AUTHORS
1856.An "Landon Fuller" Aq landonf@macports.org
1857.An "Juan Manuel Palacios" Aq jmpp@macports.org
1858.An "Mark Duling" Aq markd@macports.org
1859.An "Kevin Van Vechten" Aq kevin@opendarwin.org
1860.An "Jordan K. Hubbard" Aq jkh@macports.org
1861.An "Chris Ridd" Aq cjr@opendarwin.org
1862.An "Kevin Ballard" Aq eridius@macports.org
Note: See TracBrowser for help on using the repository browser.