source: trunk/base/doc/portfile.7 @ 3882

Last change on this file since 3882 was 3882, checked in by fkr, 17 years ago

Bug:
Submitted by: wbb4@
Reviewed by:
Approved by:
Obtained from:

platform key support by wbb4@. see portfile(7) for syntax.

  • Property svn:eol-style set to native
File size: 15.6 KB
Line 
1.\" portfite.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 17, 2003
31.Dt PORTFILE 7 "Apple Computer, Inc."
32.Os
33.Sh NAME
34.Nm Portfile
35.Nd darwin ports 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 as
42utiliziation of TCL's extensive functionality.
43.Pp
44The
45.Nm Darwin Ports System
46uses a target dependency system based on a
47depends/provides model, allowing for targets to be registered and
48executed in the correct order based on their individual requirements.
49.Pp
50A
51.Nm
52author needs to be aware of the various standard targets, the options that they
53require, and the variables that both the targets and the port system provides.
54.Sh TARGETS
55.Tp
56.Ss MAIN OPTIONS
57Neccesary standard options
58.Bl -tag -width lc
59.It Ic prefix
60Install prefix
61.br
62.Sy Type:
63.Em optional
64.Sy Default:
65.Em /opt/local
66.It Ic libpath
67Locate of ports-specific TCL libraries
68.br
69.Sy Type:
70.Em read-only
71.It Ic workdir
72Path to work directory relative to ${portpath}
73.br
74.Sy Type:
75.Em read-only
76.Sy Default:
77.Em work
78.It Ic workpath
79Full path to work directory
80.br
81.Sy Type:
82.Em read-only
83.Sy Default:
84.Em ${portpath}/${workdir}
85.It Ic name
86Full name of port
87.br
88.Sy Type:
89.Em required
90.br
91.Sy Example:
92.Dl name        XFree86
93.It Ic version
94Upstream version of software
95.br
96.Sy Type:
97.Em required
98.br
99.Sy Example:
100.Dl version     4.2.1
101.It Ic description
102One line description of the software and what it does
103.br
104.Sy Type:
105.Em required
106.br
107.Sy Example:
108.Dl description "Dictionary Server Protocol (RFC2229) client"
109.It Ic long_description
110A verbose description of the software and what it does
111.br
112.Sy Type:
113.Em required
114.br
115.Sy Example:
116.Dl long_description    The GNU Image Manipulation Program (GIMP) is a powerful tool for the preparation and manipulation of digital images.  The GIMP provides the user with a wide variety of image manipulation, painting, processing, and rendering tools.
117.It Ic revision
118Local revision number of portfile.
119Increment for port revisions.
120.br
121.Sy Type:
122.Em optional
123.Sy Default:
124.Em 0
125.br
126.Sy Example:
127.Dl revision    1
128.It Ic categories
129Categories to which this port belongs
130.br
131.Sy Type:
132.Em required
133.br
134.Sy Example:
135.Dl categories  spelling textproc
136.It Ic maintainers
137E-mail address(es) of port maintainer(s)
138.br
139.Sy Type:
140.Em required
141.br
142.Sy Example:
143.Dl maintainers landonf@opendarwin.org kevin@opendarwin.org
144.It Ic platforms
145Declares which platforms are supported by the port
146.br
147.Sy Type:
148.Em required
149.br
150.Sy Values:
151.Em darwin freebsd
152.br
153.Sy Example:
154.Dl platforms   darwin
155.It Ic worksrcdir
156Path to source directory relative to ${workpath}
157.br
158.Sy Type:
159.Em optional
160.Sy Default:
161.Em ${distname}
162.br
163.Sy Example:
164.Dl worksrcdir  ${distname}-src-${version}
165.It Ic worksrcpath
166Full path to working sources (where port has unpacked itself)
167.br
168.Sy Type:
169.Em read-only
170.Sy Default:
171.Em ${workpath}/${worksrcdir}
172.It Ic filedir
173Path to port files relative to ${portpath}
174.br
175.Sy Type:
176.Em read-only
177.Sy Default:
178.Em files
179.It Ic distname
180Name of distibution file, minus extract suffix
181.br
182.Sy Type:
183.Em optional
184.Sy Default:
185.Em ${name}-${version})
186.br
187.Sy Example:
188.Dl distname    ${name}-${version}-src
189.It Ic distpath
190Location to store downloaded distfiles
191.br
192.Sy Type:
193.Em read-only
194.Sy Default:
195.Em ${sysportpath}/distfiles
196.It Ic os_arch
197Identifies hardware type (ie, "Power Macintosh")
198.br
199.Sy Type:
200.Em read-only
201.It Ic os_version
202Version number of operating system (ie "6.0")
203.br
204.Sy Type:
205.Em read-only
206.El
207.Ss DEPENDS OPTIONS
208Checking and building of dependencies
209.Bl -tag -width lc
210.It Ic depends_fetch
211List of dependencies to check before running fetch target
212.br
213.Sy Type:
214.Em optional
215.br
216.Sy Example:
217.Dl depends_fetch       bin:fetch:net/fetch bin:wget:wget
218.It Ic depends_build
219List of dependencies to check before build, destroot, install, and package targets
220.br
221.Sy Type:
222.Em optional
223.br
224.Sy Example:
225.Dl depends_build       bin:autoconf:autoconf
226.It Ic depends_run
227List of dependencies to check before destroot, install and package targets
228.br
229.Sy Type:
230.Em optional
231.br
232.Sy Example:
233.Dl depends_run bin:bash:bash
234.It Ic depends_extract
235List of dependencies to check before extract target
236.br
237.Sy Type:
238.Em optional
239.br
240.Sy Example:
241.Dl depends_extract     bin:bzip2:bzip2
242.It Ic depends_lib
243List of dependencies to check before configure, build, destroot, install, and package targets
244.br
245.Sy Type:
246.Em optional
247.br
248.Sy Example:
249.Dl depends_lib lib:libfetch.3:libfetch
250.El
251.Ss FETCH OPTIONS
252Fetch all distribution files and patches
253.Bl -tag -width lc
254.It Ic master_sites
255List of sites to fetch ${distfiles} from or a predefined mirror site list. If set to a predefined mirror site,
256without a subdirectory being defined, the portname is used as the name of the subdirectory.
257.br
258.Sy Type:
259.Em required
260.br
261.Sy Example:
262.Dl master_sites        ftp://ftp.cdrom.com/pub/magic \
263                        sourceforge
264.It Ic patch_sites
265List of sites to fetch ${patchfiles} from or a predefined mirror site list
266.br
267.Sy Type:
268.Em optional
269.Sy Default:
270.Em ${master_sites}
271.br
272.Sy Example:
273.Dl patch_sites ftp://ftp.patchcityrepo.com/pub/magic/patches
274.It Ic master_sites.mirror_subdir
275Subdirectory to append to all mirror sites for any list specified in master_sites.
276.br
277.Sy Type:
278.Em optional
279.Sy Default:
280.Em ${name}
281.br
282.Sy Example:
283.Dl master_sites.mirror_subdir      magic
284.It Ic patch_sites.mirror_subdir
285Subdirectory to append to all mirror sites for any list specified in patch_sites.
286.br
287.Sy Type:
288.Em optional
289.Sy Default:
290.Em ${name}
291.br
292.Sy Example:
293.Dl patch_sites.mirror_subdir       magic
294.It Ic extract.sufx
295Suffix to append to ${distname}
296.br
297.Sy Type:
298.Em optional
299.Sy Default:
300.Em .tar.gz
301.br
302.Sy Example:
303.Dl extract.sufx        .tgz
304.It Ic distfiles
305List of distribution files to fetch from ${master_sites}
306.br
307.Sy Type:
308.Em optional
309.Sy Default:
310.Em [suffix ${distname}]
311.br
312.Sy Example:
313.Dl distfiles   magicsource.tar.gz cluebat.tar.bz2
314.It Ic patchfiles
315List of patches to fetch and apply
316.br
317.Sy Type:
318.Em optional
319.br
320.Sy Example:
321.Dl patchfiles  japanese-widechar-fix.diff japanese-localization.diff
322.It Ic use_zip
323Use zip.
324.br
325Sets extract.sufx to: .zip
326.br
327Sets extract.cmd to: unzip
328.br
329Sets extract.pre_args to: -q
330.br
331Sets extract.post_args to: "-d $portpath/$workdir"
332.br
333.Sy Type:
334.Em optional
335.br
336.Sy Example:
337.Dl use_zip             yes
338.It Ic use_bzip2
339Use bzip2.
340.br
341Sets extract.sufx to: .bzip2
342.br
343Sets extract.cmd to: bzip2
344.br
345.Sy Type:
346.Em optional
347.br
348.Sy Example:
349.Dl use_bzip2   yes
350.It Ic dist_subdir
351Create a sub-directory in ${distpath} to store all fetched files.
352.br
353.Sy Type:
354.Em optional
355.br
356.Sy Example:
357.Dl dist_subdir vim${version}
358.El
359.Ss CHECKSUM OPTIONS
360Compare checksums of all fetched files
361.Bl -tag -width lc
362.It Ic checksums
363List of checksums in the format: <file name> <checksum type> <checksum>
364Currently, the only supported checksum type is md5
365.br
366.Sy Type:
367.Em required
368.br
369.Sy Example:
370.Dl checkums    dictd-1.7.1.tar.gz md5 81317b86ea0a5df0163900ad2e6bb12c \
371                                magic-words-1.7.1.tar.gz md5 897a005182928613eadd30c267ce9c5b
372.El
373.Ss EXTRACT OPTIONS
374Extract all compressed/archived files
375.Bl -tag -width lc
376.It Ic extract.only
377List of files to extract into ${workpath}
378.br
379.Sy Type:
380.Em optional
381.Sy Default:
382.Em ${distfiles}
383.br
384.Sy Example:
385.Dl extract.only        worksrc-1.4.4.tar.gz
386.It Ic extract.cmd
387Command to perform extract
388.br
389.Sy Type:
390.Em optional
391.Sy Default
392.Em gzip
393.br
394.Sy Example:
395.Dl extract.cmd bzip2
396.It Ic extract.pre_args
397Arguments added to extract command before a file name
398.br
399.Sy Type:
400.Em optional
401.Sy Default:
402.Em -dc
403.br
404.Sy Example:
405.Dl extract.pre_args    -cd
406.It Ic extract.args
407Arguments to extract.cmd
408.br
409.Sy Type:
410.Em read-only
411.Sy Default:
412.Em ${distpath}/${distfile}
413.It Ic extract.post_args
414Arguments added to extract command after a file name
415.br
416.Sy Type:
417.Em optional
418.Sy Default:
419.Em "| tar -xf -"
420.br
421.Sy Example:
422.Dl extract.post_args   | tar -x -s@bladeenc-0.94.2/other_makefiles/BladeEnc..@@p -f -
423.El
424.Ss PATCH OPTIONS
425Apply all necessary patches to the extracted source
426No options defined for patch. Move patchfiles here?
427.Ss CONFIGURE OPTIONS
428Execute necessary configuration steps
429.Bl -tag -width lc
430.It Ic configure.pre_args
431Arguments added to configure command before ${configure.args}
432.br
433.Sy Type:
434.Em optional
435.br
436.Sy Example:
437.Dl configure.pre_args          --prefix=${prefix}/apache2
438.It Ic configure.args
439Arguments to pass to configure.
440.br
441.Sy Type:
442.Em optional
443.br
444.Sy Example:
445.Dl configure.args              --etcdir=${prefix}/etc
446.It Ic configure.dir
447Directory in which to run ${configure.cmd}
448.br
449.Sy Type:
450.Em optional
451.Sy Default:
452.Em ${workpath}/${worksrcdir}
453.br
454.Sy Example:
455.Dl configure.dir               src
456.It Ic configure.env
457Environmental variables to set during configure command
458.br
459.Sy Type:
460.Em optional
461.br
462.Sy Example:
463.Dl configure.env       CFLAGS="-no-cpp-precomp"
464.It Ic use_automake
465If set to yes, use automake
466.br
467.Sy Type:
468.Em optional
469.br
470.Sy Example:
471.Dl use_automake        yes
472.It Ic automake.env
473Environmental variables to pass to automake
474.br
475.Sy Type:
476.Em optional
477.br
478.Sy Example:
479.Dl automake.env        CFLAGS=-I${prefix}/include/gtk12
480.It Ic automake.args
481Arguments to pass to automake.
482.br
483.Sy Type:
484.Em optional
485.br
486.Sy Example:
487.Dl automake.args       --foreign
488.It Ic automake.dir
489Directory in which to run ${automake.cmd}
490.br
491.Sy Type:
492.Em optional
493.Sy Default:
494.Em ${workpath}/${worksrcdir}
495.br
496.Sy Example:
497.Dl automake.dir                src
498.It Ic use_autoconf
499If set to yes, run autoconf
500.br
501.Sy Type:
502.Em optional
503.br
504.Sy Example:
505.Dl use_autoconf        yes
506.It Ic autoconf.env
507Environmental variables to pass to autoconf
508.br
509.Sy Type:
510.Em optional
511.br
512.Sy Example:
513.Dl autoconf.env        CFLAGS=I${prefix}/include/gtk12
514.It Ic autoconf.args
515Arguments to pass to autoconf
516.br
517.Sy Type:
518.Em optional
519.br
520.Sy Example:
521.Dl autoconf.args       -l src/aclocaldir
522.It Ic autoconf.dir
523Directory in which to run ${autoconf.cmd}
524.br
525.Sy Type:
526.Em optional
527.Sy Default:
528.Em ${autoconf.dir}
529.br
530.Sy Example:
531.Dl autoconf.dir        src
532.It Ic xmkmf
533Does nothing
534.It Ic libtool
535Does nothing
536.El
537.Ss BUILD OPTIONS
538Execute necessary build commands
539.Bl -tag -width lc
540.It Ic build.cmd
541Make command to run relative to ${worksrcdir}
542.br
543.Sy Type:
544.Em optional
545.Sy Default:
546.Em make
547.br
548.Sy Example:
549.Dl build.cmd   pbxbuild
550.It Ic build.type
551Defines which 'make' is required, either 'gnu' or 'bsd'
552Sets build.cmd to either 'gnumake' or 'bsdmake' accordingly
553.br
554.Sy Type:
555.Em optional
556.Sy Default:
557.Em gnu
558.br
559.Sy Example:
560.Dl build.type  bsd
561.It Ic build.pre_args
562Arguments to pass to ${build.cmd} before ${build.args}
563.br
564.Sy Type:
565.Em read-only
566.Sy Default:
567.Em ${build.target}
568.It Ic build.args
569Arguments to pass to ${build.cmd}
570.br
571.Sy Type:
572.Em optional
573.br
574.Sy Example:
575.Dl build.args  -DNOWARN
576.It Ic build.env
577Environmental variables to set during build command
578.br
579.Sy Type:
580.Em optional
581.br
582.Sy Example:
583.Dl build.env       CPPFLAGS="-no-cpp-precomp"
584.It Ic build.target.all
585.br
586.Sy Deprecated:
587.Dl Replaced by build.target
588.It Ic build.target
589Target passed to ${build.cmd}
590.br
591.Sy Type:
592.Em optional
593.Sy Default:
594.Em all
595.br
596.Sy Example:
597.Dl build.target all-src
598.El
599.Ss DESTROOT OPTIONS
600Execute necessary commands to install into temporary destination root ("destroot") staging area.
601.Bl -tag -width lc
602.It Ic destroot.cmd
603Install command to run relative to ${worksrcdir}
604.br
605.Sy Type:
606.Em optional
607.Sy Default:
608.Em ${build.cmd}
609.br
610.Sy Example:
611.Dl destroot.cmd        pbxbuild
612.It Ic destroot.type
613Defines which 'make' is required, either 'gnu' or 'bsd'
614Sets destroot.cmd to either 'gnumake' or 'bsdmake' accordingly
615.br
616.Sy Type:
617.Em optional
618.Sy Default:
619.Em ${build.type}
620.br
621.Sy Example:
622.Dl destroot.type       gnu
623.It Ic destroot.pre_args
624Arguments to pass to ${destroot.cmd} before ${destroot.args}
625.br
626.Sy Type:
627.Em read-only
628.Sy Default:
629.Em ${destroot.target}
630.It Ic destroot.args
631Arguments to pass to ${destroot.cmd}
632.br
633.Sy Type:
634.Em optional
635.br
636.Sy Example:
637.Dl destroot.args       -DPREFIX=${prefix}
638.It Ic destroot.destdir
639Arguments passed to ${destroot.cmd} in order to install correctly
640into the destroot.
641.br
642.Sy Type:
643.Em optional
644.Sy Default:
645.Em DESTDIR=${destroot}
646.br
647.Sy Example:
648.Dl destroot.destdir    prefix=${destroot}${prefix}
649.It Ic build.target.install
650.br
651.Sy Deprecated:
652.Dl Replaced by destroot.target
653.It Ic destroot.target
654Install target to pass to ${destroot.cmd}
655.br
656.Sy Type:
657.Em optional
658.Sy Default:
659.Em install
660.br
661.Sy Example:
662.Dl destroot.target install-src
663.El
664.Ss TEST OPTIONS
665Execute commands to run test suites bundled with a port.
666.Bl -tag -width lc
667.It Ic test.run
668Enable running test suites bundled with a port
669.br
670.Sy Type:
671.Em optional
672.br
673.Sy Example:
674.Dl test.run     yes
675.It Ic test.cmd
676test command to run relative to ${worksrcdir}
677.br
678.Sy Type:
679.Em optional
680.Sy Default:
681.Em ${build.cmd}
682.br
683.Sy Example:
684.Dl test.cmd    checks.sh
685.It Ic test.target
686Test target to pass to ${test.cmd}
687.br
688.Sy Type:
689.Em optional
690.Sy Default:
691.Em test
692.br
693.Sy Example:
694.Dl test.target checks
695.It Ic test.dir
696Directory in which to run ${test.cmd}
697.br
698.Sy Type:
699.Em optional
700.br
701.Sy Example:
702.Dl test.dir    ${worksrcpath}/checks
703.El
704.Ss VARIANT OPTIONS
705DarwinPorts allows for conditional modification to be specified in a Portfile, allowing for handling of software's build-time settings.
706.Bl -tag -width lc
707.It Ic variant
708The key variant is used to begin the gnome variant as shown in the example.
709.br
710.Sy Type:
711.Em optional
712.br
713.Sy Example:
714.Dl variant gnome {     configure.args-append   --with-gnome \
715                                depends_lib-append              lib:gnome-session:gnome-session }
716.El
717.Ss PLATFORM OPTIONS
718DarwinPorts allows for platform-specific conditional modification to be specified in a Portfile, much like variants, for handling differences between platforms and versions of the same platform.
719.Bl -tag -width lc
720.It Ic platform
721The platform key is used to begin the darwin platform definitions as shown in the example from the databases/db4 Portfile.
722.br
723.Sy Type:
724.Em optional
725.br
726.Sy Example:
727.Dl platform darwin 6 { configure.args-append   --enable-tcl \
728                                --with-tcl=/System/Library/Tcl/8.3 }
729.br
730The platform version is optional, and an optional architecture can be specified after the version.
731.El
732.Sh AUTHORS
733.An "Landon Fuller" Aq landonf@opendarwin.org
734.An "Kevin Van Vechten" Aq kevin@opendarwin.org
735.An "Jordan K. Hubbard" Aq jkh@opendarwin.org
Note: See TracBrowser for help on using the repository browser.