.\"
.\" FreeBSD pkg - a next generation package for the installation and maintenance
.\" 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.
.\"
.\"
.\" @(#)pkg.8
.\"
.Dd January 15, 2025
.Dt PKG-CREATE 8
.Os
.\" ---------------------------------------------------------------------------
.Sh NAME
.Nm "pkg create"
.Nd a utility for creating software package distributions
.\" ---------------------------------------------------------------------------
.Sh SYNOPSIS
.Nm
.Op Fl enqv
.Op Fl f Ar format
.Op Fl l Ar level
.Op Fl o Ar outdir
.Op Fl p Ar plist
.Op Fl r Ar rootdir
.Op Fl t Ar timestamp
.Op Fl T Ar threads
.Fl m Ar metadatadir
.Nm
.Op Fl enqv
.Op Fl f Ar format
.Op Fl l Ar level
.Op Fl o Ar outdir
.Op Fl r Ar rootdir
.Op Fl t Ar timestamp
.Op Fl T Ar threads
.Fl M Ar manifest
.Nm
.Op Fl egnqvx
.Op Fl f Ar format
.Op Fl l Ar level
.Op Fl o Ar outdir
.Op Fl r Ar rootdir
.Op Fl t Ar timestamp
.Op Fl T Ar threads
.Ar pkg-name ...
.Nm
.Op Fl enqv
.Op Fl f Ar format
.Op Fl l Ar level
.Op Fl o Ar outdir
.Op Fl r Ar rootdir
.Op Fl t Ar timestamp
.Op Fl T Ar threads
.Fl a
.\" ---------------------------------------------------------------------------
.Pp
.Nm
.Op Cm --expand-manifest
.Op Cm --no-clobber
.Op Cm --quiet
.Op Cm --verbose
.Op Cm --format Ar format
.Op Cm --level Ar level
.Op Cm --out-dir Ar outdir
.Op Cm --plist Ar plist
.Op Cm --root-dir Ar rootdir
.Cm --metadata Ar metadatadir
.Nm
.Op Cm --expand-manifest
.Op Cm --no-clobber
.Op Cm --quiet
.Op Cm --verbose
.Op Cm --format Ar format
.Op Cm --level Ar level
.Op Cm --out-dir Ar outdir
.Op Cm --root-dir Ar rootdir
.Cm --manifest Ar manifest
.Nm
.Op Cm --expand-manifest
.Op Cm --{glob,no-clobber,regex}
.Op Cm --quiet
.Op Cm --verbose
.Op Cm --format Ar format
.Op Cm --level Ar level
.Op Cm --out-dir Ar outdir
.Op Cm --root-dir Ar rootdir
.Ar pkg-name ...
.Nm
.Op Cm --expand-manifest
.Op Cm --no-clobber
.Op Cm --quiet
.Op Cm --verbose
.Op Cm --format Ar format
.Op Cm --level Ar level
.Op Cm --out-dir Ar outdir
.Op Cm --root-dir Ar rootdir
.Cm --all
.\" ---------------------------------------------------------------------------
.Sh DESCRIPTION
.Nm
is used to create packages from binaries or other files installed on
your computer.
Package tarballs can be created from the files of a previously installed
package using metadata from the local package database.
Any number of packages may be created in one invocation of this style.
.Pp
Alternatively, a single package can be created from an arbitrary
selection of files on your system, but this requires a
.Ar metadatadir
and optionally
.Ar plist
to be supplied.
The package name will be derived from the
.Pa +MANIFEST
file which must be contained within the
.Ar metadatadir ,
or passed as the argument to
.Fl M .
.Pp
Packages thus created can be distributed and subsequently installed on
other machines using the
.Cm pkg add
command.
.\" ---------------------------------------------------------------------------
.Sh OPTIONS
The following options are supported by
.Nm :
.Bl -tag -width ".Fl m Ar metadatadir"
.It Fl M Ar manifest , Cm --manifest Ar manifest
Read all of the package metadata from the
.Ar manifest
file.
This is exactly the same format as
.Pa +MANIFEST
mentioned above, but any file name can be used, and no
other file will be used to read package metadata from.
If specified, only a single package will be created.
This option is incompatible with the
.Fl m , a , g
or
.Fl x
options.
.It Fl T Ar threads
.Ar threads
represent the number of threads to use during the compression of the archive.
Set it to
.Qq 0
or
.Qq auto
to let detect the number of CPU and use it.
.It Fl a , Cm --all
Create package tarballs from all packages installed on your system.
This option is incompatible with the
.Fl g , x
or
.Fl m Ar metadatadir
options.
.It Fl e , Cm --expand-manifest
The manifest contained in pkg will be expanded to readable UCL format.
.It Fl f Ar format , Cm --format Ar format
Set
.Ar format
as the package compression format.
It can be one of
.Ar tzst, txz , tbz , tgz
or
.Ar tar
which are currently the only supported formats.
If an invalid or no format is specified
.Ar tzst
is assumed.
.Po The
.Pa .pkg
extension is used for all compression types.
.Pc
.It Fl g , Cm --glob
Interpret
.Ar pkg-name
as a shell glob pattern and create package only for installed binaries whose
name match this pattern.
This option is incompatible with the
.Fl a , x
or
.Fl m Ar metadatadir
options.
.It Fl l Ar level , Cm --level Ar level
Set the compression
.Ar level
for created packages.
It can be any valid numeric compression level you might specify to the
underlying compression
.Ar format .
Additionally,
.Ar level
may be one of the special words
.Dv Dq fast
or
.Dv Dq best .
If
.Ar level
is one of these special words, the fastest or slowest compression level,
respectively, for the specified compression format, is used.
.It Fl m Ar metadatadir , Cm --metadata Ar metadatadir
Specify the directory containing the package manifest,
.Pa +MANIFEST
and optionally three other files; one containing a message to be
displayed on package installation,
.Pa +DISPLAY .
Another containing the description for the package,
.Pa +DESC .
If specified, only a single package will be created.
.Pa +DISPLAY
and
.Pa +DESC
are not required; the
.Pa +MANIFEST
file can contain all the required information needed to build a
package.
This option is incompatible with the
.Fl M , a , g
or
.Fl x
options.
.It Fl n , Cm --no-clobber
Do not overwrite already existing packages.
.It Fl o Ar outdir , Cm --out-dir Ar outdir
Set
.Ar outdir
as the output directory.
If this option is not given, all created packages will
be saved in the current directory.
.It Fl p Ar plist , Cm --plist Ar plist
Specify some package metadata using the legacy plist format from
.Xr pkg_add 1 ,
commonly found in
.Pa pkg-plist
files in the ports tree.
Metadata from the
.Ar plist
file, if specified, will take precedence over any equivalents from
the
.Ar metadatadir .
Only has any effect when used with
.Ar metadatadir .
See
.Sx "PLIST FORMAT"
for details.
.It Fl q , Cm --quiet
Force quiet output.
This is the default, unless
.Cm PKG_CREATE_VERBOSE
is set to
.Ar yes
in
.Pa pkg.conf .
.It Fl r Ar rootdir , Cm --root-dir Ar rootdir
.Ar rootdir
specifies the top-level directory to be treated as the root of the
filesystem hierarchy containing the package files.
File paths in generated packages will be relative to
.Ar rootdir .
This allows a package to be generated from content offset from its
intended final location, which allows a package building without
disturbing similar content already on the system.
If unspecified, the default is effectively
.Pa / ,
the actual root directory.
.It Fl t Ar timestamp , Cm --timestamp
Set the timestamp of the files within the archive.
.It Fl v , Cm --verbose
Force verbose output, the opposite of
.Cm --quiet .
.It Fl x , Cm --regex
Like
.Fl g ,
but interpret
.Ar pkg-name
as a regular expression using the "modern" or "extended" syntax described in
.Xr re_format 7 .
This option is incompatible with the
.Fl a , g
or
.Fl m Ar metadatadir
options.
.El
.\" ---------------------------------------------------------------------------
.Sh MANIFEST FILE DETAILS
.Bl -tag -width ".Cm www"
.It Cm name Ar pkg-name
This entry sets the package's name to
.Ar pkg-name . \" TODO: Find out why there is a space after the ``.''
Among other things, this name is used - with the version and the origin of the
concerned package - to identify a dependency.
.It Cm version Ar pkg-version
This entry sets the package's version to
.Ar pkg-version .
.It Cm origin Ar pkg-origin
This entry sets the package's origin to
.Ar pkg-origin .
This is a string of the form
.Pa category/port-dir
which designates the port this package was built from.
.It Cm comment Ar comment-string
.Ar comment-string
is a one-line description of this package.
It is the equivalent of the
.Dv COMMENT
variable for a port, not a way to put comments in a
.Pa +MANIFEST
file.
.It Cm desc Ar description
.Ar description
is a longer description of the package.
It is the equivalent of the
.Pa pkg-descr
file for a port.
It may be one to a few paragraphs.
For example:
.Bd -literal -offset indent
desc = <<EOD
This is a longer description of the package.
It can span multiple lines.
It can also span multiple paragraphs.
EOD
.Ed
.It Cm arch Ar cpu-type
The architecture of the machine the package was built on.
.Ar cpu-type
takes values like x86, amd64...
.It Cm www Ar url
The software's official website.
.It Cm maintainer Ar mail-address
The maintainer's mail address.
.It Cm prefix Ar path-prefix
The path where the files contained in this package are installed
.Pq usually Pa /usr/local .
.It Cm flatsize Ar size
The size that the files contained in this package will occupy on your system
once uncompressed.
This value does not take into account files stored in the
package database.
.It Cm deps Ar dep-name dep-origin dep-version
Associative array of package dependencies, keyed on
.Ar dep-name
and with values
.Cm version Ar dep-version
and
.Cm origin Ar dep-origin .
For example:
.Bd -literal -offset indent
"deps" : {
"pstree" : {
"version" : "2.36",
"origin" : "sysutils/pstree"
},
"cdiff" : {
"version" : "0.9.6.20140711,1",
"origin" : "textproc/cdiff"
},
},
.Ed
.It Cm conflict Ar pkg-glob
Flag this package as incompatible with the one designated by
.Ar pkg-glob .
Conflicting packages cannot be installed on the same system as they may contain
references to the same files.
.It Cm option Ar option-name option-value
Set the option
.Ar option-name
to the value
.Ar option-value .
.It Cm file Ar sha256-hash path
.Cm file
entries list files included in the package.
If the file is a regular one, such
an entry contains its sha256 digest along with its path.
If a packaged file is
a link, you must use this entry's other form, as described below.
.It Cm file Ar - path
Same as above but for file links.
The sha256 hash is replaced with a
.Ar -
(dash).
.It Cm dir Ar path
Mimics the
.Cm file
entry but for directories.
.El
.Sh PLIST FORMAT
The following describes the plist format:
.Pp
The plist is a sequential list of lines which can have keywords prepended.
A keyword starts with an
.Sq @ .
Lines not starting with a keyword are considered as paths to a file.
If started with a
.Sq /
then it is considered an absolute path.
Otherwise the file is considered as relative to
.Ev PREFIX .
.Pp
Keyword lines are formed as follows:
.Ar @keyword
.Ar line
.Pp
Available keywords are the following:
.Pp
.Bl -tag -width indent -compact
.It Cm @cwd Op Ar directory
Set the internal directory pointer to point to
.Ar directory .
All subsequent filenames will be assumed relative to this directory.
.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.
Use without an arg to set back to default (mode of the file while being packed)
permissions.
.It Cm @owner Ar user
Set default ownership for all subsequent files to
.Ar user .
Use without an arg to set back to default (root)
ownership.
.It Cm @group Ar group
Set default group ownership for all subsequent files to
.Ar group .
Use without an arg to set back to default (wheel)
group ownership.
.It Cm @comment Ar string
The line will be ignored when packing.
.It Cm @dir Ar name
Declare directory
.Pa name
to be deleted at deinstall time.
By default, most directories created by a package installation are
deleted automatically when the package is deinstalled, so this directive is
only needed for empty directories or directories outside of
.Ev PREFIX .
These directives should appear at the end of the package list.
If the directory is not empty a warning will be printed, and the
directory will not be removed.
(Subdirectories should be listed before parent directories.)
.It Cm @include Ar name
Include the
.Pa name
plist file to the plist currently being parsed. the
.Pa name
will be opened relatively to the main plist file being parsed.
Note: only one level of
.Cm @include
is allowed
.El
.Sh ESCAPE SEQUENCES
.\" ---------------------------------------------------------------------------
.Sh ENVIRONMENT
The following environment variables affect the execution of
.Nm .
See
.Xr pkg.conf 5
for further description.
.Bl -tag -width ".Ev NO_DESCRIPTIONS"
.It Ev PKG_DBDIR
.It Ev PLIST_KEYWORDS_DIR
.It Ev PORTSDIR
.It Ev SOURCE_DATE_EPOCH
Set the timestamp for every single file in the archive to the one
specified in the environment variable
.El
.\" ---------------------------------------------------------------------------
.Sh FILES
See
.Xr pkg.conf 5 .
.\" ---------------------------------------------------------------------------
.Sh EXAMPLES
Create package files for installed packages:
.Dl % pkg create -a -o /usr/ports/packages/All
.Pp
Create package file for pkg:
.Dl % pkg create -o /usr/ports/packages/All pkg
.\" ---------------------------------------------------------------------------
.Sh SEE ALSO
.Xr pkg_create 3 ,
.Xr pkg_printf 3 ,
.Xr pkg_repo_create 3 ,
.Xr pkg_repos 3 ,
.Xr pkg-keywords 5 ,
.Xr pkg-lua-script 5 ,
.Xr pkg-repository 5 ,
.Xr pkg-script 5 ,
.Xr pkg-triggers 5 ,
.Xr pkg.conf 5 ,
.Xr pkg 8 ,
.Xr pkg-add 8 ,
.Xr pkg-alias 8 ,
.Xr pkg-annotate 8 ,
.Xr pkg-audit 8 ,
.Xr pkg-autoremove 8 ,
.Xr pkg-check 8 ,
.Xr pkg-clean 8 ,
.Xr pkg-config 8 ,
.Xr pkg-delete 8 ,
.Xr pkg-fetch 8 ,
.Xr pkg-info 8 ,
.Xr pkg-install 8 ,
.Xr pkg-key 8 ,
.Xr pkg-lock 8 ,
.Xr pkg-query 8 ,
.Xr pkg-register 8 ,
.Xr pkg-repo 8 ,
.Xr pkg-repositories 8 ,
.Xr pkg-rquery 8 ,
.Xr pkg-search 8 ,
.Xr pkg-set 8 ,
.Xr pkg-shell 8 ,
.Xr pkg-shlib 8 ,
.Xr pkg-ssh 8 ,
.Xr pkg-stats 8 ,
.Xr pkg-triggers 8 ,
.Xr pkg-update 8 ,
.Xr pkg-updating 8 ,
.Xr pkg-upgrade 8 ,
.Xr pkg-version 8 ,
.Xr pkg-which 8
