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.63 2005/02/13 23:45:52 ru Exp $
19 .\" $DragonFly: src/usr.sbin/pkg_install/create/Attic/pkg_create.1,v 1.4 2005/03/08 19:11:30 joerg Exp $
21 .\" hacked up by John Kohl for NetBSD--fixed a few bugs, extended keywords,
22 .\" added dependency tracking, etc.
24 .\" [jkh] Took John's changes back and made some additional extensions for
25 .\" better integration with FreeBSD's new ports collection.
32 .Nd a utility for creating software package distributions
47 .Op Fl X Ar excludefile
48 .Op Fl D Ar displayfile
50 .Op Fl o Ar originpath
62 command is used to create packages that will subsequently be fed to
63 one of the package extraction/info utilities.
65 and command line arguments for the creation of a package are not
66 really meant to be human-generated, though it is easy enough to
68 It is more expected that you will use a front-end tool for
69 the job rather than muddling through it yourself.
71 description of the input syntax is included in this document.
73 The following command line options are supported:
74 .Bl -tag -width indent
75 .It Fl f Ar packinglist
78 for package from the file
91 .Dq one line description
97 This string should also
98 give some idea of which version of the product (if any) the package
103 Fetch long description for package from file
109 Assume a default answer of `Yes' for any questions asked.
111 Assume a default answer of `No' for any questions asked.
113 Go into a `packing list Only' mode.
114 This is a custom hack for the
116 .Em "Ports Collection"
117 and is used to do `fake pkg_add' operations when a port is installed.
118 In such cases, it is necessary to know what the final, adjusted packing
121 Turn on verbose output.
123 Force tar to follow symbolic links, so that the files they point to
124 are dumped, rather than the links themselves.
128 to be the pre-install procedure for the package.
129 This can be any executable
130 program (or shell script).
131 It will be invoked automatically when the
132 package is later installed.
133 It will be passed the package's name as the
139 option is not given, this script will serve as both the pre-install and the
140 post-install script for the package, differentiating between the
141 functionality by passing the keywords
145 respectively, after the package's name.
149 to be the post-install procedure for the package.
151 executable program (or shell script).
152 It will be invoked automatically
153 when the package is later installed.
154 It will be passed the package's name as
156 .It Fl C Ar conflicts
157 Set the initial package conflict list to
159 This is assumed to be a whitespace separated list of package names
160 and is meant as a convenient shorthand for specifying multiple
162 directives in the packing list (see PACKING LIST DETAILS section below).
164 Set the initial package dependency list to
166 This is assumed to be a whitespace separated list of package names
167 and is meant as a convenient shorthand for specifying multiple
169 directives in the packing list (see
170 .Sx "PACKING LIST DETAILS"
172 Each argument from the
174 list could be in the form
175 .Ar pkgname Ns Op : Ns Ar pkgorigin ,
178 element denotes origin of each dependency from the list and it is
179 recorded into the packing list along with the
187 as the initial directory
189 to start from in selecting files for
194 to be the de-install procedure for the package.
195 This can be any executable
196 program (or shell script).
197 It will be invoked automatically when the
198 package is later (if ever) de-installed.
199 It will be passed the package's
200 name as the first argument.
205 option is not given, this script will serve as both the de-install and the
206 post-deinstall script for the package, differentiating between the
207 functionality by passing the keywords
211 respectively, along with the package's name.
215 to be the post-deinstall procedure for the package.
217 executable program (or shell script).
218 It will be invoked automatically when
219 the package is later de-installed.
220 It will be passed the package's name as
227 procedure for the package.
229 executable program (or shell script).
230 It will be invoked automatically
231 at installation/deinstallation time to determine whether or not
232 installation/deinstallation should proceed.
233 To differentiate between installation and deinstallation, the keywords
237 are passed respectively, along with the package's name.
240 will override the value of
242 during package creation.
245 will be prefixed to all
247 during package creation.
253 By default, this is the string
254 .Pa /tmp/instmp.XXXXXX ,
255 but it may be necessary to override it in the situation where
258 directory is limited.
259 Be sure to leave some number of `X' characters
262 to fill in with a unique ID.
263 .It Fl X Ar excludefile
270 when creating final package.
277 flag) for further information on using this flag.
278 .It Fl D Ar displayfile
279 Display the file (by concatenating it to stdout)
280 after installing the package.
281 Useful for things like
282 legal notices on almost-free software, etc.
283 .It Fl m Ar mtreefile
286 with input from mtreefile before the package is installed.
298 is the name of the first directory named by a
301 .It Fl o Ar originpath
304 as location of the port from which package has been created in the
306 .Em "Ports Collection" .
307 It should be in the form
308 .Pa MASTERCATEGORY/PORTDIR .
312 utility to compress package tarball instead of
314 Please note that this option is a NO-OP if the format of the resulting
315 archive is explicitly specified by the recognizable suffix of
319 recognizes the following suffixes:
324 Compatibility synonym for
329 utility to compress package tarball.
331 Create package file from a locally installed package named
335 is not specified, then resulting archive will be created in the
336 current directory and named
338 with an appropriate extraction suffix applied.
340 .Sh PACKING LIST DETAILS
345 is fairly simple, being
346 nothing more than a single column of filenames to include in the
348 However, since absolute pathnames are generally a bad idea
349 for a package that could be installed potentially anywhere, there is
350 another method of specifying where things are supposed to go
351 and, optionally, what ownership and mode information they should be
353 This is done by embedding specialized command sequences
355 Briefly described, these sequences are:
356 .Bl -tag -width indent -compact
357 .It Cm @cwd Ar directory
358 Set the internal directory pointer to point to
360 All subsequent filenames will be assumed relative to this directory.
363 is also an alias for this command.
364 .It Cm @srcdir Ar directory
365 Set the internal directory pointer for _creation only_ to
367 That is to say that it overrides
369 for package creation but not extraction.
370 .It Cm @exec Ar command
373 as part of the unpacking process.
376 contains any of the following sequences somewhere in it, they will
378 For the following examples, assume that
382 and the last extracted file was
384 .Bl -tag -width indent -compact
386 Expands to the last filename extracted (as specified), in the example case
389 Expand to the current directory prefix, as set with
396 of the fully qualified filename, that
397 is the current directory prefix, plus the last filespec, minus
398 the trailing filename.
399 In the example case, that would be
404 part of the fully qualified name, or
407 being in the example case,
410 .It Cm @unexec Ar command
413 as part of the deinstallation process.
416 sequences is the same as for
418 This command is not executed during the package add, as
420 is, but rather when the package is deleted.
422 for deleting links and other ancillary files that were created
423 as a result of adding the package, but not directly known to
424 the package's table of contents (and hence not automatically
426 The advantage of using
428 over a deinstallation script is that you can use the
429 .Dq special sequence expansion
430 to get at files regardless of where they have
431 been potentially redirected (see
434 Set default permission for all subsequently extracted files to
436 Format is the same as that used by the
438 command (well, considering that it is later handed off to it, that is
440 Use without an arg to set back to default (extraction)
442 .It Cm @option Ar option
443 Set internal package options, the only two currently supported ones
445 .Ar extract-in-place ,
446 which tells the pkg_add command not to extract the package's tarball
447 into a staging area but rather directly into the target
448 hierarchy (this is typically meant to be used only by distributions
449 or other special package types), and
451 which tells pkg_add to move any existing files out of the way,
452 preserving the previous contents (which are also resurrected on
453 pkg_delete, so caveat emptor).
454 .It Cm @owner Ar user
455 Set default ownership for all subsequently extracted files to
457 Use without an arg to set back to default (extraction)
459 .It Cm @group Ar group
460 Set default group ownership for all subsequently extracted files to
462 Use without an arg to set back to default (extraction)
464 .It Cm @comment Ar string
465 Imbed a comment in the packing list.
467 trying to document some particularly hairy sequence that
468 may trip someone up later.
470 Used internally to tell extraction to ignore the next file (do not
471 copy it anywhere), as it is used for some special purpose.
475 but the ignoring of the next file is delayed one evaluation cycle.
477 makes it possible to use this directive in the
479 file, so you can pack a
480 specialized datafile in with a distribution for your install script (or
481 something) yet have the installer ignore it.
483 Set the name of the package.
484 This is mandatory and is usually
486 This name is potentially different from the name of
487 the file it came in, and is used when keeping track of the package
488 for later deinstallation.
491 will derive this field from the package name and add it automatically
493 .It Cm @dirrm Ar name
496 to be deleted at deinstall time.
497 By default, directories created by a
498 package installation are not deleted when the package is deinstalled;
499 this provides an explicit directory cleanup method.
501 should appear at the end of the package list.
504 directives are used, the directories are removed in the order specified.
507 directory will not be removed unless it is empty.
508 .It Cm @mtree Ar name
513 input file to be used at install time (see
518 directive is honored.
519 .It Cm @display Ar name
522 as the file to be displayed at install time (see
525 .It Cm @pkgdep Ar pkgname
526 Declare a dependency on the
531 package must be installed before this package may be
532 installed, and this package must be deinstalled before the
534 package is deinstalled.
537 directives may be used if the package depends on multiple other packages.
538 .It Cm @conflicts Ar pkgcflname
539 Declare a conflict with the
541 package, as the two packages contain references to the same files,
542 and so cannot co-exist on the same system.
545 The environment variable
547 names the directory where
549 will attempt to create its temporary files.
553 the directory named by the contents of
560 are set, the builtin defaults are used.
562 .Bl -tag -width /usr/tmp -compact
564 Temporary directory if environmental variables
587 command first appeared in
592 .An John Kohl Aq jtk@rational.com ,
593 .An Oliver Eikemeier Aq eik@FreeBSD.org
595 Hard links between files in a distribution must be bracketed by
597 directives in order to be preserved as hard links when the package is
599 They additionally must not end up being split between
601 invocations due to exec argument-space limitations (this depends on the
603 .Fn sysconf _SC_ARG_MAX ) .