The pkg_create command is normally used to create a
binary package named pkg-name, for subsequent
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 invocation is
strongly recommended.

pkg_create can also be used to recreate a binary
package from an existing installation.

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.

It will also check all required shared libraries for reachability, by looking
into all installed dependencies. It may also ask the ports tree for extra
dependencies, provided some other dependency refers to the same
BASE_PKGPATH (see
bsd.port.mk(5)). The
rationale is that those libraries must already be present for the package to
build correctly, and thus be reachable through the subset of dependencies that
are not pure RUN_DEPENDS.

Record localbase as the
localbase used in the package (By default,
/usr/local). Packages built with another
localbase can only be installed by using the same localbase in
pkg_add(1), to prevent
errors.

Declare a dependency on a package matching
pkgspec (see
packages-specs(7)).
An appropriate package must be installed before this package may be
installed, and that package must be deinstalled before this package is
deinstalled. The dependency also contains a
pkgpath (see
pkgpath(7)) and a
default package name, in case there is no
listing of available packages.

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

pkg_create can also be invoked with only the
packing-list from an installed 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:

Mechanism to prevent unwanted updates. If the new package
is installed as part of an update matching
pkgspec, the
message will be displayed to the user. In
non-interactive mode, the update will abort. Otherwise, the user will have
a chance to proceed. Automated updates can be done by using
-Dupdate_stem, with
stem the stem of the
pkgspec. Classical use case for
postgresql:

@ask-update postgresql-server-<8 Make sure your existing database is backed up

Use very sparingly. Most cases that seem to require manual updates just
require a bit more thought.

Place a comment in the packing-list. Useful in trying to
document 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 @commentno 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.

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
install the same files and thus conflict.

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 packages. If
name does not begin with an @, same as

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.

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.

During
pkg_add(1), create a new
group, using groupadd(8).
Happens 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.

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.

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 anything
changes. To be used sparingly, as this is more expensive.

is-branch

Annotate the few rare ports where several branches are
present in the ports tree (such as autoconf), to help
pkg_info(1) produce
stem%branch
annotations when needed.

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.

Declare a secondary
pkgpath for the package. This is used for
updates: 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. Note that
these pkgpath can take extra optional
components, to allow the matching of several flavors at once, and are
order independent. For instance,

@pkgpath some/dir,f1,f2

and

@pkgpath some/dir,f2,f2,f1

are equivalent.

@pkgpath some/dir,f1[,f2,f3][,f4]

will match all pkgpaths to some/dir with flavor f1, and optionally f4, and
optionally both f2 and f3, e.g.,
some/dir,f1,f4,
some/dir,f1,f2,f3,
some/dir,f1,f2,f3,f4,
some/dir,f1 would match, but
some/dir,f1,f5,
some/dir,f2,f3,
some/dir,f1,f2,f4 would not.

Each binary package contains a set of pkgpaths: the primary pkgpath that was
used to build the package, recorded as
@commentpkgpath=some/path, and secondary pkgpaths
as recorded through @pkgpath.

In order for two packages to match, their primary pkgpaths must match, or a
secondary pkgpath must match the other package's primary pkgpath.

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 directory instead.

Execute command during
pkg_delete(1).
PATH and expansion of special
% sequences are 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 special elements, such as new users and new groups,
are always deleted last, so that @unexec can
rely on them.

In packing-lists, installation, deinstallation and requirement scripts,
description and message files, constructs like ${VAR}
will be replaced with the variable value, according to
-Dname=value
options.

In particular, shared library versions should never be mentioned explicitly in a
packing-list. Shared library ‘foo’ will take its version number
from LIBfoo_VERSION. The ports framework
normally takes care of all details, see
SHARED_LIBS in
bsd.port.mk(5).

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
replaced by the corresponding positive fragment, and
!%%VAR%% will be ignored. 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 inclusion:
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 corresponding
inclusion will be ignored. However, if both the positive and negative fragment
files do not exist, pkg_create will error out, to
make it easier to spot fragment names errors.