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: src/usr.sbin/pkg_install/create/pkg_create.1,v 1.35.2.16 2002/12/29 16:35:43 schweikh Exp $
  19 .\" $DragonFly: src/usr.sbin/pkg_install/create/Attic/pkg_create.1,v 1.2 2003/06/17 04:29:59 dillon Exp $
  20 .\"
  21 .\" hacked up by John Kohl for NetBSD--fixed a few bugs, extended keywords,
  22 .\" added dependency tracking, etc.
  23 .\"
  24 .\" [jkh] Took John's changes back and made some additional extensions for
  25 .\" better integration with FreeBSD's new ports collection.
  26 .\"
  27 .Dd April 21, 1995
  28 .Dt PKG_CREATE 1
  29 .Os
  30 .Sh NAME
  31 .Nm pkg_create
  32 .Nd a utility for creating software package distributions
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl YNOhjvyz
  36 .Op Fl P Ar pkgs
  37 .Op Fl p Ar prefix
  38 .Op Fl f Ar contents
  39 .Op Fl i Ar iscript
  40 .Op Fl I Ar piscript
  41 .Op Fl k Ar dscript
  42 .Op Fl K Ar pdscript
  43 .Op Fl r Ar rscript
  44 .Op Fl s Ar srcdir
  45 .Op Fl t Ar template
  46 .Op Fl X Ar excludefile
  47 .Op Fl D Ar displayfile
  48 .Op Fl m Ar mtreefile
  49 .Op Fl o Ar originpath
  50 .Fl c Ar comment
  51 .Fl d Ar description
  52 .Fl f Ar packlist
  53 .Ar pkg-filename
  54 .Nm
  55 .Op Fl YNhvy
  56 .Fl b Ar pkg-name
  57 .Op Ar pkg-filename
  58 .Sh DESCRIPTION
  59 The
  60 .Nm
  61 command is used to create packages that will subsequently be fed to
  62 one of the package extraction/info utilities.  The input description
  63 and command line arguments for the creation of a package are not
  64 really meant to be human-generated, though it is easy enough to
  65 do so.  It is more expected that you will use a front-end tool for
  66 the job rather than muddling through it yourself.  Nonetheless, a short
  67 description of the input syntax is included in this document.
  68 .Sh OPTIONS
  69 The following command line options are supported:
  70 .Bl -tag -width indent
  71 .It Fl f Ar packinglist
  72 Fetch
  73 .Dq packing list
  74 for package from the file
  75 .Ar packinglist
  76 or
  77 .Cm stdin
  78 if
  79 .Ar packinglist
  80 is a
  81 .Cm -
  82 (dash).
  83 .It Fl c Xo
  84 .Oo Fl Oc Ns Ar desc
  85 .Xc
  86 Fetch package
  87 .Dq one line description
  88 from file
  89 .Ar desc
  90 or, if preceded by
  91 .Cm - ,
  92 the argument itself.  This string should also
  93 give some idea of which version of the product (if any) the package
  94 represents.
  95 .It Fl d Xo
  96 .Oo Fl Oc Ns Ar desc
  97 .Xc
  98 Fetch long description for package from file
  99 .Ar desc
 100 or, if preceded by
 101 .Cm - ,
 102 the argument itself.
 103 .It Fl Y
 104 Assume a default answer of `Yes' for any questions asked.
 105 .It Fl N
 106 Assume a default answer of `No' for any questions asked.
 107 .It Fl O
 108 Go into a `packing list Only' mode.  This is a custom hack for the
 109 .Fx
 110 .Em "Ports Collection"
 111 and is used to do `fake pkg_add' operations when a port is installed.
 112 In such cases, it is necessary to know what the final, adjusted packing
 113 list will look like.
 114 .It Fl v
 115 Turn on verbose output.
 116 .It Fl h
 117 Force tar to follow symbolic links, so that the files they point to
 118 are dumped, rather than the links themselves.
 119 .It Fl i Ar iscript
 120 Set
 121 .Ar iscript
 122 to be the pre-install procedure for the package.  This can be any executable
 123 program (or shell script).  It will be invoked automatically when the
 124 package is later installed.
 125 It will be passed the package's name as the
 126 first argument.
 127 .Pp
 128 .Sy Note :
 129 if the
 130 .Fl I
 131 option is not given, this script will serve as both the pre-install and the
 132 post-install script for the package, differentiating between the
 133 functionality by passing the keywords
 134 .Ar PRE-INSTALL
 135 and
 136 .Ar POST-INSTALL
 137 respectively, along with the package's name.
 138 .It Fl I Ar piscript
 139 Set
 140 .Ar piscript
 141 to be the post-install procedure for the package.  This can be any
 142 executable program (or shell script).  It will be invoked automatically
 143 when the package is later installed.
 144 It will be passed the package's name as
 145 the first argument.
 146 .It Fl P Ar pkgs
 147 Set the initial package dependency list to
 148 .Ar pkgs .
 149 This is assumed to be a whitespace separated list of package names
 150 and is meant as a convenient shorthand for specifying multiple
 151 .Cm @pkgdep
 152 directives in the packing list (see
 153 .Sx "PACKING LIST DETAILS"
 154 section below).
 155 Each argument from the
 156 .Ar pkgs
 157 list could be in the form
 158 .Ar pkgname Ns Op : Ns Ar pkgorigin ,
 159 where optional
 160 .Ar pkgorigin
 161 element denotes origin of each dependency from the list and it is
 162 recorded into the packing list along with the
 163 .Ar pkgname
 164 using
 165 .Cm @comment
 166 directive.
 167 .It Fl p Ar prefix
 168 Set
 169 .Ar prefix
 170 as the initial directory
 171 .Dq base
 172 to start from in selecting files for
 173 the package.
 174 .It Fl k Ar dscript
 175 Set
 176 .Ar dscript
 177 to be the de-install procedure for the package.  This can be any executable
 178 program (or shell script).  It will be invoked automatically when the
 179 package is later (if ever) de-installed.
 180 It will be passed the package's
 181 name as the first argument.
 182 .Pp
 183 .Sy Note :
 184 if the
 185 .Fl K
 186 option is not given, this script will serve as both the de-install and the
 187 post-deinstall script for the package, differentiating between the
 188 functionality by passing the keywords
 189 .Ar DEINSTALL
 190 and
 191 .Ar POST-DEINSTALL
 192 respectively, along with the package's name.
 193 .It Fl K Ar pdscript
 194 Set
 195 .Ar pdscript
 196 to be the post-deinstall procedure for the package.  This can be any
 197 executable program (or shell script).  It will be invoked automatically when
 198 the package is later de-installed.
 199 It will be passed the package's name as
 200 the first argument.
 201 .It Fl r Ar rscript
 202 Set
 203 .Ar rscript
 204 to be the
 205 .Dq requirements
 206 procedure for the package.  This can be any
 207 executable program (or shell script).  It will be invoked automatically
 208 at installation/deinstallation time to determine whether or not
 209 installation/deinstallation should proceed.
 210 To differentiate between installation and deinstallation, the keywords
 211 .Ar INSTALL
 212 and
 213 .Ar DEINSTALL
 214 are passed respectively, along with the package's name.
 215 .It Fl s Ar srcdir
 216 .Ar srcdir
 217 will override the value of
 218 .Cm @cwd
 219 during package creation.
 220 .It Fl t Ar template
 221 Use
 222 .Ar template
 223 as the input to
 224 .Xr mktemp 3 .
 225 By default, this is the string
 226 .Pa /tmp/instmp.XXXXXX ,
 227 but it may be necessary to override it in the situation where
 228 space in your
 229 .Pa /tmp
 230 directory is limited.  Be sure to leave some number of `X' characters
 231 for
 232 .Xr mktemp 3
 233 to fill in with a unique ID.
 234 .It Fl X Ar excludefile
 235 Pass
 236 .Ar excludefile
 237 as a
 238 .Fl exclude-from
 239 argument to
 240 .Cm tar
 241 when creating final package.  See
 242 .Cm tar
 243 man page (or run
 244 .Cm tar
 245 with
 246 .Fl -help
 247 flag) for further information on using this flag.
 248 .It Fl D Ar displayfile
 249 Display the file (by concatenating it to stdout)
 250 after installing the package.  Useful for things like
 251 legal notices on almost-free software, etc.
 252 .It Fl m Ar mtreefile
 253 Run
 254 .Xr mtree 8
 255 with input from mtreefile before the package is installed.
 256 Mtree is invoked as
 257 .Cm mtree
 258 .Fl u
 259 .Fl f
 260 .Ar mtreefile
 261 .Fl d
 262 .Fl e
 263 .Fl p
 264 .Pa prefix ,
 265 where
 266 .Pa prefix
 267 is the name of the first directory named by a
 268 .Cm @cwd
 269 directive.
 270 .It Fl o Ar originpath
 271 Record an
 272 .Ar originpath ,
 273 as location of the port from which package has been created in the
 274 .Fx
 275 .Em "Ports Collection" .
 276 It should be in the form
 277 .Pa MASTERCATEGORY/PORTDIR .
 278 .It Fl j
 279 Use
 280 .Xr bzip2 1
 281 utility to compress package tarball instead of
 282 .Xr gzip 1 .
 283 Please note that this option is a NO-OP if the format of the resulting
 284 archive is explicitly specified by the recognizable suffix of
 285 .Ar pkg-filename .
 286 Currently
 287 .Nm
 288 recognizes the following suffixes:
 289 .Pa .tbz , .tgz
 290 and
 291 .Pa .tar .
 292 .It Fl y
 293 Compatibility synonym for
 294 .Fl j .
 295 .It Fl z
 296 Use
 297 .Xr gzip 1
 298 utility to compress package tarball.
 299 .It Fl b Ar pkg-name
 300 Create package file from a locally installed package named
 301 .Ar pkg-name .
 302 If the
 303 .Ar pkg-filename
 304 is not specified, then resulting archive will be created in the
 305 current directory and named
 306 .Ar pkg-name
 307 with an appropriate extraction suffix applied.
 308 .El
 309 .Sh PACKING LIST DETAILS
 310 The
 311 .Dq packing list
 312 format (see
 313 .Fl f )
 314 is fairly simple, being
 315 nothing more than a single column of filenames to include in the
 316 package.  However, since absolute pathnames are generally a bad idea
 317 for a package that could be installed potentially anywhere, there is
 318 another method of specifying where things are supposed to go
 319 and, optionally, what ownership and mode information they should be
 320 installed with.  This is done by embedding specialized command sequences
 321 in the packing list.  Briefly described, these sequences are:
 322 .Bl -tag -width indent -compact
 323 .It Cm @cwd Ar directory
 324 Set the internal directory pointer to point to
 325 .Ar directory .
 326 All subsequent filenames will be assumed relative to this directory.
 327 Note:
 328 .Cm @cd
 329 is also an alias for this command.
 330 .It Cm @srcdir Ar directory
 331 Set the internal directory pointer for _creation only_ to
 332 .Ar directory .
 333 That is to say that it overrides
 334 .Cm @cwd
 335 for package creation but not extraction.
 336 .It Cm @exec Ar command
 337 Execute
 338 .Ar command
 339 as part of the unpacking process.  If
 340 .Ar command
 341 contains any of the following sequences somewhere in it, they will
 342 be expanded inline.  For the following examples, assume that
 343 .Cm @cwd
 344 is set to
 345 .Pa /usr/local
 346 and the last extracted file was
 347 .Pa bin/emacs .
 348 .Bl -tag -width indent -compact
 349 .It Cm "%F"
 350 Expands to the last filename extracted (as specified), in the example case
 351 .Pa bin/emacs
 352 .It Cm "\&%D"
 353 Expand to the current directory prefix, as set with
 354 .Cm @cwd ,
 355 in the example case
 356 .Pa /usr/local .
 357 .It Cm "\&%B"
 358 Expand to the
 359 .Dq basename
 360 of the fully qualified filename, that
 361 is the current directory prefix, plus the last filespec, minus
 362 the trailing filename.  In the example case, that would be
 363 .Pa /usr/local/bin .
 364 .It Cm "%f"
 365 Expand to the
 366 filename
 367 part of the fully qualified name, or
 368 the converse of
 369 .Cm \&%B ,
 370 being in the example case,
 371 .Pa emacs .
 372 .El
 373 .It Cm @unexec Ar command
 374 Execute
 375 .Ar command
 376 as part of the deinstallation process.  Expansion of special
 377 .Cm %
 378 sequences is the same as for
 379 .Cm @exec .
 380 This command is not executed during the package add, as
 381 .Cm @exec
 382 is, but rather when the package is deleted.  This is useful
 383 for deleting links and other ancillary files that were created
 384 as a result of adding the package, but not directly known to
 385 the package's table of contents (and hence not automatically
 386 removable).  The advantage of using
 387 .Cm @unexec
 388 over a deinstallation script is that you can use the
 389 .Dq special sequence expansion
 390 to get at files regardless of where they've
 391 been potentially redirected (see
 392 .Fl p ) .
 393 .It Cm @mode Ar mode
 394 Set default permission for all subsequently extracted files to
 395 .Ar mode .
 396 Format is the same as that used by the
 397 .Cm chmod
 398 command (well, considering that it's later handed off to it, that's
 399 no surprise).  Use without an arg to set back to default (extraction)
 400 permissions.
 401 .It Cm @option Ar option
 402 Set internal package options, the only two currently supported ones
 403 being
 404 .Ar extract-in-place ,
 405 which tells the pkg_add command not to extract the package's tarball
 406 into a staging area but rather directly into the target
 407 hierarchy (this is typically meant to be used only by distributions
 408 or other special package types), and
 409 .Ar preserve ,
 410 which tells pkg_add to move any existing files out of the way,
 411 preserving the previous contents (which are also resurrected on
 412 pkg_delete, so caveat emptor).
 413 .It Cm @owner Ar user
 414 Set default ownership for all subsequently extracted files to
 415 .Ar user .
 416 Use without an arg to set back to default (extraction)
 417 ownership.
 418 .It Cm @group Ar group
 419 Set default group ownership for all subsequently extracted files to
 420 .Ar group .
 421 Use without an arg to set back to default (extraction)
 422 group ownership.
 423 .It Cm @comment Ar string
 424 Imbed a comment in the packing list.  Useful in
 425 trying to document some particularly hairy sequence that
 426 may trip someone up later.
 427 .It Cm @ignore
 428 Used internally to tell extraction to ignore the next file (don't
 429 copy it anywhere), as it's used for some special purpose.
 430 .It Cm @ignore_inst
 431 Similar to
 432 .Cm @ignore ,
 433 but the ignoring of the next file is delayed one evaluation cycle.  This
 434 makes it possible to use this directive in the
 435 .Ar packinglist
 436 file, so you can pack a
 437 specialized datafile in with a distribution for your install script (or
 438 something) yet have the installer ignore it.
 439 .It Cm @name Ar name
 440 Set the name of the package.  This is mandatory and is usually
 441 put at the top.  This name is potentially different from the name of
 442 the file it came in, and is used when keeping track of the package
 443 for later deinstallation.  Note that
 444 .Nm
 445 will derive this field from the package name and add it automatically
 446 if none is given.
 447 .It Cm @dirrm Ar name
 448 Declare directory
 449 .Pa name
 450 to be deleted at deinstall time.  By default, directories created by a
 451 package installation are not deleted when the package is deinstalled;
 452 this provides an explicit directory cleanup method.  This directive
 453 should appear at the end of the package list.  If more than one
 454 .Cm @dirrm
 455 directives are used, the directories are removed in the order specified.
 456 The
 457 .Pa name
 458 directory will not be removed unless it is empty.
 459 .It Cm @mtree Ar name
 460 Declare
 461 .Pa name
 462 as an
 463 .Xr mtree 8
 464 input file to be used at install time (see
 465 .Fl m
 466 above).  Only the first
 467 .Cm @mtree
 468 directive is honored.
 469 .It Cm @display Ar name
 470 Declare
 471 .Pa name
 472 as the file to be displayed at install time (see
 473 .Fl D
 474 above).
 475 .It Cm @pkgdep Ar pkgname
 476 Declare a dependency on the
 477 .Ar pkgname
 478 package.  The
 479 .Ar pkgname
 480 package must be installed before this package may be
 481 installed, and this package must be deinstalled before the
 482 .Ar pkgname
 483 package is deinstalled.  Multiple
 484 .Cm @pkgdep
 485 directives may be used if the package depends on multiple other packages.
 486 .El
 487 .Sh ENVIRONMENT
 488 The environment variable
 489 .Ev PKG_TMPDIR
 490 names the directory where
 491 .Nm
 492 will attempt to create its temporary files.
 493 If
 494 .Ev PKG_TMPDIR
 495 is not set,
 496 the directory named by the contents of
 497 .Ev TMPDIR
 498 will be used.
 499 If neither of
 500 .Ev PKG_TMPDIR
 501 and
 502 .Ev TMPDIR
 503 are set, the builtin defaults are used.
 504 .Sh FILES
 505 .Bl -tag -width /usr/tmp -compact
 506 .It Pa /var/tmp
 507 Temporary directory if environmental variables
 508 .Ev PKG_TMPDIR
 509 and
 510 .Ev TMPDIR
 511 are not set.
 512 .It Pa /tmp
 513 The next choice if
 514 .Pa /var/tmp
 515 does not exist.
 516 .It Pa /usr/tmp
 517 The last choice if
 518 .Pa /tmp
 519 is unsuitable.
 520 .El
 521 .Sh SEE ALSO
 522 .Xr pkg_add 1 ,
 523 .Xr pkg_delete 1 ,
 524 .Xr pkg_info 1 ,
 525 .Xr pkg_update 1 ,
 526 .Xr pkg_version 1 ,
 527 .Xr sysconf 3
 528 .Sh HISTORY
 529 The
 530 .Nm
 531 command first appeared in
 532 .Fx .
 533 .Sh AUTHORS
 534 .An Jordan Hubbard
 535 .Sh CONTRIBUTORS
 536 .An John Kohl Aq jtk@rational.com
 537 .Sh BUGS
 538 Hard links between files in a distribution must be bracketed by
 539 .Cm @cwd
 540 directives in order to be preserved as hard links when the package is
 541 extracted.  They additionally must not end up being split between
 542 .Cm tar
 543 invocations due to exec argument-space limitations (this depends on the
 544 value returned by
 545 .Fn sysconf _SC_ARG_MAX ) .
 546 .Pp
 547 Sure to be others.