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.
18 .\" $FreeBSD: src/usr.sbin/pkg_install/create/pkg_create.1,v 1.35.2.16 2002/12/29 16:35:43 schweikh Exp $
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
48 .Op Fl o Ar originpath
60 command is used to create packages that will subsequently be fed to
61 one of the package extraction/info utilities. The input description
62 and command line arguments for the creation of a package are not
63 really meant to be human-generated, though it is easy enough to
64 do so. It is more expected that you will use a front-end tool for
65 the job rather than muddling through it yourself. Nonetheless, a short
66 description of the input syntax is included in this document.
68 The following command line options are supported:
69 .Bl -tag -width indent
70 .It Fl f Ar packinglist
73 for package from the file
86 .Dq one line description
91 the argument itself. This string should also
92 give some idea of which version of the product (if any) the package
97 Fetch long description for package from file
103 Assume a default answer of `Yes' for any questions asked.
105 Assume a default answer of `No' for any questions asked.
107 Go into a `packing list Only' mode. This is a custom hack for the
109 .Em "Ports Collection"
110 and is used to do `fake pkg_add' operations when a port is installed.
111 In such cases, it is necessary to know what the final, adjusted packing
114 Turn on verbose output.
116 Force tar to follow symbolic links, so that the files they point to
117 are dumped, rather than the links themselves.
121 to be the pre-install procedure for the package. This can be any executable
122 program (or shell script). It will be invoked automatically when the
123 package is later installed.
124 It will be passed the package's name as the
130 option is not given, this script will serve as both the pre-install and the
131 post-install script for the package, differentiating between the
132 functionality by passing the keywords
136 respectively, along with the package's name.
140 to be the post-install procedure for the package. This can be any
141 executable program (or shell script). It will be invoked automatically
142 when the package is later installed.
143 It will be passed the package's name as
146 Set the initial package dependency list to
148 This is assumed to be a whitespace separated list of package names
149 and is meant as a convenient shorthand for specifying multiple
151 directives in the packing list (see
152 .Sx "PACKING LIST DETAILS"
154 Each argument from the
156 list could be in the form
157 .Ar pkgname Ns Op : Ns Ar pkgorigin ,
160 element denotes origin of each dependency from the list and it is
161 recorded into the packing list along with the
169 as the initial directory
171 to start from in selecting files for
176 to be the de-install procedure for the package. This can be any executable
177 program (or shell script). It will be invoked automatically when the
178 package is later (if ever) de-installed.
179 It will be passed the package's
180 name as the first argument.
185 option is not given, this script will serve as both the de-install and the
186 post-deinstall script for the package, differentiating between the
187 functionality by passing the keywords
191 respectively, along with the package's name.
195 to be the post-deinstall procedure for the package. This can be any
196 executable program (or shell script). It will be invoked automatically when
197 the package is later de-installed.
198 It will be passed the package's name as
205 procedure for the package. This can be any
206 executable program (or shell script). It will be invoked automatically
207 at installation/deinstallation time to determine whether or not
208 installation/deinstallation should proceed.
209 To differentiate between installation and deinstallation, the keywords
213 are passed respectively, along with the package's name.
216 will override the value of
218 during package creation.
224 By default, this is the string
225 .Pa /tmp/instmp.XXXXXX ,
226 but it may be necessary to override it in the situation where
229 directory is limited. Be sure to leave some number of `X' characters
232 to fill in with a unique ID.
233 .It Fl X Ar excludefile
240 when creating final package. See
246 flag) for further information on using this flag.
247 .It Fl D Ar displayfile
248 Display the file (by concatenating it to stdout)
249 after installing the package. Useful for things like
250 legal notices on almost-free software, etc.
251 .It Fl m Ar mtreefile
254 with input from mtreefile before the package is installed.
266 is the name of the first directory named by a
269 .It Fl o Ar originpath
272 as location of the port from which package has been created in the
274 .Em "Ports Collection" .
275 It should be in the form
276 .Pa MASTERCATEGORY/PORTDIR .
280 utility to compress package tarball instead of
282 Please note that this option is a NO-OP if the format of the resulting
283 archive is explicitly specified by the recognizable suffix of
287 recognizes the following suffixes:
292 Compatibility synonym for
297 utility to compress package tarball.
299 Create package file from a locally installed package named
303 is not specified, then resulting archive will be created in the
304 current directory and named
306 with an appropriate extraction suffix applied.
308 .Sh PACKING LIST DETAILS
313 is fairly simple, being
314 nothing more than a single column of filenames to include in the
315 package. However, since absolute pathnames are generally a bad idea
316 for a package that could be installed potentially anywhere, there is
317 another method of specifying where things are supposed to go
318 and, optionally, what ownership and mode information they should be
319 installed with. This is done by embedding specialized command sequences
320 in the packing list. Briefly described, these sequences are:
321 .Bl -tag -width indent -compact
322 .It Cm @cwd Ar directory
323 Set the internal directory pointer to point to
325 All subsequent filenames will be assumed relative to this directory.
328 is also an alias for this command.
329 .It Cm @srcdir Ar directory
330 Set the internal directory pointer for _creation only_ to
332 That is to say that it overrides
334 for package creation but not extraction.
335 .It Cm @exec Ar command
338 as part of the unpacking process. If
340 contains any of the following sequences somewhere in it, they will
341 be expanded inline. For the following examples, assume that
345 and the last extracted file was
347 .Bl -tag -width indent -compact
349 Expands to the last filename extracted (as specified), in the example case
352 Expand to the current directory prefix, as set with
359 of the fully qualified filename, that
360 is the current directory prefix, plus the last filespec, minus
361 the trailing filename. In the example case, that would be
366 part of the fully qualified name, or
369 being in the example case,
372 .It Cm @unexec Ar command
375 as part of the deinstallation process. Expansion of special
377 sequences is the same as for
379 This command is not executed during the package add, as
381 is, but rather when the package is deleted. This is useful
382 for deleting links and other ancillary files that were created
383 as a result of adding the package, but not directly known to
384 the package's table of contents (and hence not automatically
385 removable). The advantage of using
387 over a deinstallation script is that you can use the
388 .Dq special sequence expansion
389 to get at files regardless of where they've
390 been potentially redirected (see
393 Set default permission for all subsequently extracted files to
395 Format is the same as that used by the
397 command (well, considering that it's later handed off to it, that's
398 no surprise). Use without an arg to set back to default (extraction)
400 .It Cm @option Ar option
401 Set internal package options, the only two currently supported ones
403 .Ar extract-in-place ,
404 which tells the pkg_add command not to extract the package's tarball
405 into a staging area but rather directly into the target
406 hierarchy (this is typically meant to be used only by distributions
407 or other special package types), and
409 which tells pkg_add to move any existing files out of the way,
410 preserving the previous contents (which are also resurrected on
411 pkg_delete, so caveat emptor).
412 .It Cm @owner Ar user
413 Set default ownership for all subsequently extracted files to
415 Use without an arg to set back to default (extraction)
417 .It Cm @group Ar group
418 Set default group ownership for all subsequently extracted files to
420 Use without an arg to set back to default (extraction)
422 .It Cm @comment Ar string
423 Imbed a comment in the packing list. Useful in
424 trying to document some particularly hairy sequence that
425 may trip someone up later.
427 Used internally to tell extraction to ignore the next file (don't
428 copy it anywhere), as it's used for some special purpose.
432 but the ignoring of the next file is delayed one evaluation cycle. This
433 makes it possible to use this directive in the
435 file, so you can pack a
436 specialized datafile in with a distribution for your install script (or
437 something) yet have the installer ignore it.
439 Set the name of the package. This is mandatory and is usually
440 put at the top. This name is potentially different from the name of
441 the file it came in, and is used when keeping track of the package
442 for later deinstallation. Note that
444 will derive this field from the package name and add it automatically
446 .It Cm @dirrm Ar name
449 to be deleted at deinstall time. By default, directories created by a
450 package installation are not deleted when the package is deinstalled;
451 this provides an explicit directory cleanup method. This directive
452 should appear at the end of the package list. If more than one
454 directives are used, the directories are removed in the order specified.
457 directory will not be removed unless it is empty.
458 .It Cm @mtree Ar name
463 input file to be used at install time (see
465 above). Only the first
467 directive is honored.
468 .It Cm @display Ar name
471 as the file to be displayed at install time (see
474 .It Cm @pkgdep Ar pkgname
475 Declare a dependency on the
479 package must be installed before this package may be
480 installed, and this package must be deinstalled before the
482 package is deinstalled. Multiple
484 directives may be used if the package depends on multiple other packages.
487 The environment variable
489 names the directory where
491 will attempt to create its temporary files.
495 the directory named by the contents of
502 are set, the builtin defaults are used.
504 .Bl -tag -width /usr/tmp -compact
506 Temporary directory if environmental variables
530 command first appeared in
535 .An John Kohl Aq jtk@rational.com
537 Hard links between files in a distribution must be bracketed by
539 directives in order to be preserved as hard links when the package is
540 extracted. They additionally must not end up being split between
542 invocations due to exec argument-space limitations (this depends on the
544 .Fn sysconf _SC_ARG_MAX ) .