home | help 
PKG_CREATE(1)		     General Commands Manual		   PKG_CREATE(1)

NAME
     pkg_create -- a utility for creating software package distributions

SYNOPSIS
     pkg_create [-YNOhvy] [-P pkgs] [-p prefix] [-f contents] [-i iscript]
		[-I piscript] [-k dscript] [-K pdscript] [-r rscript]
		[-s srcdir] [-t template] [-X excludefile] [-D displayfile]
		[-m mtreefile] [-o originpath] -c comment -d description -f
		packlist pkg-filename
     pkg_create [-YNhvy] -b pkg-name [pkg-filename]

DESCRIPTION
     The pkg_create command is used to create packages that will subsequently be
     fed to one of the package extraction/info utilities.  The input description
     and  command  line  arguments  for the creation of a package are not really
     meant to be human-generated, though it is easy enough to do so.  It is more
     expected that you will use a front-end tool for the job  rather  than  mud-
     dling  through  it yourself.  Nonetheless, a short description of the input
     syntax is included in this document.

OPTIONS
     The following command line options are supported:

     -f packinglist
	     Fetch "packing list" for package from the file packinglist or stdin
	     if packinglist is a - (dash).

     -c [-]desc
	     Fetch package "one line description" from file desc or, if preceded
	     by -, the argument itself.  This string should also give some  idea
	     of which version of the product (if any) the package represents.

     -d [-]desc
	     Fetch  long  description for package from file desc or, if preceded
	     by -, the argument itself.

     -Y      Assume a default answer of `Yes' for any questions asked.

     -N      Assume a default answer of `No' for any questions asked.

     -O      Go into a `packing list Only' mode.  This is a custom hack for  the
	     FreeBSD  Ports  Collection  and is used to do `fake pkg_add' opera-
	     tions when a port is installed.  In such cases, it is necessary  to
	     know what the final, adjusted packing list will look like.

     -v      Turn on verbose output.

     -h      Force tar to follow symbolic links, so that the files they point to
	     are dumped, rather than the links themselves.

     -i iscript
	     Set  iscript to be the pre-install procedure for the package.  This
	     can be any executable program (or shell script).  It  will  be  in-
	     voked  automatically  when the package is later installed.  It will
	     be passed the package's name as the first argument.

	     Note: if the -I option is not given, this script will serve as both
	     the pre-install and the post-install script for the  package,  dif-
	     ferentiating  between  the  functionality	by  passing the keywords
	     PRE-INSTALL and POST-INSTALL respectively, along with the package's
	     name.

     -I piscript
	     Set piscript to be the  post-install  procedure  for  the	package.
	     This  can	be any executable program (or shell script).  It will be
	     invoked automatically when the package is later installed.  It will
	     be passed the package's name as the first argument.

     -P pkgs
	     Set the initial package dependency list to pkgs.  This  is  assumed
	     to  be a whitespace separated list of package names and is meant as
	     a convenient shorthand for specifying multiple  @pkgdep  directives
	     in the packing list (see PACKING LIST DETAILS section below).

     -p prefix
	     Set prefix as the initial directory "base" to start from in select-
	     ing files for the package.

     -k dscript
	     Set  dscript  to be the de-install procedure for the package.  This
	     can be any executable program (or shell script).  It  will  be  in-
	     voked  automatically  when  the  package  is later (if ever) de-in-
	     stalled.  It will be passed the package's name as the  first  argu-
	     ment.

	     Note: if the -K option is not given, this script will serve as both
	     the  de-install and the post-deinstall script for the package, dif-
	     ferentiating between the  functionality  by  passing  the	keywords
	     DEINSTALL and POST-DEINSTALL respectively, along with the package's
	     name.

     -K pdscript
	     Set  pdscript  to	be the post-deinstall procedure for the package.
	     This can be any executable program (or shell script).  It	will  be
	     invoked  automatically  when the package is later de-installed.  It
	     will be passed the package's name as the first argument.

     -r rscript
	     Set rscript to be the "requirements"  procedure  for  the	package.
	     This  can	be any executable program (or shell script).  It will be
	     invoked automatically at installation/deinstallation time to deter-
	     mine whether or not installation/deinstallation should proceed.  To
	     differentiate between installation and deinstallation, the keywords
	     INSTALL and DEINSTALL are passed respectively, along with the pack-
	     age's name.

     -s srcdir
	     srcdir will override the value of @cwd during package creation.

     -t template
	     Use template as the input to mktemp(3).  By default,  this  is  the
	     string  /tmp/instmp.XXXXXX,  but it may be necessary to override it
	     in the situation where space in your /tmp directory is limited.  Be
	     sure to leave some number of `X' characters for mktemp(3)	to  fill
	     in with a unique ID.

     -X excludefile
	     Pass  excludefile	as a -exclude-from argument to tar when creating
	     final package.  See tar man page (or run tar with --help flag)  for
	     further information on using this flag.

     -D displayfile
	     Display  the  file (by concatenating it to stdout) after installing
	     the package.  Useful for things like legal notices  on  almost-free
	     software, etc.

     -m mtreefile
	     Run  mtree(8)  with  input from mtreefile before the package is in-
	     stalled.  Mtree is invoked as  mtree  -u  -f  mtreefile  -d  -e  -p
	     prefix,  where prefix is the name of the first directory named by a
	     @cwd directive.

     -o originpath
	     Record an originpath, as location of the port  from  which  package
	     has  been created in the FreeBSD Ports Collection.  It should be in
	     the form MASTERCATEGORY/PORTDIR.

     -y      Use  bzip2(1)  utility  to  compress  package  tarball  instead  of
	     gzip(1).	Please	note  that this option is no-op if format of the
	     resulting archive is explicitly specified by the recognizeable suf-
	     fix of pkg-filename.  Currently pkg_create recognizes the following
	     suffixes: .tgz, .tar and .tbz2.

     -b pkg-name
	     Create  package  file  from  a  locally  installed  package   named
	     pkg-name.	 If  the  pkg-filename	is not specified, then resulting
	     archive will be created in the current directory and named pkg-name
	     with an appropriate extraction suffix applied.

PACKING LIST DETAILS
     The "packing list" format (see -f) is fairly  simple,  being  nothing  more
     than  a  single  column  of  filenames to include in the package.	However,
     since absolute pathnames are generally a bad idea for a package that  could
     be  installed  potentially  anywhere, there is another method of specifying
     where things are supposed to go and, optionally, what  ownership  and  mode
     information  they	should be installed with.  This is done by imbeding spe-
     cialized command sequences in the packing list.  Briefly  described,  these
     sequences are:
     @cwd directory
	     Set the internal directory pointer to point to directory.	All sub-
	     sequent  filenames  will  be  assumed  relative  to this directory.
	     Note: @cd is also an alias for this command.
     @srcdir directory
	     Set  the  internal  directory  pointer  for  _creation   only_   to
	     directory.   That is to say that it overrides @cwd for package cre-
	     ation but not extraction.
     @exec command
	     Execute command as part of the unpacking process.	If command  con-
	     tains  any of the following sequences somewhere in it, they will be
	     expanded inline.  For the following examples, assume that	@cwd  is
	     set to /usr/local and the last extracted file was bin/emacs.
	     %F      Expands  to  the last filename extracted (as specified), in
		     the example case bin/emacs
	     %D      Expand to the current directory prefix, as set  with  @cwd,
		     in the example case /usr/local.
	     %B      Expand  to  the "basename" of the fully qualified filename,
		     that is the current directory prefix, plus the  last  file-
		     spec,  minus  the	trailing filename.  In the example case,
		     that would be /usr/local/bin.
	     %f      Expand to the filename part of the fully qualified name, or
		     the converse of %B, being in the example case, emacs.
     @unexec command
	     Execute command as part of the deinstallation  process.   Expansion
	     of  special  % sequences is the same as for @exec.  This command is
	     not executed during the package add, as @exec is, but  rather  when
	     the  package  is  deleted.   This	is useful for deleting links and
	     other ancillary files that were created as a result of  adding  the
	     package,  but not directly known to the package's table of contents
	     (and hence not automatically removable).  The  advantage  of  using
	     @unexec  over  a  deinstallation  script  is  that  you can use the
	     "special sequence expansion" to get at files  regardless  of  where
	     they've been potentially redirected (see -p).
     @mode mode
	     Set  default  permission  for  all  subsequently extracted files to
	     mode.  Format is the same as that used by the chmod command  (well,
	     considering  that it's later handed off to it, that's no surprise).
	     Use without an arg to set back to default (extraction) permissions.
     @option option
	     Set internal package options, the only two currently supported ones
	     being extract-in-place, which tells the pkg_add command not to  ex-
	     tract the package's tarball into a staging area but rather directly
	     into  the target hierarchy (this is typically meant to be used only
	     by distributions or other special	package  types),  and  preserve,
	     which tells pkg_add to move any existing files out of the way, pre-
	     serving  the  previous  contents  (which  are  also  resurrected on
	     pkg_delete, so caveat emptor).
     @owner user
	     Set default ownership for all subsequently extracted files to user.
	     Use without an arg to set back to default (extraction) ownership.
     @group group
	     Set default group ownership for all subsequently extracted files to
	     group.  Use without an arg to  set  back  to  default  (extraction)
	     group ownership.
     @comment string
	     Imbed  a comment in the packing list.  Useful in trying to document
	     some particularly hairy sequence that may trip someone up later.
     @ignore
	     Used internally to tell extraction to ignore the next  file  (don't
	     copy it anywhere), as it's used for some special purpose.
     @ignore_inst
	     Similar  to  @ignore,  but the ignoring of the next file is delayed
	     one evaluation cycle.  This makes it possible to use this directive
	     in the packinglist file, so you can pack a specialized datafile  in
	     with a distribution for your install script (or something) yet have
	     the installer ignore it.
     @name name
	     Set  the name of the package.  This is mandatory and is usually put
	     at the top.  This name is potentially different from  the	name  of
	     the  file it came in, and is used when keeping track of the package
	     for later deinstallation.	Note that pkg_create  will  derive  this
	     field  from  the  package	name and add it automatically if none is
	     given.
     @dirrm name
	     Declare directory name to be deleted at  deinstall  time.	 By  de-
	     fault,  directories  created  by  a  package  installation  are not
	     deleted when the package is deinstalled; this provides an	explicit
	     directory	cleanup method.  This directive should appear at the end
	     of the package list.  If more than one @dirrm directives are  used,
	     the  directories  are removed in the order specified.  The name di-
	     rectory will not be removed unless it is empty.
     @mtree name
	     Declare name as an mtree(8) input file to be used at  install  time
	     (see -m above).  Only the first @mtree directive is honored.
     @display name
	     Declare  name  as	the file to be displayed at install time (see -D
	     above).
     @pkgdep pkgname
	     Declare a dependency on the pkgname package.  The	pkgname  package
	     must  be  installed  before this package may be installed, and this
	     package must be deinstalled before the  pkgname  package  is  dein-
	     stalled.	Multiple  @pkgdep  directives may be used if the package
	     depends on multiple other packages.

ENVIRONMENT
     The environment variable PKG_TMPDIR names the  directory  where  pkg_create
     will  attempt to create its temporary files.  If PKG_TMPDIR is not set, the
     directory named by the contents of TMPDIR will  be  used.	 If  neither  of
     PKG_TMPDIR and TMPDIR are set, the builtin defaults are used.

FILES
     /var/tmp  Temporary  directory  if  environmental	variables PKG_TMPDIR and
	       TMPDIR are not set.
     /tmp      The next choice if /var/tmp does not exist.
     /usr/tmp  The last choice if /tmp is unsuitable.

SEE ALSO
     pkg_add(1),  pkg_delete(1),  pkg_info(1),	pkg_update(1),	 pkg_version(1),
     sysconf(3)

HISTORY
     The pkg_create command first appeared in FreeBSD.

AUTHORS
     Jordan Hubbard

CONTRIBUTORS
     John Kohl <jtk@rational.com>

BUGS
     Hard links between files in a distribution must be bracketed by @cwd direc-
     tives in order to be preserved as hard links when the package is extracted.
     They  additionally  must not end up being split between tar invocations due
     to exec argument-space limitations (this depends on the value  returned  by
     sysconf(_SC_ARG_MAX)).

     Sure to be others.

FreeBSD 4.5			 April 21, 1995 		   PKG_CREATE(1)
home | help