2 .\" FreeBSD install - a package for the installation and maintainance
3 .\" of non-core utilities.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
20 .\" hacked up by John Kohl for NetBSD--fixed a few bugs, extended keywords,
21 .\" added dependency tracking, etc.
23 .\" [jkh] Took John's changes back and made some additional extensions for
24 .\" better integration with FreeBSD's new ports collection.
31 .Nd a utility for creating software package distributions
45 .Op Fl X Ar excludefile
46 .Op Fl D Ar displayfile
55 command is used to create packages that will subsequently be fed to
56 one of the package extraction/info utilities. The input description
57 and command line arguments for the creation of a package are not
58 really meant to be human-generated, though it is easy enough to
59 do so. It is more expected that you will use a front-end tool for
60 the job rather than muddling through it yourself. Nonetheless, a short
61 description of the input syntax is included in this document.
63 The following command line options are supported:
64 .Bl -tag -width indent
65 .It Fl f Ar packinglist
68 for package from the file
79 .Dq one line description
84 the argument itself. This string should also
85 give some idea of which version of the product (if any) the package
88 Fetch long description for package from file
94 Assume a default answer of `Yes' for any questions asked.
96 Assume a default answer of `No' for any questions asked.
98 Go into a `packing list Only' mode. This is a custom hack for the
99 .Em "FreeBSD Ports Collection"
100 and is used to do `fake pkg_add' operations when a port is installed.
101 In such cases, it is necessary to know what the final, adjusted packing
104 Turn on verbose output.
106 Force tar to follow symbolic links, so that the files they point to
107 are dumped, rather than the links themselves.
111 to be the pre-install procedure for the package. This can be any executable
112 program (or shell script). It will be invoked automatically when the
113 package is later installed. It will be passed the package's name as the
119 option is not given, this script will serve as both the pre-install and the
120 post-install script for the package, differentiating between the
121 functionality by passing the keywords
125 respectively, along with the package's name.
129 to be the post-install procedure for the package. This can be any
130 executable program (or shell script). It will be invoked automatically
131 when the package is later installed. It will be passed the package's name as
134 Set the initial package dependency list to
136 This is assumed to be a whitespace separated list of package names
137 and is meant as a convenient shorthand for specifying multiple
139 directives in the packing list (see PACKING LIST DETAILS section below).
143 as the initial directory
145 to start from in selecting files for
150 to be the de-install procedure for the package. This can be any executable
151 program (or shell script). It will be invoked automatically when the
152 package is later (if ever) de-installed. It will be passed the package's
153 name as the first argument.
158 option is not given, this script will serve as both the de-install and the
159 post-deinstall script for the package, differentiating between the
160 functionality by passing the keywords
164 respectively, along with the package's name.
168 to be the post-deinstall procedure for the package. This can be any
169 executable program (or shell script). It will be invoked automatically when
170 the package is later de-installed. It will be passed the package's name as
178 procedure for the package. This can be any
179 executable program (or shell script). It will be invoked automatically
180 at installation/deinstallation time to determine whether or not
181 installation/deinstallation should proceed.
182 To differentiate between installation and deinstallation, the keywords
186 are passed respectively, along with the package's name.
189 will override the value of
191 during package creation.
197 By default, this is the string
198 .Pa /tmp/instmp.XXXXXX ,
199 but it may be necessary to override it in the situation where
202 directory is limited. Be sure to leave some number of `X' characters
205 to fill in with a unique ID.
206 .It Fl X Ar excludefile
213 when creating final package. See
219 flag) for further information on using this flag.
220 .It Fl D Ar displayfile
221 Display the file (using
223 after installing the package. Useful for things like
224 legal notices on almost-free software, etc.
225 .It Fl m Ar mtreefile
228 with input from mtreefile before the package is installed.
240 is the name of the first directory named by a
245 .Sh PACKING LIST DETAILS
250 is fairly simple, being
251 nothing more than a single column of filenames to include in the
252 package. However, since absolute pathnames are generally a bad idea
253 for a package that could be installed potentially anywhere, there is
254 another method of specifying where things are supposed to go
255 and, optionally, what ownership and mode information they should be
256 installed with. This is done by imbeding specialized command sequences
257 in the packing list. Briefly described, these sequences are:
258 .Bl -tag -width indent -compact
259 .It Cm @cwd Ar directory
260 Set the internal directory pointer to point to
262 All subsequent filenames will be assumed relative to this directory.
265 is also an alias for this command.
266 .It Cm @srcdir Ar directory
267 Set the internal directory pointer for _creation only_ to
269 That is to say that it overrides
271 for package creation but not extraction.
272 .It Cm @exec Ar command
275 as part of the unpacking process. If
277 contains any of the following sequences somewhere in it, they will
278 be expanded inline. For the following examples, assume that
282 and the last extracted file was
284 .Bl -tag -width indent -compact
286 Expands to the last filename extracted (as specified), in the example case
289 Expand to the current directory prefix, as set with
296 of the fully qualified filename, that
297 is the current directory prefix, plus the last filespec, minus
298 the trailing filename. In the example case, that would be
303 part of the fully qualified name, or
306 being in the example case,
309 .It Cm @unexec Ar command
312 as part of the deinstallation process. Expansion of special
314 sequences is the same as for
316 This command is not executed during the package add, as
318 is, but rather when the package is deleted. This is useful
319 for deleting links and other ancillary files that were created
320 as a result of adding the package, but not directly known to
321 the package's table of contents (and hence not automatically
322 removable). The advantage of using
324 over a deinstallation script is that you can use the
325 .Dq special sequence expansion
326 to get at files regardless of where they've
327 been potentially redirected (see
330 Set default permission for all subsequently extracted files to
332 Format is the same as that used by the
334 command (well, considering that it's later handed off to it, that's
335 no surprise). Use without an arg to set back to default (extraction)
337 .It Cm @option Ar option
338 Set internal package options, the only two currently supported ones
340 .Ar extract-in-place ,
341 which tells the pkg_add command not to extract the package's tarball
342 into a staging area but rather directly into the target
343 hierarchy (this is typically meant to be used only by distributions
344 or other special package types), and
346 which tells pkg_add to move any existing files out of the way,
347 preserving the previous contents (which are also resurrected on
348 pkg_delete, so caveat emptor).
349 .It Cm @owner Ar user
350 Set default ownership for all subsequently extracted files to
352 Use without an arg to set back to default (extraction)
354 .It Cm @group Ar group
355 Set default group ownership for all subsequently extracted files to
357 Use without an arg to set back to default (extraction)
359 .It Cm @comment Ar string
360 Imbed a comment in the packing list. Useful in
361 trying to document some particularly hairy sequence that
362 may trip someone up later.
364 Used internally to tell extraction to ignore the next file (don't
365 copy it anywhere), as it's used for some special purpose.
369 but the ignoring of the next file is delayed one evaluation cycle. This
370 makes it possible to use this directive in the
372 file, so you can pack a
373 specialized datafile in with a distribution for your install script (or
374 something) yet have the installer ignore it.
376 Set the name of the package. This is mandatory and is usually
377 put at the top. This name is potentially different than the name of
378 the file it came in, and is used when keeping track of the package
379 for later deinstallation. Note that
381 will derive this field from the package name and add it automatically
383 .It Cm @dirrm Ar name
386 to be deleted at deinstall time. By default, directories created by a
387 package installation are not deleted when the package is deinstalled;
388 this provides an explicit directory cleanup method. This directive
389 should appear at the end of the package list. If more than one
391 directives are used, the directories are removed in the order specified.
394 directory will not be removed unless it is empty.
395 .It Cm @mtree Ar name
400 input file to be used at install time (see
402 above). Only the first
404 directive is honored.
405 .It Cm @display Ar name
408 as the file to be displayed at install time (see
411 .It Cm @pkgdep Ar pkgname
412 Declare a dependency on the
416 package must be installed before this package may be
417 installed, and this package must be deinstalled before the
419 package is deinstalled. Multiple
421 directives may be used if the package depends on multiple other packages.
424 The environment variable
426 names the directory where
428 will attempt to create its temporary files.
432 the directory named by the contents of
439 are set, the builtin defaults are used.
441 .Bl -tag -width /usr/tmp -compact
443 Temporary directory if environmental variables
465 command first appeared in
469 for most of the work.
471 for NetBSD refinements.
473 Hard links between files in a distribution must be bracketed by
475 directives in order to be preserved as hard links when the package is
476 extracted. They additionally must not end up being split between
478 invocations due to exec argument-space limitations (this depends on the
480 .Fn sysconf _SC_ARG_MAX ) .