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

Last change on this file since 1211 was 1211, checked in by jkh, 18 years ago

Document worksrcpath since it got left out somehow (and is darn useful)

  • Property svn:eol-style set to native
File size: 11.6 KB
Line 
1.\" portfile.7
2.\"
3.\" Copyright (c) 2002 Apple Computer, Inc.
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of Apple Computer, Inc. nor the names of its
15.\"    contributors may be used to endorse or promote products derived from
16.\"    this software without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
22.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.Dd September 2, 2002
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
55.Sh TARGETS
56.Tp
57.Ss MAIN OPTIONS
58Neccesary standard options
59.Bl -tag -width lc
60.It Ic prefix
61Install prefix
62.br
63.Sy Type:
64.Em optional
65.Sy Default:
66.Em /opt/local
67
68.It Ic libpath
69Locate of ports-specific TCL libraries
70.br
71.Sy Type:
72.Em read-only
73
74.It Ic workdir
75Path to work directory relative to ${portpath}
76.br
77.Sy Type:
78.Em read-only
79.Sy Default:
80.Em work
81
82.It Ic workpath
83Full path to work directory
84.br
85.Sy Type:
86.Em read-only
87.Sy Default:
88.Em ${portpath}/${workdir}
89
90.It Ic name
91Full name of port
92.br
93.Sy Type:
94.Em required
95.br
96.Sy Example:
97.Dl name        XFree86
98
99.It Ic version
100Upstream version of software
101.br
102.Sy Type:
103.Em required
104.br
105.Sy Example:
106.Dl version     4.2.1
107
108.It Ic revision
109Local revision number of portfile.
110Increment for port revisions.
111.br
112.Sy Type:
113.Em optional
114.Sy Default:
115.Em 0
116.br
117.Sy Example:
118.Dl revision    1
119
120.It Ic categories
121Categories to which this port belongs
122.br
123.Sy Type:
124.Em required
125.br
126.Sy Example:
127.Dl categories  spelling textproc
128
129.It Ic maintainers
130E-mail address(es) of port maintainer(s)
131.br
132.Sy Type:
133.Em required
134.br
135.Sy Example:
136.Dl maintainers landonf@opendarwin.org kevin@opendarwin.org
137
138.It Ic worksrcdir
139Path to source directory relative to ${workpath}
140.br
141.Sy Type:
142.Em optional
143.Sy Default:
144.Em ${distname}
145.br
146.Sy Example:
147.Dl worksrcdir  ${distname}-src-${version}
148
149.It Ic worksrcpath
150Full path to working sources (where port has unpacked itself)
151.br
152.Sy Type:
153.Em read-only
154.Sy Default:
155.Em ${workpath}/${worksrcdir}
156
157.It Ic filedir
158Path to port files relative to ${portpath}
159.br
160.Sy Type:
161.Em read-only
162.Sy Default:
163.Em files
164
165.It Ic distname
166Name of distibution file, minus extract suffix
167.br
168.Sy Type:
169.Em optional
170.Sy Default:
171.Em ${name}-${version})
172.br
173.Sy Example:
174.Dl distname    ${name}-${version}-src
175
176.It Ic distpath
177Location to store downloaded distfiles
178.br
179.Sy Type:
180.Em read-only
181.Sy Default:
182.Em ${sysportpath}/distfiles
183
184.It Ic os_arch
185Identifies hardware type (ie, "Power Macintosh")
186.br
187.Sy Type:
188.Em read-only
189
190.It Ic os_version
191Version number of operating system (ie "6.0")
192.br
193.Sy Type:
194.Em read-only
195.El
196
197.Ss DEPENDS OPTIONS
198Checking and building of dependencies
199.Bl -tag -width lc
200.It Ic depends_fetch
201List of dependencies to check before running fetch target
202.br
203.Sy Type:
204.Em optional
205.br
206.Sy Example:
207.Dl depends_fetch       bin:fetch:net/fetch bin:wget:wget
208
209.It Ic depends_build
210List of dependencies to check before build, install, and package targets
211.br
212.Sy Type:
213.Em optional
214.br
215.Sy Example:
216.Dl depends_build       bin:autoconf:autoconf
217
218.It Ic depends_run
219List of dependencies to check before install and package targets
220.br
221.Sy Type:
222.Em optional
223.br
224.Sy Example:
225.Dl depends_run bin:bash:bash
226
227.It Ic depends_extract
228List of dependencies to check before extract target
229.br
230.Sy Type:
231.Em optional
232.br
233.Sy Example:
234.Dl depends_extract     bin:bzip2:bzip2
235
236.It Ic depends_lib
237List of dependencies to check before configure, build, install, and package targets
238.br
239.Sy Type:
240.Em optional
241.br
242.Sy Example:
243.Dl depends_lib lib:libfetch.3:libfetch
244.El
245
246.Ss FETCH OPTIONS
247Fetch all distribution files and patches
248.Bl -tag -width lc
249.It Ic master_sites
250List of sites to fetch ${distfiles} from
251.br
252.Sy Type:
253.Em required
254.br
255.Sy Example:
256.Dl master_sites        ftp://ftp.cdrom.com/pub/magic \
257                        ftp://ftp.sourceforge.net/pub/projects/magic
258
259.It Ic patch_sites
260List of sites to fetch ${patchfiles} from
261.br
262.Sy Type:
263.Em optional
264.Sy Default:
265.Em ${master_sites}
266.br
267.Sy Example:
268.Dl patch_sites ftp://ftp.patchcityrepo.com/pub/magic/patches
269
270.It Ic extract.sufx
271Suffix to append to ${distname}
272.br
273.Sy Type:
274.Em optional
275.Sy Default:
276.Em .tar.gz
277.br
278.Sy Example:
279.Dl extract.sufx        .tgz
280
281.It Ic distfiles
282List of distribution files to fetch from ${master_sites}
283.br
284.Sy Type:
285.Em optional
286.Sy Default:
287.Em [suffix ${distname}]
288.br
289.Sy Example:
290.Dl distfiles   magicsource.tar.gz cluebat.tar.bz2
291
292.It Ic patchfiles
293List of patches to fetch and apply
294.br
295.Sy Type:
296.Em optional
297.br
298.Sy Example:
299.Dl patchfiles  japanese-widechar-fix.diff japanese-localization.diff
300
301.It Ic use_zip
302Use zip.
303.br
304Sets extract.sufx to: .zip
305.br
306Sets extract.cmd to: unzip
307.br
308Sets extract.pre_args to: -q
309.br
310Sets extract.post_args to: "-d $portpath/$workdir"
311.br
312.Sy Type:
313.Em optional
314.br
315.Sy Example:
316.Dl use_zip             yes
317
318.It Ic use_bzip2
319Use bzip2.
320.br
321Sets extract.sufx to: .bzip2
322.br
323Sets extract.cmd to: bzip2
324.br
325.Sy Type:
326.Em optional
327.br
328.Sy Example:
329.Dl use_bzip2   yes
330
331.It Ic dist_subdir
332Create a sub-directory in ${distpath} to store all fetched files.
333.br
334.Sy Type:
335.Em optional
336.br
337.Sy Example:
338.Dl dist_subdir vim${version}
339
340.El
341.Ss CHECKSUM OPTIONS
342Compare checksums of all fetched files
343.Bl -tag -width lc
344.It Ic checksums
345List of checksums in the format: <file name> <checksum type> <checksum>
346Currently, the only supported checksum type is md5
347.br
348.Sy Type:
349.Em required
350.br
351.Sy Example:
352.Dl checkums    dictd-1.7.1.tar.gz md5 81317b86ea0a5df0163900ad2e6bb12c \
353                                magic-words-1.7.1.tar.gz md5 897a005182928613eadd30c267ce9c5b
354.El
355
356.Ss EXTRACT OPTIONS
357Extract all compressed/archived files
358.Bl -tag -width lc
359
360.It Ic extract.only
361List of files to extract into ${workpath}
362.br
363.Sy Type:
364.Em optional
365.Sy Default:
366.Em ${distfiles}
367.br
368.Sy Example:
369.Dl extract.only        worksrc-1.4.4.tar.gz
370
371.It Ic extract.cmd
372Command to perform extract
373.br
374.Sy Type:
375.Em optional
376.Sy Default
377.Em gzip
378.br
379.Sy Example:
380.Dl extract.cmd bzip2
381
382.It Ic extract.pre_args
383Arguments added to extract command before a file name
384.br
385.Sy Type:
386.Em optional
387.Sy Default:
388.Em -dc
389.br
390.Sy Example:
391.Dl extract.pre_args    -cd
392
393.It Ic extract.args
394Arguments to extract.cmd
395.br
396.Sy Type:
397.Em read-only
398.Sy Default:
399.Em ${distpath}/${distfile}
400
401.It Ic extract.post_args
402Arguments added to extract command after a file name
403.br
404.Sy Type:
405.Em optional
406.Sy Default:
407.Em "| tar -xf -"
408.br
409.Sy Example:
410.Dl extract.post_args   | tar -x -s@bladeenc-0.94.2/other_makefiles/BladeEnc..@@p -f -
411
412.El
413
414.Ss PATCH OPTIONS
415Apply all necessary patches to the extracted source
416No options defined for patch. Move patchfiles here?
417
418.Ss CONFIGURE OPTIONS
419Execute necessary configuration steps
420.Bl -tag -width lc
421
422.It Ic configure.pre_args
423Arguments added to configure command before ${configure.args}
424.br
425.Sy Type:
426.Em optional
427.br
428.Sy Example:
429.Dl configure.pre_args          --prefix=${prefix}/apache2
430
431.It Ic configure.args
432Arguments to pass to configure.
433.br
434.Sy Type:
435.Em optional
436.br
437.Sy Example:
438.Dl configure.args              --etcdir=${prefix}/etc
439
440.It Ic configure.dir
441Directory in which to run ${configure.cmd}
442.br
443.Sy Type:
444.Em optional
445.Sy Default:
446.Em ${workpath}/${worksrcdir}
447.br
448.Sy Example:
449.Dl configure.dir               src
450
451.It Ic use_automake
452If set to yes, use automake
453.br
454.Sy Type:
455.Em optional
456.br
457.Sy Example:
458.Dl use_automake        yes
459
460.It Ic automake.env
461Environmental variables to pass to automake
462.br
463.Sy Type:
464.Em optional
465.br
466.Sy Example:
467.Dl automake.env        CFLAGS=-I${prefix}/include/gtk12
468
469.It Ic automake.args
470Arguments to pass to automake.
471.br
472.Sy Type:
473.Em optional
474.br
475.Sy Example:
476.Dl automake.args       --foreign
477
478.It Ic automake.dir
479Directory in which to run ${automake.cmd}
480.br
481.Sy Type:
482.Em optional
483.Sy Default:
484.Em ${workpath}/${worksrcdir}
485.br
486.Sy Example:
487.Dl automake.dir                src
488
489.It Ic use_autoconf
490If set to yes, run autoconf
491.br
492.Sy Type:
493.Em optional
494.br
495.Sy Example:
496.Dl use_autoconf        yes
497
498.It Ic autoconf.env
499Environmental variables to pass to autoconf
500.br
501.Sy Type:
502.Em optional
503.br
504.Sy Example:
505.Dl autoconf.env        CFLAGS=I${prefix}/include/gtk12
506
507.It Ic autoconf.args
508Arguments to pass to autoconf
509.br
510.Sy Type:
511.Em optional
512.br
513.Sy Example:
514.Dl autoconf.args       -l src/aclocaldir
515
516.It Ic autoconf.dir
517Directory in which to run ${autoconf.cmd}
518.br
519.Sy Type:
520.Em optional
521.Sy Default:
522.Em ${autoconf.dir}
523.br
524.Sy Example:
525.Dl autoconf.dir        src
526
527.It Ic xmkmf
528Does nothing
529
530.It Ic libtool
531Does nothing
532.El
533
534.Ss BUILD OPTIONS
535Execute necessary build commands
536.Bl -tag -width lc
537.It Ic build.cmd
538Make command to run relative to ${worksrcdir}
539.br
540.Sy Type:
541.Em optional
542.Sy Default:
543.Em make
544.br
545.Sy Example:
546.Dl build.cmd   pbxbuild
547
548.It Ic build.type
549Type of make required, either 'gnu' or 'bsd'
550Sets build.cmd to either 'gnumake' or 'bsdmake' accordingly
551.br
552.Sy Type:
553.Em optional
554.Sy Default:
555.Em bsd
556.br
557.Sy Example:
558.Dl build.type  gnu
559
560.It Ic build.pre_args
561Arguments to pass to ${build.cmd} before ${build.args}
562.br
563.Sy Type:
564.Em read-only
565.Sy Default:
566.Em ${build.target.current}
567
568
569.It Ic build.args
570Arguments to pass to ${build.cmd}
571.br
572.Sy Type:
573.Em optional
574.br
575.Sy Example:
576.Dl build.args  -DNOWARN
577
578
579.It Ic build.target.all
580Target to pass to make for building everything
581.br
582.Sy Type:
583.Em optional
584.Sy Default:
585.Em all
586.br
587.Sy Example:
588.Dl build.target.all all-src
589
590.El
591
592.Ss INSTALL OPTIONS
593Execute necessary install commands
594.Bl -tag -width lc
595
596.It Ic build.target.install
597Install target to pass to ${build.cmd}
598.br
599.Sy Type:
600.Em optional
601.Sy Default:
602.Em install
603.br
604.Sy Example:
605.Dl build.target.install        install-src
606
607.El
608.Ss REGISTRY OPTIONS
609Register installed package contents
610.Bl -tag -width lc
611
612.It Ic contents
613List of files to be installed by the port
614Files are assumed to be relative to ${prefix} unless the first character is a '/'
615.br
616.Sy Type:
617.Em required
618.br
619.Sy Example:
620.Dl contents            bin/ls man/man1/ls.1.gz
621
622.It Ic description
623One line description of the software and what it does
624.br
625.Sy Type:
626.Em required
627.br
628.Sy Example:
629.Dl description "Dictionary Server Protocol (RFC2229) client"
630.El
631
632.Sh AUTHORS
633.An "Landon Fuller <landonf@opendarwin.org>"
634.An "Kevin Van Vechten <kevin@opendarwin.org>"
635.An "Jordan K. Hubbard <jkh@opendarwin.org>"
Note: See TracBrowser for help on using the repository browser.