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
46 .Op Fl X Ar excludefile
47 .Op Fl D Ar displayfile
49 .Op Fl o Ar originpath
61 command is used to create packages that will subsequently be fed to
62 one of the package extraction/info utilities.
64 and command line arguments for the creation of a package are not
65 meant to be human-generated, though it is easy enough to do so.
66 It is more expected that you will use a front-end tool for
67 the job rather than muddling through it yourself.
69 description of the input syntax is included in this document.
71 The following command line options are supported:
72 .Bl -tag -width indent
73 .It Fl f Ar packinglist
76 for package from the file
89 .Dq one line description
95 This string should also
96 give some idea of which version of the product (if any) the package
101 Fetch long description for package from file
107 Assume a default answer of `Yes' for any questions asked.
109 Assume a default answer of `No' for any questions asked.
110 .It Fl O , -plist-only
111 Go into a `packing list Only' mode.
112 This is a custom hack for the
114 .Em "Ports Collection"
115 and is used to do `fake pkg_add' operations when a port is installed.
116 In such cases, it is necessary to know what the final, adjusted packing
119 Turn on verbose output.
121 Force tar to follow symbolic links, so that the files they point to
122 are dumped, rather than the links themselves.
126 to be the pre-install procedure for the package.
127 This can be any executable
128 program (or shell script).
129 It will be invoked automatically when the
130 package is later installed.
131 It will be passed the package's name as the
137 option is not given, this script will serve as both the pre-install and the
138 post-install script for the package, differentiating between the
139 functionality by passing the keywords
143 respectively, after the package's name.
147 to be the post-install procedure for the package.
149 executable program (or shell script).
150 It will be invoked automatically
151 when the package is later installed.
152 It will be passed the package's name as
154 .It Fl C Ar conflicts
155 Set the initial package conflict list to
157 This is assumed to be a whitespace separated list of package names
158 and is meant as a convenient shorthand for specifying multiple
160 directives in the packing list (see PACKING LIST DETAILS section below).
162 Set the initial package dependency list to
164 This is assumed to be a whitespace separated list of package names
165 and is meant as a convenient shorthand for specifying multiple
167 directives in the packing list (see
168 .Sx "PACKING LIST DETAILS"
170 Each argument from the
172 list could be in the form
173 .Ar pkgname Ns Op : Ns Ar pkgorigin ,
176 element denotes origin of each dependency from the list and it is
177 recorded into the packing list along with the
182 .It Fl p , -prefix Ar prefix
185 as the initial directory
187 to start from in selecting files for
192 to be the de-install procedure for the package.
193 This can be any executable
194 program (or shell script).
195 It will be invoked automatically when the
196 package is later (if ever) de-installed.
197 It will be passed the package's
198 name as the first argument.
203 option is not given, this script will serve as both the de-install and the
204 post-deinstall script for the package, differentiating between the
205 functionality by passing the keywords
209 respectively, along with the package's name.
213 to be the post-deinstall procedure for the package.
215 executable program (or shell script).
216 It will be invoked automatically when
217 the package is later de-installed.
218 It will be passed the package's name as
225 procedure for the package.
227 executable program (or shell script).
228 It will be invoked automatically
229 at installation/deinstallation time to determine whether or not
230 installation/deinstallation should proceed.
231 To differentiate between installation and deinstallation, the keywords
235 are passed respectively, along with the package's name.
238 will override the value of
240 during package creation.
243 will be prefixed to all
245 during package creation.
246 .It Fl t , -template Ar template
251 By default, this is the string
252 .Pa /tmp/instmp.XXXXXX ,
253 but it may be necessary to override it in the situation where
256 directory is limited.
257 Be sure to leave some number of `X' characters
260 to fill in with a unique ID.
261 .It Fl X Ar excludefile
268 when creating final package.
275 flag) for further information on using this flag.
276 .It Fl D Ar displayfile
277 Display the file (by concatenating it to stdout)
278 after installing the package.
279 Useful for things like
280 legal notices on almost-free software, etc.
281 .It Fl m Ar mtreefile
284 with input from mtreefile before the package is installed.
296 is the name of the first directory named by a
299 .It Fl o , -origin Ar originpath
302 as location of the port from which package has been created in the
304 .Em "Ports Collection" .
305 It should be in the form
306 .Pa MASTERCATEGORY/PORTDIR .
310 utility to compress package tarball instead of
312 Please note that this option is a NO-OP if the format of the resulting
313 archive is explicitly specified by the recognizable suffix of
317 recognizes the following suffixes:
322 Compatibility synonym for
327 utility to compress package tarball.
328 .It Fl b , -backup Ar pkg-name
329 Create package file from a locally installed package named
333 is not specified, then resulting archive will be created in the
334 current directory and named
336 with an appropriate extraction suffix applied.
337 .It Fl R , -recursive
338 When creating package file from a locally installed package
339 also create package files for all packages required by
341 Resulting archive(s) will be created in the current directory
342 and named using name of the respective package with appropriate
343 extraction suffix applied.
345 Use basic regular expressions for
348 Use extended (modern) regular expressions for
351 Use exact matching for
357 If a package tarball exists, the
359 utility will not overwrite it.
360 This is useful, for example, when multiple packages are saved with
361 several consecutive runs of
366 Saving common dependencies multiple times would do a lot of duplicate
370 option avoids repackaging common dependencies multiple times.
372 .Sh PACKING LIST DETAILS
377 is fairly simple, being
378 nothing more than a single column of filenames to include in the
380 However, since absolute pathnames are generally a bad idea
381 for a package that could be installed potentially anywhere, there is
382 another method of specifying where things are supposed to go
383 and, optionally, what ownership and mode information they should be
385 This is done by embedding specialized command sequences
387 Briefly described, these sequences are:
388 .Bl -tag -width indent -compact
389 .It Cm @cwd Op Ar directory
390 Set the internal directory pointer to point to
392 All subsequent filenames will be assumed relative to this directory.
395 argument is given, it will set the internal directory pointer to the
399 is also an alias for this command.
400 .It Cm @srcdir Ar directory
401 Set the internal directory pointer for _creation only_ to
403 That is to say that it overrides
405 for package creation but not extraction.
406 .It Cm @exec Ar command
409 as part of the unpacking process.
412 contains any of the following sequences somewhere in it, they will
414 For the following examples, assume that
418 and the last extracted file was
420 .Bl -tag -width indent -compact
422 Expands to the last filename extracted (as specified), in the example case
425 Expand to the current directory prefix, as set with
432 of the fully qualified filename, that
433 is the current directory prefix, plus the last filespec, minus
434 the trailing filename.
435 In the example case, that would be
440 part of the fully qualified name, or
443 being in the example case,
446 .It Cm @unexec Ar command
449 as part of the deinstallation process.
452 sequences is the same as for
454 This command is not executed during the package add, as
456 is, but rather when the package is deleted.
458 for deleting links and other ancillary files that were created
459 as a result of adding the package, but not directly known to
460 the package's table of contents (and hence not automatically
462 The advantage of using
464 over a deinstallation script is that you can use the
465 .Dq special sequence expansion
466 to get at files regardless of where they have
467 been potentially redirected (see
470 Set default permission for all subsequently extracted files to
472 Format is the same as that used by the
474 command (well, considering that it is later handed off to it, that is
476 Use without an arg to set back to default (extraction)
478 .It Cm @option Ar option
479 Set internal package options, the only two currently supported ones
481 .Ar extract-in-place ,
482 which tells the pkg_add command not to extract the package's tarball
483 into a staging area but rather directly into the target
484 hierarchy (this is typically meant to be used only by distributions
485 or other special package types), and
487 which tells pkg_add to move any existing files out of the way,
488 preserving the previous contents (which are also resurrected on
489 pkg_delete, so caveat emptor).
490 .It Cm @owner Ar user
491 Set default ownership for all subsequently extracted files to
493 Use without an arg to set back to default (extraction)
495 .It Cm @group Ar group
496 Set default group ownership for all subsequently extracted files to
498 Use without an arg to set back to default (extraction)
500 .It Cm @comment Ar string
501 Imbed a comment in the packing list.
503 trying to document some particularly hairy sequence that
504 may trip someone up later.
505 .It Cm @noinst Ar option Ar file
506 Specify that the package would have installed
510 had been specified at build time.
515 (which is doing nothing, it is just additional information).
517 Used internally to tell extraction to ignore the next file (do not
518 copy it anywhere), as it is used for some special purpose.
522 but the ignoring of the next file is delayed one evaluation cycle.
524 makes it possible to use this directive in the
526 file, so you can pack a
527 specialized datafile in with a distribution for your install script (or
528 something) yet have the installer ignore it.
530 Set the name of the package.
531 This is mandatory and is usually
533 This name is potentially different from the name of
534 the file it came in, and is used when keeping track of the package
535 for later deinstallation.
538 will derive this field from the package name and add it automatically
540 .It Cm @dirrm Ar name
543 to be deleted at deinstall time.
544 By default, directories created by a
545 package installation are not deleted when the package is deinstalled;
546 this provides an explicit directory cleanup method.
548 should appear at the end of the package list.
551 directives are used, the directories are removed in the order specified.
554 directory will not be removed unless it is empty.
555 .It Cm @mtree Ar name
560 input file to be used at install time (see
565 directive is honored.
566 .It Cm @display Ar name
569 as the file to be displayed at install time (see
572 .It Cm @pkgdep Ar pkgname
573 Declare a dependency on the
578 package must be installed before this package may be
579 installed, and this package must be deinstalled before the
581 package is deinstalled.
584 directives may be used if the package depends on multiple other packages.
585 .It Cm @conflicts Ar pkgcflname
586 Declare a conflict with the
588 package, as the two packages contain references to the same files,
589 and so cannot co-exist on the same system.
592 The environment variable
594 names the directory where
596 will attempt to create its temporary files.
600 the directory named by the contents of
607 are set, the builtin defaults are used.
609 .Bl -tag -width /usr/tmp -compact
611 Temporary directory if environmental variables
634 command first appeared in
639 .An John Kohl Aq jtk@rational.com ,
640 .An Oliver Eikemeier Aq eik@FreeBSD.org
642 Hard links between files in a distribution must be bracketed by
644 directives in order to be preserved as hard links when the package is
646 They additionally must not end up being split between
648 invocations due to exec argument-space limitations (this depends on the
650 .Fn sysconf _SC_ARG_MAX ) .