source: branches/gsoc11-statistics/base/doc/portfile.7 @ 79661

Last change on this file since 79661 was 78662, checked in by jmr@…, 9 years ago

document add_users in portfile(7)

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 49.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 notes
133Notes for setup and use of the port.  This is shown after the port is
134activated and anytime the
135.Ic notes
136command is used; for example:
137.Pp
138.Dl "port notes python26"
139.Pp
140The advantage to using
141.Ic notes
142instead of
143.Ic ui_msg
144is that it can be queried after a port is installed but
145.Ic ui_msg
146is only printed during an install.  Therefore
147.Ic notes
148is good for any information which may be needed anytime after an install.
149.br
150.Sy Type:
151.Em optional
152.br
153.Sy Example:
154.Bd -literal -offset indent -compact
155notes To fully complete your installation and make python \e\
156
157   ${branch} the default, please run: \e\
158
159   sudo port install python_select \e\
160
161   sudo python_select ${name}
162.Ed
163.It Ic revision
164Local revision number of
165.Nm .
166Increment for port revisions which would change its installation in any way.
167.br
168.Sy Type:
169.Em optional
170.br
171.Sy Default:
172.Em 0
173.br
174.Sy Example:
175.Dl revision 1
176.It Ic categories
177Categories to which this port belongs.
178.br
179.Sy Type:
180.Em required
181.br
182.Sy Example:
183.Dl categories spelling textproc
184.It Ic maintainers
185E-mail address(es) of port maintainer(s).
186.br
187.Sy Type:
188.Em required
189.br
190.Sy Example:
191.Dl maintainers landonf@macports.org
192.It Ic platforms
193Declares which platforms are supported by the port.
194.br
195.Sy Type:
196.Em required
197.br
198.Sy Values:
199.Em darwin freebsd
200.br
201.Sy Example:
202.Dl platforms darwin
203.It Ic homepage
204Project homepage for the port.
205.br
206.Sy Type:
207.Em required
208.br
209.Sy Example:
210.Dl http://wireshark.org
211.It Ic master_sites
212List of sites to fetch
213.Ic distfiles
214from or a predefined mirror site
215list. If set to a predefined mirror site, without a subdirectory being
216defined, the portname is used as the name of the subdirectory.
217.br
218.Sy Type:
219.Em required
220.br
221.Sy Example:
222.Bd -literal -offset indent -compact
223master_sites ftp://ftp.cdrom.com/pub/magic \e\
224
225    sourceforge
226.Ed
227.It Ic worksrcdir
228Path to source directory relative to
229.Ic workpath .
230.br
231.Sy Type:
232.Em optional
233.br
234.Sy Default:
235.Em ${distname}
236.br
237.Sy Example:
238.Dl worksrcdir ${distname}-src-${version}
239.It Ic distname
240Name of distribution file, without the
241.Cm extract.suffix .
242.br
243.Sy Type:
244.Em optional
245.br
246.Sy Default:
247.Em ${name}-${version}
248.br
249.Sy Example:
250.Dl distname ${name}-${version}-src
251.It Xo
252.Ic checksums Ar filename Ar type Ar checksum
253.Op Ar filename Ar type checksum ...
254.Xc
255List of checksums for the
256.Ic distfiles .
257The checksum
258.Ar type
259can currently be md5, rmd160 or sha1. The
260.Ar filename
261can be omitted if there is only one distfile.
262.br
263.Sy Type:
264.Em required
265.br
266.Sy Example:
267.Bd -literal -offset indent -compact
268checksums dictd-1.7.1.tar.gz md5 81317b86ea0a5df0163900ad2e6bb12c \e\
269        magic-words-1.7.1.tar.gz md5 897a005182928613eadd30c267ce9c5b
270.Ed
271.br
272.Sy Example (ledit 1.11):
273.Bd -literal -offset indent -compact
274checksums md5 a2d38ba641682509c1e964ad699a9dd2 \e\
275        sha1 1fb6443b5fdf3c83787953f06282d256477c1288
276.Ed
277.br
278.Sy Example (ssldump 0.9b3):
279.Bd -literal -offset indent -compact
280checksums md5 ac8c28fe87508d6bfb06344ec496b1dd \e\
281        sha1 a633a9a811a138eac5ed440d583473b644135ef5 \e\
282        rmd160 941cf8f2ef8459ec4f9ce65772e134505d46566
283.Ed
284.It Ic macosx_deployment_target
285Value for MACOSX_DEPLOYMENT_TARGET environment variable when invoking the configure script.
286.br
287.Sy Type:
288.Em optional
289.br
290.Sy Default:
291.Em (current OS version)
292.br
293.Sy Example:
294.Dl macosx_deployment_target 10.4
295.It Ic use_parallel_build
296If set to yes (and the user has enabled buildmakejobs in
297.Pa macports.conf
298), the port can be built using more than one job.
299.Sy Type:
300.Em optional
301.br
302.Sy Default:
303.Em no
304.br
305.Sy Example:
306.Dl use_parallel_build yes
307.It Ic use_automake
308If set to yes, run the
309.Cm automake
310target to build any
311.Pa Makefile.in
312files for use by
313.Pa configure .
314.br
315.Sy Type:
316.Em optional
317.br
318.Sy Default:
319.Em no
320.br
321.Sy Example:
322.Dl use_automake yes
323.It Ic use_autoconf
324If set to yes, run the
325.Cm autoconf
326target to build any
327.Pa configure
328script required.
329.br
330.Sy Type:
331.Em optional
332.br
333.Sy Default:
334.Em no
335.br
336.Sy Example:
337.Dl use_autoconf yes
338.It Ic use_configure
339If set to yes, run the
340.Cm configure
341target to configure the build.
342.br
343.Sy Type:
344.Em optional
345.br
346.Sy Default:
347.Em yes
348.br
349.Sy Example:
350.Dl use_configure no
351.It Ic copy_log_files Ar path/to/logfile1 Ar path/to/logfile2 Ar ...
352Copy specific log files from the workdir to the main macports log dir
353.br
354.Sy Type:
355.Em optional
356.br
357.Sy Example:
358.Dl copy_log_files config.log
359.It Ic conflicts
360Used to list ports which conflict with the one containing the
361.Cm conflicts
362declaration.
363.br
364.Sy Type:
365.Em optional
366.br
367.Sy Default:
368.Em none (empty)
369.br
370.Sy Example:
371.Dl conflicts cdrtools
372.It Ic replaced_by
373When a particular port is deprecated in favor of another, use
374.Cm replaced_by
375in the deprecated port and list the new one to be used.
376.br
377.Sy Type:
378.Em optional
379.br
380.Sy Default:
381.Em none (empty)
382.br
383.Sy Example:
384.Dl replaced_by xorg-renderproto
385.It Ic add_users
386Consists of a list of usernames and settings. At appropriate times during the
387port installation process, a user will be created for each username with the
388corresponding settings. Settings are of the form name=value. A setting
389applies to the username that appeared most recently before it in the list.
390.sp
391Applicable options are: group, gid (may be used instead of group), passwd,
392realname, home, and shell.
393.sp
394.Sy Type:
395.Em optional
396.br
397.Sy Default:
398.Em none (empty)
399.br
400.Sy Example:
401.Dl add_users squid group=squid realname=Squid\e Proxy home=${prefix}/var/squid
402.sp
403.Dl add_users user1 group=mygroup user2 group=mygroup
404.El
405.Sh TARGET HOOKS
406A number of hooks are available for customizing many of the standard
407targets that
408.Xr port 1
409executes. The targets supporting these hooks are
410.Cm fetch ,
411.Cm automake ,
412.Cm autoconf ,
413.Cm configure ,
414.Cm build ,
415.Cm destroot ,
416and
417.Cm test .
418The hooks are:
419.Bl -tag -width lc
420.It Va target Ns Ic .asroot
421Run the
422.Va target
423with root privileges.
424.br
425.Sy Example:
426.Dl install.asroot yes
427.It Va target Ns Ic .dir
428Directory in which to run the
429.Va target .
430.br
431.Sy Example:
432.Dl automake.dir src
433.It Va target Ns Ic .env
434Change the environment the
435.Va target
436is run in. This is often overridden on a per
437.Nm
438basis.
439.br
440.Sy Example:
441.Dl configure.env CPP=/usr/bin/cpp-4.0
442.It Va target Ns Ic .pre_args
443Additional arguments passed before the main arguments.
444.br
445.Sy Example:
446.Dl extract.pre_args -cd
447.It Va target Ns Ic .args
448Main arguments to pass to the
449.Va target .
450This is often overridden on a per
451.Nm
452basis.
453.br
454.Sy Example:
455.Dl configure.args --enable-fooble
456.It Va target Ns Ic .post_args
457Additional arguments passed after the main arguments.
458.br
459.Sy Example:
460.Dl extract.post_args | tar xf -
461.El
462.Sh RUNTIME VARIABLES
463Read-only access to the MacPorts configuration is provided.
464.Bl -tag -width lc
465.It Ic prefix
466Install prefix
467.br
468.Sy Type:
469.Em optional
470.br
471.Sy Default:
472.Em /opt/local
473.It Ic libpath
474Location of ports-specific TCL libraries.
475.br
476.Sy Type:
477.Em read-only
478.It Ic portpath
479Full path to the Portfile location.
480.br
481.Sy Type:
482.Em read-only
483.br
484.Sy Default:
485.Em work
486.It Ic workpath
487Full path to work directory.
488.br
489.Sy Type:
490.Em read-only
491.br
492.Sy Default:
493.Em ${portbuildpath}/work
494.It Ic worksrcpath
495Full path to working sources (where port has unpacked itself).
496.br
497.Sy Type:
498.Em read-only
499.br
500.Sy Default:
501.Em ${workpath}/${worksrcdir}
502.It Ic filesdir
503Path to port files relative to
504.Ic portpath .
505.br
506.Sy Type:
507.Em read-only
508.br
509.Sy Default:
510.Em files
511.It Ic filespath
512Full path to the port files location.
513.br
514.Sy Type:
515.Em read-only
516.br
517.Sy Default:
518.Em ${portpath}/${filesdir}
519.It Ic distpath
520Location to store downloaded distfiles.
521.br
522.Sy Type:
523.Em read-only
524.br
525.Sy Default:
526.Em ${sysportpath}/distfiles/${dist_subdir}/
527.It Ic os.arch
528Identifies hardware type (e.g. "powerpc").
529.br
530.Sy Type:
531.Em read-only
532.It Ic os.version
533Version number of operating system (e.g. "7.0").
534.br
535.Sy Type:
536.Em read-only
537.It Ic os.major
538Major version number of operating system (e.g. "7").
539.br
540.Sy Type:
541.Em read-only
542.It Ic os.endian
543Endianness of the processor (e.g. "big").
544.br
545.Sy Type:
546.Em read-only
547.It Ic os.platform
548Operating system name (e.g. "darwin").
549.br
550.Sy Type:
551.Em read-only
552.It Ic os.subplatform
553Name of specific operating system variant (e.g. "macosx").
554.br
555.Sy Type:
556.Em read-only
557.It Ic install.user
558User for MacPorts installation (e.g.
559.Pa root )
560.br
561.Sy Type:
562.Em read-only
563.It Ic install.group
564Group for MacPorts installation (e.g.
565.Pa wheel )
566.br
567.Sy Type:
568.Em read-only
569.It Ic applications_dir
570Absolute path to the final location to install Mac OS X application
571bundles (.app directories).
572.br
573.Sy Type:
574.Em read-only
575.br
576.Sy Default:
577.Em /Applications/Macports
578.It Ic frameworks_dir
579Absolute path to the final location to install Mac OS X framework
580bundles (.framework directories).
581.br
582.Sy Type:
583.Em read-only
584.br
585.Sy Default:
586.Em ${prefix}/Library/Frameworks
587.El
588.Sh DEPENDENCY OPTIONS
589Port dependencies should refer to other MacPort ports
590whenever possible, therefore each dependency should be
591expressed in the format:
592.Bl -tag -width ls
593.It port: Ns Ao port Ac
594.El
595.Pp
596Where
597.Ao port Ac represents the name of an existing MacPorts
598.Nm port .
599If satisfying a dependency with a MacPorts port is not
600practical and it is likely that a dependency must be met
601by an Apple optional install, then the alternative dependency
602format:
603.Bl -tag -width lc
604.It Ar type Ns : Ns Ao filename Ac Ns : Ns Ao port Ac
605.El
606.Pp
607may be used. Where
608.Ar type
609is "bin" if
610.Ao filename Ac
611is a program, "lib" if it is a library, or "path" if it is a path to an
612installed file.
613.br
614.Sy Example:
615.Dl lib:libX11.6:XFree86
616.Bl -tag -width lc
617.It Ic depends_fetch
618List of dependencies to check before
619.Cm fetch ,
620.Cm checksum ,
621.Cm extract ,
622.Cm patch ,
623.Cm configure ,
624.Cm build ,
625.Cm destroot ,
626.Cm install ,
627and
628.Cm package
629targets.
630.br
631.Sy Type:
632.Em optional
633.br
634.Sy Example:
635.Dl depends_fetch port:mercurial
636.It Ic depends_extract
637List of dependencies to check before
638.Cm extract ,
639.Cm patch ,
640.Cm configure ,
641.Cm build ,
642.Cm destroot ,
643.Cm install ,
644and
645.Cm package
646targets.
647.br
648.Sy Type:
649.Em optional
650.br
651.Sy Example:
652.Dl depends_extract port:xz-devel
653.It Ic depends_build
654List of dependencies to check before
655.Cm configure ,
656.Cm build ,
657.Cm destroot ,
658.Cm install ,
659and
660.Cm package
661targets.
662.br
663.Sy Type:
664.Em optional
665.br
666.Sy Example:
667.Dl depends_build port:autoconf
668.It Ic depends_run
669List of dependencies to check before
670.Cm destroot ,
671.Cm install
672and
673.Cm package
674targets. Will be recorded in the registry as being required by the dependent
675port when it is installed.
676.br
677.Sy Type:
678.Em optional
679.br
680.Sy Example:
681.Dl depends_run port:bash
682.It Ic depends_lib
683List of dependencies to check before
684.Cm configure ,
685.Cm build ,
686.Cm destroot ,
687.Cm install ,
688and
689.Cm package
690targets. Will be recorded in the registry as being required by the dependent
691port when it is installed.
692.br
693.Sy Type:
694.Em optional
695.br
696.Sy Example:
697.Dl depends_lib port:libfetch
698.El
699.Sh FETCH OPTIONS
700Fetch all distribution files and patches.
701.Bl -tag -width lc
702.It Ic master_sites.mirror_subdir
703Subdirectory to append to all mirror sites for any list specified in
704master_sites.
705.br
706.Sy Type:
707.Em optional
708.br
709.Sy Default:
710.Em ${name}
711.br
712.Sy Example:
713.Dl master_sites.mirror_subdir      magic
714.It Ic patch_sites
715List of sites to fetch
716.Ic patchfiles
717from or a predefined mirror site list.
718.br
719.Sy Type:
720.Em optional
721.br
722.Sy Default:
723.Em ${master_sites}
724.br
725.Sy Example:
726.Dl patch_sites ftp://ftp.patchcityrepo.com/pub/magic/patches
727.It Ic patch_sites.mirror_subdir
728Subdirectory to append to all mirror sites for any list specified in
729.Ic patch_sites .
730.br
731.Sy Type:
732.Em optional
733.br
734.Sy Default:
735.Em ${name}
736.br
737.Sy Example:
738.Dl patch_sites.mirror_subdir       magic
739.It Ic extract.suffix
740Suffix to append to
741.Ic distname .
742.br
743.Sy Type:
744.Em optional
745.br
746.Sy Default:
747.Em .tar.gz
748.br
749.Sy Example:
750.Dl extract.suffix .tgz
751.It Ic distfiles
752List of distribution files to fetch from
753.Ic master_sites .
754.br
755.Sy Type:
756.Em optional
757.br
758.Sy Default:
759.Em [suffix ${distname}]
760.br
761.Sy Example:
762.Dl distfiles magicsource.tar.gz cluebat.tar.bz2
763.It Ic patchfiles
764List of patches to fetch and apply.
765.br
766.Sy Type:
767.Em optional
768.br
769.Sy Example:
770.Dl patchfiles japanese-widechar-fix.diff japanese-localization.diff
771.It Ic use_zip
772Use zip.
773.br
774Sets extract.suffix to: .zip
775.br
776Sets extract.cmd to: unzip
777.br
778Sets extract.pre_args to: -q
779.br
780Sets extract.post_args to: "-d ${workpath}"
781.br
782.Sy Type:
783.Em optional
784.br
785.Sy Example:
786.Dl use_zip yes
787.It Ic use_bzip2
788Use bzip2.
789.br
790Sets extract.suffix to: .bz2
791.br
792Sets extract.cmd to: bzip2
793.br
794.Sy Type:
795.Em optional
796.br
797.Sy Example:
798.Dl use_bzip2 yes
799.It Ic use_lzma
800Use lzma.
801.br
802Sets extract.suffix to: .lzma
803.br
804Sets extract.cmd to: lzma
805.br
806.Sy Type:
807.Em optional
808.br
809.Sy Example:
810.Dl use_lzma yes
811.It Ic use_xz
812Use xz.
813.br
814Sets extract.suffix to: .xz
815.br
816Sets extract.cmd to: xz
817.br
818.Sy Type:
819.Em optional
820.br
821.Sy Example:
822.Dl use_xz yes
823.It Ic use_7z
824Use 7z (7zip).
825.br
826Sets extract.suffix to: .7z
827.br
828Sets extract.cmd to: 7za
829.br
830.Sy Type:
831.Em optional
832.br
833.Sy Example:
834.Dl use_7z yes
835.It Ic dist_subdir
836Create a sub-directory in
837.Ic distpath
838to store all fetched files.
839.br
840.Sy Type:
841.Em optional
842.br
843.Sy Default:
844.Em ${name}
845.br
846.Sy Example:
847.Dl dist_subdir vim${version}
848.El
849.Ss ADVANCED FETCH OPTIONS
850Some mirrors require special options for a resource to be properly
851fetched.
852.Bl -tag -width lc
853.It Ic fetch.user
854HTTP or FTP user to fetch the resource.
855.br
856.Sy Type:
857.Em optional
858.It Ic fetch.password
859HTTP or FTP password to fetch the resource.
860.br
861.Sy Type:
862.Em optional
863.It Ic fetch.use_epsv
864Whether to use EPSV command for FTP transfers.
865.br
866.Sy Type:
867.Em optional
868.br
869.Sy Default:
870.Em yes
871.br
872.It Ic fetch.ignore_sslcert
873Whether to ignore the host SSL certificate (for HTTPS).
874.br
875.Sy Type:
876.Em optional
877.br
878.Sy Default:
879.Em no
880.br
881.El
882.Ss FETCHING FROM CVS
883As an alternative to fetching distribution files, pulling the sources
884from a CVS repository is supported. Use of CVS can give rise to
885non-reproducible builds, so it is strongly discouraged.
886.Bl -tag -width lc
887.It Ic cvs.root
888Specify the address to a CVS repository from which to checkout files.
889.br
890.Sy Type:
891.Em optional
892.br
893.Sy Default:
894.Em none
895.br
896.Sy Example:
897.Dl cvs.root :pserver:anonymous@cvs.sv.gnu.org:/sources/emacs
898.It Ic cvs.tag
899Specify a CVS tag identifying the code to checkout.
900.br
901.Sy Type:
902.Em optional
903.br
904.Sy Default
905.Em none
906.br
907.Sy Example:
908.Dl cvs.tag HEAD
909.It Ic cvs.date
910A date that identifies the CVS code set to checkout.
911.br
912.Sy Type:
913.Em optional
914.br
915.Sy Default
916.Em none
917.br
918.Sy Example:
919.Dl cvs.date \*q12-April-2005\*q
920.It Ic cvs.module
921A CVS module from which to check out the code.
922.br
923.Sy Type:
924.Em optional
925.br
926.Sy Default
927.Em none
928.br
929.Sy Example:
930.Dl cvs.module Sources
931.El
932.Ss FETCHING FROM SUBVERSION
933As an alternative to fetching distribution files, pulling the sources
934from a subversion repository is supported. Use of subversion can give
935rise to non-reproducible builds, so it is strongly discouraged.
936.Bl -tag -width lc
937.It Ic svn.url
938Specify the url from which to fetch files.
939.br
940.Sy Type:
941.Em required
942.br
943.Sy Default:
944.Em none
945.br
946.Sy Example:
947.Dl svn.url http://www.domain.com/svn-repo/mydirectory
948      svn.url svn://www.domain.com/svn-repo/mydirectory
949.It Ic svn.tag
950Specify a tag from which svn should fetch files. This
951corresponds to the -r option to the svn cli.  Note that you
952will need to use backslashes to escape characters that have
953meaning to the Tcl interpreter, such as braces and double
954quotes.
955.br
956.Sy Type:
957.Em optional
958.br
959.Sy Default:
960.Em none
961.br
962.Sy Example:
963.Dl svn.tag 37192
964      svn.tag \\{\\"2006-02-17 15:30 +0230\\"\\}
965.El
966.Ss FETCHING FROM GIT
967As an alternative to fetching distribution files, pulling the sources
968from a git repository is supported. Use of git can give rise to
969non-reproducible builds, so it is strongly discouraged.
970.Bl -tag -width lc
971.It Ic git.url
972Specify the url from which to fetch files
973.br
974.Sy Type:
975.Em required
976.br
977.Sy Default:
978.Em none
979.br
980.Sy Example:
981.Dl git.url git://git.kernel.org/pub/scm/git/git.git
982      git.url http://www.kernel.org/pub/scm/git/git.git
983.It Ic git.branch
984Specify a branch (or other commit-ish) that git should checkout.
985Note that any branch besides HEAD should be prefixed by origin/.
986.br
987.Sy Type:
988.Em optional
989.br
990.Sy Default:
991.Em none
992.br
993.Sy Example:
994.Dl git.branch 72bf1c8
995      git.branch origin/next
996.El
997.Sh EXTRACT OPTIONS
998Extract all compressed/archived files.
999.Bl -tag -width lc
1000.It Ic extract.only
1001List of files to extract into
1002.Ic workpath .
1003.br
1004.Sy Type:
1005.Em optional
1006.br
1007.Sy Default:
1008.Em ${distfiles}
1009.br
1010.Sy Example:
1011.Dl extract.only worksrc-1.4.4.tar.gz
1012.It Ic extract.cmd
1013Command to perform the extraction.
1014.br
1015.Sy Type:
1016.Em optional
1017.br
1018.Sy Default:
1019.Em gzip
1020.br
1021.Sy Example:
1022.Dl extract.cmd bzip2
1023.It Ic extract.mkdir
1024Create the
1025.Ic worksrcdir
1026prior to extraction; useful for ports which extract directly into the current
1027working directory instead of a subdirectory.
1028.br
1029.Sy Type:
1030.Em optional
1031.br
1032.Sy Default:
1033.Em no
1034.br
1035.Sy Example:
1036.Dl extract.mkdir yes
1037.El
1038.Sh CONFIGURE OPTIONS
1039MacPorts 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:
1040.Bl -tag -width lc
1041.It Ic configure.optflags
1042Flags to use for optimization.
1043.br
1044.Sy Type:
1045.Em optional
1046.br
1047.Sy Default:
1048.Em -O2
1049.br
1050.Sy Example:
1051.Dl configure.optflags -O3
1052.It Ic configure.cflags
1053Flags to put in the CFLAGS environment variable when invoking the configure script.
1054.br
1055.Sy Type:
1056.Em optional
1057.br
1058.Sy Default:
1059.Em ${configure.optflags}
1060.br
1061.Sy Example:
1062.Dl configure.cflags-append -DHAS_LRINTF
1063.It Ic configure.cppflags
1064Flags to put in the CPPFLAGS environment variable when invoking the configure script.
1065.br
1066.Sy Type:
1067.Em optional
1068.br
1069.Sy Default:
1070.Em -I${prefix}/include
1071.It Ic configure.cxxflags
1072Flags to put in the CXXFLAGS environment variable when invoking the configure script.
1073.br
1074.Sy Type:
1075.Em optional
1076.br
1077.Sy Default:
1078.Em ${configure.optflags}
1079.It Ic configure.objcflags
1080Flags to put in the OBJCFLAGS environment variable when invoking the configure script.
1081.br
1082.Sy Type:
1083.Em optional
1084.br
1085.Sy Default:
1086.Em ${configure.optflags}
1087.It Ic configure.ldflags
1088Flags to put in the LDFLAGS environment variable when invoking the configure script.
1089.br
1090.Sy Type:
1091.Em optional
1092.br
1093.Sy Default:
1094.Em -L${prefix}/lib
1095.It Ic configure.fflags
1096Flags to put in the FFLAGS environment variable when invoking the configure script.
1097.br
1098.Sy Type:
1099.Em optional
1100.br
1101.Sy Default:
1102.Em ${configure.optflags}
1103.It Ic configure.f90flags
1104Flags to put in the F90FLAGS environment variable when invoking the configure script.
1105.br
1106.Sy Type:
1107.Em optional
1108.br
1109.Sy Default:
1110.Em ${configure.optflags}
1111.It Ic configure.fcflags
1112Flags to put in the FCFLAGS environment variable when invoking the configure script.
1113.br
1114.Sy Type:
1115.Em optional
1116.br
1117.Sy Default:
1118.Em ${configure.optflags}
1119.It Ic configure.classpath
1120Flags to put in the CLASSPATH environment variable when invoking the configure script.
1121.br
1122.Sy Type:
1123.Em optional
1124.It Ic configure.cc
1125C-compiler to put in the CC environment variable when invoking the configure script.
1126.br
1127.Sy Type:
1128.Em optional
1129.br
1130.Sy Example:
1131.Dl configure.cc /usr/bin/gcc
1132.It Ic configure.cpp
1133C-preprocessor to put in the CPP environment variable when invoking the configure script.
1134.br
1135.Sy Type:
1136.Em optional
1137.It Ic configure.cxx
1138C++-compiler to put in the CXX environment variable when invoking the configure script.
1139.br
1140.Sy Type:
1141.Em optional
1142.It Ic configure.objc
1143Objective-C-compiler to put in the OBJC environment variable when invoking the configure script.
1144.br
1145.Sy Type:
1146.Em optional
1147.br
1148.Sy Example:
1149.Dl configure.objc ${prefix}/bin/gcc-mp-4.1
1150.It Ic configure.fc
1151Fortran-compiler to put in the FC environment variable when invoking the configure script.
1152.br
1153.Sy Type:
1154.Em optional
1155.It Ic configure.f77
1156Fortran-77-compiler to put in the F77 environment variable when invoking the configure script.
1157.br
1158.Sy Type:
1159.Em optional
1160.It Ic configure.f90
1161Fortran-90-compiler to put in the F90 environment variable when invoking the configure script.
1162.br
1163.Sy Type:
1164.Em optional
1165.It Ic configure.javac
1166Java compiler to put in the JAVAC environment variable when invoking the configure script.
1167.br
1168.Sy Type:
1169.Em optional
1170.It Ic configure.compiler
1171Selects 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!
1172.Em gcc-3.3
1173.Em gcc-4.0
1174.Em gcc-4.2
1175use the standard system compiler suites,
1176.Em llvm-gcc-4.2
1177.Em clang
1178use the newer, non-default compilers installed by Xcode,
1179.Em apple-gcc-3.3
1180.Em apple-gcc-4.0
1181.Em apple-gcc-4.2
1182use Apple's gcc suite installed via MacPorts,
1183.Em macports-gcc-3.3
1184.Em macports-gcc-3.4
1185.Em macports-gcc-4.0
1186.Em macports-gcc-4.1
1187.Em macports-gcc-4.2
1188.Em macports-gcc-4.3
1189.Em macports-gcc-4.4
1190.Em macports-gcc-4.5
1191use the vanilla gcc installed via MacPorts.
1192.br
1193.Sy Type:
1194.Em optional
1195.br
1196.Sy Values:
1197.Em gcc-3.3 gcc-4.0 gcc-4.2 llvm-gcc-4.2 clang apple-gcc-3.3 apple-gcc-4.0 apple-gcc-4.2 macports-gcc-3.3 macports-gcc-3.4 macports-gcc-4.0 macports-gcc-4.1 macports-gcc-4.2 macports-gcc-4.3 macports-gcc-4.4 macports-gcc-4.5
1198.br
1199.Sy Example:
1200.Dl configure.compiler gcc-4.0
1201.\" FOOBAR
1202.El
1203.Ss UNIVERSAL TARGET HOOKS
1204For 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.
1205.Bl -tag -width lc
1206.It Ic configure.universal_args
1207Arguments appended to the configure script to build the port universal.
1208.br
1209.Sy Type:
1210.Em optional
1211.br
1212.Sy Default:
1213.Em --disable-dependency-tracking
1214.It Ic configure.universal_cflags
1215Additional flags to put in the CFLAGS environment variable when invoking the configure script.
1216.br
1217.Sy Type:
1218.Em optional
1219.br
1220.Sy Default:
1221.Em -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc
1222.It Ic configure.universal_cppflags
1223Additional flags to put in the CPPFLAGS environment variable when invoking the configure script.
1224.br
1225.Sy Type:
1226.Em optional
1227.It Ic configure.universal_cxxflags
1228Additional flags to put in the CXXFLAGS environment variable when invoking the configure script.
1229.br
1230.Sy Type:
1231.Em optional
1232.br
1233.Sy Default:
1234.Em -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc
1235.It Ic configure.universal_ldflags
1236Additional flags to put in the LDFLAGS environment variable when invoking the configure script.
1237.br
1238.Sy Type:
1239.Em optional
1240.br
1241.Sy Default:
1242.Em -arch i386 -arch ppc
1243.El
1244.Sh BUILD OPTIONS
1245Execute necessary build commands.
1246.Bl -tag -width lc
1247.It Ic build.cmd
1248Make command to run relative to
1249.Ic worksrcdir .
1250.br
1251.Sy Type:
1252.Em optional
1253.br
1254.Sy Default:
1255.Em make
1256.br
1257.Sy Example:
1258.Dl build.cmd scons
1259.It Ic build.type
1260Defines which 'make' is required, either 'gnu' or 'bsd'. Can also choose 'xcode'
1261(or the deprecated synonym 'pbx'), however you should generally use
1262the xcode PortGroup rather than setting this directly.
1263Sets
1264.Ic build.cmd
1265to either
1266.Pa gnumake,
1267.Pa bsdmake
1268or
1269.Pa xcodebuild
1270accordingly.
1271.br
1272.Sy Type:
1273.Em optional
1274.br
1275.Sy Default:
1276.Em gnu
1277.br
1278.Sy Example:
1279.Dl build.type bsd
1280.It Ic build.target
1281Target passed to
1282.Ic build.cmd .
1283.br
1284.Sy Type:
1285.Em optional
1286.br
1287.Sy Default:
1288.Em all
1289.br
1290.Sy Example:
1291.Dl build.target all-src
1292.El
1293.Sh DESTROOT OPTIONS
1294Execute necessary commands to install into a temporary destination root
1295("destroot") staging area.
1296.Bl -tag -width lc
1297.It Ic destroot.cmd
1298Install command to run relative to
1299.Ic worksrcdir .
1300.br
1301.Sy Type:
1302.Em optional
1303.br
1304.Sy Default:
1305.Em ${build.cmd}
1306.br
1307.Sy Example:
1308.Dl destroot.cmd scons
1309.It Ic destroot.destdir
1310Arguments passed to
1311.Ic destroot.cmd
1312in order to install correctly
1313into the destroot.
1314.br
1315.Sy Type:
1316.Em optional
1317.br
1318.Sy Default:
1319.Em DESTDIR=${destroot}
1320.br
1321.Sy Example:
1322.Dl destroot.destdir prefix=${destroot}${prefix}
1323.It Ic destroot.target
1324Install target to pass to
1325.Ic destroot.cmd .
1326.br
1327.Sy Type:
1328.Em optional
1329.br
1330.Sy Default:
1331.Em install
1332.br
1333.Sy Example:
1334.Dl destroot.target install-src
1335.It Ic destroot.umask
1336Umask to use during destroot.
1337.br
1338.Sy Type:
1339.Em optional
1340.br
1341.Sy Default:
1342.Em 022
1343.br
1344.Sy Example:
1345.Dl destroot.umask 002
1346.It Ic destroot.keepdirs
1347List of directories that should not be pruned if empty upon
1348.Cm destroot
1349completion.
1350.br
1351.Sy Type:
1352.Em optional
1353.br
1354.Sy Example:
1355.Dl destroot.keepdirs ${destroot}${prefix}/var/log/mysql
1356.It Ic destroot.violate_mtree
1357Indicates 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
1358.Xr porthier 7 .
1359.br
1360.Sy Type:
1361.Em optional
1362.br
1363.Sy Values:
1364.Em yes no
1365.br
1366.Sy Default:
1367.Em no
1368.El
1369.Sh TEST OPTIONS
1370Execute commands to run test suites bundled with a port.
1371.Bl -tag -width lc
1372.It Ic test.run
1373Enable running test suites bundled with a port.
1374.br
1375.Sy Type:
1376.Em optional
1377.br
1378.Sy Example:
1379.Dl test.run     yes
1380.It Ic test.cmd
1381Test command to run relative to
1382.Ic worksrcdir .
1383.br
1384.Sy Type:
1385.Em optional
1386.br
1387.Sy Default:
1388.Em ${build.cmd}
1389.br
1390.Sy Example:
1391.Dl test.cmd checks.sh
1392.It Ic test.target
1393Test target to pass to
1394.Ic test.cmd .
1395.br
1396.Sy Type:
1397.Em optional
1398.br
1399.Sy Default:
1400.Em test
1401.br
1402.Sy Example:
1403.Dl test.target checks
1404.El
1405.Sh STARTUPITEM OPTIONS
1406If a port needs to run on system startup, it can use MacPorts
1407startupitem keywords to install native OS X startup scripts.
1408Startup scripts require user interaction after port installation
1409to activate them and instructions are given during port installs.
1410.Bl -tag -width lc
1411.It Ic startupitem.create
1412Choose whether or not to generate a startup item.
1413.br
1414.Sy Type:
1415.Em optional
1416.br
1417.Sy Default:
1418.Em no
1419.br
1420.Sy Values:
1421.Em yes no
1422.br
1423.Sy Example:
1424.Dl startupitem.create yes
1425.It Ic startupitem.type
1426Select the type of startupitem to generate. By default, a startupitem
1427will be generated that is of the appropriate type for the OS. For
1428instance, launchd is used on system 10.4, while SystemStarter is used
1429on prior Mac OS X systems. A global default may be specified with the startupitem_type preference in ports.conf.
1430.br
1431.Sy Type:
1432.Em optional
1433.br
1434.Sy Default:
1435.Em default
1436.br
1437.Sy Values:
1438.Em SystemStarter launchd default rcNG
1439.br
1440.Sy Example
1441.Dl startupitem.type launchd
1442.It Ic startupitem.name
1443Displayed name of the startup item.
1444.br
1445.Sy Type:
1446.Em required
1447.br
1448.Sy Example:
1449.Dl startupitem.name OpenSSH
1450.It Ic startupitem.executable
1451The name of the daemon to be run in the background. This is
1452the preferred type of startup item rather than any of
1453startupitem.init, startupitem.start, startupitem.stop, or
1454startupitem.restart, and may not be used together with any
1455of these options.  This option may contain multiple
1456arguments, but they must be appropriate for a call to exec; they
1457may not contain arbitrary shell code.
1458.br
1459.Sy Type:
1460.Em optional
1461.br
1462.Sy Values:
1463.Em /path/to/executable <args>
1464.br
1465.Sy Example:
1466.Dl startupitem.executable ${prefix}/bin/wonka
1467.It Ic startupitem.init
1468Shell code that will be executed prior to any of the options
1469startupitem.start, startupitem.stop and startupitem.restart.
1470.br
1471.Sy Type:
1472.Em optional
1473.br
1474.Sy Values:
1475.Em sh code
1476.br
1477.Sy Example:
1478.Dl startupitem.init FOO=start
1479.It Ic startupitem.start
1480Shell code executed to start the daemon.
1481.br
1482.Sy Type:
1483.Em optional
1484.br
1485.Sy Values:
1486.Em sh code
1487.br
1488.Sy Example:
1489.Dl startupitem.start ${prefix}/share/mysql/mysql.server start
1490.It Ic startupitem.stop
1491Shell code executed to stop the daemon.
1492.br
1493.Sy Type:
1494.Em optional
1495.br
1496.Sy Values:
1497.Em sh code
1498.br
1499.Sy Example:
1500.Dl startupitem.stop ${prefix}/share/mysql/mysql.server stop
1501.It Ic startupitem.restart
1502Shell code executed to restart the daemon. In the absence
1503of this key, the daemon will be restarted by taking the
1504stop action, followed by taking the start action.
1505.br
1506.Sy Type:
1507.Em optional
1508.br
1509.Sy Values:
1510.Em sh code
1511.br
1512.Sy Example:
1513.Dl startupitem.restart ${prefix}/share/mysql/mysql.server restart
1514.It Ic startupitem.pidfile
1515Specification for pidfile handling. This is particularly useful
1516in conjunction with the startupitem.executable key, because it is
1517important that the startupitem know how to track the executable.
1518This specifies whether the daemon generates its own pidfile (auto),
1519whether it generates its own but forgets to delete it, so that the
1520startupitem should delete it (clean), or whether it never generates
1521one, in which case the startupitem should manage the pidfile on its
1522own (manual), or whether no pidfile should be used at all (none).
1523.br
1524.Sy Type:
1525.Em optional
1526.br
1527.Sy Default:
1528.Em none "${prefix}/var/run/${name}.pid"
1529.br
1530.Sy Values:
1531.Em none|auto|manual|clean [/path/to/pidfile]
1532.br
1533.Sy Example:
1534.Dl startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile
1535.It Ic startupitem.logfile
1536Path to a logfile for logging events about the lifetime of the
1537startupitem. Depending on the type of startupitem, and the manner
1538in which it is started, standard output from the daemon may also be
1539directed to the logfile.
1540.br
1541.Sy Type:
1542.Em optional
1543.br
1544.Sy Default:
1545.Em /dev/null
1546.br
1547.Sy Values:
1548.Em path
1549.br
1550.Sy Example:
1551.Dl startupitem.logfile ${prefix}/var/log/mydaemon.log
1552.It Ic startupitem.logevents
1553Control whether or not to log events to the log file. If logevents
1554is set, events with timestamps are logged to the logfile.
1555.br
1556.Sy Type:
1557.Em optional
1558.br
1559.Sy Default:
1560.Em no
1561.br
1562.Sy Values:
1563.Em yes|no
1564.br
1565.Sy Example:
1566.Dl startupitem.logevents yes
1567.It Ic startupitem.netchange
1568Control whether the startupitem should be restarted when a change in the
1569machine's network state is detected.
1570.br
1571.Sy Type:
1572.Em optional
1573.br
1574.Sy Default:
1575.Em no
1576.br
1577.Sy Values:
1578.Em yes|no
1579.br
1580.Sy Example:
1581.Dl startupitem.netchange yes
1582.El
1583.Sh DISTCHECK AND LIVECHECK OPTIONS
1584MacPorts can automatically check if the software has been updated
1585since the Portfile was modified and if some external changes require
1586an update to the Portfile. This helps maintainers have up-to-date
1587and working Portfiles.
1588.br
1589Two checks are available. With distcheck, MacPorts can check that the
1590distfile(s) are still downloadable and did not change since the portfile
1591was modified.
1592With livecheck, MacPorts can query a resource to determine if a newer
1593version of the software is available.
1594.Bl -tag -width lc
1595.It Ic distcheck.check
1596This option can be used to disable distcheck. It specifies what kind
1597of check should be performed on distfiles:
1598.Em moddate
1599(check if the Portfile is older than the distfile) or
1600.Em none
1601(no check).
1602.br
1603.Sy Type:
1604.Em optional
1605.br
1606.Sy Default:
1607.Em moddate
1608.br
1609.Sy Values:
1610.Em moddate none
1611.It Ic livecheck.type
1612What kind of check to perform to figure out if the software has been updated.
1613Can be
1614.Em freshmeat
1615(uses the date_updated tag of the freshmeat XML file),
1616.Em sourceforge
1617(uses the version of the latest file release of the project),
1618.Em googlecode
1619(uses the version of the latest file release of the project),
1620.Em moddate
1621(uses the modification date of some URL resource),
1622.Em regex
1623(retrieve the version by applying a regex to some URL resource),
1624.Em regexm
1625(retrieve the version by applying a multi-line regex to some URL resource),
1626.Em md5
1627(compares the md5 sum of some URL resource) or
1628.Em none
1629(no check).
1630.br
1631.Sy Type:
1632.Em optional
1633.br
1634.Sy Default:
1635.Em sourceforge
1636or
1637.Em googlecode
1638if the master_sites is one of these, else
1639.Em freshmeat
1640.br
1641.Sy Values:
1642.Em freshmeat sourceforge googlecode moddate regex regexm md5 none
1643.It Ic livecheck.name
1644Name of the project for live checks (used for freshmeat, sourceforge, and googlecode checks).
1645.br
1646.Sy Type:
1647.Em optional
1648.br
1649.Sy Default:
1650.Em ${name}
1651or the sourceforge/freshmeat/googlecode project name if it can be guessed by looking at the master_sites.
1652.It Ic livecheck.distname
1653Name of the file release (used for sourceforge and googlecode checks).
1654For sourceforge releases use the name of the package release.
1655For googlecode releases use the name of the file download, including extension.
1656Replace the version part of the name with "(.*)".
1657.br
1658.Sy Type:
1659.Em optional
1660.br
1661.Sy Default:
1662.Em ${livecheck.name}
1663for sourceforge projects or the first entry in
1664.Em ${distfiles}
1665for googlecode projects
1666.It Ic livecheck.version
1667Version of the project for live checks (used for regex-based checks).
1668.br
1669.Sy Type:
1670.Em optional
1671.br
1672.Sy Default:
1673.Em ${version}
1674.It Ic livecheck.url
1675URL to query for the check.
1676.br
1677.Sy Type:
1678.Em optional
1679.br
1680.Sy Default:
1681.Em ${homepage}
1682or
1683.Em http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml
1684or
1685.Em http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}
1686or
1687.Em http://code.google.com/p/${livecheck.name}/downloads/list
1688.It Ic livecheck.regex
1689Regular expression to parse the resource for regex checks.
1690Be sure to use a regular expression grouping around the version component.
1691.br
1692.Sy Type:
1693.Em optional
1694.It Ic livecheck.md5
1695md5 sum to use for md5 comparison.
1696.br
1697.Sy Type:
1698.Em optional
1699.El
1700.Sh VARIANT OPTIONS
1701MacPorts allows for conditional modification to be specified in a
1702.Nm ,
1703allowing for user-customization of a software's build-time settings.
1704.Bl -tag -width lc
1705.It Xo
1706.Ic variant
1707.Op Cm requires Ar variant
1708.Op Cm conflicts Ar variant
1709.Op Cm description Ar "description"
1710.Xc
1711The value is usually a TCL script which modifies one or more
1712.Nm
1713variables. Dependencies and conflicts with other variants in the same
1714port can be expressed with
1715.Cm requires
1716and
1717.Cm conflicts .
1718.Cm description
1719provides a means to supply a description of the variant for the user.
1720.br
1721.Sy Type:
1722.Em optional
1723.br
1724.Sy Example:
1725Add a "gnome" variant to a port.
1726.Bd -literal -offset indent -compact
1727variant gnome requires glib { configure.args-append --with-gnome \e\
1728
1729    depends_lib-append lib:gnome-session:gnome-session }
1730.Ed
1731.It Ic default_variants
1732If variants are defined, then the
1733.Ic default_variants
1734value lists which variants are enabled by default.
1735.br
1736.Sy Type:
1737.Em optional
1738.br
1739.Sy Example:
1740.Dl default_variants +ssl +tcpd
1741.It Ic universal_variant
1742When using MacPorts on Mac OS X, a universal variant is defined and
1743the default behavior is to configure ports with universal flags
1744(see the
1745.Ic UNIVERSAL TARGET HOOKS
1746section above). The variant can be
1747overridden if the default code does not work. It can also be
1748suppressed if having a universal variant for the port does not make
1749sense. To suppress it, use the
1750.Ic universal_variant
1751option.
1752.br
1753.Sy Type:
1754.Em optional
1755.br
1756.Sy Default:
1757.Em yes
1758.br
1759.Sy Example:
1760.Dl universal_variant no
1761.El
1762.Sh PLATFORM OPTIONS
1763MacPorts allows for platform-specific conditional code to be
1764specified in a
1765.Nm ,
1766for handling differences between platforms and
1767versions of the same platform.
1768.Bl -tag -width lc
1769.It Xo
1770.Ic platform
1771.Ar platform
1772.Op Ar version
1773.Op Ar arch
1774.Ar body
1775.Xc
1776The body is executed if the given platform/version/arch combination matches
1777os.platform or os.subplatform and/or os.major and/or os.arch.
1778The following examples are from the databases/db4 and devel/libidl1
1779.Nm Portfiles
1780respectively.
1781.br
1782.Sy Type:
1783.Em optional
1784.br
1785.Sy Example:
1786.Bd -literal -offset indent -compact
1787platform darwin 6 { configure.args-append   --enable-tcl \e\
1788
1789        --with-tcl=/System/Library/Tcl/8.3 }
1790.Ed
1791.br
1792.Sy Example:
1793.Bd -literal -offset indent -compact
1794platform darwin powerpc { configure.args-append \e\
1795
1796        --host=${os.arch}-apple-rhapsody${os.version} }
1797platform darwin i386 { configure.args-append \e\
1798
1799        --host=i386-gnu-rhapsody${os.version} }
1800.Ed
1801.El
1802.Sh PORTGROUP
1803To factorize the work with similar ports, MacPorts provides the notion of
1804.Nm PortGroup
1805that can be used to load definitions for a given class or group of ports. See
1806.Xr portgroup 7
1807for more details on the various PortGroup classes.
1808.Sh TCL EXTENSIONS
1809A number of TCL extensions are available for use in
1810.Nm Portfiles .
1811.Pp
1812.Bl -tag -width lc
1813.Bl -tag -width lc -compact
1814.It Xo
1815.Ic xinstall
1816.Op Fl c
1817.Op Fl B Ar suffix
1818.Op Fl b
1819.Op Fl C
1820.Op Fl f Ar flags
1821.Op Fl g Ar group
1822.Op Fl M
1823.Op Fl m Ar mode
1824.Op Fl o Ar owner
1825.Op Fl p
1826.Op Fl S
1827.Op Fl s
1828.Op Fl W Ar dir
1829.Op Ar
1830.Ar destination
1831.Xc
1832.It Xo
1833.Ic xinstall
1834.Fl d
1835.Op Fl B Ar suffix
1836.Op Fl b
1837.Op Fl C
1838.Op Fl f Ar flags
1839.Op Fl g Ar group
1840.Op Fl M
1841.Op Fl m Ar mode
1842.Op Fl o Ar owner
1843.Op Fl p
1844.Op Fl S
1845.Op Fl s
1846.Op Fl W Ar dir
1847.Ar directory
1848.Xc
1849Install file(s) to a target file or directory. The options are
1850intended to be compatible with
1851.Xr install 1 :
1852.Bl -tag -width indent
1853.It Fl b
1854Backup any existing files with an
1855.Pa .old
1856extension.
1857.It Fl B
1858Specify a different backup suffix for the
1859.Fl b
1860flag.
1861.It Fl c
1862Install files (this is the default).
1863.It Fl C
1864Only copy a file if it is different.
1865.It Fl d
1866Create directories, including (if necessary) parent directories.
1867.It Fl f
1868Specify target flags, see
1869.Xr chflags 1
1870for details.
1871.It Fl g
1872Specify the group.
1873.It Fl M
1874Disable use of
1875.Xr mmap 2 .
1876.It Fl m
1877Specify an alternate mode. The default is 0755. See
1878.Xr chmod 1
1879for defails.
1880.It Fl p
1881Preserve the modification time.
1882.It Fl S
1883Copy safely, using a temporary file.
1884.It Fl s
1885Strip binaries using
1886.Xr strip 1 .
1887.It Fl W
1888Change to
1889.Ar dir
1890before working.
1891.El
1892.El
1893.It Xo
1894.Ic fs-traverse
1895.Op Fl depth
1896.Op Fl ignoreErrors
1897.Ar varname
1898.Ar target-list
1899.Ar body
1900.Xc
1901Traverse the filesystem hierarchy rooted in each element of
1902.Ar target-list
1903and execute
1904.Ar body
1905for each found file/directory.
1906.Va varname
1907is set to the path of the file/directory. If
1908.Ic break
1909is called during execution, the filesystem traversal is stopped. If
1910.Ic continue
1911is called during execution, the current file and any children are skipped
1912and traversal continues with the next file/directory.
1913.Bl -tag -width indent
1914.It Fl depth
1915Equivalent to the
1916.Fl d
1917switch to
1918.Xr find 1 .
1919Please note that using
1920.Fl depth
1921means you cannot prune a directory with
1922.Ic continue
1923as it will be processed after its children.
1924.It Fl ignoreErrors
1925Causes
1926.Ic fs-traverse
1927to ignore any permissions/read errors encountered during processing.
1928.El
1929.Pp
1930If
1931.Nm fs-traverse
1932is called directly on a symbolic link, the link will be followed. All other
1933links encountered during traversal will not be followed.
1934.Pp
1935.Nm fs-traverse
1936will not descend into directories that have a different device number than
1937the root of the descent.
1938.Pp
1939If you remove the current directory during traversal, be aware that you must call
1940.Nm continue
1941to inform
1942.Nm fs-traverse
1943that the directory should not be descended into.
1944.It Xo
1945.Ic curl fetch
1946.Ar url
1947.Ar file
1948.Xc
1949Fetch a resource at
1950.Ar url
1951and save it to
1952.Ar file .
1953.It Xo
1954.Ic curl isnewer
1955.Ar url
1956.Ar date
1957.Xc
1958Determine if resource at
1959.Ar url
1960is newer than
1961.Ar date
1962(expressed in seconds since epoch).
1963.It Xo
1964.Ic adduser
1965.Ar username
1966.Op Cm uid Ns = Ns uid
1967.Op Cm gid Ns = Ns gid
1968.Op Cm passwd Ns = Ns passwd
1969.Op Cm realname Ns = Ns realname
1970.Op Cm home Ns = Ns home
1971.Op Cm shell Ns = Ns shell
1972.Xc
1973Add a new local user to the system with the specified uid, gid,
1974password, real name, home directory and login shell. Note that it is usually
1975preferable to set the add_users option rather than call adduser directly,
1976since it may need to be called in multiple places to handle all cases (e.g.
1977installing from a binary archive).
1978.It Ic existsuser Ar username
1979Check if a local user exists.
1980.It Ic nextuid
1981Returns the highest used uid plus one.
1982.It Xo
1983.Ic addgroup
1984.Ar group
1985.Op Cm gid Ns = Ns gid
1986.Op Cm passwd Ns = Ns passwd
1987.Op Cm realname Ns = Ns realname
1988.Op Cm users Ns = Ns users
1989.Xc
1990Add a new local group to the system, with the specified gid, password,
1991real name, and with a list users as members.
1992.It Ic existsgroup Ar group
1993Check if a local group exists and return the corresponding gid. This can be used
1994with adduser:
1995.Dl addgroup foo
1996.Dl adduser foo gid=[existsgroup foo]
1997.It Ic nextgid
1998Returns the highest used gid plus one.
1999.It Xo
2000.Ic reinplace
2001.Op Fl E
2002.Ar regex
2003.Ar
2004.Xc
2005Provide in-place
2006.Xr sed 1
2007like editing of a file.
2008The -E flag does the same thing as in
2009.Xr sed 1
2010.br
2011.Sy Example:
2012.Dl reinplace \*qs|/usr/local|${prefix}|g\*q doc/manpage.1
2013.It Ic file
2014Standard TCL command to manipulate file names and attributes, recommended if you wish to preserve Mac OS
2015resource forks when destrooting ports on Mac OS X 10.3.x and Mac OS X 10.4.x . Use
2016.Nm xinstall
2017to also preserve Extended Attributes (i.e. Access Control Lists). See
2018.Xr file n
2019for more information on this command.
2020.It Ic copy
2021Built-in shorthand alternative to "file copy".
2022.It Ic move
2023Built-in shorthand alternative to "file rename".
2024.It Ic delete Ar
2025Deletes each of the given files/directories. Behaves similarly to
2026.Ic file delete -force
2027except that
2028.Ic file delete -force
2029will fail to delete directories properly on 10.3 systems.
2030.It Ic touch
2031Built-in command mimicking the BSD touch command.
2032.It Ic ln
2033.br
2034Built-in command mimicking the BSD ln command.
2035.It Ic system Ar commandline
2036Execute a program. See
2037.Xr system 3 .
2038For calls to
2039.Xr install 1
2040please use
2041.Nm xinstall .
2042For calls to
2043.Xr mv 1 ,
2044.Xr cp 1 ,
2045.Xr rm 1
2046or similar, please use the built-in commands or
2047.Nm file
2048if they don't meet your requirements.
2049.It Ic variant_isset Ar variant
2050Checks if the given
2051.Ar variant
2052is being built.
2053.It Ic variant_set Ar variant
2054Set the given
2055.Ar variant .
2056.It Va variable Ns - Ns Ic append Ar item
2057Append
2058.Ar item
2059to the
2060.Va variable .
2061.br
2062.Sy Example:
2063.Dl configure.args-append --with-gnomedb
2064.It Va variable Ns - Ns Ic delete Ar item
2065Delete
2066.Ar item
2067from the
2068.Va variable .
2069.br
2070.Sy Example:
2071.Dl configure.args-delete --with-gnomedb
2072.It Ic readdir Ar directory
2073Return the list of elements in a
2074.Ar directory ,
2075excluding
2076.Pa \&.
2077and
2078.Pa \&.. .
2079.It Ic strsed Ar string Ar pattern
2080Perform
2081.Xr ed 1 Ns / Ns
2082.Xr tr 1 Ns -like
2083search, replace, and transliteration on a string.
2084.It Ic mktemp Ar template
2085Create a temporary file using a
2086.Ar template .
2087See
2088.Xr mktemp 3 .
2089.It Ic mkstemp Ar template
2090Create a temporary file securely using a
2091.Ar template .
2092See
2093.Xr mkstemp 3 .
2094.It Ic mkdtemp Ar template
2095Create a temporary directory using a
2096.Ar template .
2097See
2098.Xr mkdtemp 3 .
2099.It Ic md5 Ar
2100Compute the MD5 hashes of the file(s).
2101.It Ic rpm-vercomp Ar versionA Ar versionB
2102Compare two RPM-format versions for equality.  The return value is like
2103strcmp(), returning -1, 0, or 1 when versionA is earlier, equal to, or
2104later than versionB, respectively.  Note that some comparisions featuring
2105floating-point notation may compare incorrectly, e.g. 2.101 is considered
2106later than 2.2 (101 is larger than 2) which may be incorrect per some
2107projects versioning methods (see ticket #11873).
2108.It Xo
2109.Ic lpush
2110.Ar varName
2111.Op Ar value \&...
2112.Xc
2113Treats the variable given by
2114.Ar varName
2115as a list and appends each of the
2116.Ar value
2117arguments to that list as a separate element. If
2118.Ar varName
2119doesn't exist, it is created as a list with elements
2120given by the
2121.Ar value
2122arguments.
2123Really just an alias for
2124.Xr lappend n .
2125.It Ic lpop Ar varName
2126Removes the last element from the list given by
2127.Ar varName
2128and returns it. If there are no elements in the list,
2129the empty string is returned. If
2130.Ar varName
2131doesn't exist, an exception is raised.
2132.It Xo
2133.Ic lunshift
2134.Ar varName
2135.Op Ar value \&...
2136.Xc
2137Treats the variable given by
2138.Ar varName
2139as a list and prepends each of the
2140.Ar value
2141arguments to that list as a separate element. If
2142.Ar varName
2143doesn't exist, it is created as a list with elements
2144given by the
2145.Ar value
2146arguments.
2147.It Ic lshift Ar varName
2148Removes the first element from the list given by
2149.Ar varName
2150and returns it. If there are no elements in the list,
2151the empty string is returned. If
2152.Ar varName
2153doesn't exist, an exception is raised.
2154.It Xo
2155.Ic ldindex
2156.Ar varName
2157.Op Ar index \&...
2158.Xc
2159Treats the variable given by
2160.Ar varName
2161as a list and removes the element pointed to by the sequence of
2162.Ar index
2163arguments and returns it. If no
2164.Ar index
2165arguments are provided,
2166.Ar varName
2167is set to the empty string and the entire former value is returned.
2168Has the same usage semantics as
2169.Xr lindex n .
2170.It Xo
2171.Ic try
2172.Ar body
2173.Oo
2174.Nm catch Nm {
2175.Ar type-list
2176.Op Ar ecvar
2177.Op Ar msgvar
2178.Op Ar infovar
2179.Nm }
2180.Ar body Ar \&...
2181.Oc
2182.Op Nm finally Ar body
2183.Xc
2184Implements a try-catch-finally block as defined in TIP #89.
2185.br
2186.Sy Example:
2187Basic try-finally construct.
2188.Bd -literal -offset indent -compact
2189try {
2190    set fd [open $file r]
2191    # do stuff here
2192} finally {
2193    close $fd
2194}
2195.Ed
2196.Sy Example:
2197Basic try-catch construct
2198.Bd -literal -offset indent -compact
2199try {
2200    set result [expr $num / $div]
2201} catch {{ARITH DIVZERO}} {
2202    set result -1
2203}
2204.Ed
2205.Sy Example:
2206Basic try with multiple catches construct
2207.Bd -literal -offset indent -compact
2208try {
2209    set fd [open $file r]
2210    # do stuff here
2211} catch {{POSIX ENOENT} {} msgvar} {
2212    puts stderr $msgvar
2213} catch {*} {
2214    puts stderr "An error occurred while processing the file"
2215    close $fd
2216    throw
2217}
2218.Ed
2219.It Xo
2220.Ic throw
2221.Op Ar type
2222.Op Ar message
2223.Op Ar info
2224.Xc
2225Throws an exception. If given arguments, works just like
2226.Ic error
2227.Ar message
2228.Ar info
2229.Ar type .
2230If called with no arguments from within a
2231.Ic catch
2232block, re-throws the caught exception.
2233.El
2234.Pp
2235.Bl -tag -width lc -compact
2236.It Ic ui_debug Ar message
2237.It Ic ui_error Ar message
2238.It Ic ui_info Ar message
2239.It Ic ui_msg Ar message
2240.It Ic ui_warn Ar message
2241Display a
2242.Ar message
2243to the user, at various different levels.
2244.br
2245.Sy Example:
2246.Dl ui_msg \*qAdd each user to the system using the clamav command\*q
2247.El
2248.Sh SEE ALSO
2249.Xr port 1 ,
2250.Xr macports.conf 5 ,
2251.Xr portgroup 7 ,
2252.Xr portstyle 7 ,
2253.Xr porthier 7 ,
2254.Xr file n
2255.Sh AUTHORS
2256.An "Landon Fuller" Aq landonf@macports.org
2257.An "Juan Manuel Palacios" Aq jmpp@macports.org
2258.An "Mark Duling" Aq markd@macports.org
2259.An "Kevin Van Vechten" Aq kevin@opendarwin.org
2260.An "Jordan K. Hubbard" Aq jkh@macports.org
2261.An "Chris Ridd" Aq cjr@opendarwin.org
2262.An "Kevin Ballard" Aq eridius@macports.org
2263.An "Markus W. Weissmann" Aq mww@macports.org
Note: See TracBrowser for help on using the repository browser.