PKG_CREATE(1)              OpenBSD Reference Manual              PKG_CREATE(1)

NAME
     pkg_create - create binary software package for distribution

SYNOPSIS
     pkg_create [-nQqvx] [-A arches] [-B pkg-destdir] [-D name[=value]]
                [-L localbase] [-M displayfile] [-P pkg-dependency]
                [-s signature-parameter] [-U undisplayfile] [-W wantedlib]
                -d desc -D COMMENT=value -f packinglist -p prefix pkg-name
     pkg_create [-s signature-parameter] -f packinglist

DESCRIPTION
     The pkg_create command creates a binary package named pkg-name, for sub-
     sequent use with pkg_add(1), pkg_delete(1) and pkg_info(1).  pkg-name
     will traditionally have a ``.tgz'' extension, to denote the underlying
     binary format.  pkg-name must follow packages-specs(7).

     Use of the ports(7) infrastructure instead of manual pkg_create invoca-
     tion is strongly recommended.

     During package creation, pkg_create replaces too long file names with
     smaller equivalents (see package(5)), records extra information in the
     packing-list, such as the existence of symlinks and hard links, computes
     and stores file checksums, and verifies that all special objects are
     properly annotated in the packing-list.

     The options are as follows:

     -A arches
             Register a list of architectures for which this package should
             install.  arches is a comma-separated list of architectures.  Use
             `*' to mean any architecture (e.g., arch-independent packages).

     -B pkg-destdir
             Set pkg-destdir as the prefix to prepend to any file to select
             for the package.

     -D name[=value]
             Define name to value (or just define it) for substitution and
             fragment inclusion purposes.  Some specific names have extra
             meaning, see bsd.port.mk(5) for details:

             CDROM        Set to the port's Makefile PERMIT_PACKAGE_CDROM.
             COMMENT      Set package ``one line description'' (mandatory).
             FTP          Set to the port's Makefile PERMIT_PACKAGE_FTP.
             FULLPKGPATH  Strongly recommended, otherwise updates won't work.
             HOMEPAGE     If defined, appended to the description.
             MAINTAINER   If defined, appended to the description.

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

     -f packinglist
             Fetch ``packing list'' for package from the file packinglist.
             Several packing-lists can be mentioned, in which case they will
             be concatenated together.

     -L localbase
             Record localbase as the localbase used in the package.  By de-
             fault, /usr/local.  Packages built with another localbase can on-
             ly be installed by using the same localbase in pkg_add(1), to
             prevent errors.

     -M displayfile
             Display the file (using more(1)) after installing the package.
             Useful for things like legal notices on almost-free software,
             etc.

     -n      Don't actually create a package.

     -P pkg-dependency
             Specify a @depend dependency on the command line.

     -p prefix
             Set prefix as the initial directory ``base'' to start from in se-
             lecting files for the package, and to record as the base for in-
             stalling the package.

     -Q      Print out the files in the actual packing-list of the package be-
             ing generated, with explicit typing (e.g. @file, @lib, ...).

     -q      Print out the actual packing-list of the package being generated
             (query mode).  Most often used in combination with -n.

     -s x509 -s cert -s privkey
             Specify signature parameters for signed packages.  For now, the
             only supported use involves three -s options: x509 to indicate
             x509-style signatures, cert the path to the signer's certificate
             and privkey the path to the signer's private key.  The signer's
             certificate and the signer's private key should be generated us-
             ing standard openssl x509 commands.  This assumes the existence
             of a certificate authority (or several), whose public information
             is recorded as a /etc/ssl/pkgca.pem file.

     -U undisplayfile
             Display the file (using more(1)) when deinstalling the package.
             Useful for reminders about stuff to clean up.

     -v      Turn on verbose output.

     -W wantedlib
             Specify a @wantlib requirement on the command line.

     -x      Disable progress meter.

     pkg_create can also be invoked with only the packing-list from an in-
     stalled package.  It will recreate the corresponding binary package in
     the current directory from the installation, or error out if any problem
     is found.  For example, the following will recreate a kdelibs-3.4.3.tgz
     package:

           pkg_create -f /var/db/pkg/kdelibs-3.4.3/+CONTENTS

PACKING LIST DETAILS
     The ``packing list'' format (see -f) is fairly simple, being basically a
     list of filenames and directory names to include in the package.

     Substitution of variables and inclusion of fragments is documented in the
     next section.

     Directory names are denoted by a trailing slash.

     There are a few annotations that can be inserted for better control.  All
     these commands start with an `@'.  Here is a list:

     @arch arches
             List of architectures for which this package is intended.

     @bin filename
             Describe the file as an OpenBSD binary executable (not a script).

     @comment string
             Imbed a comment in the packing list.  Useful in trying to docu-
             ment some particularly hairy sequence that may trip someone up
             later.  Can also be used to comment out elements that update-
             plist (see bsd.port.mk(5)) will insist in inserting in a packing-
             list.

             The special comment @comment no checksum can be used to tag the
             next file as special: even though its characteristics will be
             recorded in the package, it can be altered after installation,
             and pkg_delete(1) will still delete it.

     @conflict pkgspec
             Declare a conflict with packages matching pkgspec (see
             packages-specs(7)).  The pkgname package can not be installed if
             a package matching pkgspec has been installed because they in-
             stall the same files and thus conflict.

     @cwd pathname
             Set the package current directory.  All subsequent filenames will
             be assumed relative to pathname.

     @depend pkgpath:pkgspec:default
             Declare a dependency on a package matching pkgspec (see
             packages-specs(7)).  An appropriate package must be installed be-
             fore this package may be installed, and that package must be de-
             installed before this package is deinstalled.  The dependency al-
             so contains a pkgpath (see FULLPKGPATH in bsd.port.mk(5)) and a
             default package name, in case there is no listing of available
             packages.

     @dir directoryname
             Create directory directoryname at pkg_add(1) time, taking @mode,
             @group, and @owner into account, and remove it during
             pkg_delete(1).  Directories to remove can be shared between pack-
             ages.  If name does not begin with an @, same as
                   name/

     @display name
             Declare name as the file to be displayed at install time (see -M
             above).

     @endfake
             Mark end of packing-list for pkg_add(1) -Q option.

     @exec command
             Execute command during pkg_add(1).  Note that @exec commands are
             executed relative to their location in the packing-list, so they
             can rely on any data that have already been extracted, but not on
             anything that is listed after them.  Some special elements, such
             as new users and new groups, are always created first, so that
             @exec can rely on them.  If command contains 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.

             %B      Expands to the ``basename'' of the fully qualified file-
                     name, that is the current directory prefix, plus the last
                     filespec, minus the trailing filename.  In the example
                     case, that would be /usr/local/bin.

             %D      Expands to the current directory prefix, as set with
                     @cwd; in the example case /usr/local.

             %F      Expands to the last filename extracted (as specified); in
                     the example case, bin/emacs.

             %f      Expands to the ``filename'' part of the fully qualified
                     name, or the converse of %B; in the example case, emacs.

     @exec-always command
             Synonym of @exec.

     @exec-add command
             Similar to @exec, except it only gets executed during new instal-
             lations, and not during updates.

     @exec-update command
             Similar to @exec, except it only gets executed during updates,
             and not during new installations.

     @extra filename
             Declare extra file filename to be deleted at deinstall time, if
             user sets the -c option.  Those files are extra configuration
             files that are normally not deleted.  filename can be an absolute
             path.  If filename ends with a slash, it is a directory.

     @extraunexec command
             Extra command to execute when removing extra files.

     @file filename
             Default annotation, to use if filename begins with @.  filename
             is always a relative path, relative to the current @cwd.

     @fontdir directoryname
             Specialized version of @dir, to handle font directories: create
             font.alias from font.alias-* fragments, execute mkfontdir(1),
             mkfontscale(1) and fc-cache(1) when needed.  Delete extra files
             at pkg_delete(1) time.

     @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.

     @ignore
             Was used internally to tell extraction to ignore the next file.
             No longer needed.

     @info filename
             Specialized version of @file, to handle GNU info files.  Automat-
             ically grab filename-* chapter files, run install-info(1) as
             needed.

     @lib filename
             Specialized version of @file, to handle shared libraries.  Satis-
             fy LIB_DEPENDS, run ldconfig(8) as needed.

     @link name
             Added after a file entry by pkg_create to record that the entry
             is actually a hard link.

     @localbase base
             Used internally to record the settings of -L option.

     @man filename
             Specialized version of @file, to handle manual pages.

     @mandir directoryname
             Specialized version of @dir, to handle manual directories: in-
             struct user to add/remove the directory to man.conf(5), remove
             apropos(1) database when needed.

     @md5    Added after a file entry by pkg_create to record the files's
             cryptographic checksum.  Replaced by @sha since OpenBSD 4.5.

     @mode mode
             Set default permission for all subsequently extracted files to
             mode.  Format is the same as that used by the chmod(1) command.
             Use without an arg to set back to default (extraction) permis-
             sions.

     @name pkgname
             Set the name of the package.  This name is potentially different
             than 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.

     @newgroup name:gid
             During pkg_add(1), create a new group, using groupadd(8).  Hap-
             pens before file and user creations.  gid can be prefixed with a
             `!' to ensure group has the correct GID.  During pkg_delete(1),
             groups will be deleted if extra clean-up has been requested, and
             if other installed packages don't list the same group.

     @newuser name:uid:group:loginclass:comment:home:shell
             During pkg_add(1), create a new user.  Happens before any file
             creation.  All fields correspond to useradd(8) parameters.  Some
             fields are optional and can be left empty.  If the user already
             exists, no action is taken.  Individual fields can be prefixed by
             a `!' to make sure an existing user matches.  For instance, the
             directive @newuser foo:!42 will make sure user foo has UID 42.
             During pkg_delete(1), users will be deleted if extra clean-up has
             been requested, and if other installed packages don't list the
             same user.

     @option name
             Effects vary depending on name.  Some options are not documented
             yet.

             always-update
                     By default, pkg_add(1) uses some simplified information
                     to decide whether an installed package needs updating.
                     With this option, the package is updated whenever any-
                     thing changes.  To be used sparingly, as this is more ex-
                     pensive.

             explicit-update
                     packages tagged with this option, either in the installed
                     version or in an update candidate, won't be considered
                     during a global update.  User has to explicitly ask to
                     update them.  Typical use is for firmware packages, whose
                     updates are usually tied to kernel changes.

             no-default-conflict
                     By default, a package conflicts with other versions of
                     the same package.  With this option, the older package
                     version will still be noticed, but the installation will
                     proceed anyway.

     @owner user
             Set default ownership for all subsequently extracted files to
             user.  Use without an arg to set back to default (extraction)
             ownership.

     @pkgcfl pkgcflname
             Declare a conflict to the pkgcflname package.  The pkgcflname
             package must not be installed if pkgname package gets installed
             because they install the same files and thus conflict.
             pkgcflname may use fnmatch(3) wildcards.  Deprecated, use
             @conflict instead.

     @pkgpath pkgpath
             Declare an extra pkgpath for the package.  This is used for up-
             dates: pkg_add -u normally checks that the pkgpath embedded in
             the package corresponds to the old package, to solve ambiguities
             when packages with similar names are involved.  When ports get
             renamed, or flavors change, extra @pkgpath annotations can help
             pkg_add get a sense of continuity.

     @sample filename
             Last preceding @file item is a sample configuration file, to be
             copied to filename at pkg_add(1) time and to be removed at
             pkg_delete(1) time.  During installation, existing configuration
             files are untouched.  During deinstallation, configuration files
             are only removed if unchanged.  filename can be an absolute path.
             If filename ends with a slash, it refers to a configuration di-
             rectory instead.

     @sha    Added after a file entry by pkg_create to record the files's
             cryptographic checksum, as a sha25 digest encoded in base64.

     @shell filename
             Specialized version of @file, to handle shells.  See shells(5).

     @size   Added after a file entry by pkg_create to record a file size.

     @symlink name
             Added after a file entry by pkg_create to record that the entry
             is actually a symbolic link.

     @sysctl var=val
     @sysctl var>=val
             During pkg_add(1), check that sysctl(8) variable var is set to
             exactly/at least a given value val.  Adjust it otherwise.

     @unexec command
             Execute command during pkg_delete(1).  Expansion of special % se-
             quences is the same as for @exec.  Note that @unexec commands are
             executed relative to their location in the packing-list, so they
             cannot rely on any data that has already been deleted, thus they
             should occur before the files they need to function.  Some spe-
             cial elements, such as new users and new groups, are always
             deleted last, so that @unexec can rely on them.

     @unexec-always command
             Synonym of @unexec.

     @unexec-delete command
             Similar to @unexec, except it only gets executed during true
             deletions and not while removing an old package during updates.

     @unexec-update command
             Similar to @unexec, except it only gets executed while removing
             an old package during updates, and not during true deletions.

     @url    Original location of the package, automatically recorded in in-
             stalled packages by pkg_add(1).
     @wantlib libspec
             Package needs a shared library to work.  libspec is
             `name.major.minor' or `path/name.major.minor'.  The package won't
             be installed unless a library with the same name, the exact same
             major number and at least the same minor number can be located.
             A library without path is searched through dependent packages un-
             der the same localbase, then in the system libraries under
             /usr/lib and /usr/X11R6/lib.  A library with a path is only
             searched through dependent packages, that path being relative to
             localbase.

VARIABLE SUBSTITUTION AND FRAGMENT INCLUSION
     In packing-lists, installation, deinstallation and requirement scripts,
     description and message files, constructs like ${VAR} will be replaced
     with the variable value, according to -D name=value options.

     Constructs like %%VAR%% and !%%VAR%% trigger fragment inclusion.  If such
     a line is encountered in a packing-list, the corresponding variable must
     be defined to 0 or 1.  If the variable's value is 1, %%VAR%% will be re-
     placed by the corresponding positive fragment, and !%%VAR%% will be ig-
     nored.  If the variable's value is 0, %%VAR%% will be ignored, and
     !%%VAR%% will be replaced by the corresponding positive fragment.

     A fragment is an auxiliary packing-list file, whose name is derived from
     the current packing-list, and the variable name VAR triggering the inclu-
     sion: pkg/PLIST yields a positive fragment pkg/PFRAG.VAR and a negative
     fragment pkg/PFRAG.no-VAR, pkg/PLIST-FOO yields a positive fragment
     pkg/PFRAG.VAR-foo and a negative fragment pkg/PFRAG.no-VAR-foo.

     Fragments can be included inside fragments, so that %%VAR2%% inside
     pkg/PFRAG.VAR triggers the inclusion of pkg/PFRAG.VAR2-VAR and !%%VAR2%%
     triggers the inclusion of pkg/PFRAG.no-VAR2-VAR.

     If a positive or a negative fragment file does not exist, the correspond-
     ing inclusion will be ignored.  However, if both the positive and nega-
     tive fragment files do not exist, pkg_create will error out, to make it
     easier to spot fragment names errors.

     As a special historical exception, the variable SHARED_LIBS controls the
     inclusion of fragments PFRAG.shared and PFRAG.no-shared through the lines
     %%SHARED%% and !%%SHARED%%.

ENVIRONMENT
     PKG_DESTDIR  Default value for pkg-destdir, if no -B option is specified.

SEE ALSO
     openssl(1), pkg_add(1), pkg_delete(1), pkg_info(1), tar(1),
     bsd.port.mk(5), package(5), packages-specs(7), ports(7)

HISTORY
     The pkg_create command first appeared in FreeBSD.

AUTHORS
     Jordan Hubbard
             initial design
     Marc Espie
             complete rewrite.

OpenBSD 4.7                    February 28, 2010                             7
