Context Navigation

Back to Ticket #11445

Ticket #11445: portfile.7

File portfile.7, 32.3 KB (added by markd@…, 17 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
37	A complete reference of all available
38	.Nm
39	variables and example syntax.
40	.Nm Portfiles
41	consist of valid TCL, allowing for simple key/value pair syntax as well
42	as utilization of TCL's extensive functionality.
43	.Nm Portfiles
44	are encoded in UTF-8.
45	.Pp
46	The
47	.Nm Macports System
48	uses a target dependency system based on a
49	depends/provides model, allowing for targets to be registered and
50	executed in the correct order based on their individual requirements.
51	.Pp
52	A
53	.Nm
54	author needs to be aware of the various standard targets, the options
55	that they require and the variables that both the targets and the port
56	system provide.
57	.Sh PORTSYSTEM
58	Portfiles must begin with a PortSystem line that defines which version of the
59	Portfile interpreter should be used.
60	.br
61	.Sy Synopsis:
62	.Dl PortSystem 1.0
63	.Sh MAIN VARIABLES
64	All ports are required to set certain variables.
65	.Bl -tag -width lc
66	.It Ic name
67	Full name of port.
68	.br
69	.Sy Type:
70	.Em required
71	.br
72	.Sy Example:
73	.Dl name XFree86
74	.It Ic version
75	Upstream 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
83	If a port's version numbering changes such that a newer version looks
84	older than the previous version, the
85	.Ic epoch
86	should be increased. Often the
87	.Ic epoch
88	is 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
99	One 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
107	A 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
114	long_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
125	Local revision number of
126	.Nm .
127	Increment 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
138	Categories 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
146	E-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
154	Declares 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
165	Project 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
173	List of sites to fetch
174	.Ic distfiles
175	from or a predefined mirror site
176	list. If set to a predefined mirror site, without a subdirectory being
177	defined, 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
184	master_sites ftp://ftp.cdrom.com/pub/magic \e\
185
186	sourceforge
187	.Ed
188	.It Ic worksrcdir
189	Path 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
201	Name 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
216	List of checksums for the
217	.Ic distfiles .
218	The checksum
219	.Ar type
220	can currently be md5, rmd160 or sha1. The
221	.Ar filename
222	can 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
229	checksums 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
235	checksums md5 a2d38ba641682509c1e964ad699a9dd2 \e\
236	sha1 1fb6443b5fdf3c83787953f06282d256477c1288
237	.Ed
238	.br
239	.Sy Example (ssldump 0.9b3):
240	.Bd -literal -offset indent -compact
241	checksums md5 ac8c28fe87508d6bfb06344ec496b1dd \e\
242	sha1 a633a9a811a138eac5ed440d583473b644135ef5 \e\
243	rmd160 941cf8f2ef8459ec4f9ce65772e134505d46566
244	.Ed
245	.It Ic use_automake
246	If set to yes, run the
247	.Cm automake
248	target to build any
249	.Pa Makefile.in
250	files 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
262	If set to yes, run the
263	.Cm autoconf
264	target to build any
265	.Pa configure
266	script 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
277	If set to yes, run the
278	.Cm configure
279	target 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
291	A number of hooks are available for customizing many of the standard
292	targets that
293	.Xr port 1
294	executes. The targets supporting these hooks are
295	.Cm fetch ,
296	.Cm automake ,
297	.Cm autoconf ,
298	.Cm configure ,
299	.Cm build ,
300	.Cm destroot ,
301	and
302	.Cm test .
303	The hooks are:
304	.Bl -tag -width lc
305	.It Va target Ns Ic .dir
306	Directory 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
312	Change the environment the
313	.Va target
314	is run in. This is often overridden on a per
315	.Nm
316	basis.
317	.br
318	.Sy Example:
319	.Dl configure.env CFLAGS=-O
320	.It Va target Ns Ic .pre_args
321	Additional arguments passed before the main arguments.
322	.br
323	.Sy Example:
324	.Dl extract.pre_args -cd
325	.It Va target Ns Ic .args
326	Main arguments to pass to the
327	.Va target .
328	This is often overridden on a per
329	.Nm
330	basis.
331	.br
332	.Sy Example:
333	.Dl configure.args --enable-fooble
334	.It Va target Ns Ic .post_args
335	Additional 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
341	For 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
344	Arguments 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
352	Value 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
360	Value 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
368	Environment 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
377	Read-only access to the MacPorts configuration is provided.
378	.Bl -tag -width lc
379	.It Ic prefix
380	Install prefix
381	.br
382	.Sy Type:
383	.Em optional
384	.br
385	.Sy Default:
386	.Em /opt/local
387	.It Ic libpath
388	Location of ports-specific TCL libraries.
389	.br
390	.Sy Type:
391	.Em read-only
392	.It Ic portpath
393	Full path to the Portfile location.
394	.br
395	.Sy Type:
396	.Em read-only
397	.It Ic workdir
398	Path to work directory relative to
399	.Ic portpath .
400	Where possible use
401	.Ic workpath
402	instead.
403	.br
404	.Sy Type:
405	.Em read-only
406	.br
407	.Sy Default:
408	.Em work
409	.It Ic workpath
410	Full 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
418	Full 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
426	Path 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
435	Location 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
443	Identifies hardware type (eg "powerpc").
444	.br
445	.Sy Type:
446	.Em read-only
447	.It Ic os.version
448	Version number of operating system (eg "7.0").
449	.br
450	.Sy Type:
451	.Em read-only
452	.It Ic os.endian
453	Endianness of the processor (eg "bigEndian").
454	.br
455	.Sy Type:
456	.Em read-only
457	.It Ic os.platform
458	Operating system name (eg "darwin").
459	.br
460	.Sy Type:
461	.Em read-only
462	.It Ic install.user
463	User for MacPorts installation (eg
464	.Pa root )
465	.br
466	.Sy Type:
467	.Em read-only
468	.It Ic install.group
469	Group for MacPorts installation (eg
470	.Pa wheel )
471	.br
472	.Sy Type:
473	.Em read-only
474	.It Ic x11prefix
475	Absolute path to X11 (eg
476	.Pa /usr/X11R6 )
477	.br
478	.Sy Type:
479	.Em read-only
480	.El
481	.Sh DEPENDENCY OPTIONS
482	Port dependencies should refer to other MacPort ports
483	whenever possible, therefore each dependency should be
484	expressed in the format:
485	.Bl -tag -width ls
486	.It port: Ns Ao port Ac
487	.El
488	.Pp
489	Where
490	.Ao port Ac represents the name of an existing MacPorts
491	.Nm port .
492	If satisfying a dependency with a MacPorts port is not
493	practical and it is likely that a dependency must be met
494	by an Apple optional install, then the alternative dependency
495	format:
496	.Bl -tag -width lc
497	.It Ar type Ns : Ns Ao filename Ac Ns : Ns Ao port Ac
498	.El
499	.Pp
500	may be used. Where
501	.Ar type
502	is "bin" if
503	.Ao filename Ac
504	is a program, "lib" if it is a library, or "path" if it is a path to an
505	installed file.
506	.br
507	.Sy Example:
508	.Dl lib:libX11.6:XFree86
509	.Bl -tag -width lc
510	.It Ic depends_build
511	List of dependencies to check before
512	.Cm build ,
513	.Cm destroot ,
514	.Cm install ,
515	and
516	.Cm package
517	targets.
518	.br
519	.Sy Type:
520	.Em optional
521	.br
522	.Sy Example:
523	.Dl depends_build port:autoconf
524	.It Ic depends_run
525	List of dependencies to check before
526	.Cm destroot ,
527	.Cm install
528	and
529	.Cm package
530	targets.
531	.br
532	.Sy Type:
533	.Em optional
534	.br
535	.Sy Example:
536	.Dl depends_run port:bash
537	.It Ic depends_lib
538	List of dependencies to check before
539	.Cm configure ,
540	.Cm build ,
541	.Cm destroot ,
542	.Cm install ,
543	and
544	.Cm package
545	targets.
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
554	Fetch all distribution files and patches.
555	.Bl -tag -width lc
556	.It Ic master_sites.mirror_subdir
557	Subdirectory to append to all mirror sites for any list specified in
558	master_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
569	List of sites to fetch
570	.Ic patchfiles
571	from 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
582	Subdirectory 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
594	Suffix 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
606	List 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
618	List 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
626	Use zip.
627	.br
628	Sets extract.suffix to: .zip
629	.br
630	Sets extract.cmd to: unzip
631	.br
632	Sets extract.pre_args to: -q
633	.br
634	Sets 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
642	Use bzip2.
643	.br
644	Sets extract.suffix to: .bzip2
645	.br
646	Sets 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
654	Create a sub-directory in
655	.Ic distpath
656	to 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
668	Some mirrors require special options for a resource to be properly
669	fetched.
670	.Bl -tag -width lc
671	.It Ic fetch.user
672	HTTP or FTP user to fetch the resource.
673	.br
674	.Sy Type:
675	.Em optional
676	.It Ic fetch.password
677	HTTP or FTP password to fetch the resource.
678	.br
679	.Sy Type:
680	.Em optional
681	.It Ic fetch.use_epsv
682	Whether 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
692	As an alternative to fetching distribution files, pulling the sources
693	from a CVS repository is supported. Use of CVS can give rise to
694	non-reproducible builds, so it is strongly discouraged.
695	.Bl -tag -width lc
696	.It Ic cvs.root
697	Specify 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
708	Specify 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
719	A 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
730	A 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
742	As an alternative to fetching distribution files, pulling the sources
743	from a subversion repository is supported. Use of subversion can give
744	rise to non-reproducible builds, so it is strongly discouraged.
745	.Bl -tag -width lc
746	.It Ic svn.url
747	Specify 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
759	Specify the a tag from which svn should fetch files. This
760	corresponds 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
773	Extract all compressed/archived files.
774	.Bl -tag -width lc
775	.It Ic extract.only
776	List 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
788	Command 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
800	Execute necessary build commands.
801	.Bl -tag -width lc
802	.It Ic build.cmd
803	Make 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
815	Defines which 'make' is required, either 'gnu' or 'bsd'.
816	Sets
817	.Ic build.cmd
818	to either
819	.Pa gnumake
820	or
821	.Pa bsdmake
822	accordingly.
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
833	Target 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
846	Execute necessary commands to install into a temporary destination root
847	("destroot") staging area.
848	.Bl -tag -width lc
849	.It Ic destroot.cmd
850	Install 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
862	Defines which 'make' is required, either 'gnu' or 'bsd'.
863	Sets
864	.Ic destroot.cmd
865	to either
866	.Pa gnumake
867	or
868	.Pa bsdmake
869	accordingly.
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
880	Arguments passed to
881	.Ic destroot.cmd
882	in order to install correctly
883	into 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
894	Install 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
906	Umask 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
917	List of directories that should not be pruned if empty upon
918	.Cm destroot
919	completion.
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
928	Execute commands to run test suites bundled with a port.
929	.Bl -tag -width lc
930	.It Ic test.run
931	Enable 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
939	Test 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
951	Test 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
964	If a port needs to run on system startup, it can use MacPorts
965	startupitem keywords to install native OS X startup scripts.
966	Startup scripts require user interaction after port installation
967	to activate them and instructions are given during port installs.
968	.Bl -tag -width lc
969	.It Ic startupitem.create
970	Choose 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
984	Select the type of startupitem to generate. By default, a startupitem
985	will be generated that is of the appropriate type for the OS. For
986	instance, launchd is used on system 10.4, while SystemStarter is used
987	on 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
1001	Displayed 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
1009	The name of the daemon to be run in the background. This is
1010	the preferred type of startup item rather than any of
1011	startupitem.init, startupitem.start, startupitem.stop, or
1012	startupitem.restart, and may not be used together with any
1013	of these options. This option may contain multiple
1014	arguments, but they must be appropriate for a call to exec; they
1015	may 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
1026	Shell code that will be executed prior to any of the options
1027	startupitem.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
1038	Shell 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
1049	Shell 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
1060	Shell code executed to restart the daemon. In the absence
1061	of this key, the daemon will be restarted by taking the
1062	stop 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
1073	Specification for pidfile handling. This is particularly useful
1074	in conjunction with the startupitem.executable key, because it is
1075	important that the startupitem know how to track the executable.
1076	This specifies whether the daemon generates its own pidfile (auto),
1077	whether it generates its own but forgets to delete it, so that the
1078	startupitem should delete it (clean), or whether it never generates
1079	one, in which case the startupitem should manage the pidfile on its
1080	own (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
1094	Path to a logfile for logging events about the lifetime of the
1095	startupitem. Depending on the type of startupitem, and the manner
1096	in which it is started, standard output from the daemon may also be
1097	directed 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
1111	Control whether or not to log events to the log file. If logevents
1112	is 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
1127	MacPorts can automatically check if the software has been updated
1128	since the Portfile was modified and if some external changes require
1129	an update to the Portfile. This helps maintainers have up-to-date
1130	and working Portfiles.
1131	.br
1132	Two checks are available. With distcheck, MacPorts can check that the
1133	distfile(s) are still downloadable and did not change since the portfile
1134	was modified.
1135	With livecheck, MacPorts can query a resource to determine if a newer
1136	version of the software is available.
1137	.Bl -tag -width lc
1138	.It Ic distcheck.check
1139	This option can be used to disable distcheck. It specifies what kind
1140	of 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
1155	What kind of check to perform to figure out if the software has been updated.
1156	Can 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
1177	or
1178	.Em sourceforge
1179	if the master_sites is sourceforge.
1180	.br
1181	.Sy Values:
1182	.Em freshmeat sourceforge moddate regex regexm md5 none
1183	.It Ic livecheck.name
1184	Name 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}
1191	or the sourceforge project name if it can be guessed by looking at the master_sites.
1192	.It Ic livecheck.version
1193	Version 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
1201	URL to query for the check.
1202	.br
1203	.Sy Type:
1204	.Em optional
1205	.br
1206	.Sy Default:
1207	.Em ${homepage}
1208	or
1209	.Em http://freshmeat.net/projects-xml/${livecheck.name}/${livecheck.name}.xml
1210	or
1211	.Em http://sourceforge.net/export/rss2_projfiles.php?project=${livecheck.name}
1212	.It Ic livecheck.regex
1213	Regular expression to parse the resource for regex checks.
1214	.br
1215	.Sy Type:
1216	.Em optional
1217	.It Ic livecheck.md5
1218	md5 sum to use for md5 comparison.
1219	.br
1220	.Sy Type:
1221	.Em optional
1222	.El
1223	.Sh VARIANT OPTIONS
1224	MacPorts allows for conditional modification to be specified in a
1225	.Nm ,
1226	allowing 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
1233	The value is usually a TCL script which modifies other port's
1234	.Nm
1235	variables. Dependencies and conflicts with other variants in the same
1236	port can be expressed with
1237	.Cm requires
1238	and
1239	.Cm conflicts .
1240	The 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
1247	variant 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
1252	If variants are defined, then the
1253	.Ic default_variants
1254	value 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
1263	MacPorts allows for platform-specific conditional modification to be
1264	specified in a
1265	.Nm ,
1266	much like variants, for handling differences between platforms and
1267	versions 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
1275	The platform key is used to begin the darwin platform definitions as
1276	shown in the examples from the databases/db4 and devel/libidl1
1277	.Nm Portfiles
1278	respectively.
1279	.br
1280	.Sy Type:
1281	.Em optional
1282	.br
1283	.Sy Example:
1284	.Bd -literal -offset indent -compact
1285	platform 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
1292	platform darwin powerpc { configure.args-append \e\
1293
1294	--host=${os.arch}-apple-rhapsody${os.version} }
1295	platform darwin i386 { configure.args-append \e\
1296
1297	--host=i386-gnu-rhapsody${os.version} }
1298	.Ed
1299	.El
1300	.Sh PORTGROUP
1301	To factorize the work with similar ports, MacPorts provides the notion of
1302	.Nm PortGroup
1303	that can be used to load definitions for a given class or group of ports. See
1304	.Xr portgroup 7
1305	for more details on the various PortGroup classes.
1306	.Sh TCL EXTENSIONS
1307	A 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
1347	Install file(s) to a target file or directory. The options are
1348	intended to be compatible with
1349	.Xr install 1 :
1350	.Bl -tag -width indent
1351	.It Fl b
1352	Backup any existing files with an
1353	.Pa .old
1354	extension.
1355	.It Fl B
1356	Specify a different backup suffix for the
1357	.Fl b
1358	flag.
1359	.It Fl c
1360	Install files (this is the default).
1361	.It Fl C
1362	Only copy a file if it is different.
1363	.It Fl d
1364	Create directories, including (if necessary) parent directories.
1365	.It Fl f
1366	Specify target flags, see
1367	.Xr chflags 1
1368	for details.
1369	.It Fl g
1370	Specify the group.
1371	.It Fl M
1372	Disable use of
1373	.Xr mmap 2 .
1374	.It Fl m
1375	Specify an alternate mode. The default is 0755. See
1376	.Xr chmod 1
1377	for defails.
1378	.It Fl p
1379	Preserve the modification time.
1380	.It Fl S
1381	Copy safely, using a temporary file.
1382	.It Fl s
1383	Strip binaries using
1384	.Xr strip 1 .
1385	.It Fl W
1386	Change to
1387	.Ar dir
1388	before working.
1389	.El
1390	.El
1391	.It Xo
1392	.Ic curl fetch
1393	.Ar url
1394	.Ar file
1395	.Xc
1396	Fetch a resource at
1397	.Ar url
1398	and save it to
1399	.Ar file .
1400	.It Xo
1401	.Ic curl isnewer
1402	.Ar url
1403	.Ar date
1404	.Xc
1405	Determine if resource at
1406	.Ar url
1407	is 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
1420	Add a new local user to the system with the specified uid, gid,
1421	password, real name, home directory and login shell.
1422	.It Ic existsuser Ar username
1423	Check if a local user exists.
1424	.It Ic nextuid
1425	Returns 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
1433	Add a new local group to the system, with the specified gid, password
1434	and with a list users as members.
1435	.It Ic existsgroup Ar group
1436	Check if a local group exists and return the corresponding gid. This can be used
1437	with adduser:
1438	.Dl addgroup foo
1439	.Dl adduser foo gid=[existsgroup foo]
1440	.It Ic nextgid
1441	Returns the highest used gid plus one.
1442	.It Ic reinplace Ar regex Ar filename
1443	Provide 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
1448	Standard TCL command to manipulate file names and attributes, recommended if you wish to preserve Mac OS
1449	resource forks when destrooting ports on Mac OS X 10.3.x and Mac OS X 10.4.x . Use
1450	.Nm xinstall
1451	to also preserve Extended Attributes (i.e. Access Control Lists). See
1452	.Xr file n .
1453	.It Ic copy
1454	An alternative to "file -copy".
1455	.It Ic move
1456	An alternative to "file -rename".
1457	.It Ic delete
1458	An alternative to "file -delete". It is required on OS X 10.3 and earlier to delete directories because
1459	of an ananomaly in 10.3's version of Tcl that makes "file -delete" fail.
1460	.It Ic touch
1461	Mimics the BSD touch command.
1462	.It Ic ln
1463	.br
1464	Mimics the BSD ln command.
1465	.It Ic system Ar commandline
1466	Execute a program. See
1467	.Xr system 3 .
1468	For calls to
1469	.Xr install 1
1470	please use
1471	.Nm xinstall .
1472	For calls to
1473	.Xr mv 1 ,
1474	.Xr cp 1 ,
1475	.Xr rm 1
1476	or similar, please use
1477	.Nm file .
1478	.It Ic variant_isset Ar variant
1479	Checks if the given
1480	.Ar variant
1481	is being built.
1482	.It Ic variant_set Ar variant
1483	Set the given
1484	.Ar variant .
1485	.It Ic variant_unset Ar variant
1486	Unset the given
1487	.Ar variant .
1488	.It Va variable Ns - Ns Ic append Ar item
1489	Append
1490	.Ar item
1491	to 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
1497	Delete
1498	.Ar item
1499	from the
1500	.Va variable .
1501	.br
1502	.Sy Example:
1503	.Dl configure.args-delete --with-gnomedb
1504	.It Ic readdir Ar directory
1505	Return the list of elements in a
1506	.Ar directory ,
1507	excluding
1508	.Pa \&.
1509	and
1510	.Pa \&.. .
1511	.It Ic strsed Ar string Ar pattern
1512	Perform
1513	.Xr ed 1 Ns / Ns
1514	.Xr tr 1 Ns -like
1515	search, replace, and transliteration on a string.
1516	.It Ic mktemp Ar template
1517	Create a temporary file using a
1518	.Ar template .
1519	See
1520	.Xr mktemp 3 .
1521	.It Ic mkstemp Ar template
1522	Create a temporary file securely using a
1523	.Ar template .
1524	See
1525	.Xr mkstemp 3 .
1526	.It Ic md5 Ar
1527	Compute the MD5 hashes of the file(s).
1528	.It Ic rpm-vercomp Ar versionA Ar versionB
1529	Compare two RPM-format versions for equality.
1530	.It Ic sudo Ar password Ar command Ar \&...
1531	Execute
1532	.Ar command
1533	using
1534	.Cm sudo
1535	with 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
1544	Display a
1545	.Ar message
1546	to 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

Download in other formats:

Original Format