496 lines
14 KiB
Groff
496 lines
14 KiB
Groff
.\"
|
|
.\" FreeBSD install - a package for the installation and maintainance
|
|
.\" of non-core utilities.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" Jordan K. Hubbard
|
|
.\"
|
|
.\"
|
|
.\" @(#)pkg_create.1
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.\" hacked up by John Kohl for NetBSD--fixed a few bugs, extended keywords,
|
|
.\" added dependency tracking, etc.
|
|
.\"
|
|
.\" [jkh] Took John's changes back and made some additional extensions for
|
|
.\" better integration with FreeBSD's new ports collection.
|
|
.\"
|
|
.Dd April 21, 1995
|
|
.Dt PKG_CREATE 1
|
|
.Os FreeBSD
|
|
.Sh NAME
|
|
.Nm pkg_create
|
|
.Nd a utility for creating software package distributions
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl YNOhv
|
|
.Op Fl P Ar pkgs
|
|
.Op Fl p Ar prefix
|
|
.Op Fl f Ar contents
|
|
.Op Fl i Ar iscript
|
|
.Op Fl I Ar piscript
|
|
.Op Fl k Ar dscript
|
|
.Op Fl K Ar pdscript
|
|
.Op Fl r Ar rscript
|
|
.Op Fl s Ar srcdir
|
|
.Op Fl t Ar template
|
|
.Op Fl X Ar excludefile
|
|
.Op Fl D Ar displayfile
|
|
.Op Fl m Ar mtreefile
|
|
.Op Fl o Ar originpath
|
|
.Fl c Ar comment
|
|
.Fl d Ar description
|
|
.Fl f Ar packlist
|
|
.Ar pkg-name
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
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 muddling through it yourself. Nonetheless, a short
|
|
description of the input syntax is included in this document.
|
|
.Sh OPTIONS
|
|
The following command line options are supported:
|
|
.Bl -tag -width indent
|
|
.It Fl f Ar packinglist
|
|
Fetch
|
|
.Dq packing list
|
|
for package from the file
|
|
.Ar packinglist
|
|
or
|
|
.Cm stdin
|
|
if
|
|
.Ar packinglist
|
|
is a
|
|
.Cm -
|
|
(dash).
|
|
.It Fl c Ar [-]desc
|
|
Fetch package
|
|
.Dq one line description
|
|
from file
|
|
.Ar desc
|
|
or, if preceded by
|
|
.Cm - ,
|
|
the argument itself. This string should also
|
|
give some idea of which version of the product (if any) the package
|
|
represents.
|
|
.It Fl d Ar [-]desc
|
|
Fetch long description for package from file
|
|
.Ar desc
|
|
or, if preceded by
|
|
.Cm - ,
|
|
the argument itself.
|
|
.It Fl Y
|
|
Assume a default answer of `Yes' for any questions asked.
|
|
.It Fl N
|
|
Assume a default answer of `No' for any questions asked.
|
|
.It Fl O
|
|
Go into a `packing list Only' mode. This is a custom hack for the
|
|
.Fx
|
|
.Em "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.
|
|
.It Fl v
|
|
Turn on verbose output.
|
|
.It Fl h
|
|
Force tar to follow symbolic links, so that the files they point to
|
|
are dumped, rather than the links themselves.
|
|
.It Fl i Ar iscript
|
|
Set
|
|
.Ar 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 installed.
|
|
It will be passed the package's name as the
|
|
first argument.
|
|
.Pp
|
|
.Cm Note:
|
|
if the
|
|
.Cm Fl 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
|
|
.Ar PRE-INSTALL
|
|
and
|
|
.Ar POST-INSTALL
|
|
respectively, along with the package's name.
|
|
.It Fl I Ar piscript
|
|
Set
|
|
.Ar 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.
|
|
.It Fl P Ar pkgs
|
|
Set the initial package dependency list to
|
|
.Ar pkgs .
|
|
This is assumed to be a whitespace separated list of package names
|
|
and is meant as a convenient shorthand for specifying multiple
|
|
.Cm @pkgdep
|
|
directives in the packing list (see PACKING LIST DETAILS section below).
|
|
.It Fl p Ar prefix
|
|
Set
|
|
.Ar prefix
|
|
as the initial directory
|
|
.Dq base
|
|
to start from in selecting files for
|
|
the package.
|
|
.It Fl k Ar dscript
|
|
Set
|
|
.Ar 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) de-installed.
|
|
It will be passed the package's
|
|
name as the first argument.
|
|
.Pp
|
|
.Cm Note:
|
|
if the
|
|
.Cm Fl 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
|
|
.Ar DEINSTALL
|
|
and
|
|
.Ar POST-DEINSTALL
|
|
respectively, along with the package's name.
|
|
.It Fl K Ar pdscript
|
|
Set
|
|
.Ar 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.
|
|
.It Fl r Ar rscript
|
|
Set
|
|
.Ar rscript
|
|
to be the
|
|
.Dq 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 deinstallation, the keywords
|
|
.Ar INSTALL
|
|
and
|
|
.Ar DEINSTALL
|
|
are passed respectively, along with the package's name.
|
|
.It Fl s Ar srcdir
|
|
.Ar srcdir
|
|
will override the value of
|
|
.Cm @cwd
|
|
during package creation.
|
|
.It Fl t Ar template
|
|
Use
|
|
.Ar template
|
|
as the input to
|
|
.Xr mktemp 3 .
|
|
By default, this is the string
|
|
.Pa /tmp/instmp.XXXXXX ,
|
|
but it may be necessary to override it in the situation where
|
|
space in your
|
|
.Pa /tmp
|
|
directory is limited. Be sure to leave some number of `X' characters
|
|
for
|
|
.Xr mktemp 3
|
|
to fill in with a unique ID.
|
|
.It Fl X Ar excludefile
|
|
Pass
|
|
.Ar excludefile
|
|
as a
|
|
.Fl exclude-from
|
|
argument to
|
|
.Cm tar
|
|
when creating final package. See
|
|
.Cm tar
|
|
man page (or run
|
|
.Cm tar
|
|
with
|
|
.Fl -help
|
|
flag) for further information on using this flag.
|
|
.It Fl D Ar displayfile
|
|
Display the file (by concatenating it to stdout)
|
|
after installing the package. Useful for things like
|
|
legal notices on almost-free software, etc.
|
|
.It Fl m Ar mtreefile
|
|
Run
|
|
.Xr mtree 8
|
|
with input from mtreefile before the package is installed.
|
|
Mtree is invoked as
|
|
.Cm mtree
|
|
.Fl u
|
|
.Fl f
|
|
.Ar mtreefile
|
|
.Fl d
|
|
.Fl e
|
|
.Fl p
|
|
.Pa prefix ,
|
|
where
|
|
.Pa prefix
|
|
is the name of the first directory named by a
|
|
.Cm @cwd
|
|
directive.
|
|
.It Fl o Ar originpath
|
|
Record an
|
|
.Ar originpath ,
|
|
as location of the port from which package has been created in the
|
|
.Fx
|
|
.Em "Ports Collection" .
|
|
It should be in the form
|
|
.Pa MASTERCATEGORY/PORTDIR .
|
|
.El
|
|
.Pp
|
|
.Sh PACKING LIST DETAILS
|
|
The
|
|
.Dq packing list
|
|
format (see
|
|
.Fl 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 specialized command sequences
|
|
in the packing list. Briefly described, these sequences are:
|
|
.Bl -tag -width indent -compact
|
|
.It Cm @cwd Ar directory
|
|
Set the internal directory pointer to point to
|
|
.Ar directory .
|
|
All subsequent filenames will be assumed relative to this directory.
|
|
Note:
|
|
.Cm @cd
|
|
is also an alias for this command.
|
|
.It Cm @srcdir Ar directory
|
|
Set the internal directory pointer for _creation only_ to
|
|
.Ar directory .
|
|
That is to say that it overrides
|
|
.Cm @cwd
|
|
for package creation but not extraction.
|
|
.It Cm @exec Ar command
|
|
Execute
|
|
.Ar command
|
|
as part of the unpacking process. If
|
|
.Ar command
|
|
contains any of the following sequences somewhere in it, they will
|
|
be expanded inline. For the following examples, assume that
|
|
.Cm @cwd
|
|
is set to
|
|
.Pa /usr/local
|
|
and the last extracted file was
|
|
.Pa bin/emacs .
|
|
.Bl -tag -width indent -compact
|
|
.It Cm "%F"
|
|
Expands to the last filename extracted (as specified), in the example case
|
|
.Pa bin/emacs
|
|
.It Cm "\&%D"
|
|
Expand to the current directory prefix, as set with
|
|
.Cm @cwd ,
|
|
in the example case
|
|
.Pa /usr/local .
|
|
.It Cm "\&%B"
|
|
Expand to the
|
|
.Dq basename
|
|
of the fully qualified filename, that
|
|
is the current directory prefix, plus the last filespec, minus
|
|
the trailing filename. In the example case, that would be
|
|
.Pa /usr/local/bin .
|
|
.It Cm "%f"
|
|
Expand to the
|
|
filename
|
|
part of the fully qualified name, or
|
|
the converse of
|
|
.Cm \&%B ,
|
|
being in the example case,
|
|
.Pa emacs .
|
|
.El
|
|
.It Cm @unexec Ar command
|
|
Execute
|
|
.Ar command
|
|
as part of the deinstallation process. Expansion of special
|
|
.Cm %
|
|
sequences is the same as for
|
|
.Cm @exec .
|
|
This command is not executed during the package add, as
|
|
.Cm @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
|
|
.Cm @unexec
|
|
over a deinstallation script is that you can use the
|
|
.Dq special sequence expansion
|
|
to get at files regardless of where they've
|
|
been potentially redirected (see
|
|
.Fl p ) .
|
|
.It Cm @mode Ar mode
|
|
Set default permission for all subsequently extracted files to
|
|
.Ar mode .
|
|
Format is the same as that used by the
|
|
.Cm 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.
|
|
.It Cm @option Ar option
|
|
Set internal package options, the only two currently supported ones
|
|
being
|
|
.Ar 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 typically meant to be used only by distributions
|
|
or other special package types), and
|
|
.Ar 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).
|
|
.It Cm @owner Ar user
|
|
Set default ownership for all subsequently extracted files to
|
|
.Ar user .
|
|
Use without an arg to set back to default (extraction)
|
|
ownership.
|
|
.It Cm @group Ar group
|
|
Set default group ownership for all subsequently extracted files to
|
|
.Ar group .
|
|
Use without an arg to set back to default (extraction)
|
|
group ownership.
|
|
.It Cm @comment Ar string
|
|
Imbed a comment in the packing list. Useful in
|
|
trying to document some particularly hairy sequence that
|
|
may trip someone up later.
|
|
.It Cm @ignore
|
|
Used internally to tell extraction to ignore the next file (don't
|
|
copy it anywhere), as it's used for some special purpose.
|
|
.It Cm @ignore_inst
|
|
Similar to
|
|
.Cm @ignore ,
|
|
but the ignoring of the next file is delayed one evaluation cycle. This
|
|
makes it possible to use this directive in the
|
|
.Ar 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.
|
|
.It Cm @name Ar 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
|
|
.Nm
|
|
will derive this field from the package name and add it automatically
|
|
if none is given.
|
|
.It Cm @dirrm Ar name
|
|
Declare directory
|
|
.Pa name
|
|
to be deleted at deinstall time. By default, 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
|
|
.Cm @dirrm
|
|
directives are used, the directories are removed in the order specified.
|
|
The
|
|
.Pa name
|
|
directory will not be removed unless it is empty.
|
|
.It Cm @mtree Ar name
|
|
Declare
|
|
.Pa name
|
|
as an
|
|
.Xr mtree 8
|
|
input file to be used at install time (see
|
|
.Fl m
|
|
above). Only the first
|
|
.Cm @mtree
|
|
directive is honored.
|
|
.It Cm @display Ar name
|
|
Declare
|
|
.Pa name
|
|
as the file to be displayed at install time (see
|
|
.Fl D
|
|
above).
|
|
.It Cm @pkgdep Ar pkgname
|
|
Declare a dependency on the
|
|
.Ar pkgname
|
|
package. The
|
|
.Ar pkgname
|
|
package must be installed before this package may be
|
|
installed, and this package must be deinstalled before the
|
|
.Ar pkgname
|
|
package is deinstalled. Multiple
|
|
.Cm @pkgdep
|
|
directives may be used if the package depends on multiple other packages.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
The environment variable
|
|
.Ev PKG_TMPDIR
|
|
names the directory where
|
|
.Nm
|
|
will attempt to create its temporary files.
|
|
If
|
|
.Ev PKG_TMPDIR
|
|
is not set,
|
|
the directory named by the contents of
|
|
.Ev TMPDIR
|
|
will be used.
|
|
If neither of
|
|
.Ev PKG_TMPDIR
|
|
and
|
|
.Ev TMPDIR
|
|
are set, the builtin defaults are used.
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/tmp -compact
|
|
.It Pa /var/tmp
|
|
Temporary directory if environmental variables
|
|
.Ev PKG_TMPDIR
|
|
and
|
|
.Ev TMPDIR
|
|
are not set.
|
|
.It Pa /tmp
|
|
The next choice if
|
|
.Pa /var/tmp
|
|
does not exist.
|
|
.It Pa /usr/tmp
|
|
The last choice if
|
|
.Pa /tmp
|
|
is unsuitable.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr pkg_add 1 ,
|
|
.Xr pkg_delete 1 ,
|
|
.Xr pkg_info 1 ,
|
|
.Xr pkg_version 1 ,
|
|
.Xr sysconf 3
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
command first appeared in
|
|
.Fx .
|
|
.Sh AUTHORS
|
|
.An Jordan Hubbard
|
|
for most of the work.
|
|
.An John Kohl
|
|
for NetBSD refinements.
|
|
.Sh BUGS
|
|
Hard links between files in a distribution must be bracketed by
|
|
.Cm @cwd
|
|
directives in order to be preserved as hard links when the package is
|
|
extracted. They additionally must not end up being split between
|
|
.Cm tar
|
|
invocations due to exec argument-space limitations (this depends on the
|
|
value returned by
|
|
.Fn sysconf _SC_ARG_MAX ) .
|
|
.Pp
|
|
Sure to be others.
|