usr.sbin/pkg_install/create/pkg_create.1

   1 .\"
   2 .\" FreeBSD install - a package for the installation and maintainance
   3 .\" of non-core utilities.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   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.
  13 .\"
  14 .\" Jordan K. Hubbard
  15 .\"
  16 .\"
  17 .\"     @(#)pkg_create.1
  18 .\" $FreeBSD$
  19 .\"
  20 .\" hacked up by John Kohl for NetBSD--fixed a few bugs, extended keywords,
  21 .\" added dependency tracking, etc.
  22 .\"
  23 .\" [jkh] Took John's changes back and made some additional extensions for
  24 .\" better integration with FreeBSD's new ports collection.
  25 .\"
  26 .Dd April 21, 1995
  27 .Dt PKG_CREATE 1
  28 .Os FreeBSD
  29 .Sh NAME
  30 .Nm pkg_create
  31 .Nd a utility for creating software package distributions
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Op Fl YNOhv
  35 .Op Fl P Ar pkgs
  36 .Op Fl p Ar prefix
  37 .Op Fl f Ar contents
  38 .Op Fl i Ar iscript
  39 .Op Fl I Ar piscript
  40 .Op Fl k Ar dscript
  41 .Op Fl K Ar pdscript
  42 .Op Fl r Ar rscript
  43 .Op Fl s Ar srcdir
  44 .Op Fl t Ar template
  45 .Op Fl X Ar excludefile
  46 .Op Fl D Ar displayfile
  47 .Op Fl m Ar mtreefile
  48 .Fl c Ar comment
  49 .Fl d Ar description
  50 .Fl f Ar packlist
  51 .Ar pkg-name
  52 .Sh DESCRIPTION
  53 The
  54 .Nm
  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.
  62 .Sh OPTIONS
  63 The following command line options are supported:
  64 .Bl -tag -width indent
  65 .It Fl f Ar packinglist
  66 Fetch
  67 .Dq packing list
  68 for package from the file
  69 .Ar packinglist
  70 or
  71 .Cm stdin
  72 if
  73 .Ar packinglist
  74 is a
  75 .Cm -
  76 (dash).
  77 .It Fl c Ar [-]desc
  78 Fetch package
  79 .Dq one line description
  80 from file
  81 .Ar desc
  82 or, if preceded by
  83 .Cm - ,
  84 the argument itself.  This string should also
  85 give some idea of which version of the product (if any) the package
  86 represents.
  87 .It Fl d Ar [-]desc
  88 Fetch long description for package from file
  89 .Ar desc
  90 or, if preceded by
  91 .Cm - ,
  92 the argument itself.
  93 .It Fl Y
  94 Assume a default answer of `Yes' for any questions asked.
  95 .It Fl N
  96 Assume a default answer of `No' for any questions asked.
  97 .It Fl O
  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
 102 list will look like.
 103 .It Fl v
 104 Turn on verbose output.
 105 .It Fl h
 106 Force tar to follow symbolic links, so that the files they point to
 107 are dumped, rather than the links themselves.
 108 .It Fl i Ar iscript
 109 Set
 110 .Ar iscript
 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
 114 first argument.
 115
 116 .Cm Note:
 117 if the
 118 .Cm Fl I
 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
 122 .Ar PRE-INSTALL
 123 and
 124 .Ar POST-INSTALL
 125 respectively, along with the package's name.
 126 .It Fl I Ar piscript
 127 Set
 128 .Ar piscript
 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
 132 the first argument.
 133 .It Fl P Ar pkgs
 134 Set the initial package dependency list to
 135 .Ar pkgs .
 136 This is assumed to be a whitespace separated list of package names
 137 and is meant as a convenient shorthand for specifying multiple
 138 .Cm @pkgdep
 139 directives in the packing list (see PACKING LIST DETAILS section below).
 140 .It Fl p Ar prefix
 141 Set
 142 .Ar prefix
 143 as the initial directory
 144 .Dq base
 145 to start from in selecting files for
 146 the package.
 147 .It Fl k Ar dscript
 148 Set
 149 .Ar dscript
 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.
 154
 155 .Cm Note:
 156 if the
 157 .Cm Fl K
 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
 161 .Ar DEINSTALL
 162 and
 163 .Ar POST-DEINSTALL
 164 respectively, along with the package's name.
 165 .It Fl K Ar pdscript
 166 Set
 167 .Ar pdscript
 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
 171 the first argument.
 172
 173 .It Fl r Ar rscript
 174 Set
 175 .Ar rscript
 176 to be the
 177 .Dq requirements
 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
 183 .Ar INSTALL
 184 and
 185 .Ar DEINSTALL
 186 are passed respectively, along with the package's name.
 187 .It Fl s Ar srcdir
 188 .Ar srcdir
 189 will override the value of
 190 .Cm @cwd
 191 during package creation.
 192 .It Fl t Ar template
 193 Use
 194 .Ar template
 195 as the input to
 196 .Xr mktemp 3 .
 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
 200 space in your
 201 .Pa /tmp
 202 directory is limited.  Be sure to leave some number of `X' characters
 203 for
 204 .Xr mktemp 3
 205  to fill in with a unique ID.
 206 .It Fl X Ar excludefile
 207 Pass
 208 .Ar excludefile
 209 as a
 210 .Fl exclude-from
 211 argument to
 212 .Cm tar
 213 when creating final package.  See
 214 .Cm tar
 215 man page (or run
 216 .Cm tar
 217 with
 218 .Fl -help
 219 flag) for further information on using this flag.
 220 .It Fl D Ar displayfile
 221 Display the file (using
 222 .Xr more 1 )
 223 after installing the package.  Useful for things like
 224 legal notices on almost-free software, etc.
 225 .It Fl m Ar mtreefile
 226 Run
 227 .Xr mtree 8
 228 with input from mtreefile before the package is installed.
 229 Mtree is invoked as
 230 .Cm mtree
 231 .Fl u
 232 .Fl f
 233 .Ar mtreefile
 234 .Fl d
 235 .Fl e
 236 .Fl p
 237 .Pa prefix ,
 238 where
 239 .Pa prefix
 240 is the name of the first directory named by a
 241 .Cm @cwd
 242 directive.
 243 .El
 244 .Pp
 245 .Sh PACKING LIST DETAILS
 246 The
 247 .Dq packing list
 248 format (see
 249 .Fl f )
 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
 261 .Ar directory .
 262 All subsequent filenames will be assumed relative to this directory.
 263 Note:
 264 .Cm @cd
 265 is also an alias for this command.
 266 .It Cm @srcdir Ar directory
 267 Set the internal directory pointer for _creation only_ to
 268 .Ar directory .
 269 That is to say that it overrides
 270 .Cm @cwd
 271 for package creation but not extraction.
 272 .It Cm @exec Ar command
 273 Execute
 274 .Ar command
 275 as part of the unpacking process.  If
 276 .Ar command
 277 contains any of the following sequences somewhere in it, they will
 278 be expanded inline.  For the following examples, assume that
 279 .Cm @cwd
 280 is set to
 281 .Pa /usr/local
 282 and the last extracted file was
 283 .Pa bin/emacs .
 284 .Bl -tag -width indent -compact
 285 .It Cm "%F"
 286 Expands to the last filename extracted (as specified), in the example case
 287 .Pa bin/emacs
 288 .It Cm "%D"
 289 Expand to the current directory prefix, as set with
 290 .Cm @cwd ,
 291 in the example case
 292 .Pa /usr/local .
 293 .It Cm "%B"
 294 Expand to the
 295 .Dq basename
 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
 299 .Pa /usr/local/bin .
 300 .It Cm "%f"
 301 Expand to the
 302 filename
 303 part of the fully qualified name, or
 304 the converse of
 305 .Cm %B ,
 306 being in the example case,
 307 .Pa emacs .
 308 .El
 309 .It Cm @unexec Ar command
 310 Execute
 311 .Ar command
 312 as part of the deinstallation process.  Expansion of special
 313 .Cm %
 314 sequences is the same as for
 315 .Cm @exec .
 316 This command is not executed during the package add, as
 317 .Cm @exec
 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
 323 .Cm @unexec
 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
 328 .Fl p ) .
 329 .It Cm @mode Ar mode
 330 Set default permission for all subsequently extracted files to
 331 .Ar mode .
 332 Format is the same as that used by the
 333 .Cm chmod
 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)
 336 permissions.
 337 .It Cm @option Ar option
 338 Set internal package options, the only two currently supported ones
 339 being
 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
 345 .Ar preserve ,
 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
 351 .Ar user .
 352 Use without an arg to set back to default (extraction)
 353 ownership.
 354 .It Cm @group Ar group
 355 Set default group ownership for all subsequently extracted files to
 356 .Ar group .
 357 Use without an arg to set back to default (extraction)
 358 group ownership.
 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.
 363 .It Cm @ignore
 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.
 366 .It Cm @ignore_inst
 367 Similar to
 368 .Cm @ignore ,
 369 but the ignoring of the next file is delayed one evaluation cycle.  This
 370 makes it possible to use this directive in the
 371 .Ar packinglist
 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.
 375 .It Cm @name Ar name
 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
 380 .Nm
 381 will derive this field from the package name and add it automatically
 382 if none is given.
 383 .It Cm @dirrm Ar name
 384 Declare directory
 385 .Pa 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
 390 .Cm @dirrm
 391 directives are used, the directories are removed in the order specified.
 392 The
 393 .Pa name
 394 directory will not be removed unless it is empty.
 395 .It Cm @mtree Ar name
 396 Declare
 397 .Pa name
 398 as an
 399 .Xr mtree 8
 400 input file to be used at install time (see
 401 .Fl m
 402 above).  Only the first
 403 .Cm @mtree
 404 directive is honored.
 405 .It Cm @display Ar name
 406 Declare
 407 .Pa name
 408 as the file to be displayed at install time (see
 409 .Fl D
 410 above).
 411 .It Cm @pkgdep Ar pkgname
 412 Declare a dependency on the
 413 .Ar pkgname
 414 package.  The
 415 .Ar pkgname
 416 package must be installed before this package may be
 417 installed, and this package must be deinstalled before the
 418 .Ar pkgname
 419 package is deinstalled.  Multiple
 420 .Cm @pkgdep
 421 directives may be used if the package depends on multiple other packages.
 422 .El
 423 .Sh ENVIRONMENT
 424 The environment variable
 425 .Ev PKG_TMPDIR
 426 names the directory where
 427 .Nm
 428 will attempt to create its temporary files.
 429 If
 430 .Ev PKG_TMPDIR
 431 is not set,
 432 the directory named by the contents of
 433 .Ev TMPDIR
 434 will be used.
 435 If neither of
 436 .Ev PKG_TMPDIR
 437 and
 438 .Ev TMPDIR
 439 are set, the builtin defaults are used.
 440 .Sh FILES
 441 .Bl -tag -width /usr/tmp -compact
 442 .It Pa /var/tmp
 443 Temporary directory if environmental variables
 444 .Ev PKG_TMPDIR
 445 and
 446 .Ev TMPDIR
 447 are not set.
 448 .It Pa /tmp
 449 The next choice if
 450 .Pa /var/tmp
 451 does not exist.
 452 .It Pa /usr/tmp
 453 The last choice if
 454 .Pa /tmp
 455 is unsuitable.
 456 .El
 457 .Sh SEE ALSO
 458 .Xr pkg_add 1 ,
 459 .Xr pkg_delete 1 ,
 460 .Xr pkg_info 1 ,
 461 .Xr sysconf 3
 462 .Sh HISTORY
 463 The
 464 .Nm
 465 command first appeared in
 466 .Bx Free .
 467 .Sh AUTHORS
 468 .An Jordan Hubbard
 469 for most of the work.
 470 .An John Kohl
 471 for NetBSD refinements.
 472 .Sh BUGS
 473 Hard links between files in a distribution must be bracketed by
 474 .Cm @cwd
 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
 477 .Cm tar
 478 invocations due to exec argument-space limitations (this depends on the
 479 value returned by
 480 .Fn sysconf _SC_ARG_MAX ) .
 481 .Pp
 482 Sure to be others.