Ticket #4905: portfile.7

File portfile.7, 30.5 KB (added by markd@…, 18 years ago)

Updated portfile.7

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