pkg_create(1)

NAME

pkg_create - a utility for creating software package distri

butions

SYNOPSIS

pkg_create  [-YNOhjvyz] [-C conflicts] [-P pkgs] [-p prefix]
[-i iscript]
           [-I piscript]  [-k  dscript]  [-K  pdscript]  [-r
rscript]
           [-s   srcdir]  [-S  basedir]  [-t  template]  [-X
excludefile]
           [-D displayfile] [-m mtreefile]  [-o  originpath]
-c comment -d
           description -f packlist pkg-filename
pkg_create [-EGYNRhvxy] -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 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 muddling through it yourself. Nonetheless, a short de

scription 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 cus

tom hack for

the FreeBSD Ports Collection and is used to do `fake

pkg_add'
operations 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
invoked automatically when the package is later in

stalled. It
will be passed the package's name as the first argu

ment.

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,
differentiating between the functionality by passing

the keywords
PRE-INSTALL and POST-INSTALL respectively, after 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 in

stalled. It
will be passed the package's name as the first argu

ment.

-C conflicts

Set the initial package conflict list to conflicts.

This is
assumed to be a whitespace separated list of package

names and is
meant as a convenient shorthand for specifying mul

tiple
@conflicts directives in the packing list (see PACK

ING LIST
DETAILS section below).

-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). Each argument from the pkgs list could be

in the form
pkgname[:pkgorigin], where optional pkgorigin ele

ment denotes
origin of each dependency from the list and it is

recorded into
the packing list along with the pkgname using

@comment directive.

-p prefix

Set prefix as the initial directory ``base'' to

start from in
selecting 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
invoked automatically when the package is later (if

ever) deinstalled. It will be passed the package's name as

the first
argument.

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, differentiating 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 argu

ment.

-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
determine whether or not installation/deinstallation

should proceed. To differentiate between installation and de

installation,
the keywords INSTALL and DEINSTALL are passed re

spectively, along
with the package's name.

-s srcdir

srcdir will override the value of @cwd during pack

age creation.

-S basedir

basedir will be prefixed to all @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) af

ter 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
installed. Mtree is invoked as mtree -u -f

mtreefile -d -e -p
prefix, where prefix is the name of the first direc

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

-j Use bzip2(1) utility to compress package tarball in

stead of

gzip(1). Please note that this option is a NO-OP if

the format
of the resulting archive is explicitly specified by

the recognizable suffix of pkg-filename. Currently pkg_create

recognizes the
following suffixes: .tbz, .tgz and .tar.

-y Compatibility synonym for -j.

-z Use gzip(1) utility to compress package tarball.

-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 ap

plied.

-R When creating package file from a locally installed

package also

create package files for all packages required by

pkg-name.
Resulting archive(s) will be created in the current

directory and
named using name of the respective package with ap

propriate
extraction suffix applied.

-x Use basic regular expressions for pkg-name.

-E Use extended (modern) regular expressions for

pkg-name.

-G Use exact matching for pkg-name.

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
embedding specialized command sequences in the packing list.

Briefly
described, these sequences are:
@cwd [directory]

Set the internal directory pointer to point to

directory. All
subsequent filenames will be assumed relative to

this directory.
If no directory argument is given, it will set the

internal
directory pointer to the first prefix value. Note:

@cd is also
an alias for this command.

@srcdir directory

Set the internal directory pointer for _creation on

ly_ to
directory. That is to say that it overrides @cwd

for package
creation but not extraction.

@exec command

Execute command as part of the unpacking process.

If command
contains any of the following sequences somewhere in

it, they
will be expanded inline. For the following exam

ples, 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 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.

%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 pro

cess. 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 have been potentially redirected (see

-p).

@mode mode

Set default permission for all subsequently extract

ed files to
mode. Format is the same as that used by the chmod

command
(well, considering that it is later handed off to

it, that is no
surprise). Use without an arg to set back to de

fault (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 extract the package's tarball into a staging area

but rather
directly into the target hierarchy (this is typical

ly 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, preserving 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 ex

tracted 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 try

ing to document some particularly hairy sequence that may trip

someone up
later.

@noinst option file

Specify that the package would have installed file

if option had
been specified at build time. The action of @noinst

is the same
that @comment (which is doing nothing, it is just

additional
information).

@ignore

Used internally to tell extraction to ignore the

next file (do
not copy it anywhere), as it is used for some spe

cial 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 spe

cialized
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
default, directories created by a package installa

tion are not
deleted when the package is deinstalled; this pro

vides 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 directory 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 in

stalled, and this
package must be deinstalled before the pkgname pack

age is deinstalled. Multiple @pkgdep directives may be used if

the package
depends on multiple other packages.

@conflicts pkgcflname

Declare a conflict with the pkgcflname package, as

the two packages contain references to the same files, and so

cannot co-exist
on the same system.

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_version(1),

sysconf(3)

HISTORY

The pkg_create command first appeared in FreeBSD.

AUTHORS

Jordan Hubbard

CONTRIBUTORS

John Kohl <jtk@rational.com>, Oliver Eikemeier <eik@FreeB

SD.org>

BUGS

Hard links between files in a distribution must be bracketed

by @cwd
directives 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 de

pends on the
value returned by sysconf(_SC_ARG_MAX)).

Sure to be others.

BSD November 8, 2005

BSD