1.\"
2.\" FreeBSD install - a package for the installation and maintainance
3.\" of non-core utilities.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" Jordan K. Hubbard
15.\"
16.\"
17.\" @(#)pkg_create.1
18.\" $FreeBSD: head/usr.sbin/pkg_install/create/pkg_create.1 96076 2002-05-05 21:03:25Z sobomax $
19.\"
20.\" hacked up by John Kohl for NetBSD--fixed a few bugs, extended keywords,
21.\" added dependency tracking, etc.
22.\"
23.\" [jkh] Took John's changes back and made some additional extensions for
24.\" better integration with FreeBSD's new ports collection.
25.\"
26.Dd April 21, 1995
27.Dt PKG_CREATE 1
28.Os
29.Sh NAME
30.Nm pkg_create
31.Nd a utility for creating software package distributions
32.Sh SYNOPSIS
33.Nm
34.Op Fl YNOhjvyz
35.Op Fl P Ar pkgs
36.Op Fl p Ar prefix
37.Op Fl f Ar contents
38.Op Fl i Ar iscript
39.Op Fl I Ar piscript
40.Op Fl k Ar dscript
41.Op Fl K Ar pdscript
42.Op Fl r Ar rscript
43.Op Fl s Ar srcdir
44.Op Fl t Ar template
45.Op Fl X Ar excludefile
46.Op Fl D Ar displayfile
47.Op Fl m Ar mtreefile
48.Op Fl o Ar originpath
49.Fl c Ar comment
50.Fl d Ar description
51.Fl f Ar packlist
52.Ar pkg-filename
53.Nm
54.Op Fl YNhvy
55.Fl b Ar pkg-name
56.Op Ar pkg-filename
57.Sh DESCRIPTION
58The
59.Nm
60command is used to create packages that will subsequently be fed to
61one of the package extraction/info utilities. The input description
62and command line arguments for the creation of a package are not
63really meant to be human-generated, though it is easy enough to
64do so. It is more expected that you will use a front-end tool for
65the job rather than muddling through it yourself. Nonetheless, a short
66description of the input syntax is included in this document.
67.Sh OPTIONS
68The following command line options are supported:
69.Bl -tag -width indent
70.It Fl f Ar packinglist
71Fetch
72.Dq packing list
73for package from the file
74.Ar packinglist
75or
76.Cm stdin
77if
78.Ar packinglist
79is a
80.Cm -
81(dash).
82.It Fl c Xo
83.Oo Fl Oc Ns Ar desc
84.Xc
85Fetch package
86.Dq one line description
87from file
88.Ar desc
89or, if preceded by
90.Cm - ,
91the argument itself. This string should also
92give some idea of which version of the product (if any) the package
93represents.
94.It Fl d Xo
95.Oo Fl Oc Ns Ar desc
96.Xc
97Fetch long description for package from file
98.Ar desc
99or, if preceded by
100.Cm - ,
101the argument itself.
102.It Fl Y
103Assume a default answer of `Yes' for any questions asked.
104.It Fl N
105Assume a default answer of `No' for any questions asked.
106.It Fl O
107Go into a `packing list Only' mode. This is a custom hack for the
108.Fx
109.Em "Ports Collection"
110and is used to do `fake pkg_add' operations when a port is installed.
111In such cases, it is necessary to know what the final, adjusted packing
112list will look like.
113.It Fl v
114Turn on verbose output.
115.It Fl h
116Force tar to follow symbolic links, so that the files they point to
117are dumped, rather than the links themselves.
118.It Fl i Ar iscript
119Set
120.Ar iscript
121to be the pre-install procedure for the package. This can be any executable
122program (or shell script). It will be invoked automatically when the
123package is later installed.
124It will be passed the package's name as the
125first argument.
126.Pp
127.Sy Note :
128if the
129.Fl I
130option is not given, this script will serve as both the pre-install and the
131post-install script for the package, differentiating between the
132functionality by passing the keywords
133.Ar PRE-INSTALL
134and
135.Ar POST-INSTALL
136respectively, along with the package's name.
137.It Fl I Ar piscript
138Set
139.Ar piscript
140to be the post-install procedure for the package. This can be any
141executable program (or shell script). It will be invoked automatically
142when the package is later installed.
143It will be passed the package's name as
144the first argument.
145.It Fl P Ar pkgs
146Set the initial package dependency list to
147.Ar pkgs .
148This is assumed to be a whitespace separated list of package names
149and is meant as a convenient shorthand for specifying multiple
150.Cm @pkgdep
151directives in the packing list (see PACKING LIST DETAILS section below).
152Each argiment from the
153.Ar pkgs
154list could be in the form
155.Ar pkgname Ns Op Ar :pkgorigin ,
156where optional
157.Ar pkgorigin
158element denotes origin of each dependency from the list and it is
159recorded into the packing list along with the
160.Ar pkgname
161using
162.Cm @comment
163directive.
164.It Fl p Ar prefix
165Set
166.Ar prefix
167as the initial directory
168.Dq base
169to start from in selecting files for
170the package.
171.It Fl k Ar dscript
172Set
173.Ar dscript
174to be the de-install procedure for the package. This can be any executable
175program (or shell script). It will be invoked automatically when the
176package is later (if ever) de-installed.
177It will be passed the package's
178name as the first argument.
179.Pp
180.Sy Note :
181if the
182.Fl K
183option is not given, this script will serve as both the de-install and the
184post-deinstall script for the package, differentiating between the
185functionality by passing the keywords
186.Ar DEINSTALL
187and
188.Ar POST-DEINSTALL
189respectively, along with the package's name.
190.It Fl K Ar pdscript
191Set
192.Ar pdscript
193to be the post-deinstall procedure for the package. This can be any
194executable program (or shell script). It will be invoked automatically when
195the package is later de-installed.
196It will be passed the package's name as
197the first argument.
198.It Fl r Ar rscript
199Set
200.Ar rscript
201to be the
202.Dq requirements
203procedure for the package. This can be any
204executable program (or shell script). It will be invoked automatically
205at installation/deinstallation time to determine whether or not
206installation/deinstallation should proceed.
207To differentiate between installation and deinstallation, the keywords
208.Ar INSTALL
209and
210.Ar DEINSTALL
211are passed respectively, along with the package's name.
212.It Fl s Ar srcdir
213.Ar srcdir
214will override the value of
215.Cm @cwd
216during package creation.
217.It Fl t Ar template
218Use
219.Ar template
220as the input to
221.Xr mktemp 3 .
222By default, this is the string
223.Pa /tmp/instmp.XXXXXX ,
224but it may be necessary to override it in the situation where
225space in your
226.Pa /tmp
227directory is limited. Be sure to leave some number of `X' characters
228for
229.Xr mktemp 3
230to fill in with a unique ID.
231.It Fl X Ar excludefile
232Pass
233.Ar excludefile
234as a
235.Fl exclude-from
236argument to
237.Cm tar
238when creating final package. See
239.Cm tar
240man page (or run
241.Cm tar
242with
243.Fl -help
244flag) for further information on using this flag.
245.It Fl D Ar displayfile
246Display the file (by concatenating it to stdout)
247after installing the package. Useful for things like
248legal notices on almost-free software, etc.
249.It Fl m Ar mtreefile
250Run
251.Xr mtree 8
252with input from mtreefile before the package is installed.
253Mtree is invoked as
254.Cm mtree
255.Fl u
256.Fl f
257.Ar mtreefile
258.Fl d
259.Fl e
260.Fl p
261.Pa prefix ,
262where
263.Pa prefix
264is the name of the first directory named by a
265.Cm @cwd
266directive.
267.It Fl o Ar originpath
268Record an
269.Ar originpath ,
270as location of the port from which package has been created in the
271.Fx
272.Em "Ports Collection" .
273It should be in the form
274.Pa MASTERCATEGORY/PORTDIR .
275.It Fl j
276Use
277.Xr bzip2 1
278utility to compress package tarball instead of
279.Xr gzip 1 .
280Please note that this option is a NO-OP if format of the resulting
281archive is explicitly specified by the recognizeable suffix of
282.Ar pkg-filename .
283Currently
284.Nm
285recognizes the following suffixes:
286.Pa .tgz , .tar , .tbz
287and
288.Pa .tbz2 .
289.It Fl y
290Compatibility synonym for
291.Fl j .
292.It Fl z
293Use
294.Xr gzip 1
295utility to compress package tarball.
296.It Fl b Ar pkg-name
297Create package file from a locally installed package named
298.Ar pkg-name .
299If the
300.Ar pkg-filename
301is not specified, then resulting archive will be created in the
302current directory and named
303.Ar pkg-name
304with an appropriate extraction suffix applied.
305.El
306.Sh PACKING LIST DETAILS
307The
308.Dq packing list
309format (see
310.Fl f )
311is fairly simple, being
312nothing more than a single column of filenames to include in the
313package. However, since absolute pathnames are generally a bad idea
314for a package that could be installed potentially anywhere, there is
315another method of specifying where things are supposed to go
316and, optionally, what ownership and mode information they should be
317installed with. This is done by imbeding specialized command sequences
318in the packing list. Briefly described, these sequences are:
319.Bl -tag -width indent -compact
320.It Cm @cwd Ar directory
321Set the internal directory pointer to point to
322.Ar directory .
323All subsequent filenames will be assumed relative to this directory.
324Note:
325.Cm @cd
326is also an alias for this command.
327.It Cm @srcdir Ar directory
328Set the internal directory pointer for _creation only_ to
329.Ar directory .
330That is to say that it overrides
331.Cm @cwd
332for package creation but not extraction.
333.It Cm @exec Ar command
334Execute
335.Ar command
336as part of the unpacking process. If
337.Ar command
338contains any of the following sequences somewhere in it, they will
339be expanded inline. For the following examples, assume that
340.Cm @cwd
341is set to
342.Pa /usr/local
343and the last extracted file was
344.Pa bin/emacs .
345.Bl -tag -width indent -compact
346.It Cm "%F"
347Expands to the last filename extracted (as specified), in the example case
348.Pa bin/emacs
349.It Cm "\&%D"
350Expand to the current directory prefix, as set with
351.Cm @cwd ,
352in the example case
353.Pa /usr/local .
354.It Cm "\&%B"
355Expand to the
356.Dq basename
357of the fully qualified filename, that
358is the current directory prefix, plus the last filespec, minus
359the trailing filename. In the example case, that would be
360.Pa /usr/local/bin .
361.It Cm "%f"
362Expand to the
363filename
364part of the fully qualified name, or
365the converse of
366.Cm \&%B ,
367being in the example case,
368.Pa emacs .
369.El
370.It Cm @unexec Ar command
371Execute
372.Ar command
373as part of the deinstallation process. Expansion of special
374.Cm %
375sequences is the same as for
376.Cm @exec .
377This command is not executed during the package add, as
378.Cm @exec
379is, but rather when the package is deleted. This is useful
380for deleting links and other ancillary files that were created
381as a result of adding the package, but not directly known to
382the package's table of contents (and hence not automatically
383removable). The advantage of using
384.Cm @unexec
385over a deinstallation script is that you can use the
386.Dq special sequence expansion
387to get at files regardless of where they've
388been potentially redirected (see
389.Fl p ) .
390.It Cm @mode Ar mode
391Set default permission for all subsequently extracted files to
392.Ar mode .
393Format is the same as that used by the
394.Cm chmod
395command (well, considering that it's later handed off to it, that's
396no surprise). Use without an arg to set back to default (extraction)
397permissions.
398.It Cm @option Ar option
399Set internal package options, the only two currently supported ones
400being
401.Ar extract-in-place ,
402which tells the pkg_add command not to extract the package's tarball
403into a staging area but rather directly into the target
404hierarchy (this is typically meant to be used only by distributions
405or other special package types), and
406.Ar preserve ,
407which tells pkg_add to move any existing files out of the way,
408preserving the previous contents (which are also resurrected on
409pkg_delete, so caveat emptor).
410.It Cm @owner Ar user
411Set default ownership for all subsequently extracted files to
412.Ar user .
413Use without an arg to set back to default (extraction)
414ownership.
415.It Cm @group Ar group
416Set default group ownership for all subsequently extracted files to
417.Ar group .
418Use without an arg to set back to default (extraction)
419group ownership.
420.It Cm @comment Ar string
421Imbed a comment in the packing list. Useful in
422trying to document some particularly hairy sequence that
423may trip someone up later.
424.It Cm @ignore
425Used internally to tell extraction to ignore the next file (don't
426copy it anywhere), as it's used for some special purpose.
427.It Cm @ignore_inst
428Similar to
429.Cm @ignore ,
430but the ignoring of the next file is delayed one evaluation cycle. This
431makes it possible to use this directive in the
432.Ar packinglist
433file, so you can pack a
434specialized datafile in with a distribution for your install script (or
435something) yet have the installer ignore it.
436.It Cm @name Ar name
437Set the name of the package. This is mandatory and is usually
438put at the top. This name is potentially different from the name of
439the file it came in, and is used when keeping track of the package
440for later deinstallation. Note that
441.Nm
442will derive this field from the package name and add it automatically
443if none is given.
444.It Cm @dirrm Ar name
445Declare directory
446.Pa name
447to be deleted at deinstall time. By default, directories created by a
448package installation are not deleted when the package is deinstalled;
449this provides an explicit directory cleanup method. This directive
450should appear at the end of the package list. If more than one
451.Cm @dirrm
452directives are used, the directories are removed in the order specified.
453The
454.Pa name
455directory will not be removed unless it is empty.
456.It Cm @mtree Ar name
457Declare
458.Pa name
459as an
460.Xr mtree 8
461input file to be used at install time (see
462.Fl m
463above). Only the first
464.Cm @mtree
465directive is honored.
466.It Cm @display Ar name
467Declare
468.Pa name
469as the file to be displayed at install time (see
470.Fl D
471above).
472.It Cm @pkgdep Ar pkgname
473Declare a dependency on the
474.Ar pkgname
475package. The
476.Ar pkgname
477package must be installed before this package may be
478installed, and this package must be deinstalled before the
479.Ar pkgname
480package is deinstalled. Multiple
481.Cm @pkgdep
482directives may be used if the package depends on multiple other packages.
483.El
484.Sh ENVIRONMENT
485The environment variable
486.Ev PKG_TMPDIR
487names the directory where
488.Nm
489will attempt to create its temporary files.
490If
491.Ev PKG_TMPDIR
492is not set,
493the directory named by the contents of
494.Ev TMPDIR
495will be used.
496If neither of
497.Ev PKG_TMPDIR
498and
499.Ev TMPDIR
500are set, the builtin defaults are used.
501.Sh FILES
502.Bl -tag -width /usr/tmp -compact
503.It Pa /var/tmp
504Temporary directory if environmental variables
505.Ev PKG_TMPDIR
506and
507.Ev TMPDIR
508are not set.
509.It Pa /tmp
510The next choice if
511.Pa /var/tmp
512does not exist.
513.It Pa /usr/tmp
514The last choice if
515.Pa /tmp
516is unsuitable.
517.El
518.Sh SEE ALSO
519.Xr pkg_add 1 ,
520.Xr pkg_delete 1 ,
521.Xr pkg_info 1 ,
522.Xr pkg_update 1 ,
523.Xr pkg_version 1 ,
524.Xr sysconf 3
525.Sh HISTORY
526The
527.Nm
528command first appeared in
529.Fx .
530.Sh AUTHORS
531.An Jordan Hubbard
532.Sh CONTRIBUTORS
533.An John Kohl Aq jtk@rational.com
534.Sh BUGS
535Hard links between files in a distribution must be bracketed by
536.Cm @cwd
537directives in order to be preserved as hard links when the package is
538extracted. They additionally must not end up being split between
539.Cm tar
540invocations due to exec argument-space limitations (this depends on the
541value returned by
542.Fn sysconf _SC_ARG_MAX ) .
543.Pp
544Sure to be others.
2.\" FreeBSD install - a package for the installation and maintainance
3.\" of non-core utilities.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" Jordan K. Hubbard
15.\"
16.\"
17.\" @(#)pkg_create.1
18.\" $FreeBSD: head/usr.sbin/pkg_install/create/pkg_create.1 96076 2002-05-05 21:03:25Z sobomax $
19.\"
20.\" hacked up by John Kohl for NetBSD--fixed a few bugs, extended keywords,
21.\" added dependency tracking, etc.
22.\"
23.\" [jkh] Took John's changes back and made some additional extensions for
24.\" better integration with FreeBSD's new ports collection.
25.\"
26.Dd April 21, 1995
27.Dt PKG_CREATE 1
28.Os
29.Sh NAME
30.Nm pkg_create
31.Nd a utility for creating software package distributions
32.Sh SYNOPSIS
33.Nm
34.Op Fl YNOhjvyz
35.Op Fl P Ar pkgs
36.Op Fl p Ar prefix
37.Op Fl f Ar contents
38.Op Fl i Ar iscript
39.Op Fl I Ar piscript
40.Op Fl k Ar dscript
41.Op Fl K Ar pdscript
42.Op Fl r Ar rscript
43.Op Fl s Ar srcdir
44.Op Fl t Ar template
45.Op Fl X Ar excludefile
46.Op Fl D Ar displayfile
47.Op Fl m Ar mtreefile
48.Op Fl o Ar originpath
49.Fl c Ar comment
50.Fl d Ar description
51.Fl f Ar packlist
52.Ar pkg-filename
53.Nm
54.Op Fl YNhvy
55.Fl b Ar pkg-name
56.Op Ar pkg-filename
57.Sh DESCRIPTION
58The
59.Nm
60command is used to create packages that will subsequently be fed to
61one of the package extraction/info utilities. The input description
62and command line arguments for the creation of a package are not
63really meant to be human-generated, though it is easy enough to
64do so. It is more expected that you will use a front-end tool for
65the job rather than muddling through it yourself. Nonetheless, a short
66description of the input syntax is included in this document.
67.Sh OPTIONS
68The following command line options are supported:
69.Bl -tag -width indent
70.It Fl f Ar packinglist
71Fetch
72.Dq packing list
73for package from the file
74.Ar packinglist
75or
76.Cm stdin
77if
78.Ar packinglist
79is a
80.Cm -
81(dash).
82.It Fl c Xo
83.Oo Fl Oc Ns Ar desc
84.Xc
85Fetch package
86.Dq one line description
87from file
88.Ar desc
89or, if preceded by
90.Cm - ,
91the argument itself. This string should also
92give some idea of which version of the product (if any) the package
93represents.
94.It Fl d Xo
95.Oo Fl Oc Ns Ar desc
96.Xc
97Fetch long description for package from file
98.Ar desc
99or, if preceded by
100.Cm - ,
101the argument itself.
102.It Fl Y
103Assume a default answer of `Yes' for any questions asked.
104.It Fl N
105Assume a default answer of `No' for any questions asked.
106.It Fl O
107Go into a `packing list Only' mode. This is a custom hack for the
108.Fx
109.Em "Ports Collection"
110and is used to do `fake pkg_add' operations when a port is installed.
111In such cases, it is necessary to know what the final, adjusted packing
112list will look like.
113.It Fl v
114Turn on verbose output.
115.It Fl h
116Force tar to follow symbolic links, so that the files they point to
117are dumped, rather than the links themselves.
118.It Fl i Ar iscript
119Set
120.Ar iscript
121to be the pre-install procedure for the package. This can be any executable
122program (or shell script). It will be invoked automatically when the
123package is later installed.
124It will be passed the package's name as the
125first argument.
126.Pp
127.Sy Note :
128if the
129.Fl I
130option is not given, this script will serve as both the pre-install and the
131post-install script for the package, differentiating between the
132functionality by passing the keywords
133.Ar PRE-INSTALL
134and
135.Ar POST-INSTALL
136respectively, along with the package's name.
137.It Fl I Ar piscript
138Set
139.Ar piscript
140to be the post-install procedure for the package. This can be any
141executable program (or shell script). It will be invoked automatically
142when the package is later installed.
143It will be passed the package's name as
144the first argument.
145.It Fl P Ar pkgs
146Set the initial package dependency list to
147.Ar pkgs .
148This is assumed to be a whitespace separated list of package names
149and is meant as a convenient shorthand for specifying multiple
150.Cm @pkgdep
151directives in the packing list (see PACKING LIST DETAILS section below).
152Each argiment from the
153.Ar pkgs
154list could be in the form
155.Ar pkgname Ns Op Ar :pkgorigin ,
156where optional
157.Ar pkgorigin
158element denotes origin of each dependency from the list and it is
159recorded into the packing list along with the
160.Ar pkgname
161using
162.Cm @comment
163directive.
164.It Fl p Ar prefix
165Set
166.Ar prefix
167as the initial directory
168.Dq base
169to start from in selecting files for
170the package.
171.It Fl k Ar dscript
172Set
173.Ar dscript
174to be the de-install procedure for the package. This can be any executable
175program (or shell script). It will be invoked automatically when the
176package is later (if ever) de-installed.
177It will be passed the package's
178name as the first argument.
179.Pp
180.Sy Note :
181if the
182.Fl K
183option is not given, this script will serve as both the de-install and the
184post-deinstall script for the package, differentiating between the
185functionality by passing the keywords
186.Ar DEINSTALL
187and
188.Ar POST-DEINSTALL
189respectively, along with the package's name.
190.It Fl K Ar pdscript
191Set
192.Ar pdscript
193to be the post-deinstall procedure for the package. This can be any
194executable program (or shell script). It will be invoked automatically when
195the package is later de-installed.
196It will be passed the package's name as
197the first argument.
198.It Fl r Ar rscript
199Set
200.Ar rscript
201to be the
202.Dq requirements
203procedure for the package. This can be any
204executable program (or shell script). It will be invoked automatically
205at installation/deinstallation time to determine whether or not
206installation/deinstallation should proceed.
207To differentiate between installation and deinstallation, the keywords
208.Ar INSTALL
209and
210.Ar DEINSTALL
211are passed respectively, along with the package's name.
212.It Fl s Ar srcdir
213.Ar srcdir
214will override the value of
215.Cm @cwd
216during package creation.
217.It Fl t Ar template
218Use
219.Ar template
220as the input to
221.Xr mktemp 3 .
222By default, this is the string
223.Pa /tmp/instmp.XXXXXX ,
224but it may be necessary to override it in the situation where
225space in your
226.Pa /tmp
227directory is limited. Be sure to leave some number of `X' characters
228for
229.Xr mktemp 3
230to fill in with a unique ID.
231.It Fl X Ar excludefile
232Pass
233.Ar excludefile
234as a
235.Fl exclude-from
236argument to
237.Cm tar
238when creating final package. See
239.Cm tar
240man page (or run
241.Cm tar
242with
243.Fl -help
244flag) for further information on using this flag.
245.It Fl D Ar displayfile
246Display the file (by concatenating it to stdout)
247after installing the package. Useful for things like
248legal notices on almost-free software, etc.
249.It Fl m Ar mtreefile
250Run
251.Xr mtree 8
252with input from mtreefile before the package is installed.
253Mtree is invoked as
254.Cm mtree
255.Fl u
256.Fl f
257.Ar mtreefile
258.Fl d
259.Fl e
260.Fl p
261.Pa prefix ,
262where
263.Pa prefix
264is the name of the first directory named by a
265.Cm @cwd
266directive.
267.It Fl o Ar originpath
268Record an
269.Ar originpath ,
270as location of the port from which package has been created in the
271.Fx
272.Em "Ports Collection" .
273It should be in the form
274.Pa MASTERCATEGORY/PORTDIR .
275.It Fl j
276Use
277.Xr bzip2 1
278utility to compress package tarball instead of
279.Xr gzip 1 .
280Please note that this option is a NO-OP if format of the resulting
281archive is explicitly specified by the recognizeable suffix of
282.Ar pkg-filename .
283Currently
284.Nm
285recognizes the following suffixes:
286.Pa .tgz , .tar , .tbz
287and
288.Pa .tbz2 .
289.It Fl y
290Compatibility synonym for
291.Fl j .
292.It Fl z
293Use
294.Xr gzip 1
295utility to compress package tarball.
296.It Fl b Ar pkg-name
297Create package file from a locally installed package named
298.Ar pkg-name .
299If the
300.Ar pkg-filename
301is not specified, then resulting archive will be created in the
302current directory and named
303.Ar pkg-name
304with an appropriate extraction suffix applied.
305.El
306.Sh PACKING LIST DETAILS
307The
308.Dq packing list
309format (see
310.Fl f )
311is fairly simple, being
312nothing more than a single column of filenames to include in the
313package. However, since absolute pathnames are generally a bad idea
314for a package that could be installed potentially anywhere, there is
315another method of specifying where things are supposed to go
316and, optionally, what ownership and mode information they should be
317installed with. This is done by imbeding specialized command sequences
318in the packing list. Briefly described, these sequences are:
319.Bl -tag -width indent -compact
320.It Cm @cwd Ar directory
321Set the internal directory pointer to point to
322.Ar directory .
323All subsequent filenames will be assumed relative to this directory.
324Note:
325.Cm @cd
326is also an alias for this command.
327.It Cm @srcdir Ar directory
328Set the internal directory pointer for _creation only_ to
329.Ar directory .
330That is to say that it overrides
331.Cm @cwd
332for package creation but not extraction.
333.It Cm @exec Ar command
334Execute
335.Ar command
336as part of the unpacking process. If
337.Ar command
338contains any of the following sequences somewhere in it, they will
339be expanded inline. For the following examples, assume that
340.Cm @cwd
341is set to
342.Pa /usr/local
343and the last extracted file was
344.Pa bin/emacs .
345.Bl -tag -width indent -compact
346.It Cm "%F"
347Expands to the last filename extracted (as specified), in the example case
348.Pa bin/emacs
349.It Cm "\&%D"
350Expand to the current directory prefix, as set with
351.Cm @cwd ,
352in the example case
353.Pa /usr/local .
354.It Cm "\&%B"
355Expand to the
356.Dq basename
357of the fully qualified filename, that
358is the current directory prefix, plus the last filespec, minus
359the trailing filename. In the example case, that would be
360.Pa /usr/local/bin .
361.It Cm "%f"
362Expand to the
363filename
364part of the fully qualified name, or
365the converse of
366.Cm \&%B ,
367being in the example case,
368.Pa emacs .
369.El
370.It Cm @unexec Ar command
371Execute
372.Ar command
373as part of the deinstallation process. Expansion of special
374.Cm %
375sequences is the same as for
376.Cm @exec .
377This command is not executed during the package add, as
378.Cm @exec
379is, but rather when the package is deleted. This is useful
380for deleting links and other ancillary files that were created
381as a result of adding the package, but not directly known to
382the package's table of contents (and hence not automatically
383removable). The advantage of using
384.Cm @unexec
385over a deinstallation script is that you can use the
386.Dq special sequence expansion
387to get at files regardless of where they've
388been potentially redirected (see
389.Fl p ) .
390.It Cm @mode Ar mode
391Set default permission for all subsequently extracted files to
392.Ar mode .
393Format is the same as that used by the
394.Cm chmod
395command (well, considering that it's later handed off to it, that's
396no surprise). Use without an arg to set back to default (extraction)
397permissions.
398.It Cm @option Ar option
399Set internal package options, the only two currently supported ones
400being
401.Ar extract-in-place ,
402which tells the pkg_add command not to extract the package's tarball
403into a staging area but rather directly into the target
404hierarchy (this is typically meant to be used only by distributions
405or other special package types), and
406.Ar preserve ,
407which tells pkg_add to move any existing files out of the way,
408preserving the previous contents (which are also resurrected on
409pkg_delete, so caveat emptor).
410.It Cm @owner Ar user
411Set default ownership for all subsequently extracted files to
412.Ar user .
413Use without an arg to set back to default (extraction)
414ownership.
415.It Cm @group Ar group
416Set default group ownership for all subsequently extracted files to
417.Ar group .
418Use without an arg to set back to default (extraction)
419group ownership.
420.It Cm @comment Ar string
421Imbed a comment in the packing list. Useful in
422trying to document some particularly hairy sequence that
423may trip someone up later.
424.It Cm @ignore
425Used internally to tell extraction to ignore the next file (don't
426copy it anywhere), as it's used for some special purpose.
427.It Cm @ignore_inst
428Similar to
429.Cm @ignore ,
430but the ignoring of the next file is delayed one evaluation cycle. This
431makes it possible to use this directive in the
432.Ar packinglist
433file, so you can pack a
434specialized datafile in with a distribution for your install script (or
435something) yet have the installer ignore it.
436.It Cm @name Ar name
437Set the name of the package. This is mandatory and is usually
438put at the top. This name is potentially different from the name of
439the file it came in, and is used when keeping track of the package
440for later deinstallation. Note that
441.Nm
442will derive this field from the package name and add it automatically
443if none is given.
444.It Cm @dirrm Ar name
445Declare directory
446.Pa name
447to be deleted at deinstall time. By default, directories created by a
448package installation are not deleted when the package is deinstalled;
449this provides an explicit directory cleanup method. This directive
450should appear at the end of the package list. If more than one
451.Cm @dirrm
452directives are used, the directories are removed in the order specified.
453The
454.Pa name
455directory will not be removed unless it is empty.
456.It Cm @mtree Ar name
457Declare
458.Pa name
459as an
460.Xr mtree 8
461input file to be used at install time (see
462.Fl m
463above). Only the first
464.Cm @mtree
465directive is honored.
466.It Cm @display Ar name
467Declare
468.Pa name
469as the file to be displayed at install time (see
470.Fl D
471above).
472.It Cm @pkgdep Ar pkgname
473Declare a dependency on the
474.Ar pkgname
475package. The
476.Ar pkgname
477package must be installed before this package may be
478installed, and this package must be deinstalled before the
479.Ar pkgname
480package is deinstalled. Multiple
481.Cm @pkgdep
482directives may be used if the package depends on multiple other packages.
483.El
484.Sh ENVIRONMENT
485The environment variable
486.Ev PKG_TMPDIR
487names the directory where
488.Nm
489will attempt to create its temporary files.
490If
491.Ev PKG_TMPDIR
492is not set,
493the directory named by the contents of
494.Ev TMPDIR
495will be used.
496If neither of
497.Ev PKG_TMPDIR
498and
499.Ev TMPDIR
500are set, the builtin defaults are used.
501.Sh FILES
502.Bl -tag -width /usr/tmp -compact
503.It Pa /var/tmp
504Temporary directory if environmental variables
505.Ev PKG_TMPDIR
506and
507.Ev TMPDIR
508are not set.
509.It Pa /tmp
510The next choice if
511.Pa /var/tmp
512does not exist.
513.It Pa /usr/tmp
514The last choice if
515.Pa /tmp
516is unsuitable.
517.El
518.Sh SEE ALSO
519.Xr pkg_add 1 ,
520.Xr pkg_delete 1 ,
521.Xr pkg_info 1 ,
522.Xr pkg_update 1 ,
523.Xr pkg_version 1 ,
524.Xr sysconf 3
525.Sh HISTORY
526The
527.Nm
528command first appeared in
529.Fx .
530.Sh AUTHORS
531.An Jordan Hubbard
532.Sh CONTRIBUTORS
533.An John Kohl Aq jtk@rational.com
534.Sh BUGS
535Hard links between files in a distribution must be bracketed by
536.Cm @cwd
537directives in order to be preserved as hard links when the package is
538extracted. They additionally must not end up being split between
539.Cm tar
540invocations due to exec argument-space limitations (this depends on the
541value returned by
542.Fn sysconf _SC_ARG_MAX ) .
543.Pp
544Sure to be others.