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

Last change on this file since 49854 was 49854, checked in by toby@…, 11 years ago

remove variant_unset and variant_undef, they are not used anywhere

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 45.0 KB
1.\" portfile.7
3.\" Copyright (c) 2002 Apple Computer, Inc.
4.\" All rights reserved.
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.
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
37A complete reference of all available
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.
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.
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.
58Portfiles must begin with a PortSystem line that defines which version of the
59Portfile interpreter should be used.
61.Sy Synopsis:
62.Dl PortSystem 1.0
64All ports are required to set certain variables.
65.Bl -tag -width lc
66.It Ic name
67Full name of port.
69.Sy Type:
70.Em required
72.Sy Example:
73.Dl name XFree86
74.It Ic version
75Upstream version of software.
77.Sy Type:
78.Em required
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.
90.Sy Type:
91.Em optional
93.Sy Default:
94.Em 0
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.
105.Sy Type:
106.Em required
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.
117.Sy Type:
118.Em required
120.Sy Example:
121.Bd -literal -offset indent -compact
122long_description The GNU Image Manipulation Program \e\
124    (GIMP) is a powerful tool for the preparation and \e\
126    manipulation of digital images. The GIMP provides \e\
128    the user with a wide variety of image manipulation, \e\
130    painting, processing, and rendering tools.
132.It Ic revision
133Local revision number of
134.Nm .
135Increment for port revisions which would change its installation in any way.
137.Sy Type:
138.Em optional
140.Sy Default:
141.Em 0
143.Sy Example:
144.Dl revision 1
145.It Ic categories
146Categories to which this port belongs.
148.Sy Type:
149.Em required
151.Sy Example:
152.Dl categories spelling textproc
153.It Ic maintainers
154E-mail address(es) of port maintainer(s).
156.Sy Type:
157.Em required
159.Sy Example:
160.Dl maintainers
161.It Ic platforms
162Declares which platforms are supported by the port.
164.Sy Type:
165.Em required
167.Sy Values:
168.Em darwin freebsd
170.Sy Example:
171.Dl platforms darwin
172.It Ic homepage
173Project homepage for the port.
175.Sy Type:
176.Em required
178.Sy Example:
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.
187.Sy Type:
188.Em required
190.Sy Example:
191.Bd -literal -offset indent -compact
192master_sites \e\
194    sourceforge
196.It Ic worksrcdir
197Path to source directory relative to
198.Ic workpath .
200.Sy Type:
201.Em optional
203.Sy Default:
204.Em ${distname}
206.Sy Example:
207.Dl worksrcdir ${distname}-src-${version}
208.It Ic distname
209Name of distribution file, without the
210.Cm extract.suffix .
212.Sy Type:
213.Em optional
215.Sy Default:
216.Em ${name}-${version}
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 ...
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.
232.Sy Type:
233.Em required
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
241.Sy Example (ledit 1.11):
242.Bd -literal -offset indent -compact
243checksums md5 a2d38ba641682509c1e964ad699a9dd2 \e\
244        sha1 1fb6443b5fdf3c83787953f06282d256477c1288
247.Sy Example (ssldump 0.9b3):
248.Bd -literal -offset indent -compact
249checksums md5 ac8c28fe87508d6bfb06344ec496b1dd \e\
250        sha1 a633a9a811a138eac5ed440d583473b644135ef5 \e\
251        rmd160 941cf8f2ef8459ec4f9ce65772e134505d46566
253.It Ic use_parallel_build
254If set to yes (and the user has enabled buildmakejobs in
255.Pa macports.conf
256), the port can be built using more than one job.
257.Sy Type:
258.Em optional
260.Sy Default:
261.Em no
263.Sy Example:
264.Dl use_parallel_build yes
265.It Ic use_automake
266If set to yes, run the
267.Cm automake
268target to build any
270files for use by
271.Pa configure .
273.Sy Type:
274.Em optional
276.Sy Default:
277.Em no
279.Sy Example:
280.Dl use_automake yes
281.It Ic use_autoconf
282If set to yes, run the
283.Cm autoconf
284target to build any
285.Pa configure
286script required.
288.Sy Type:
289.Em optional
291.Sy Default:
292.Em no
294.Sy Example:
295.Dl use_autoconf yes
296.It Ic use_configure
297If set to yes, run the
298.Cm configure
299target to configure the build.
301.Sy Type:
302.Em optional
304.Sy Default:
305.Em yes
307.Sy Example:
308.Dl use_configure no
311A number of hooks are available for customizing many of the standard
312targets that
313.Xr port 1
314executes. The targets supporting these hooks are
315.Cm fetch ,
316.Cm automake ,
317.Cm autoconf ,
318.Cm configure ,
319.Cm build ,
320.Cm destroot ,
322.Cm test .
323The hooks are:
324.Bl -tag -width lc
325.It Va target Ns Ic .asroot
326Run the
327.Va target
328with root privileges.
330.Sy Example:
331.Dl install.asroot yes
332.It Va target Ns Ic .dir
333Directory in which to run the
334.Va target .
336.Sy Example:
337.Dl automake.dir src
338.It Va target Ns Ic .env
339Change the environment the
340.Va target
341is run in. This is often overridden on a per
345.Sy Example:
346.Dl configure.env CPP=/usr/bin/cpp-4.0
347.It Va target Ns Ic .pre_args
348Additional arguments passed before the main arguments.
350.Sy Example:
351.Dl extract.pre_args -cd
352.It Va target Ns Ic .args
353Main arguments to pass to the
354.Va target .
355This is often overridden on a per
359.Sy Example:
360.Dl configure.args --enable-fooble
361.It Va target Ns Ic .post_args
362Additional arguments passed after the main arguments.
364.Sy Example:
365.Dl extract.post_args | tar xf -
368Read-only access to the MacPorts configuration is provided.
369.Bl -tag -width lc
370.It Ic prefix
371Install prefix
373.Sy Type:
374.Em optional
376.Sy Default:
377.Em /opt/local
378.It Ic libpath
379Location of ports-specific TCL libraries.
381.Sy Type:
382.Em read-only
383.It Ic portpath
384Full path to the Portfile location.
386.Sy Type:
387.Em read-only
389.Sy Default:
390.Em work
391.It Ic workpath
392Full path to work directory.
394.Sy Type:
395.Em read-only
397.Sy Default:
398.Em ${portbuildpath}/work
399.It Ic worksrcpath
400Full path to working sources (where port has unpacked itself).
402.Sy Type:
403.Em read-only
405.Sy Default:
406.Em ${workpath}/${worksrcdir}
407.It Ic filesdir
408Path to port files relative to
409.Ic portpath .
411.Sy Type:
412.Em read-only
414.Sy Default:
415.Em files
416.It Ic filespath
417Full path to the port files location.
419.Sy Type:
420.Em read-only
422.Sy Default:
423.Em ${portpath}/${filesdir}
424.It Ic distpath
425Location to store downloaded distfiles.
427.Sy Type:
428.Em read-only
430.Sy Default:
431.Em ${sysportpath}/distfiles/${dist_subdir}/
432.It Ic os.arch
433Identifies hardware type (eg "powerpc").
435.Sy Type:
436.Em read-only
437.It Ic os.version
438Version number of operating system (eg "7.0").
440.Sy Type:
441.Em read-only
442.It Ic os.endian
443Endianness of the processor (eg "bigEndian").
445.Sy Type:
446.Em read-only
447.It Ic os.platform
448Operating system name (eg "darwin").
450.Sy Type:
451.Em read-only
452.It Ic install.user
453User for MacPorts installation (eg
454.Pa root )
456.Sy Type:
457.Em read-only
458.It Ic
459Group for MacPorts installation (eg
460.Pa wheel )
462.Sy Type:
463.Em read-only
464.It Ic applications_dir
465Absolute path to the final location to install Mac OS X application
466bundles (.app directories).
468.Sy Type:
469.Em read-only
471.Sy Default:
472.Em /Applications/Macports
473.It Ic frameworks_dir
474Absolute path to the final location to install Mac OS X framework
475bundles (.framework directories).
477.Sy Type:
478.Em read-only
480.Sy Default:
481.Em ${prefix}/Library/Frameworks
482.It Ic x11prefix
483Absolute path to X11 (eg
484.Pa /usr/X11R6 )
486.Sy Type:
487.Em read-only
490Port dependencies should refer to other MacPort ports
491whenever possible, therefore each dependency should be
492expressed in the format:
493.Bl -tag -width ls
494.It port: Ns Ao port Ac
498.Ao port Ac represents the name of an existing MacPorts
499.Nm port .
500If satisfying a dependency with a MacPorts port is not
501practical and it is likely that a dependency must be met
502by an Apple optional install, then the alternative dependency
504.Bl -tag -width lc
505.It Ar type Ns : Ns Ao filename Ac Ns : Ns Ao port Ac
508may be used. Where
509.Ar type
510is "bin" if
511.Ao filename Ac
512is a program, "lib" if it is a library, or "path" if it is a path to an
513installed file.
515.Sy Example:
516.Dl lib:libX11.6:XFree86
517.Bl -tag -width lc
518.It Ic depends_build
519List of dependencies to check before
520.Cm configure ,
521.Cm build ,
522.Cm destroot ,
523.Cm install ,
525.Cm package
528.Sy Type:
529.Em optional
531.Sy Example:
532.Dl depends_build port:autoconf
533.It Ic depends_run
534List of dependencies to check before
535.Cm destroot ,
536.Cm install
538.Cm package
541.Sy Type:
542.Em optional
544.Sy Example:
545.Dl depends_run port:bash
546.It Ic depends_lib
547List of dependencies to check before
548.Cm configure ,
549.Cm build ,
550.Cm destroot ,
551.Cm install ,
553.Cm package
556.Sy Type:
557.Em optional
559.Sy Example:
560.Dl depends_lib port:libfetch
563Fetch all distribution files and patches.
564.Bl -tag -width lc
565.It Ic master_sites.mirror_subdir
566Subdirectory to append to all mirror sites for any list specified in
569.Sy Type:
570.Em optional
572.Sy Default:
573.Em ${name}
575.Sy Example:
576.Dl master_sites.mirror_subdir      magic
577.It Ic patch_sites
578List of sites to fetch
579.Ic patchfiles
580from or a predefined mirror site list.
582.Sy Type:
583.Em optional
585.Sy Default:
586.Em ${master_sites}
588.Sy Example:
589.Dl patch_sites
590.It Ic patch_sites.mirror_subdir
591Subdirectory to append to all mirror sites for any list specified in
592.Ic patch_sites .
594.Sy Type:
595.Em optional
597.Sy Default:
598.Em ${name}
600.Sy Example:
601.Dl patch_sites.mirror_subdir       magic
602.It Ic extract.suffix
603Suffix to append to
604.Ic distname .
606.Sy Type:
607.Em optional
609.Sy Default:
610.Em .tar.gz
612.Sy Example:
613.Dl extract.suffix .tgz
614.It Ic distfiles
615List of distribution files to fetch from
616.Ic master_sites .
618.Sy Type:
619.Em optional
621.Sy Default:
622.Em [suffix ${distname}]
624.Sy Example:
625.Dl distfiles magicsource.tar.gz cluebat.tar.bz2
626.It Ic patchfiles
627List of patches to fetch and apply.
629.Sy Type:
630.Em optional
632.Sy Example:
633.Dl patchfiles japanese-widechar-fix.diff japanese-localization.diff
634.It Ic use_zip
635Use zip.
637Sets extract.suffix to: .zip
639Sets extract.cmd to: unzip
641Sets extract.pre_args to: -q
643Sets extract.post_args to: "-d ${workpath}"
645.Sy Type:
646.Em optional
648.Sy Example:
649.Dl use_zip yes
650.It Ic use_bzip2
651Use bzip2.
653Sets extract.suffix to: .bz2
655Sets extract.cmd to: bzip2
657.Sy Type:
658.Em optional
660.Sy Example:
661.Dl use_bzip2 yes
662.It Ic use_lzma
663Use lzma.
665Sets extract.suffix to: .lzma
667Sets extract.cmd to: lzma
669.Sy Type:
670.Em optional
672.Sy Example:
673.Dl use_lzma yes
674.It Ic use_7z
675Use 7z (7zip).
677Sets extract.suffix to: .7z
679Sets extract.cmd to: 7za
681.Sy Type:
682.Em optional
684.Sy Example:
685.Dl use_7z yes
686.It Ic dist_subdir
687Create a sub-directory in
688.Ic distpath
689to store all fetched files.
691.Sy Type:
692.Em optional
694.Sy Default:
695.Em ${name}
697.Sy Example:
698.Dl dist_subdir vim${version}
701Some mirrors require special options for a resource to be properly
703.Bl -tag -width lc
704.It Ic fetch.user
705HTTP or FTP user to fetch the resource.
707.Sy Type:
708.Em optional
709.It Ic fetch.password
710HTTP or FTP password to fetch the resource.
712.Sy Type:
713.Em optional
714.It Ic fetch.use_epsv
715Whether to use EPSV command for FTP transfers.
717.Sy Type:
718.Em optional
720.Sy Default:
721.Em yes
723.It Ic fetch.ignore_sslcert
724Whether to ignore the host SSL certificate (for HTTPS).
726.Sy Type:
727.Em optional
729.Sy Default:
730.Em no
734As an alternative to fetching distribution files, pulling the sources
735from a CVS repository is supported. Use of CVS can give rise to
736non-reproducible builds, so it is strongly discouraged.
737.Bl -tag -width lc
738.It Ic cvs.root
739Specify the address to a CVS repository from which to checkout files.
741.Sy Type:
742.Em optional
744.Sy Default:
745.Em none
747.Sy Example:
748.Dl cvs.root
749.It Ic cvs.tag
750Specify a CVS tag identifying the code to checkout.
752.Sy Type:
753.Em optional
755.Sy Default
756.Em none
758.Sy Example:
759.Dl cvs.tag HEAD
760.It Ic
761A date that identifies the CVS code set to checkout.
763.Sy Type:
764.Em optional
766.Sy Default
767.Em none
769.Sy Example:
770.Dl \*q12-April-2005\*q
771.It Ic cvs.module
772A CVS module from which to check out the code.
774.Sy Type:
775.Em optional
777.Sy Default
778.Em none
780.Sy Example:
781.Dl cvs.module Sources
784As an alternative to fetching distribution files, pulling the sources
785from a subversion repository is supported. Use of subversion can give
786rise to non-reproducible builds, so it is strongly discouraged.
787.Bl -tag -width lc
788.It Ic svn.url
789Specify the url from which to fetch files.
791.Sy Type:
792.Em required
794.Sy Default:
795.Em none
797.Sy Example:
798.Dl svn.url
799      svn.url svn://
800.It Ic svn.tag
801Specify a tag from which svn should fetch files. This
802corresponds to the -r option to the svn cli.  Note that you
803will need to use backslashes to escape characters that have
804meaning to the Tcl interpreter, such as braces and double
807.Sy Type:
808.Em optional
810.Sy Default:
811.Em none
813.Sy Example:
814.Dl svn.tag 37192
815      svn.tag \\{\\"2006-02-17 15:30 +0230\\"\\}
818As an alternative to fetching distribution files, pulling the sources
819from a git repository is supported. Use of git can give rise to
820non-reproducible builds, so it is strongly discouraged.
821.Bl -tag -width lc
822.It Ic git.url
823Specify the url from which to fetch files
825.Sy Type:
826.Em required
828.Sy Default:
829.Em none
831.Sy Example:
832.Dl git.url git://
833      git.url
834.It Ic git.branch
835Specify a branch (or other commit-ish) that git should checkout.
836Note that any branch besides HEAD should be prefixed by origin/.
838.Sy Type:
839.Em optional
841.Sy Default:
842.Em none
844.Sy Example:
845.Dl git.branch 72bf1c8
846      git.branch origin/next
849Extract all compressed/archived files.
850.Bl -tag -width lc
851.It Ic extract.only
852List of files to extract into
853.Ic workpath .
855.Sy Type:
856.Em optional
858.Sy Default:
859.Em ${distfiles}
861.Sy Example:
862.Dl extract.only worksrc-1.4.4.tar.gz
863.It Ic extract.cmd
864Command to perform the extraction.
866.Sy Type:
867.Em optional
869.Sy Default:
870.Em gzip
872.Sy Example:
873.Dl extract.cmd bzip2
874.It Ic extract.mkdir
875Create the
876.Ic worksrcdir
877prior to extraction; useful for ports which extract directly into the current
878working directory instead of a subdirectory.
880.Sy Type:
881.Em optional
883.Sy Default:
884.Em no
886.Sy Example:
887.Dl extract.mkdir yes
890MacPorts provide special support for configure flags (CFLAGS, LDFLAGS, CPPFLAGS, CXXFLAGS, CC, CXX, CPP, FC, F77, F90). Please note that the previous way to alter these flags (using configure.env) may become deprecated at some point. The following options are defined:
891.Bl -tag -width lc
892.It Ic configure.cflags
893Flags to put in the CFLAGS environment variable when invoking the configure script.
895.Sy Type:
896.Em optional
898.Sy Default:
899.Em -O2
901.Sy Example:
902.Dl configure.cflags-append -DHAS_LRINTF
903.It Ic configure.cppflags
904Flags to put in the CPPFLAGS environment variable when invoking the configure script.
906.Sy Type:
907.Em optional
909.Sy Default:
910.Em -I${prefix}/include
911.It Ic configure.cxxflags
912Flags to put in the CXXFLAGS environment variable when invoking the configure script.
914.Sy Type:
915.Em optional
917.Sy Default:
918.Em -O2
919.It Ic configure.objcflags
920Flags to put in the OBJCFLAGS environment variable when invoking the configure script.
922.Sy Type:
923.Em optional
925.Sy Default:
926.Em -O2
927.It Ic configure.ldflags
928Flags to put in the LDFLAGS environment variable when invoking the configure script.
930.Sy Type:
931.Em optional
933.Sy Default:
934.Em -L${prefix}/lib
935.It Ic configure.fflags
936Flags to put in the FFLAGS environment variable when invoking the configure script.
938.Sy Type:
939.Em optional
941.Sy Default:
942.Em -O2
943.It Ic configure.f90flags
944Flags to put in the F90FLAGS environment variable when invoking the configure script.
946.Sy Type:
947.Em optional
949.Sy Default:
950.Em -O2
951.It Ic configure.fcflags
952Flags to put in the FCFLAGS environment variable when invoking the configure script.
954.Sy Type:
955.Em optional
957.Sy Default:
958.Em -O2
959.It Ic configure.classpath
960Flags to put in the CLASSPATH environment variable when invoking the configure script.
962.Sy Type:
963.Em optional
964.It Ic configure.macosx_deployment_target
965Flags to put in the MACOSX_DEPLOYMENT_TARGET environment variable when invoking the configure script.
967.Sy Type:
968.Em optional
970.Sy Example:
971.Dl configure.macosx_deployment_target 10.4
972.It Ic
973C-compiler to put in the CC environment variable when invoking the configure script.
975.Sy Type:
976.Em optional
978.Sy Example:
979.Dl /usr/bin/gcc
980.It Ic configure.cpp
981C-preprocessor to put in the CPP environment variable when invoking the configure script.
983.Sy Type:
984.Em optional
985.It Ic configure.cxx
986C++-compiler to put in the CXX environment variable when invoking the configure script.
988.Sy Type:
989.Em optional
990.It Ic configure.objc
991Objective-C-compiler to put in the OBJC environment variable when invoking the configure script.
993.Sy Type:
994.Em optional
996.Sy Example:
997.Dl configure.objc ${prefix}/bin/gcc-mp-4.1
998.It Ic configure.fc
999Fortran-compiler to put in the FC environment variable when invoking the configure script.
1001.Sy Type:
1002.Em optional
1003.It Ic configure.f77
1004Fortran-77-compiler to put in the F77 environment variable when invoking the configure script.
1006.Sy Type:
1007.Em optional
1008.It Ic configure.f90
1009Fortran-90-compiler to put in the F90 environment variable when invoking the configure script.
1011.Sy Type:
1012.Em optional
1013.It Ic configure.javac
1014Java compiler to put in the JAVAC environment variable when invoking the configure script.
1016.Sy Type:
1017.Em optional
1018.It Ic configure.compiler
1019Selects a complete compiler suite to use. This option will override the compiler environment variable for all compilers the named suite features. Please note that this option will intentionally not set any dependencies on the selected compiler suite!
1020.Em gcc-3.3
1021.Em gcc-4.0
1022use the standard system compiler suites,
1023.Em apple-gcc-3.3
1024.Em apple-gcc-4.0
1025use Apple's gcc suite installed via MacPorts,
1026.Em macports-gcc-3.3
1027.Em macports-gcc-3.4
1028.Em macports-gcc-4.0
1029.Em macports-gcc-4.1
1030.Em macports-gcc-4.2
1031.Em macports-gcc-4.3
1032use the vanilla gcc installed via MacPorts.
1034.Sy Type:
1035.Em optional
1037.Sy Values:
1038.Em gcc-3.3 gcc-4.0 apple-gcc-3.3 apple-gcc-4.0 macports-gcc-3.3 macports-gcc-3.4 macports-gcc-4.0 macports-gcc-4.1 macports-gcc-4.2 macports-gcc-4.3
1040.Sy Example:
1041.Dl configure.compiler gcc-4.0
1042.\" FOOBAR
1045For 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.
1046.Bl -tag -width lc
1047.It Ic configure.universal_args
1048Arguments appended to the configure script to build the port universal.
1050.Sy Type:
1051.Em optional
1053.Sy Default:
1054.Em --disable-dependency-tracking
1055.It Ic configure.universal_cflags
1056Additional flags to put in the CFLAGS environment variable when invoking the configure script.
1058.Sy Type:
1059.Em optional
1061.Sy Default:
1062.Em -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc
1063.It Ic configure.universal_cppflags
1064Additional flags to put in the CPPFLAGS environment variable when invoking the configure script.
1066.Sy Type:
1067.Em optional
1068.It Ic configure.universal_cxxflags
1069Additional flags to put in the CXXFLAGS environment variable when invoking the configure script.
1071.Sy Type:
1072.Em optional
1074.Sy Default:
1075.Em -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc
1076.It Ic configure.universal_ldflags
1077Additional flags to put in the LDFLAGS environment variable when invoking the configure script.
1079.Sy Type:
1080.Em optional
1082.Sy Default:
1083.Em -arch i386 -arch ppc
1086Execute necessary build commands.
1087.Bl -tag -width lc
1088.It Ic build.cmd
1089Make command to run relative to
1090.Ic worksrcdir .
1092.Sy Type:
1093.Em optional
1095.Sy Default:
1096.Em make
1098.Sy Example:
1099.Dl build.cmd pbxbuild
1100.It Ic build.type
1101Defines which 'make' is required, either 'gnu' or 'bsd'.
1103.Ic build.cmd
1104to either
1105.Pa gnumake
1107.Pa bsdmake
1110.Sy Type:
1111.Em optional
1113.Sy Default:
1114.Em gnu
1116.Sy Example:
1117.Dl build.type bsd
1118.It Ic
1119Target passed to
1120.Ic build.cmd .
1122.Sy Type:
1123.Em optional
1125.Sy Default:
1126.Em all
1128.Sy Example:
1129.Dl all-src
1132Execute necessary commands to install into a temporary destination root
1133("destroot") staging area.
1134.Bl -tag -width lc
1135.It Ic destroot.cmd
1136Install command to run relative to
1137.Ic worksrcdir .
1139.Sy Type:
1140.Em optional
1142.Sy Default:
1143.Em ${build.cmd}
1145.Sy Example:
1146.Dl destroot.cmd pbxbuild
1147.It Ic destroot.type
1148Defines which 'make' is required, either 'gnu' or 'bsd'.
1150.Ic destroot.cmd
1151to either
1152.Pa gnumake
1154.Pa bsdmake
1157.Sy Type:
1158.Em optional
1160.Sy Default:
1161.Em ${build.type}
1163.Sy Example:
1164.Dl destroot.type gnu
1165.It Ic destroot.destdir
1166Arguments passed to
1167.Ic destroot.cmd
1168in order to install correctly
1169into the destroot.
1171.Sy Type:
1172.Em optional
1174.Sy Default:
1175.Em DESTDIR=${destroot}
1177.Sy Example:
1178.Dl destroot.destdir prefix=${destroot}${prefix}
1179.It Ic
1180Install target to pass to
1181.Ic destroot.cmd .
1183.Sy Type:
1184.Em optional
1186.Sy Default:
1187.Em install
1189.Sy Example:
1190.Dl install-src
1191.It Ic destroot.umask
1192Umask to use during destroot.
1194.Sy Type:
1195.Em optional
1197.Sy Default:
1198.Em 022
1200.Sy Example:
1201.Dl destroot.umask 002
1202.It Ic destroot.keepdirs
1203List of directories that should not be pruned if empty upon
1204.Cm destroot
1207.Sy Type:
1208.Em optional
1210.Sy Example:
1211.Dl destroot.keepdirs ${destroot}${prefix}/var/log/mysql
1212.It Ic destroot.violate_mtree
1213Indicates if a port will violate the common directory structure. Enables or disables tests for violations of mtree (e. g. non-standard directories in ${prefix}). The standard mtree can be found in
1214.Xr porthier 7 .
1216.Sy Type:
1217.Em optional
1219.Sy Values:
1220.Em yes no
1222.Sy Default:
1223.Em no
1226Execute commands to run test suites bundled with a port.
1227.Bl -tag -width lc
1228.It Ic
1229Enable running test suites bundled with a port.
1231.Sy Type:
1232.Em optional
1234.Sy Example:
1235.Dl     yes
1236.It Ic test.cmd
1237Test command to run relative to
1238.Ic worksrcdir .
1240.Sy Type:
1241.Em optional
1243.Sy Default:
1244.Em ${build.cmd}
1246.Sy Example:
1247.Dl test.cmd
1248.It Ic
1249Test target to pass to
1250.Ic test.cmd .
1252.Sy Type:
1253.Em optional
1255.Sy Default:
1256.Em test
1258.Sy Example:
1259.Dl checks
1262If a port needs to run on system startup, it can use MacPorts
1263startupitem keywords to install native OS X startup scripts.
1264Startup scripts require user interaction after port installation
1265to activate them and instructions are given during port installs.
1266.Bl -tag -width lc
1267.It Ic startupitem.create
1268Choose whether or not to generate a startup item.
1270.Sy Type:
1271.Em optional
1273.Sy Default:
1274.Em no
1276.Sy Values:
1277.Em yes no
1279.Sy Example:
1280.Dl startupitem.create yes
1281.It Ic startupitem.type
1282Select the type of startupitem to generate. By default, a startupitem
1283will be generated that is of the appropriate type for the OS. For
1284instance, launchd is used on system 10.4, while SystemStarter is used
1285on prior Mac OS X systems. A global default may be specified with the startupitem_type preference in ports.conf.
1287.Sy Type:
1288.Em optional
1290.Sy Default:
1291.Em default
1293.Sy Values:
1294.Em SystemStarter launchd default rcNG
1296.Sy Example
1297.Dl startupitem.type launchd
1298.It Ic
1299Displayed name of the startup item.
1301.Sy Type:
1302.Em required
1304.Sy Example:
1305.Dl OpenSSH
1306.It Ic startupitem.executable
1307The name of the daemon to be run in the background. This is
1308the preferred type of startup item rather than any of
1309startupitem.init, startupitem.start, startupitem.stop, or
1310startupitem.restart, and may not be used together with any
1311of these options.  This option may contain multiple
1312arguments, but they must be appropriate for a call to exec; they
1313may not contain arbitrary shell code.
1315.Sy Type:
1316.Em optional
1318.Sy Values:
1319.Em /path/to/executable <args>
1321.Sy Example:
1322.Dl startupitem.executable ${prefix}/bin/wonka
1323.It Ic startupitem.init
1324Shell code that will be executed prior to any of the options
1325startupitem.start, startupitem.stop and startupitem.restart.
1327.Sy Type:
1328.Em optional
1330.Sy Values:
1331.Em sh code
1333.Sy Example:
1334.Dl startupitem.init FOO=start
1335.It Ic startupitem.start
1336Shell code executed to start the daemon.
1338.Sy Type:
1339.Em optional
1341.Sy Values:
1342.Em sh code
1344.Sy Example:
1345.Dl startupitem.start ${prefix}/share/mysql/mysql.server start
1346.It Ic startupitem.stop
1347Shell code executed to stop the daemon.
1349.Sy Type:
1350.Em optional
1352.Sy Values:
1353.Em sh code
1355.Sy Example:
1356.Dl startupitem.stop ${prefix}/share/mysql/mysql.server stop
1357.It Ic startupitem.restart
1358Shell code executed to restart the daemon. In the absence
1359of this key, the daemon will be restarted by taking the
1360stop action, followed by taking the start action.
1362.Sy Type:
1363.Em optional
1365.Sy Values:
1366.Em sh code
1368.Sy Example:
1369.Dl startupitem.restart ${prefix}/share/mysql/mysql.server restart
1370.It Ic startupitem.pidfile
1371Specification for pidfile handling. This is particularly useful
1372in conjunction with the startupitem.executable key, because it is
1373important that the startupitem know how to track the executable.
1374This specifies whether the daemon generates its own pidfile (auto),
1375whether it generates its own but forgets to delete it, so that the
1376startupitem should delete it (clean), or whether it never generates
1377one, in which case the startupitem should manage the pidfile on its
1378own (manual), or whether no pidfile should be used at all (none).
1380.Sy Type:
1381.Em optional
1383.Sy Default:
1384.Em none "${prefix}/var/run/${name}.pid"
1386.Sy Values:
1387.Em none|auto|manual|clean [/path/to/pidfile]
1389.Sy Example:
1390.Dl startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile
1391.It Ic startupitem.logfile
1392Path to a logfile for logging events about the lifetime of the
1393startupitem. Depending on the type of startupitem, and the manner
1394in which it is started, standard output from the daemon may also be
1395directed to the logfile.
1397.Sy Type:
1398.Em optional
1400.Sy Default:
1401.Em /dev/null
1403.Sy Values:
1404.Em path
1406.Sy Example:
1407.Dl startupitem.logfile ${prefix}/var/log/mydaemon.log
1408.It Ic startupitem.logevents
1409Control whether or not to log events to the log file. If logevents
1410is set, events with timestamps are logged to the logfile.
1412.Sy Type:
1413.Em optional
1415.Sy Default:
1416.Em no
1418.Sy Values:
1419.Em yes|no
1421.Sy Example:
1422.Dl startupitem.logevents yes
1423.It Ic startupitem.netchange
1424Control whether the startupitem should be restarted when a change in the
1425machine's network state is detected.
1427.Sy Type:
1428.Em optional
1430.Sy Default:
1431.Em no
1433.Sy Values:
1434.Em yes|no
1436.Sy Example:
1437.Dl startupitem.netchange yes
1440MacPorts can automatically check if the software has been updated
1441since the Portfile was modified and if some external changes require
1442an update to the Portfile. This helps maintainers have up-to-date
1443and working Portfiles.
1445Two checks are available. With distcheck, MacPorts can check that the
1446distfile(s) are still downloadable and did not change since the portfile
1447was modified.
1448With livecheck, MacPorts can query a resource to determine if a newer
1449version of the software is available.
1450.Bl -tag -width lc
1451.It Ic distcheck.check
1452This option can be used to disable distcheck. It specifies what kind
1453of check should be performed on distfiles:
1454.Em moddate
1455(check if the Portfile is older than the distfile) or
1456.Em none
1457(no check).
1459.Sy Type:
1460.Em optional
1462.Sy Default:
1463.Em moddate
1465.Sy Values:
1466.Em moddate none
1467.It Ic livecheck.check
1468What kind of check to perform to figure out if the software has been updated.
1469Can be
1470.Em freshmeat
1471(uses the date_updated tag of the freshmeat XML file),
1472.Em sourceforge
1473(uses the version of the latest file release of the project),
1474.Em googlecode
1475(uses the version of the latest file release of the project),
1476.Em moddate
1477(uses the modification date of some URL resource),
1478.Em regex
1479(retrieve the version by applying a regex to some URL resource),
1480.Em regexm
1481(retrieve the version by applying a multi-line regex to some URL resource),
1482.Em md5
1483(compares the md5 sum of some URL resource) or
1484.Em none
1485(no check).
1487.Sy Type:
1488.Em optional
1490.Sy Default:
1491.Em sourceforge
1493.Em googlecode
1494if the master_sites is one of these, else
1495.Em freshmeat
1497.Sy Values:
1498.Em freshmeat sourceforge googlecode moddate regex regexm md5 none
1499.It Ic
1500Name of the project for live checks (used for freshmeat, sourceforge, and googlecode checks).
1502.Sy Type:
1503.Em optional
1505.Sy Default:
1506.Em ${name}
1507or the sourceforge/freshmeat/googlecode project name if it can be guessed by looking at the master_sites.
1508.It Ic livecheck.distname
1509Name of the file release (used for sourceforge and googlecode checks).
1510For sourceforge releases use the name of the package release.
1511For googlecode releases use the name of the file download, including extension.
1512Replace the version part of the name with "(.*)".
1514.Sy Type:
1515.Em optional
1517.Sy Default:
1518.Em ${}
1519for sourceforge projects or the first entry in
1520.Em ${distfiles}
1521for googlecode projects
1522.It Ic livecheck.version
1523Version of the project for live checks (used for regex-based checks).
1525.Sy Type:
1526.Em optional
1528.Sy Default:
1529.Em ${version}
1530.It Ic livecheck.url
1531URL to query for the check.
1533.Sy Type:
1534.Em optional
1536.Sy Default:
1537.Em ${homepage}
1544.It Ic livecheck.regex
1545Regular expression to parse the resource for regex checks.
1546Be sure to use a regular expression grouping around the version component.
1548.Sy Type:
1549.Em optional
1550.It Ic livecheck.md5
1551md5 sum to use for md5 comparison.
1553.Sy Type:
1554.Em optional
1557MacPorts allows for conditional modification to be specified in a
1558.Nm ,
1559allowing for user-customization of a software's build-time settings.
1560.Bl -tag -width lc
1561.It Xo
1562.Ic variant
1563.Op Cm requires Ar variant
1564.Op Cm conflicts Ar variant
1565.Op Cm description Ar "description"
1567The value is usually a TCL script which modifies other port's
1569variables. Dependencies and conflicts with other variants in the same
1570port can be expressed with
1571.Cm requires
1573.Cm conflicts .
1574.Cm description
1575provides a means to supply a description of the variant for the user.
1577.Sy Type:
1578.Em optional
1580.Sy Example:
1581Add a "gnome" variant to a port.
1582.Bd -literal -offset indent -compact
1583variant gnome requires glib { configure.args-append --with-gnome \e\
1585    depends_lib-append lib:gnome-session:gnome-session }
1587.It Ic default_variants
1588If variants are defined, then the
1589.Ic default_variants
1590value lists which variants are enabled by default.
1592.Sy Type:
1593.Em optional
1595.Sy Example:
1596.Dl default_variants +ssl +tcpd
1597.It Ic universal_variant
1598When using MacPorts on Mac OS X, a universal variant is defined and
1599the default behavior is to configure ports with universal flags
1600(see the
1602section above). The variant can be
1603overridden if the default code does not work. It can also be
1604suppressed if having a universal variant for the port does not make
1605sense. To suppress it, use the
1606.Ic universal_variant
1609.Sy Type:
1610.Em optional
1612.Sy Default:
1613.Em yes
1615.Sy Example:
1616.Dl universal_variant no
1619MacPorts allows for platform-specific conditional modification to be
1620specified in a
1621.Nm ,
1622much like variants, for handling differences between platforms and
1623versions of the same platform.
1624.Bl -tag -width lc
1625.It Xo
1626.Ic platform
1627.Ar platform
1628.Op Ar version
1629.Op Ar arch
1631The platform key is used to begin the darwin platform definitions as
1632shown in the examples from the databases/db4 and devel/libidl1
1633.Nm Portfiles
1636.Sy Type:
1637.Em optional
1639.Sy Example:
1640.Bd -literal -offset indent -compact
1641platform darwin 6 { configure.args-append   --enable-tcl \e\
1643        --with-tcl=/System/Library/Tcl/8.3 }
1646.Sy Example:
1647.Bd -literal -offset indent -compact
1648platform darwin powerpc { configure.args-append \e\
1650        --host=${os.arch}-apple-rhapsody${os.version} }
1651platform darwin i386 { configure.args-append \e\
1653        --host=i386-gnu-rhapsody${os.version} }
1657To factorize the work with similar ports, MacPorts provides the notion of
1658.Nm PortGroup
1659that can be used to load definitions for a given class or group of ports. See
1660.Xr portgroup 7
1661for more details on the various PortGroup classes.
1663A number of TCL extensions are available for use in
1664.Nm Portfiles .
1666.Bl -tag -width lc
1667.Bl -tag -width lc -compact
1668.It Xo
1669.Ic xinstall
1670.Op Fl c
1671.Op Fl B Ar suffix
1672.Op Fl b
1673.Op Fl C
1674.Op Fl f Ar flags
1675.Op Fl g Ar group
1676.Op Fl M
1677.Op Fl m Ar mode
1678.Op Fl o Ar owner
1679.Op Fl p
1680.Op Fl S
1681.Op Fl s
1682.Op Fl W Ar dir
1683.Op Ar
1684.Ar destination
1686.It Xo
1687.Ic xinstall
1688.Fl d
1689.Op Fl B Ar suffix
1690.Op Fl b
1691.Op Fl C
1692.Op Fl f Ar flags
1693.Op Fl g Ar group
1694.Op Fl M
1695.Op Fl m Ar mode
1696.Op Fl o Ar owner
1697.Op Fl p
1698.Op Fl S
1699.Op Fl s
1700.Op Fl W Ar dir
1701.Ar directory
1703Install file(s) to a target file or directory. The options are
1704intended to be compatible with
1705.Xr install 1 :
1706.Bl -tag -width indent
1707.It Fl b
1708Backup any existing files with an
1709.Pa .old
1711.It Fl B
1712Specify a different backup suffix for the
1713.Fl b
1715.It Fl c
1716Install files (this is the default).
1717.It Fl C
1718Only copy a file if it is different.
1719.It Fl d
1720Create directories, including (if necessary) parent directories.
1721.It Fl f
1722Specify target flags, see
1723.Xr chflags 1
1724for details.
1725.It Fl g
1726Specify the group.
1727.It Fl M
1728Disable use of
1729.Xr mmap 2 .
1730.It Fl m
1731Specify an alternate mode. The default is 0755. See
1732.Xr chmod 1
1733for defails.
1734.It Fl p
1735Preserve the modification time.
1736.It Fl S
1737Copy safely, using a temporary file.
1738.It Fl s
1739Strip binaries using
1740.Xr strip 1 .
1741.It Fl W
1742Change to
1743.Ar dir
1744before working.
1747.It Xo
1748.Ic fs-traverse
1749.Op Fl depth
1750.Op Fl ignoreErrors
1751.Ar varname
1752.Ar target-list
1753.Ar body
1755Traverse the filesystem hierarchy rooted in each element of
1756.Ar target-list
1757and execute
1758.Ar body
1759for each found file/directory.
1760.Va varname
1761is set to the path of the file/directory. If
1762.Ic break
1763is called during execution, the filesystem traversal is stopped. If
1764.Ic continue
1765is called during execution, the current file and any children are skipped
1766and traversal continues with the next file/directory.
1767.Bl -tag -width indent
1768.It Fl depth
1769Equivalent to the
1770.Fl d
1771switch to
1772.Xr find 1 .
1773Please note that using
1774.Fl depth
1775means you cannot prune a directory with
1776.Ic continue
1777as it will be processed after its children.
1778.It Fl ignoreErrors
1780.Ic fs-traverse
1781to ignore any permissions/read errors encountered during processing.
1785.Nm fs-traverse
1786is called directly on a symbolic link, the link will be followed. All other
1787links encountered during traversal will not be followed.
1789.Nm fs-traverse
1790will not descend into directories that have a different device number than
1791the root of the descent.
1793If you remove the current directory during traversal, be aware that you must call
1794.Nm continue
1795to inform
1796.Nm fs-traverse
1797that the directory should not be descended into.
1798.It Xo
1799.Ic curl fetch
1800.Ar url
1801.Ar file
1803Fetch a resource at
1804.Ar url
1805and save it to
1806.Ar file .
1807.It Xo
1808.Ic curl isnewer
1809.Ar url
1810.Ar date
1812Determine if resource at
1813.Ar url
1814is newer than
1815.Ar date
1816(expressed in seconds since epoch).
1817.It Xo
1818.Ic adduser
1819.Ar username
1820.Op Cm uid Ns = Ns uid
1821.Op Cm gid Ns = Ns gid
1822.Op Cm passwd Ns = Ns passwd
1823.Op Cm realname Ns = Ns realname
1824.Op Cm home Ns = Ns home
1825.Op Cm shell Ns = Ns shell
1827Add a new local user to the system with the specified uid, gid,
1828password, real name, home directory and login shell.
1829.It Ic existsuser Ar username
1830Check if a local user exists.
1831.It Ic nextuid
1832Returns the highest used uid plus one.
1833.It Xo
1834.Ic addgroup
1835.Ar group
1836.Op Cm gid Ns = Ns gid
1837.Op Cm passwd Ns = Ns passwd
1838.Op Cm realname Ns = Ns realname
1839.Op Cm users Ns = Ns users
1841Add a new local group to the system, with the specified gid, password,
1842real name, and with a list users as members.
1843.It Ic existsgroup Ar group
1844Check if a local group exists and return the corresponding gid. This can be used
1845with adduser:
1846.Dl addgroup foo
1847.Dl adduser foo gid=[existsgroup foo]
1848.It Ic nextgid
1849Returns the highest used gid plus one.
1850.It Xo
1851.Ic reinplace
1852.Op Fl E
1853.Ar regex
1856Provide in-place
1857.Xr sed 1
1858like editing of a file.
1859The -E flag does the same thing as in
1860.Xr sed 1
1862.Sy Example:
1863.Dl reinplace \*qs|/usr/local|${prefix}|g\*q doc/manpage.1
1864.It Ic file
1865Standard TCL command to manipulate file names and attributes, recommended if you wish to preserve Mac OS
1866resource forks when destrooting ports on Mac OS X 10.3.x and Mac OS X 10.4.x . Use
1867.Nm xinstall
1868to also preserve Extended Attributes (i.e. Access Control Lists). See
1869.Xr file n
1870for more information on this command.
1871.It Ic copy
1872Built-in shorthand alternative to "file copy".
1873.It Ic move
1874Built-in shorthand alternative to "file rename".
1875.It Ic delete Ar
1876Deletes each of the given files/directories. Behaves similarly to
1877.Ic file delete -force
1878except that
1879.Ic file delete -force
1880will fail to delete directories properly on 10.3 systems.
1881.It Ic touch
1882Built-in command mimicking the BSD touch command.
1883.It Ic ln
1885Built-in command mimicking the BSD ln command.
1886.It Ic system Ar commandline
1887Execute a program. See
1888.Xr system 3 .
1889For calls to
1890.Xr install 1
1891please use
1892.Nm xinstall .
1893For calls to
1894.Xr mv 1 ,
1895.Xr cp 1 ,
1896.Xr rm 1
1897or similar, please use the built-in commands or
1898.Nm file
1899if they don't meet your requirements.
1900.It Ic variant_isset Ar variant
1901Checks if the given
1902.Ar variant
1903is being built.
1904.It Ic variant_set Ar variant
1905Set the given
1906.Ar variant .
1907.It Va variable Ns - Ns Ic append Ar item
1909.Ar item
1910to the
1911.Va variable .
1913.Sy Example:
1914.Dl configure.args-append --with-gnomedb
1915.It Va variable Ns - Ns Ic delete Ar item
1917.Ar item
1918from the
1919.Va variable .
1921.Sy Example:
1922.Dl configure.args-delete --with-gnomedb
1923.It Ic readdir Ar directory
1924Return the list of elements in a
1925.Ar directory ,
1927.Pa \&.
1929.Pa \&.. .
1930.It Ic strsed Ar string Ar pattern
1932.Xr ed 1 Ns / Ns
1933.Xr tr 1 Ns -like
1934search, replace, and transliteration on a string.
1935.It Ic mktemp Ar template
1936Create a temporary file using a
1937.Ar template .
1939.Xr mktemp 3 .
1940.It Ic mkstemp Ar template
1941Create a temporary file securely using a
1942.Ar template .
1944.Xr mkstemp 3 .
1945.It Ic md5 Ar
1946Compute the MD5 hashes of the file(s).
1947.It Ic rpm-vercomp Ar versionA Ar versionB
1948Compare two RPM-format versions for equality.
1949.It Ic sudo Ar password Ar command Ar \&...
1951.Ar command
1953.Cm sudo
1954with the provided password.
1955.It Xo
1956.Ic lpush
1957.Ar varName
1958.Op Ar value \&...
1960Treats the variable given by
1961.Ar varName
1962as a list and appends each of the
1963.Ar value
1964arguments to that list as a separate element. If
1965.Ar varName
1966doesn't exist, it is created as a list with elements
1967given by the
1968.Ar value
1970Really just an alias for
1971.Xr lappend n .
1972.It Ic lpop Ar varName
1973Removes the last element from the list given by
1974.Ar varName
1975and returns it. If there are no elements in the list,
1976the empty string is returned. If
1977.Ar varName
1978doesn't exist, an exception is raised.
1979.It Xo
1980.Ic lunshift
1981.Ar varName
1982.Op Ar value \&...
1984Treats the variable given by
1985.Ar varName
1986as a list and prepends each of the
1987.Ar value
1988arguments to that list as a separate element. If
1989.Ar varName
1990doesn't exist, it is created as a list with elements
1991given by the
1992.Ar value
1994.It Ic lshift Ar varName
1995Removes the first element from the list given by
1996.Ar varName
1997and returns it. If there are no elements in the list,
1998the empty string is returned. If
1999.Ar varName
2000doesn't exist, an exception is raised.
2001.It Xo
2002.Ic ldindex
2003.Ar varName
2004.Op Ar index \&...
2006Treats the variable given by
2007.Ar varName
2008as a list and removes the element pointed to by the sequence of
2009.Ar index
2010arguments and returns it. If no
2011.Ar index
2012arguments are provided,
2013.Ar varName
2014is set to the empty string and the entire former value is returned.
2015Has the same usage semantics as
2016.Xr lindex n .
2017.It Xo
2018.Ic try
2019.Ar body
2021.Nm catch Nm {
2022.Ar type-list
2023.Op Ar ecvar
2024.Op Ar msgvar
2025.Op Ar infovar
2026.Nm }
2027.Ar body Ar \&...
2029.Op Nm finally Ar body
2031Implements a try-catch-finally block as defined in TIP #89.
2033.Sy Example:
2034Basic try-finally construct.
2035.Bd -literal -offset indent -compact
2036try {
2037    set fd [open $file r]
2038    # do stuff here
2039} finally {
2040    close $fd
2043.Sy Example:
2044Basic try-catch construct
2045.Bd -literal -offset indent -compact
2046try {
2047    set result [expr $num / $div]
2048} catch {{ARITH DIVZERO}} {
2049    set result -1
2052.Sy Example:
2053Basic try with multiple catches construct
2054.Bd -literal -offset indent -compact
2055try {
2056    set fd [open $file r]
2057    # do stuff here
2058} catch {{POSIX ENOENT} {} msgvar} {
2059    puts stderr $msgvar
2060} catch {*} {
2061    puts stderr "An error occurred while processing the file"
2062    close $fd
2063    throw
2066.It Xo
2067.Ic throw
2068.Op Ar type
2069.Op Ar message
2070.Op Ar info
2072Throws an exception. If given arguments, works just like
2073.Ic error
2074.Ar message
2075.Ar info
2076.Ar type .
2077If called with no arguments from within a
2078.Ic catch
2079block, re-throws the caught exception.
2082.Bl -tag -width lc -compact
2083.It Ic ui_debug Ar message
2084.It Ic ui_error Ar message
2085.It Ic ui_info Ar message
2086.It Ic ui_msg Ar message
2087.It Ic ui_warn Ar message
2088Display a
2089.Ar message
2090to the user, at various different levels.
2092.Sy Example:
2093.Dl ui_msg \*qAdd each user to the system using the clamav command\*q
2095.Sh SEE ALSO
2096.Xr port 1 ,
2097.Xr macports.conf 5 ,
2098.Xr portgroup 7 ,
2099.Xr portstyle 7 ,
2100.Xr porthier 7 ,
2101.Xr file n
2103.An "Landon Fuller" Aq
2104.An "Juan Manuel Palacios" Aq
2105.An "Mark Duling" Aq
2106.An "Kevin Van Vechten" Aq
2107.An "Jordan K. Hubbard" Aq
2108.An "Chris Ridd" Aq
2109.An "Kevin Ballard" Aq
2110.An "Markus W. Weissmann" Aq
Note: See TracBrowser for help on using the repository browser.