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
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_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
259.br
260.Sy Default:
261.Em no
262.br
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
269.Pa Makefile.in
270files for use by
271.Pa configure .
272.br
273.Sy Type:
274.Em optional
275.br
276.Sy Default:
277.Em no
278.br
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.
287.br
288.Sy Type:
289.Em optional
290.br
291.Sy Default:
292.Em no
293.br
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.
300.br
301.Sy Type:
302.Em optional
303.br
304.Sy Default:
305.Em yes
306.br
307.Sy Example:
308.Dl use_configure no
309.El
310.Sh TARGET HOOKS
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 ,
321and
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.
329.br
330.Sy Example:
331.Dl install.asroot yes
332.It Va target Ns Ic .dir
333Directory in which to run the
334.Va target .
335.br
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
342.Nm
343basis.
344.br
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.
349.br
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
356.Nm
357basis.
358.br
359.Sy Example:
360.Dl configure.args --enable-fooble
361.It Va target Ns Ic .post_args
362Additional arguments passed after the main arguments.
363.br
364.Sy Example:
365.Dl extract.post_args | tar xf -
366.El
367.Sh RUNTIME VARIABLES
368Read-only access to the MacPorts configuration is provided.
369.Bl -tag -width lc
370.It Ic prefix
371Install prefix
372.br
373.Sy Type:
374.Em optional
375.br
376.Sy Default:
377.Em /opt/local
378.It Ic libpath
379Location of ports-specific TCL libraries.
380.br
381.Sy Type:
382.Em read-only
383.It Ic portpath
384Full path to the Portfile location.
385.br
386.Sy Type:
387.Em read-only
388.br
389.Sy Default:
390.Em work
391.It Ic workpath
392Full path to work directory.
393.br
394.Sy Type:
395.Em read-only
396.br
397.Sy Default:
398.Em ${portbuildpath}/work
399.It Ic worksrcpath
400Full path to working sources (where port has unpacked itself).
401.br
402.Sy Type:
403.Em read-only
404.br
405.Sy Default:
406.Em ${workpath}/${worksrcdir}
407.It Ic filesdir
408Path to port files relative to
409.Ic portpath .
410.br
411.Sy Type:
412.Em read-only
413.br
414.Sy Default:
415.Em files
416.It Ic filespath
417Full path to the port files location.
418.br
419.Sy Type:
420.Em read-only
421.br
422.Sy Default:
423.Em ${portpath}/${filesdir}
424.It Ic distpath
425Location to store downloaded distfiles.
426.br
427.Sy Type:
428.Em read-only
429.br
430.Sy Default:
431.Em ${sysportpath}/distfiles/${dist_subdir}/
432.It Ic os.arch
433Identifies hardware type (eg "powerpc").
434.br
435.Sy Type:
436.Em read-only
437.It Ic os.version
438Version number of operating system (eg "7.0").
439.br
440.Sy Type:
441.Em read-only
442.It Ic os.endian
443Endianness of the processor (eg "bigEndian").
444.br
445.Sy Type:
446.Em read-only
447.It Ic os.platform
448Operating system name (eg "darwin").
449.br
450.Sy Type:
451.Em read-only
452.It Ic install.user
453User for MacPorts installation (eg
454.Pa root )
455.br
456.Sy Type:
457.Em read-only
458.It Ic install.group
459Group for MacPorts installation (eg
460.Pa wheel )
461.br
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).
467.br
468.Sy Type:
469.Em read-only
470.br
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).
476.br
477.Sy Type:
478.Em read-only
479.br
480.Sy Default:
481.Em ${prefix}/Library/Frameworks
482.It Ic x11prefix
483Absolute path to X11 (eg
484.Pa /usr/X11R6 )
485.br
486.Sy Type:
487.Em read-only
488.El
489.Sh DEPENDENCY OPTIONS
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
495.El
496.Pp
497Where
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
503format:
504.Bl -tag -width lc
505.It Ar type Ns : Ns Ao filename Ac Ns : Ns Ao port Ac
506.El
507.Pp
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.
514.br
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 ,
524and
525.Cm package
526targets.
527.br
528.Sy Type:
529.Em optional
530.br
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
537and
538.Cm package
539targets.
540.br
541.Sy Type:
542.Em optional
543.br
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 ,
552and
553.Cm package
554targets.
555.br
556.Sy Type:
557.Em optional
558.br
559.Sy Example:
560.Dl depends_lib port:libfetch
561.El
562.Sh FETCH OPTIONS
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
567master_sites.
568.br
569.Sy Type:
570.Em optional
571.br
572.Sy Default:
573.Em ${name}
574.br
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.
581.br
582.Sy Type:
583.Em optional
584.br
585.Sy Default:
586.Em ${master_sites}
587.br
588.Sy Example:
589.Dl patch_sites ftp://ftp.patchcityrepo.com/pub/magic/patches
590.It Ic patch_sites.mirror_subdir
591Subdirectory to append to all mirror sites for any list specified in
592.Ic patch_sites .
593.br
594.Sy Type:
595.Em optional
596.br
597.Sy Default:
598.Em ${name}
599.br
600.Sy Example:
601.Dl patch_sites.mirror_subdir       magic
602.It Ic extract.suffix
603Suffix to append to
604.Ic distname .
605.br
606.Sy Type:
607.Em optional
608.br
609.Sy Default:
610.Em .tar.gz
611.br
612.Sy Example:
613.Dl extract.suffix .tgz
614.It Ic distfiles
615List of distribution files to fetch from
616.Ic master_sites .
617.br
618.Sy Type:
619.Em optional
620.br
621.Sy Default:
622.Em [suffix ${distname}]
623.br
624.Sy Example:
625.Dl distfiles magicsource.tar.gz cluebat.tar.bz2
626.It Ic patchfiles
627List of patches to fetch and apply.
628.br
629.Sy Type:
630.Em optional
631.br
632.Sy Example:
633.Dl patchfiles japanese-widechar-fix.diff japanese-localization.diff
634.It Ic use_zip
635Use zip.
636.br
637Sets extract.suffix to: .zip
638.br
639Sets extract.cmd to: unzip
640.br
641Sets extract.pre_args to: -q
642.br
643Sets extract.post_args to: "-d ${workpath}"
644.br
645.Sy Type:
646.Em optional
647.br
648.Sy Example:
649.Dl use_zip yes
650.It Ic use_bzip2
651Use bzip2.
652.br
653Sets extract.suffix to: .bz2
654.br
655Sets extract.cmd to: bzip2
656.br
657.Sy Type:
658.Em optional
659.br
660.Sy Example:
661.Dl use_bzip2 yes
662.It Ic use_lzma
663Use lzma.
664.br
665Sets extract.suffix to: .lzma
666.br
667Sets extract.cmd to: lzma
668.br
669.Sy Type:
670.Em optional
671.br
672.Sy Example:
673.Dl use_lzma yes
674.It Ic use_7z
675Use 7z (7zip).
676.br
677Sets extract.suffix to: .7z
678.br
679Sets extract.cmd to: 7za
680.br
681.Sy Type:
682.Em optional
683.br
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.
690.br
691.Sy Type:
692.Em optional
693.br
694.Sy Default:
695.Em ${name}
696.br
697.Sy Example:
698.Dl dist_subdir vim${version}
699.El
700.Ss ADVANCED FETCH OPTIONS
701Some mirrors require special options for a resource to be properly
702fetched.
703.Bl -tag -width lc
704.It Ic fetch.user
705HTTP or FTP user to fetch the resource.
706.br
707.Sy Type:
708.Em optional
709.It Ic fetch.password
710HTTP or FTP password to fetch the resource.
711.br
712.Sy Type:
713.Em optional
714.It Ic fetch.use_epsv
715Whether to use EPSV command for FTP transfers.
716.br
717.Sy Type:
718.Em optional
719.br
720.Sy Default:
721.Em yes
722.br
723.It Ic fetch.ignore_sslcert
724Whether to ignore the host SSL certificate (for HTTPS).
725.br
726.Sy Type:
727.Em optional
728.br
729.Sy Default:
730.Em no
731.br
732.El
733.Ss FETCHING FROM CVS
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.
740.br
741.Sy Type:
742.Em optional
743.br
744.Sy Default:
745.Em none
746.br
747.Sy Example:
748.Dl cvs.root :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs
749.It Ic cvs.tag
750Specify a CVS tag identifying the code to checkout.
751.br
752.Sy Type:
753.Em optional
754.br
755.Sy Default
756.Em none
757.br
758.Sy Example:
759.Dl cvs.tag HEAD
760.It Ic cvs.date
761A date that identifies the CVS code set to checkout.
762.br
763.Sy Type:
764.Em optional
765.br
766.Sy Default
767.Em none
768.br
769.Sy Example:
770.Dl cvs.date \*q12-April-2005\*q
771.It Ic cvs.module
772A CVS module from which to check out the code.
773.br
774.Sy Type:
775.Em optional
776.br
777.Sy Default
778.Em none
779.br
780.Sy Example:
781.Dl cvs.module Sources
782.El
783.Ss FETCHING FROM SUBVERSION
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.
790.br
791.Sy Type:
792.Em required
793.br
794.Sy Default:
795.Em none
796.br
797.Sy Example:
798.Dl svn.url http://www.domain.com/svn-repo/mydirectory
799      svn.url svn://www.domain.com/svn-repo/mydirectory
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
805quotes.
806.br
807.Sy Type:
808.Em optional
809.br
810.Sy Default:
811.Em none
812.br
813.Sy Example:
814.Dl svn.tag 37192
815      svn.tag \\{\\"2006-02-17 15:30 +0230\\"\\}
816.El
817.Ss FETCHING FROM GIT
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
824.br
825.Sy Type:
826.Em required
827.br
828.Sy Default:
829.Em none
830.br
831.Sy Example:
832.Dl git.url git://git.kernel.org/pub/scm/git/git.git
833      git.url http://www.kernel.org/pub/scm/git/git.git
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/.
837.br
838.Sy Type:
839.Em optional
840.br
841.Sy Default:
842.Em none
843.br
844.Sy Example:
845.Dl git.branch 72bf1c8
846      git.branch origin/next
847.El
848.Sh EXTRACT OPTIONS
849Extract all compressed/archived files.
850.Bl -tag -width lc
851.It Ic extract.only
852List of files to extract into
853.Ic workpath .
854.br
855.Sy Type:
856.Em optional
857.br
858.Sy Default:
859.Em ${distfiles}
860.br
861.Sy Example:
862.Dl extract.only worksrc-1.4.4.tar.gz
863.It Ic extract.cmd
864Command to perform the extraction.
865.br
866.Sy Type:
867.Em optional
868.br
869.Sy Default:
870.Em gzip
871.br
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.
879.br
880.Sy Type:
881.Em optional
882.br
883.Sy Default:
884.Em no
885.br
886.Sy Example:
887.Dl extract.mkdir yes
888.El
889.Sh CONFIGURE OPTIONS
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.
894.br
895.Sy Type:
896.Em optional
897.br
898.Sy Default:
899.Em -O2
900.br
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.
905.br
906.Sy Type:
907.Em optional
908.br
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.
913.br
914.Sy Type:
915.Em optional
916.br
917.Sy Default:
918.Em -O2
919.It Ic configure.objcflags
920Flags to put in the OBJCFLAGS environment variable when invoking the configure script.
921.br
922.Sy Type:
923.Em optional
924.br
925.Sy Default:
926.Em -O2
927.It Ic configure.ldflags
928Flags to put in the LDFLAGS environment variable when invoking the configure script.
929.br
930.Sy Type:
931.Em optional
932.br
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.
937.br
938.Sy Type:
939.Em optional
940.br
941.Sy Default:
942.Em -O2
943.It Ic configure.f90flags
944Flags to put in the F90FLAGS environment variable when invoking the configure script.
945.br
946.Sy Type:
947.Em optional
948.br
949.Sy Default:
950.Em -O2
951.It Ic configure.fcflags
952Flags to put in the FCFLAGS environment variable when invoking the configure script.
953.br
954.Sy Type:
955.Em optional
956.br
957.Sy Default:
958.Em -O2
959.It Ic configure.classpath
960Flags to put in the CLASSPATH environment variable when invoking the configure script.
961.br
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.
966.br
967.Sy Type:
968.Em optional
969.br
970.Sy Example:
971.Dl configure.macosx_deployment_target 10.4
972.It Ic configure.cc
973C-compiler to put in the CC environment variable when invoking the configure script.
974.br
975.Sy Type:
976.Em optional
977.br
978.Sy Example:
979.Dl configure.cc /usr/bin/gcc
980.It Ic configure.cpp
981C-preprocessor to put in the CPP environment variable when invoking the configure script.
982.br
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.
987.br
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.
992.br
993.Sy Type:
994.Em optional
995.br
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.
1000.br
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.
1005.br
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.
1010.br
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.
1015.br
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.
1033.br
1034.Sy Type:
1035.Em optional
1036.br
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
1039.br
1040.Sy Example:
1041.Dl configure.compiler gcc-4.0
1042.\" FOOBAR
1043.El
1044.Ss UNIVERSAL TARGET HOOKS
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.
1049.br
1050.Sy Type:
1051.Em optional
1052.br
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.
1057.br
1058.Sy Type:
1059.Em optional
1060.br
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.
1065.br
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.
1070.br
1071.Sy Type:
1072.Em optional
1073.br
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.
1078.br
1079.Sy Type:
1080.Em optional
1081.br
1082.Sy Default:
1083.Em -arch i386 -arch ppc
1084.El
1085.Sh BUILD OPTIONS
1086Execute necessary build commands.
1087.Bl -tag -width lc
1088.It Ic build.cmd
1089Make command to run relative to
1090.Ic worksrcdir .
1091.br
1092.Sy Type:
1093.Em optional
1094.br
1095.Sy Default:
1096.Em make
1097.br
1098.Sy Example:
1099.Dl build.cmd pbxbuild
1100.It Ic build.type
1101Defines which 'make' is required, either 'gnu' or 'bsd'.
1102Sets
1103.Ic build.cmd
1104to either
1105.Pa gnumake
1106or
1107.Pa bsdmake
1108accordingly.
1109.br
1110.Sy Type:
1111.Em optional
1112.br
1113.Sy Default:
1114.Em gnu
1115.br
1116.Sy Example:
1117.Dl build.type bsd
1118.It Ic build.target
1119Target passed to
1120.Ic build.cmd .
1121.br
1122.Sy Type:
1123.Em optional
1124.br
1125.Sy Default:
1126.Em all
1127.br
1128.Sy Example:
1129.Dl build.target all-src
1130.El
1131.Sh DESTROOT OPTIONS
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 .
1138.br
1139.Sy Type:
1140.Em optional
1141.br
1142.Sy Default:
1143.Em ${build.cmd}
1144.br
1145.Sy Example:
1146.Dl destroot.cmd pbxbuild
1147.It Ic destroot.type
1148Defines which 'make' is required, either 'gnu' or 'bsd'.
1149Sets
1150.Ic destroot.cmd
1151to either
1152.Pa gnumake
1153or
1154.Pa bsdmake
1155accordingly.
1156.br
1157.Sy Type:
1158.Em optional
1159.br
1160.Sy Default:
1161.Em ${build.type}
1162.br
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.
1170.br
1171.Sy Type:
1172.Em optional
1173.br
1174.Sy Default:
1175.Em DESTDIR=${destroot}
1176.br
1177.Sy Example:
1178.Dl destroot.destdir prefix=${destroot}${prefix}
1179.It Ic destroot.target
1180Install target to pass to
1181.Ic destroot.cmd .
1182.br
1183.Sy Type:
1184.Em optional
1185.br
1186.Sy Default:
1187.Em install
1188.br
1189.Sy Example:
1190.Dl destroot.target install-src
1191.It Ic destroot.umask
1192Umask to use during destroot.
1193.br
1194.Sy Type:
1195.Em optional
1196.br
1197.Sy Default:
1198.Em 022
1199.br
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
1205completion.
1206.br
1207.Sy Type:
1208.Em optional
1209.br
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 .
1215.br
1216.Sy Type:
1217.Em optional
1218.br
1219.Sy Values:
1220.Em yes no
1221.br
1222.Sy Default:
1223.Em no
1224.El
1225.Sh TEST OPTIONS
1226Execute commands to run test suites bundled with a port.
1227.Bl -tag -width lc
1228.It Ic test.run
1229Enable running test suites bundled with a port.
1230.br
1231.Sy Type:
1232.Em optional
1233.br
1234.Sy Example:
1235.Dl test.run     yes
1236.It Ic test.cmd
1237Test command to run relative to
1238.Ic worksrcdir .
1239.br
1240.Sy Type:
1241.Em optional
1242.br
1243.Sy Default:
1244.Em ${build.cmd}
1245.br
1246.Sy Example:
1247.Dl test.cmd checks.sh
1248.It Ic test.target
1249Test target to pass to
1250.Ic test.cmd .
1251.br
1252.Sy Type:
1253.Em optional
1254.br
1255.Sy Default:
1256.Em test
1257.br
1258.Sy Example:
1259.Dl test.target checks
1260.El
1261.Sh STARTUPITEM OPTIONS
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.
1269.br
1270.Sy Type:
1271.Em optional
1272.br
1273.Sy Default:
1274.Em no
1275.br
1276.Sy Values:
1277.Em yes no
1278.br
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.
1286.br
1287.Sy Type:
1288.Em optional
1289.br
1290.Sy Default:
1291.Em default
1292.br
1293.Sy Values:
1294.Em SystemStarter launchd default rcNG
1295.br
1296.Sy Example
1297.Dl startupitem.type launchd
1298.It Ic startupitem.name
1299Displayed name of the startup item.
1300.br
1301.Sy Type:
1302.Em required
1303.br
1304.Sy Example:
1305.Dl startupitem.name 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.
1314.br
1315.Sy Type:
1316.Em optional
1317.br
1318.Sy Values:
1319.Em /path/to/executable <args>
1320.br
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.
1326.br
1327.Sy Type:
1328.Em optional
1329.br
1330.Sy Values:
1331.Em sh code
1332.br
1333.Sy Example:
1334.Dl startupitem.init FOO=start
1335.It Ic startupitem.start
1336Shell code executed to start the daemon.
1337.br
1338.Sy Type:
1339.Em optional
1340.br
1341.Sy Values:
1342.Em sh code
1343.br
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.
1348.br
1349.Sy Type:
1350.Em optional
1351.br
1352.Sy Values:
1353.Em sh code
1354.br
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.
1361.br
1362.Sy Type:
1363.Em optional
1364.br
1365.Sy Values:
1366.Em sh code
1367.br
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).
1379.br
1380.Sy Type:
1381.Em optional
1382.br
1383.Sy Default:
1384.Em none "${prefix}/var/run/${name}.pid"
1385.br
1386.Sy Values:
1387.Em none|auto|manual|clean [/path/to/pidfile]
1388.br
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.
1396.br
1397.Sy Type:
1398.Em optional
1399.br
1400.Sy Default:
1401.Em /dev/null
1402.br
1403.Sy Values:
1404.Em path
1405.br
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.
1411.br
1412.Sy Type:
1413.Em optional
1414.br
1415.Sy Default:
1416.Em no
1417.br
1418.Sy Values:
1419.Em yes|no
1420.br
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.
1426.br
1427.Sy Type:
1428.Em optional
1429.br
1430.Sy Default:
1431.Em no
1432.br
1433.Sy Values:
1434.Em yes|no
1435.br
1436.Sy Example:
1437.Dl startupitem.netchange yes
1438.El
1439.Sh DISTCHECK AND LIVECHECK OPTIONS
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.
1444.br
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).
1458.br
1459.Sy Type:
1460.Em optional
1461.br
1462.Sy Default:
1463.Em moddate
1464.br
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).
1486.br
1487.Sy Type:
1488.Em optional
1489.br
1490.Sy Default:
1491.Em sourceforge
1492or
1493.Em googlecode
1494if the master_sites is one of these, else
1495.Em freshmeat
1496.br
1497.Sy Values:
1498.Em freshmeat sourceforge googlecode moddate regex regexm md5 none
1499.It Ic livecheck.name
1500Name of the project for live checks (used for freshmeat, sourceforge, and googlecode checks).
1501.br
1502.Sy Type:
1503.Em optional
1504.br
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 "(.*)".
1513.br
1514.Sy Type:
1515.Em optional
1516.br
1517.Sy Default:
1518.Em ${livecheck.name}
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).
1524.br
1525.Sy Type:
1526.Em optional
1527.br
1528.Sy Default:
1529.Em ${version}
1530.It Ic livecheck.url
1531URL to query for the check.
1532.br
1533.Sy Type:
1534.Em optional
1535.br
1536.Sy Default:
1537.Em ${homepage}
1538or
1539.Em http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml
1540or
1541.Em http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}
1542or
1543.Em http://code.google.com/p/${livecheck.name}/downloads/list
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.
1547.br
1548.Sy Type:
1549.Em optional
1550.It Ic livecheck.md5
1551md5 sum to use for md5 comparison.
1552.br
1553.Sy Type:
1554.Em optional
1555.El
1556.Sh VARIANT OPTIONS
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"
1566.Xc
1567The value is usually a TCL script which modifies other port's
1568.Nm
1569variables. Dependencies and conflicts with other variants in the same
1570port can be expressed with
1571.Cm requires
1572and
1573.Cm conflicts .
1574.Cm description
1575provides a means to supply a description of the variant for the user.
1576.br
1577.Sy Type:
1578.Em optional
1579.br
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\
1584
1585    depends_lib-append lib:gnome-session:gnome-session }
1586.Ed
1587.It Ic default_variants
1588If variants are defined, then the
1589.Ic default_variants
1590value lists which variants are enabled by default.
1591.br
1592.Sy Type:
1593.Em optional
1594.br
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
1601.Ic UNIVERSAL TARGET HOOKS
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
1607option.
1608.br
1609.Sy Type:
1610.Em optional
1611.br
1612.Sy Default:
1613.Em yes
1614.br
1615.Sy Example:
1616.Dl universal_variant no
1617.El
1618.Sh PLATFORM OPTIONS
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
1630.Xc
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
1634respectively.
1635.br
1636.Sy Type:
1637.Em optional
1638.br
1639.Sy Example:
1640.Bd -literal -offset indent -compact
1641platform darwin 6 { configure.args-append   --enable-tcl \e\
1642
1643        --with-tcl=/System/Library/Tcl/8.3 }
1644.Ed
1645.br
1646.Sy Example:
1647.Bd -literal -offset indent -compact
1648platform darwin powerpc { configure.args-append \e\
1649
1650        --host=${os.arch}-apple-rhapsody${os.version} }
1651platform darwin i386 { configure.args-append \e\
1652
1653        --host=i386-gnu-rhapsody${os.version} }
1654.Ed
1655.El
1656.Sh PORTGROUP
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.
1662.Sh TCL EXTENSIONS
1663A number of TCL extensions are available for use in
1664.Nm Portfiles .
1665.Pp
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
1685.Xc
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
1702.Xc
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
1710extension.
1711.It Fl B
1712Specify a different backup suffix for the
1713.Fl b
1714flag.
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.
1745.El
1746.El
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
1754.Xc
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
1779Causes
1780.Ic fs-traverse
1781to ignore any permissions/read errors encountered during processing.
1782.El
1783.Pp
1784If
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.
1788.Pp
1789.Nm fs-traverse
1790will not descend into directories that have a different device number than
1791the root of the descent.
1792.Pp
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
1802.Xc
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
1811.Xc
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
1826.Xc
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
1840.Xc
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
1854.Ar
1855.Xc
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
1861.br
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
1884.br
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
1908Append
1909.Ar item
1910to the
1911.Va variable .
1912.br
1913.Sy Example:
1914.Dl configure.args-append --with-gnomedb
1915.It Va variable Ns - Ns Ic delete Ar item
1916Delete
1917.Ar item
1918from the
1919.Va variable .
1920.br
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 ,
1926excluding
1927.Pa \&.
1928and
1929.Pa \&.. .
1930.It Ic strsed Ar string Ar pattern
1931Perform
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 .
1938See
1939.Xr mktemp 3 .
1940.It Ic mkstemp Ar template
1941Create a temporary file securely using a
1942.Ar template .
1943See
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 \&...
1950Execute
1951.Ar command
1952using
1953.Cm sudo
1954with the provided password.
1955.It Xo
1956.Ic lpush
1957.Ar varName
1958.Op Ar value \&...
1959.Xc
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
1969arguments.
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 \&...
1983.Xc
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
1993arguments.
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 \&...
2005.Xc
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
2020.Oo
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 \&...
2028.Oc
2029.Op Nm finally Ar body
2030.Xc
2031Implements a try-catch-finally block as defined in TIP #89.
2032.br
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
2041}
2042.Ed
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
2050}
2051.Ed
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
2064}
2065.Ed
2066.It Xo
2067.Ic throw
2068.Op Ar type
2069.Op Ar message
2070.Op Ar info
2071.Xc
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.
2080.El
2081.Pp
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.
2091.br
2092.Sy Example:
2093.Dl ui_msg \*qAdd each user to the system using the clamav command\*q
2094.El
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
2102.Sh AUTHORS
2103.An "Landon Fuller" Aq landonf@macports.org
2104.An "Juan Manuel Palacios" Aq jmpp@macports.org
2105.An "Mark Duling" Aq markd@macports.org
2106.An "Kevin Van Vechten" Aq kevin@opendarwin.org
2107.An "Jordan K. Hubbard" Aq jkh@macports.org
2108.An "Chris Ridd" Aq cjr@opendarwin.org
2109.An "Kevin Ballard" Aq eridius@macports.org
2110.An "Markus W. Weissmann" Aq mww@macports.org
Note: See TracBrowser for help on using the repository browser.