2 .\" FreeBSD install - a package for the installation and maintenance
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:
318 .Pa .tbz , .tgz, .txz
322 Compatibility synonym for
327 utility to compress package tarball.
331 utility to compress package tarball instead of
333 Please note that this option is a NO-OP if the format of the resulting
334 archive is explicitly specified by the recognizable suffix of
338 recognizes the following suffixes:
339 .Pa .tbz , .tgz, .txz
342 .It Fl b , -backup Ar pkg-name
343 Create package file from a locally installed package named
347 is not specified, then resulting archive will be created in the
348 current directory and named
350 with an appropriate extraction suffix applied.
351 .It Fl R , -recursive
352 When creating package file from a locally installed package
353 also create package files for all packages required by
355 Resulting archive(s) will be created in the current directory
356 and named using name of the respective package with appropriate
357 extraction suffix applied.
359 Use basic regular expressions for
362 Use extended (modern) regular expressions for
365 Use exact matching for
371 If a package tarball exists, the
373 utility will not overwrite it.
374 This is useful, for example, when multiple packages are saved with
375 several consecutive runs of
380 Saving common dependencies multiple times would do a lot of duplicate
384 option avoids repackaging common dependencies multiple times.
386 .Sh PACKING LIST DETAILS
391 is fairly simple, being
392 nothing more than a single column of filenames to include in the
394 However, since absolute pathnames are generally a bad idea
395 for a package that could be installed potentially anywhere, there is
396 another method of specifying where things are supposed to go
397 and, optionally, what ownership and mode information they should be
399 This is done by embedding specialized command sequences
401 Briefly described, these sequences are:
402 .Bl -tag -width indent -compact
403 .It Cm @cwd Op Ar directory
404 Set the internal directory pointer to point to
406 All subsequent filenames will be assumed relative to this directory.
409 argument is given, it will set the internal directory pointer to the
413 is also an alias for this command.
414 .It Cm @srcdir Ar directory
415 Set the internal directory pointer for _creation only_ to
417 That is to say that it overrides
419 for package creation but not extraction.
420 .It Cm @exec Ar command
423 as part of the unpacking process.
426 contains any of the following sequences somewhere in it, they will
428 For the following examples, assume that
432 and the last extracted file was
434 .Bl -tag -width indent -compact
436 Expands to the last filename extracted (as specified), in the example case
439 Expand to the current directory prefix, as set with
446 of the fully qualified filename, that
447 is the current directory prefix, plus the last filespec, minus
448 the trailing filename.
449 In the example case, that would be
454 part of the fully qualified name, or
457 being in the example case,
460 .It Cm @unexec Ar command
463 as part of the deinstallation process.
466 sequences is the same as for
468 This command is not executed during the package add, as
470 is, but rather when the package is deleted.
472 for deleting links and other ancillary files that were created
473 as a result of adding the package, but not directly known to
474 the package's table of contents (and hence not automatically
476 The advantage of using
478 over a deinstallation script is that you can use the
479 .Dq special sequence expansion
480 to get at files regardless of where they have
481 been potentially redirected (see
484 Set default permission for all subsequently extracted files to
486 Format is the same as that used by the
488 command (well, considering that it is later handed off to it, that is
490 Use without an arg to set back to default (extraction)
492 .It Cm @option Ar option
493 Set internal package options, the only two currently supported ones
495 .Ar extract-in-place ,
496 which tells the pkg_add command not to extract the package's tarball
497 into a staging area but rather directly into the target
498 hierarchy (this is typically meant to be used only by distributions
499 or other special package types), and
501 which tells pkg_add to move any existing files out of the way,
502 preserving the previous contents (which are also resurrected on
503 pkg_delete, so caveat emptor).
504 .It Cm @owner Ar user
505 Set default ownership for all subsequently extracted files to
507 Use without an arg to set back to default (extraction)
509 .It Cm @group Ar group
510 Set default group ownership for all subsequently extracted files to
512 Use without an arg to set back to default (extraction)
514 .It Cm @comment Ar string
515 Imbed a comment in the packing list.
517 trying to document some particularly hairy sequence that
518 may trip someone up later.
519 .It Cm @noinst Ar option Ar file
520 Specify that the package would have installed
524 had been specified at build time.
529 (which is doing nothing, it is just additional information).
531 Used internally to tell extraction to ignore the next file (do not
532 copy it anywhere), as it is used for some special purpose.
536 but the ignoring of the next file is delayed one evaluation cycle.
538 makes it possible to use this directive in the
540 file, so you can pack a
541 specialized datafile in with a distribution for your install script (or
542 something) yet have the installer ignore it.
544 Set the name of the package.
545 This is mandatory and is usually
547 This name is potentially different from the name of
548 the file it came in, and is used when keeping track of the package
549 for later deinstallation.
552 will derive this field from the package name and add it automatically
554 .It Cm @dirrm Ar name
557 to be deleted at deinstall time.
558 By default, directories created by a
559 package installation are not deleted when the package is deinstalled;
560 this provides an explicit directory cleanup method.
562 should appear at the end of the package list.
565 directives are used, the directories are removed in the order specified.
568 directory will not be removed unless it is empty.
569 .It Cm @mtree Ar name
574 input file to be used at install time (see
579 directive is honored.
580 .It Cm @display Ar name
583 as the file to be displayed at install time (see
586 .It Cm @pkgdep Ar pkgname
587 Declare a dependency on the
592 package must be installed before this package may be
593 installed, and this package must be deinstalled before the
595 package is deinstalled.
598 directives may be used if the package depends on multiple other packages.
599 .It Cm @conflicts Ar pkgcflname
600 Declare a conflict with the
602 package, as the two packages contain references to the same files,
603 and so cannot co-exist on the same system.
606 The environment variable
608 names the directory where
610 will attempt to create its temporary files.
614 the directory named by the contents of
621 are set, the builtin defaults are used.
623 .Bl -tag -width /usr/tmp -compact
625 Temporary directory if environmental variables
638 .It Ev PKG_OLD_NOWARN
641 will not warn about its use in the presence of pkgng databases.
652 command first appeared in
657 .An John Kohl Aq jtk@rational.com ,
658 .An Oliver Eikemeier Aq eik@FreeBSD.org
660 Hard links between files in a distribution must be bracketed by
662 directives in order to be preserved as hard links when the package is
664 They additionally must not end up being split between
666 invocations due to exec argument-space limitations (this depends on the
668 .Fn sysconf _SC_ARG_MAX ) .