Ticket #11445: portfile.7

File portfile.7, 32.3 KB (added by markd@…, 18 years ago)
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 "Apple Computer, Inc."
32.Os
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.
100.br
101.Sy Type:
102.Em required
103.br
104.Sy Example:
105.Dl description Dictionary Server Protocol (RFC2229) client
106.It Ic long_description
107A verbose description of the software and what it does.
108.br
109.Sy Type:
110.Em required
111.br
112.Sy Example:
113.Bd -literal -offset indent -compact
114long_description The GNU Image Manipulation Program \e\
115
116    (GIMP) is a powerful tool for the preparation and \e\
117
118    manipulation of digital images. The GIMP provides \e\
119
120    the user with a wide variety of image manipulation, \e\
121
122    painting, processing, and rendering tools.
123.Ed
124.It Ic revision
125Local revision number of
126.Nm .
127Increment for port revisions which would change its installation in any way.
128.br
129.Sy Type:
130.Em optional
131.br
132.Sy Default:
133.Em 0
134.br
135.Sy Example:
136.Dl revision 1
137.It Ic categories
138Categories to which this port belongs.
139.br
140.Sy Type:
141.Em required
142.br
143.Sy Example:
144.Dl categories spelling textproc
145.It Ic maintainers
146E-mail address(es) of port maintainer(s).
147.br
148.Sy Type:
149.Em required
150.br
151.Sy Example:
152.Dl maintainers landonf@opendarwin.org kevin@opendarwin.org
153.It Ic platforms
154Declares which platforms are supported by the port.
155.br
156.Sy Type:
157.Em required
158.br
159.Sy Values:
160.Em darwin freebsd
161.br
162.Sy Example:
163.Dl platforms darwin
164.It Ic homepage
165Project homepage for the port.
166.br
167.Sy Type:
168.Em required
169.br
170.Sy Example:
171.Dl http://wireshark.org
172.It Ic master_sites
173List of sites to fetch
174.Ic distfiles
175from or a predefined mirror site
176list. If set to a predefined mirror site, without a subdirectory being
177defined, the portname is used as the name of the subdirectory.
178.br
179.Sy Type:
180.Em required
181.br
182.Sy Example:
183.Bd -literal -offset indent -compact
184master_sites ftp://ftp.cdrom.com/pub/magic \e\
185
186    sourceforge
187.Ed
188.It Ic worksrcdir
189Path to source directory relative to
190.Ic workpath .
191.br
192.Sy Type:
193.Em optional
194.br
195.Sy Default:
196.Em ${distname}
197.br
198.Sy Example:
199.Dl worksrcdir ${distname}-src-${version}
200.It Ic distname
201Name of distribution file, without the
202.Cm extract.suffix .
203.br
204.Sy Type:
205.Em optional
206.br
207.Sy Default:
208.Em ${name}-${version}
209.br
210.Sy Example:
211.Dl distname ${name}-${version}-src
212.It Xo
213.Ic checksums Ar filename Ar type Ar checksum
214.Op Ar filename Ar type checksum ...
215.Xc
216List of checksums for the
217.Ic distfiles .
218The checksum
219.Ar type
220can currently be md5, rmd160 or sha1. The
221.Ar filename
222can be omitted if there is only one distfile.
223.br
224.Sy Type:
225.Em required
226.br
227.Sy Example:
228.Bd -literal -offset indent -compact
229checksums dictd-1.7.1.tar.gz md5 81317b86ea0a5df0163900ad2e6bb12c \e\
230        magic-words-1.7.1.tar.gz md5 897a005182928613eadd30c267ce9c5b
231.Ed
232.br
233.Sy Example (ledit 1.11):
234.Bd -literal -offset indent -compact
235checksums md5 a2d38ba641682509c1e964ad699a9dd2 \e\
236        sha1 1fb6443b5fdf3c83787953f06282d256477c1288
237.Ed
238.br
239.Sy Example (ssldump 0.9b3):
240.Bd -literal -offset indent -compact
241checksums md5 ac8c28fe87508d6bfb06344ec496b1dd \e\
242        sha1 a633a9a811a138eac5ed440d583473b644135ef5 \e\
243        rmd160 941cf8f2ef8459ec4f9ce65772e134505d46566
244.Ed
245.It Ic use_automake
246If set to yes, run the
247.Cm automake
248target to build any
249.Pa Makefile.in
250files for use by
251.Pa configure .
252.br
253.Sy Type:
254.Em optional
255.br
256.Sy Default:
257.Em no
258.br
259.Sy Example:
260.Dl use_automake yes
261.It Ic use_autoconf
262If set to yes, run the
263.Cm autoconf
264target to build any
265.Pa configure
266script required.
267.br
268.Sy Type:
269.Em optional
270.br
271.Sy Default:
272.Em no
273.br
274.Sy Example:
275.Dl use_autoconf yes
276.It Ic use_configure
277If set to yes, run the
278.Cm configure
279target to configure the build.
280.br
281.Sy Type:
282.Em optional
283.br
284.Sy Default:
285.Em yes
286.br
287.Sy Example:
288.Dl use_configure no
289.El
290.Sh TARGET HOOKS
291A number of hooks are available for customizing many of the standard
292targets that
293.Xr port 1
294executes. The targets supporting these hooks are
295.Cm fetch ,
296.Cm automake ,
297.Cm autoconf ,
298.Cm configure ,
299.Cm build ,
300.Cm destroot ,
301and
302.Cm test .
303The hooks are:
304.Bl -tag -width lc
305.It Va target Ns Ic .dir
306Directory in which to run the
307.Va target .
308.br
309.Sy Example:
310.Dl automake.dir src
311.It Va target Ns Ic .env
312Change the environment the
313.Va target
314is run in. This is often overridden on a per
315.Nm
316basis.
317.br
318.Sy Example:
319.Dl configure.env CFLAGS=-O
320.It Va target Ns Ic .pre_args
321Additional arguments passed before the main arguments.
322.br
323.Sy Example:
324.Dl extract.pre_args -cd
325.It Va target Ns Ic .args
326Main arguments to pass to the
327.Va target .
328This is often overridden on a per
329.Nm
330basis.
331.br
332.Sy Example:
333.Dl configure.args --enable-fooble
334.It Va target Ns Ic .post_args
335Additional arguments passed after the main arguments.
336.br
337.Sy Example:
338.Dl extract.post_args | tar xf -
339.El
340.Sh UNIVERSAL TARGET HOOKS
341For 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. Please also note that problems may occur with the default code if a port already overrides LDFLAGS or CFLAGS (port(1) will display a warning in such a case).
342.Bl -tag -width lc
343.It Ic configure.universal_args
344Arguments appended to the configure script to build the port universal.
345.br
346.Sy Type:
347.Em optional
348.br
349.Sy Default:
350.Em --disable-dependency-tracking
351.It Ic configure.universal_cflags
352Value of the CFLAGS environment variable when invoking the configure script.
353.br
354.Sy Type:
355.Em optional
356.br
357.Sy Default:
358.Em -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc
359.It Ic configure.universal_ldflags
360Value of the LDFLAGS environment variable when invoking the configure script.
361.br
362.Sy Type:
363.Em optional
364.br
365.Sy Default:
366.Em -arch i386 -arch ppc
367.It Ic configure.universal_env
368Environment appended to the port-defined environment when invoking the configure script.
369.br
370.Sy Type:
371.Em optional
372.br
373.Sy Default:
374.Em CFLAGS="${configure.universal_cflags}" LDFLAGS="${configure.universal_ldflags}"
375.El
376.Sh RUNTIME VARIABLES
377Read-only access to the MacPorts configuration is provided.
378.Bl -tag -width lc
379.It Ic prefix
380Install prefix
381.br
382.Sy Type:
383.Em optional
384.br
385.Sy Default:
386.Em /opt/local
387.It Ic libpath
388Location of ports-specific TCL libraries.
389.br
390.Sy Type:
391.Em read-only
392.It Ic portpath
393Full path to the Portfile location.
394.br
395.Sy Type:
396.Em read-only
397.It Ic workdir
398Path to work directory relative to
399.Ic portpath .
400Where possible use
401.Ic workpath
402instead.
403.br
404.Sy Type:
405.Em read-only
406.br
407.Sy Default:
408.Em work
409.It Ic workpath
410Full path to work directory.
411.br
412.Sy Type:
413.Em read-only
414.br
415.Sy Default:
416.Em ${portpath}/${workdir}
417.It Ic worksrcpath
418Full path to working sources (where port has unpacked itself).
419.br
420.Sy Type:
421.Em read-only
422.br
423.Sy Default:
424.Em ${workpath}/${worksrcdir}
425.It Ic filesdir
426Path to port files relative to
427.Ic portpath .
428.br
429.Sy Type:
430.Em read-only
431.br
432.Sy Default:
433.Em files
434.It Ic distpath
435Location to store downloaded distfiles.
436.br
437.Sy Type:
438.Em read-only
439.br
440.Sy Default:
441.Em ${sysportpath}/distfiles/${dist_subdir}/
442.It Ic os.arch
443Identifies hardware type (eg "powerpc").
444.br
445.Sy Type:
446.Em read-only
447.It Ic os.version
448Version number of operating system (eg "7.0").
449.br
450.Sy Type:
451.Em read-only
452.It Ic os.endian
453Endianness of the processor (eg "bigEndian").
454.br
455.Sy Type:
456.Em read-only
457.It Ic os.platform
458Operating system name (eg "darwin").
459.br
460.Sy Type:
461.Em read-only
462.It Ic install.user
463User for MacPorts installation (eg
464.Pa root )
465.br
466.Sy Type:
467.Em read-only
468.It Ic install.group
469Group for MacPorts installation (eg
470.Pa wheel )
471.br
472.Sy Type:
473.Em read-only
474.It Ic x11prefix
475Absolute path to X11 (eg
476.Pa /usr/X11R6 )
477.br
478.Sy Type:
479.Em read-only
480.El
481.Sh DEPENDENCY OPTIONS
482Port dependencies should refer to other MacPort ports
483whenever possible, therefore each dependency should be
484expressed in the format:
485.Bl -tag -width ls
486.It port: Ns Ao port Ac
487.El
488.Pp
489Where
490.Ao port Ac represents the name of an existing MacPorts
491.Nm port .
492If satisfying a dependency with a MacPorts port is not
493practical and it is likely that a dependency must be met
494by an Apple optional install, then the alternative dependency
495format:
496.Bl -tag -width lc
497.It Ar type Ns : Ns Ao filename Ac Ns : Ns Ao port Ac
498.El
499.Pp
500may be used. Where
501.Ar type
502is "bin" if
503.Ao filename Ac
504is a program, "lib" if it is a library, or "path" if it is a path to an
505installed file.
506.br
507.Sy Example:
508.Dl lib:libX11.6:XFree86
509.Bl -tag -width lc
510.It Ic depends_build
511List of dependencies to check before
512.Cm build ,
513.Cm destroot ,
514.Cm install ,
515and
516.Cm package
517targets.
518.br
519.Sy Type:
520.Em optional
521.br
522.Sy Example:
523.Dl depends_build port:autoconf
524.It Ic depends_run
525List of dependencies to check before
526.Cm destroot ,
527.Cm install
528and
529.Cm package
530targets.
531.br
532.Sy Type:
533.Em optional
534.br
535.Sy Example:
536.Dl depends_run port:bash
537.It Ic depends_lib
538List of dependencies to check before
539.Cm configure ,
540.Cm build ,
541.Cm destroot ,
542.Cm install ,
543and
544.Cm package
545targets.
546.br
547.Sy Type:
548.Em optional
549.br
550.Sy Example:
551.Dl depends_lib port:libfetch
552.El
553.Sh FETCH OPTIONS
554Fetch all distribution files and patches.
555.Bl -tag -width lc
556.It Ic master_sites.mirror_subdir
557Subdirectory to append to all mirror sites for any list specified in
558master_sites.
559.br
560.Sy Type:
561.Em optional
562.br
563.Sy Default:
564.Em ${name}
565.br
566.Sy Example:
567.Dl master_sites.mirror_subdir      magic
568.It Ic patch_sites
569List of sites to fetch
570.Ic patchfiles
571from or a predefined mirror site list.
572.br
573.Sy Type:
574.Em optional
575.br
576.Sy Default:
577.Em ${master_sites}
578.br
579.Sy Example:
580.Dl patch_sites ftp://ftp.patchcityrepo.com/pub/magic/patches
581.It Ic patch_sites.mirror_subdir
582Subdirectory to append to all mirror sites for any list specified in
583.Ic patch_sites .
584.br
585.Sy Type:
586.Em optional
587.br
588.Sy Default:
589.Em ${name}
590.br
591.Sy Example:
592.Dl patch_sites.mirror_subdir       magic
593.It Ic extract.suffix
594Suffix to append to
595.Ic distname .
596.br
597.Sy Type:
598.Em optional
599.br
600.Sy Default:
601.Em .tar.gz
602.br
603.Sy Example:
604.Dl extract.suffix .tgz
605.It Ic distfiles
606List of distribution files to fetch from
607.Ic master_sites .
608.br
609.Sy Type:
610.Em optional
611.br
612.Sy Default:
613.Em [suffix ${distname}]
614.br
615.Sy Example:
616.Dl distfiles magicsource.tar.gz cluebat.tar.bz2
617.It Ic patchfiles
618List of patches to fetch and apply.
619.br
620.Sy Type:
621.Em optional
622.br
623.Sy Example:
624.Dl patchfiles japanese-widechar-fix.diff japanese-localization.diff
625.It Ic use_zip
626Use zip.
627.br
628Sets extract.suffix to: .zip
629.br
630Sets extract.cmd to: unzip
631.br
632Sets extract.pre_args to: -q
633.br
634Sets extract.post_args to: "-d ${portpath}/${workdir}"
635.br
636.Sy Type:
637.Em optional
638.br
639.Sy Example:
640.Dl use_zip yes
641.It Ic use_bzip2
642Use bzip2.
643.br
644Sets extract.suffix to: .bzip2
645.br
646Sets extract.cmd to: bzip2
647.br
648.Sy Type:
649.Em optional
650.br
651.Sy Example:
652.Dl use_bzip2 yes
653.It Ic dist_subdir
654Create a sub-directory in
655.Ic distpath
656to store all fetched files.
657.br
658.Sy Type:
659.Em optional
660.br
661.Sy Default:
662.Em ${name}
663.br
664.Sy Example:
665.Dl dist_subdir vim${version}
666.El
667.Ss ADVANCED FETCH OPTIONS
668Some mirrors require special options for a resource to be properly
669fetched.
670.Bl -tag -width lc
671.It Ic fetch.user
672HTTP or FTP user to fetch the resource.
673.br
674.Sy Type:
675.Em optional
676.It Ic fetch.password
677HTTP or FTP password to fetch the resource.
678.br
679.Sy Type:
680.Em optional
681.It Ic fetch.use_epsv
682Whether to use EPSV command for FTP transfers.
683.br
684.Sy Type:
685.Em optional
686.br
687.Sy Default:
688.Em yes
689.br
690.El
691.Ss FETCHING FROM CVS
692As an alternative to fetching distribution files, pulling the sources
693from a CVS repository is supported. Use of CVS can give rise to
694non-reproducible builds, so it is strongly discouraged.
695.Bl -tag -width lc
696.It Ic cvs.root
697Specify the address to a CVS repository from which to checkout files.
698.br
699.Sy Type:
700.Em optional
701.br
702.Sy Default:
703.Em none
704.br
705.Sy Example:
706.Dl cvs.root :pserver:anonymous cvs.sv.gnu.org:/sources/emacs
707.It Ic cvs.tag
708Specify a CVS tag identifying the code to checkout.
709.br
710.Sy Type:
711.Em optional
712.br
713.Sy Default
714.Em none
715.br
716.Sy Example:
717.Dl cvs.tag HEAD
718.It Ic cvs.date
719A date that identifies the CVS code set to checkout.
720.br
721.Sy Type:
722.Em optional
723.br
724.Sy Default
725.Em none
726.br
727.Sy Example:
728.Dl cvs.date \*q12-April-2005\*q
729.It Ic cvs.module
730A CVS module from which to check out the code.
731.br
732.Sy Type:
733.Em optional
734.br
735.Sy Default
736.Em none
737.br
738.Sy Example:
739.Dl cvs.module Sources
740.El
741.Ss FETCHING FROM SUBVERSION
742As an alternative to fetching distribution files, pulling the sources
743from a subversion repository is supported. Use of subversion can give
744rise to non-reproducible builds, so it is strongly discouraged.
745.Bl -tag -width lc
746.It Ic svn.url
747Specify the url from which to fetch files.
748.br
749.Sy Type:
750.Em required
751.br
752.Sy Default:
753.Em none
754.br
755.Sy Example:
756.Dl svn.url http://www.domain.com/svn-repo/mydirectory
757      svn.url svn://www.domain.com/svn-repo/mydirectory
758.It Ic svn.tag
759Specify the a tag from which svn should fetch files. This
760corresponds to the -r option to the svn cli.
761.br
762.Sy Type:
763.Em optional
764.br
765.Sy Default:
766.Em none
767.br
768.Sy Example:
769.Dl svn.url http://www.domain.com/svn-repo/mydirectory
770      svn.url svn://www.domain.com/svn-repo/mydirectory
771.El
772.Sh EXTRACT OPTIONS
773Extract all compressed/archived files.
774.Bl -tag -width lc
775.It Ic extract.only
776List of files to extract into
777.Ic workpath .
778.br
779.Sy Type:
780.Em optional
781.br
782.Sy Default:
783.Em ${distfiles}
784.br
785.Sy Example:
786.Dl extract.only worksrc-1.4.4.tar.gz
787.It Ic extract.cmd
788Command to perform the extraction.
789.br
790.Sy Type:
791.Em optional
792.br
793.Sy Default:
794.Em gzip
795.br
796.Sy Example:
797.Dl extract.cmd bzip2
798.El
799.Sh BUILD OPTIONS
800Execute necessary build commands.
801.Bl -tag -width lc
802.It Ic build.cmd
803Make command to run relative to
804.Ic worksrcdir .
805.br
806.Sy Type:
807.Em optional
808.br
809.Sy Default:
810.Em make
811.br
812.Sy Example:
813.Dl build.cmd pbxbuild
814.It Ic build.type
815Defines which 'make' is required, either 'gnu' or 'bsd'.
816Sets
817.Ic build.cmd
818to either
819.Pa gnumake
820or
821.Pa bsdmake
822accordingly.
823.br
824.Sy Type:
825.Em optional
826.br
827.Sy Default:
828.Em gnu
829.br
830.Sy Example:
831.Dl build.type bsd
832.It Ic build.target
833Target passed to
834.Ic build.cmd .
835.br
836.Sy Type:
837.Em optional
838.br
839.Sy Default:
840.Em all
841.br
842.Sy Example:
843.Dl build.target all-src
844.El
845.Sh DESTROOT OPTIONS
846Execute necessary commands to install into a temporary destination root
847("destroot") staging area.
848.Bl -tag -width lc
849.It Ic destroot.cmd
850Install command to run relative to
851.Ic worksrcdir .
852.br
853.Sy Type:
854.Em optional
855.br
856.Sy Default:
857.Em ${build.cmd}
858.br
859.Sy Example:
860.Dl destroot.cmd pbxbuild
861.It Ic destroot.type
862Defines which 'make' is required, either 'gnu' or 'bsd'.
863Sets
864.Ic destroot.cmd
865to either
866.Pa gnumake
867or
868.Pa bsdmake
869accordingly.
870.br
871.Sy Type:
872.Em optional
873.br
874.Sy Default:
875.Em ${build.type}
876.br
877.Sy Example:
878.Dl destroot.type gnu
879.It Ic destroot.destdir
880Arguments passed to
881.Ic destroot.cmd
882in order to install correctly
883into the destroot.
884.br
885.Sy Type:
886.Em optional
887.br
888.Sy Default:
889.Em DESTDIR=${destroot}
890.br
891.Sy Example:
892.Dl destroot.destdir prefix=${destroot}${prefix}
893.It Ic destroot.target
894Install target to pass to
895.Ic destroot.cmd .
896.br
897.Sy Type:
898.Em optional
899.br
900.Sy Default:
901.Em install
902.br
903.Sy Example:
904.Dl destroot.target install-src
905.It Ic destroot.umask
906Umask to use during destroot.
907.br
908.Sy Type:
909.Em optional
910.br
911.Sy Default:
912.Em 022
913.br
914.Sy Example:
915.Dl destroot.umask 002
916.It Ic destroot.keepdirs
917List of directories that should not be pruned if empty upon
918.Cm destroot
919completion.
920.br
921.Sy Type:
922.Em optional
923.br
924.Sy Example:
925.Dl destroot.keepdirs ${destroot}${prefix}/var/log/mysql
926.El
927.Sh TEST OPTIONS
928Execute commands to run test suites bundled with a port.
929.Bl -tag -width lc
930.It Ic test.run
931Enable running test suites bundled with a port.
932.br
933.Sy Type:
934.Em optional
935.br
936.Sy Example:
937.Dl test.run     yes
938.It Ic test.cmd
939Test command to run relative to
940.Ic worksrcdir .
941.br
942.Sy Type:
943.Em optional
944.br
945.Sy Default:
946.Em ${build.cmd}
947.br
948.Sy Example:
949.Dl test.cmd checks.sh
950.It Ic test.target
951Test target to pass to
952.Ic test.cmd .
953.br
954.Sy Type:
955.Em optional
956.br
957.Sy Default:
958.Em test
959.br
960.Sy Example:
961.Dl test.target checks
962.El
963.Sh STARTUPITEM OPTIONS
964If a port needs to run on system startup, it can use MacPorts
965startupitem keywords to install native OS X startup scripts.
966Startup scripts require user interaction after port installation
967to activate them and instructions are given during port installs.
968.Bl -tag -width lc
969.It Ic startupitem.create
970Choose whether or not to generate a startup item.
971.br
972.Sy Type:
973.Em optional
974.br
975.Sy Default:
976.Em no
977.br
978.Sy Values:
979.Em yes no
980.br
981.Sy Example:
982.Dl startupitem.create yes
983.It Ic startupitem.type
984Select the type of startupitem to generate. By default, a startupitem
985will be generated that is of the appropriate type for the OS. For
986instance, launchd is used on system 10.4, while SystemStarter is used
987on prior Mac OS X systems. A global default may be specified with the startupitem_type preference in ports.conf.
988.br
989.Sy Type:
990.Em optional
991.br
992.Sy Default:
993.Em default
994.br
995.Sy Values:
996.Em SystemStarter launchd default rcNG
997.br
998.Sy Example
999.Dl startupitem.type launchd
1000.It Ic startupitem.name
1001Displayed name of the startup item.
1002.br
1003.Sy Type:
1004.Em required
1005.br
1006.Sy Example:
1007.Dl startupitem.name OpenSSH
1008.It Ic startupitem.executable
1009The name of the daemon to be run in the background. This is
1010the preferred type of startup item rather than any of
1011startupitem.init, startupitem.start, startupitem.stop, or
1012startupitem.restart, and may not be used together with any
1013of these options.  This option may contain multiple
1014arguments, but they must be appropriate for a call to exec; they
1015may not contain arbitrary shell code.
1016.br
1017.Sy Type:
1018.Em optional
1019.br
1020.Sy Values:
1021.Em /path/to/executable <args>
1022.br
1023.Sy Example:
1024.Dl startupitem.executable ${prefix}/bin/wonka
1025.It Ic startupitem.init
1026Shell code that will be executed prior to any of the options
1027startupitem.start, startupitem.stop and startupitem.restart.
1028.br
1029.Sy Type:
1030.Em optional
1031.br
1032.Sy Values:
1033.Em sh code
1034.br
1035.Sy Example:
1036.Dl startupitem.init FOO=start
1037.It Ic startupitem.start
1038Shell code executed to start the daemon.
1039.br
1040.Sy Type:
1041.Em optional
1042.br
1043.Sy Values:
1044.Em sh code
1045.br
1046.Sy Example:
1047.Dl startupitem.start ${prefix}/share/mysql/mysql.server start
1048.It Ic startupitem.stop
1049Shell code executed to stop the daemon.
1050.br
1051.Sy Type:
1052.Em optional
1053.br
1054.Sy Values:
1055.Em sh code
1056.br
1057.Sy Example:
1058.Dl startupitem.stop ${prefix}/share/mysql/mysql.server stop
1059.It Ic startupitem.restart
1060Shell code executed to restart the daemon. In the absence
1061of this key, the daemon will be restarted by taking the
1062stop action, followed by taking the start action.
1063.br
1064.Sy Type:
1065.Em optional
1066.br
1067.Sy Values:
1068.Em sh code
1069.br
1070.Sy Example:
1071.Dl startupitem.restart ${prefix}/share/mysql/mysql.server restart
1072.It Ic startupitem.pidfile
1073Specification for pidfile handling. This is particularly useful
1074in conjunction with the startupitem.executable key, because it is
1075important that the startupitem know how to track the executable.
1076This specifies whether the daemon generates its own pidfile (auto),
1077whether it generates its own but forgets to delete it, so that the
1078startupitem should delete it (clean), or whether it never generates
1079one, in which case the startupitem should manage the pidfile on its
1080own (manual), or whether no pidfile should be used at all (none).
1081.br
1082.Sy Type:
1083.Em optional
1084.br
1085.Sy Default:
1086.Em none "${prefix}/var/run/${name}.pid"
1087.br
1088.Sy Values:
1089.Em none|auto|manual|clean [/path/to/pidfile]
1090.br
1091.Sy Example:
1092.Dl startupitem.pidfile auto ${prefix}/var/run/${name}.pidfile
1093.It Ic startupitem.logfile
1094Path to a logfile for logging events about the lifetime of the
1095startupitem. Depending on the type of startupitem, and the manner
1096in which it is started, standard output from the daemon may also be
1097directed to the logfile.
1098.br
1099.Sy Type:
1100.Em optional
1101.br
1102.Sy Default:
1103.Em /dev/null
1104.br
1105.Sy Values:
1106.Em path
1107.br
1108.Sy Example:
1109.Dl startupitem.logfile ${prefix}/var/log/mydaemon.log
1110.It Ic startupitem.logevents
1111Control whether or not to log events to the log file. If logevents
1112is set, events with timestamps are logged to the logfile.
1113.br
1114.Sy Type:
1115.Em optional
1116.br
1117.Sy Default:
1118.Em no
1119.br
1120.Sy Values:
1121.Em yes|no
1122.br
1123.Sy Example:
1124.Dl startupitem.logevents yes
1125.El
1126.Sh DISTCHECK AND LIVECHECK OPTIONS
1127MacPorts can automatically check if the software has been updated
1128since the Portfile was modified and if some external changes require
1129an update to the Portfile. This helps maintainers have up-to-date
1130and working Portfiles.
1131.br
1132Two checks are available. With distcheck, MacPorts can check that the
1133distfile(s) are still downloadable and did not change since the portfile
1134was modified.
1135With livecheck, MacPorts can query a resource to determine if a newer
1136version of the software is available.
1137.Bl -tag -width lc
1138.It Ic distcheck.check
1139This option can be used to disable distcheck. It specifies what kind
1140of check should be performed on distfiles:
1141.Em moddate
1142(check if the Portfile is older than the distfile) or
1143.Em none
1144(no check).
1145.br
1146.Sy Type:
1147.Em optional
1148.br
1149.Sy Default:
1150.Em moddate
1151.br
1152.Sy Values:
1153.Em moddate none
1154.It Ic livecheck.check
1155What kind of check to perform to figure out if the software has been updated.
1156Can be
1157.Em freshmeat
1158(uses the date_updated tag of the freshmeat XML file),
1159.Em sourceforge
1160(uses the version of the latest file release of the project),
1161.Em moddate
1162(uses the modification date of some URL resource),
1163.Em regex
1164(retrieve the version by applying a regex to some URL resource),
1165.Em regexm
1166(retrieve the version by applying a multi-line regex to some URL resource),
1167.Em md5
1168(compares the md5 sum of some URL resource) or
1169.Em none
1170(no check).
1171.br
1172.Sy Type:
1173.Em optional
1174.br
1175.Sy Default:
1176.Em freshmeat
1177or
1178.Em sourceforge
1179if the master_sites is sourceforge.
1180.br
1181.Sy Values:
1182.Em freshmeat sourceforge moddate regex regexm md5 none
1183.It Ic livecheck.name
1184Name of the project for live checks (used for freshmeat and sourceforge checks).
1185.br
1186.Sy Type:
1187.Em optional
1188.br
1189.Sy Default:
1190.Em ${name}
1191or the sourceforge project name if it can be guessed by looking at the master_sites.
1192.It Ic livecheck.version
1193Version of the project for live checks (used for regex-based checks).
1194.br
1195.Sy Type:
1196.Em optional
1197.br
1198.Sy Default:
1199.Em ${version}
1200.It Ic livecheck.url
1201URL to query for the check.
1202.br
1203.Sy Type:
1204.Em optional
1205.br
1206.Sy Default:
1207.Em ${homepage}
1208or
1209.Em http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml
1210or
1211.Em http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}
1212.It Ic livecheck.regex
1213Regular expression to parse the resource for regex checks.
1214.br
1215.Sy Type:
1216.Em optional
1217.It Ic livecheck.md5
1218md5 sum to use for md5 comparison.
1219.br
1220.Sy Type:
1221.Em optional
1222.El
1223.Sh VARIANT OPTIONS
1224MacPorts allows for conditional modification to be specified in a
1225.Nm ,
1226allowing for user-customization of a software's build-time settings.
1227.Bl -tag -width lc
1228.It Xo
1229.Ic variant
1230.Op Cm requires Ar variant
1231.Op Cm conflicts Ar variant
1232.Xc
1233The value is usually a TCL script which modifies other port's
1234.Nm
1235variables. Dependencies and conflicts with other variants in the same
1236port can be expressed with
1237.Cm requires
1238and
1239.Cm conflicts .
1240The example adds a "gnome" variant to a port.
1241.br
1242.Sy Type:
1243.Em optional
1244.br
1245.Sy Example:
1246.Bd -literal -offset indent -compact
1247variant gnome requires glib { configure.args-append --with-gnome \e\
1248
1249    depends_lib-append lib:gnome-session:gnome-session }
1250.Ed
1251.It Ic default_variants
1252If variants are defined, then the
1253.Ic default_variants
1254value lists which variants are enabled by default.
1255.br
1256.Sy Type:
1257.Em optional
1258.br
1259.Sy Example:
1260.Dl default_variants +ssl +tcpd
1261.El
1262.Sh PLATFORM OPTIONS
1263MacPorts allows for platform-specific conditional modification to be
1264specified in a
1265.Nm ,
1266much like variants, for handling differences between platforms and
1267versions of the same platform.
1268.Bl -tag -width lc
1269.It Xo
1270.Ic platform
1271.Ar platform
1272.Op Ar version
1273.Op Ar arch
1274.Xc
1275The platform key is used to begin the darwin platform definitions as
1276shown in the examples from the databases/db4 and devel/libidl1
1277.Nm Portfiles
1278respectively.
1279.br
1280.Sy Type:
1281.Em optional
1282.br
1283.Sy Example:
1284.Bd -literal -offset indent -compact
1285platform darwin 6 { configure.args-append   --enable-tcl \e\
1286
1287        --with-tcl=/System/Library/Tcl/8.3 }
1288.Ed
1289.br
1290.Sy Example:
1291.Bd -literal -offset indent -compact
1292platform darwin powerpc { configure.args-append \e\
1293
1294        --host=${os.arch}-apple-rhapsody${os.version} }
1295platform darwin i386 { configure.args-append \e\
1296
1297        --host=i386-gnu-rhapsody${os.version} }
1298.Ed
1299.El
1300.Sh PORTGROUP
1301To factorize the work with similar ports, MacPorts provides the notion of
1302.Nm PortGroup
1303that can be used to load definitions for a given class or group of ports. See
1304.Xr portgroup 7
1305for more details on the various PortGroup classes.
1306.Sh TCL EXTENSIONS
1307A number of TCL extensions are available for use in
1308.Nm Portfiles .
1309.Pp
1310.Bl -tag -width lc
1311.Bl -tag -width lc -compact
1312.It Xo
1313.Ic xinstall
1314.Op Fl c
1315.Op Fl B Ar suffix
1316.Op Fl b
1317.Op Fl C
1318.Op Fl f Ar flags
1319.Op Fl g Ar group
1320.Op Fl M
1321.Op Fl m Ar mode
1322.Op Fl o Ar owner
1323.Op Fl p
1324.Op Fl S
1325.Op Fl s
1326.Op Fl W Ar dir
1327.Op Ar
1328.Ar destination
1329.Xc
1330.It Xo
1331.Ic xinstall
1332.Fl d
1333.Op Fl B Ar suffix
1334.Op Fl b
1335.Op Fl C
1336.Op Fl f Ar flags
1337.Op Fl g Ar group
1338.Op Fl M
1339.Op Fl m Ar mode
1340.Op Fl o Ar owner
1341.Op Fl p
1342.Op Fl S
1343.Op Fl s
1344.Op Fl W Ar dir
1345.Ar directory
1346.Xc
1347Install file(s) to a target file or directory. The options are
1348intended to be compatible with
1349.Xr install 1 :
1350.Bl -tag -width indent
1351.It Fl b
1352Backup any existing files with an
1353.Pa .old
1354extension.
1355.It Fl B
1356Specify a different backup suffix for the
1357.Fl b
1358flag.
1359.It Fl c
1360Install files (this is the default).
1361.It Fl C
1362Only copy a file if it is different.
1363.It Fl d
1364Create directories, including (if necessary) parent directories.
1365.It Fl f
1366Specify target flags, see
1367.Xr chflags 1
1368for details.
1369.It Fl g
1370Specify the group.
1371.It Fl M
1372Disable use of
1373.Xr mmap 2 .
1374.It Fl m
1375Specify an alternate mode. The default is 0755. See
1376.Xr chmod 1
1377for defails.
1378.It Fl p
1379Preserve the modification time.
1380.It Fl S
1381Copy safely, using a temporary file.
1382.It Fl s
1383Strip binaries using
1384.Xr strip 1 .
1385.It Fl W
1386Change to
1387.Ar dir
1388before working.
1389.El
1390.El
1391.It Xo
1392.Ic curl fetch
1393.Ar url
1394.Ar file
1395.Xc
1396Fetch a resource at
1397.Ar url
1398and save it to
1399.Ar file .
1400.It Xo
1401.Ic curl isnewer
1402.Ar url
1403.Ar date
1404.Xc
1405Determine if resource at
1406.Ar url
1407is newer than
1408.Ar date
1409(expressed in seconds since epoch).
1410.It Xo
1411.Ic adduser
1412.Ar username
1413.Op Cm uid Ns = Ns uid
1414.Op Cm gid Ns = Ns gid
1415.Op Cm passwd Ns = Ns passwd
1416.Op Cm realname Ns = Ns realname
1417.Op Cm home Ns = Ns home
1418.Op Cm shell Ns = Ns shell
1419.Xc
1420Add a new local user to the system with the specified uid, gid,
1421password, real name, home directory and login shell.
1422.It Ic existsuser Ar username
1423Check if a local user exists.
1424.It Ic nextuid
1425Returns the highest used uid plus one.
1426.It Xo
1427.Ic addgroup
1428.Ar group
1429.Op Cm gid Ns = Ns gid
1430.Op Cm passwd Ns = Ns passwd
1431.Op Cm users Ns = Ns users
1432.Xc
1433Add a new local group to the system, with the specified gid, password
1434and with a list users as members.
1435.It Ic existsgroup Ar group
1436Check if a local group exists and return the corresponding gid. This can be used
1437with adduser:
1438.Dl addgroup foo
1439.Dl adduser foo gid=[existsgroup foo]
1440.It Ic nextgid
1441Returns the highest used gid plus one.
1442.It Ic reinplace Ar regex Ar filename
1443Provide in-place sed like editing of a file.
1444.br
1445.Sy Example:
1446.Dl reinplace \*qs|/usr/local|${prefix}|g\*q doc/manpage.1
1447.It Ic file
1448Standard TCL command to manipulate file names and attributes, recommended if you wish to preserve Mac OS
1449resource forks when destrooting ports on Mac OS X 10.3.x and Mac OS X 10.4.x . Use
1450.Nm xinstall
1451to also preserve Extended Attributes (i.e. Access Control Lists). See
1452.Xr file n .
1453.It Ic copy
1454An alternative to "file -copy".
1455.It Ic move
1456An alternative to "file -rename".
1457.It Ic delete
1458An alternative to "file -delete". It is required on OS X 10.3 and earlier to delete directories because
1459of an ananomaly in 10.3's version of Tcl that makes "file -delete" fail.
1460.It Ic touch
1461Mimics the BSD touch command.
1462.It Ic ln
1463.br
1464Mimics the BSD ln command.
1465.It Ic system Ar commandline
1466Execute a program. See
1467.Xr system 3 .
1468For calls to
1469.Xr install 1
1470please use
1471.Nm xinstall .
1472For calls to
1473.Xr mv 1 ,
1474.Xr cp 1 ,
1475.Xr rm 1
1476or similar, please use
1477.Nm file .
1478.It Ic variant_isset Ar variant
1479Checks if the given
1480.Ar variant
1481is being built.
1482.It Ic variant_set Ar variant
1483Set the given
1484.Ar variant .
1485.It Ic variant_unset Ar variant
1486Unset the given
1487.Ar variant .
1488.It Va variable Ns - Ns Ic append Ar item
1489Append
1490.Ar item
1491to the
1492.Va variable .
1493.br
1494.Sy Example:
1495.Dl configure.args-append --with-gnomedb
1496.It Va variable Ns - Ns Ic delete Ar item
1497Delete
1498.Ar item
1499from the
1500.Va variable .
1501.br
1502.Sy Example:
1503.Dl configure.args-delete --with-gnomedb
1504.It Ic readdir Ar directory
1505Return the list of elements in a
1506.Ar directory ,
1507excluding
1508.Pa \&.
1509and
1510.Pa \&.. .
1511.It Ic strsed Ar string Ar pattern
1512Perform
1513.Xr ed 1 Ns / Ns
1514.Xr tr 1 Ns -like
1515search, replace, and transliteration on a string.
1516.It Ic mktemp Ar template
1517Create a temporary file using a
1518.Ar template .
1519See
1520.Xr mktemp 3 .
1521.It Ic mkstemp Ar template
1522Create a temporary file securely using a
1523.Ar template .
1524See
1525.Xr mkstemp 3 .
1526.It Ic md5 Ar
1527Compute the MD5 hashes of the file(s).
1528.It Ic rpm-vercomp Ar versionA Ar versionB
1529Compare two RPM-format versions for equality.
1530.It Ic sudo Ar password Ar command Ar \&...
1531Execute
1532.Ar command
1533using
1534.Cm sudo
1535with the provided password.
1536.El
1537.Pp
1538.Bl -tag -width lc -compact
1539.It Ic ui_debug Ar message
1540.It Ic ui_error Ar message
1541.It Ic ui_info Ar message
1542.It Ic ui_msg Ar message
1543.It Ic ui_warn Ar message
1544Display a
1545.Ar message
1546to the user, at various different levels.
1547.br
1548.Sy Example:
1549.Dl ui_msg \*qAdd each user to the system using the clamav command\*q
1550.El
1551.Sh SEE ALSO
1552.Xr port 1 ,
1553.Xr ports.conf 5 ,
1554.Xr portgroup 7 ,
1555.Xr portstyle 7 ,
1556.Xr porthier 7 ,
1557.Xr file n
1558.Sh AUTHORS
1559.An "Landon Fuller" Aq landonf@macports.org
1560.An "Juan Manuel Palacios" Aq jmpp@macports.org
1561.An "Mark Duling" Aq markd@macports.org
1562.An "Kevin Van Vechten" Aq kevin@opendarwin.org
1563.An "Jordan K. Hubbard" Aq jkh@opendarwin.org
1564.An "Chris Ridd" Aq cjr@opendarwin.org