path: root/man/man8/mkpkg.8

.Dd September 27, 2026
.Dt MKPKG 8
.Os
.Sh NAME
.Nm mkpkg
.Nd build packages from source
.Sh SYNOPSIS
.Nm
.Op Ar dir
.Op Fl bdw
.Op Fl i Ns Op Ar bcfs
.Op Fl g Ar file
.Op Fl r Ar root
.Nm
.Op Ar dir
.Fl c | e | f | p | s
.Nm
.Op Ar dir
.Fl o Ns Ar d | Fl o Ns Ar e
.Nm
.Op Ar dir
.Fl u Ns Op Ar cfsp
.Op Fl i Ns Op Ar bcfs
.Nm
.Op Ar dir
.Fl x Ns Op Ar dfsw
.Nm
.Fl h | v
.Sh DESCRIPTION
.Nm
reads a
.Xr MAKEPKG 5
recipe from the current directory, or from
.Ar dir
if given, and builds a binary package from it.
The package is written as
.Sm off
.Ar name No # Ar version No - Ar release No .pkg.tar.\& Ar ext
.Sm on
into the package directory, where
.Ar ext
follows
.Ev MKPKG_COMPRESSION_MODE
in
.Xr mkpkg.conf 5 .
.Pp
If
.Pa MAKEPKG.lock
exists, it is built instead of
.Pa MAKEPKG ;
see
.Sx LOCKED PORTS .
.Pp
A build runs these steps, in order:
.Bl -enum -offset indent
.It
Verify the port signature; see
.Sx SIGNATURE VERIFICATION .
Skipped with
.Fl is .
.It
If the package must be built, make sure every source is present.
Missing downloads are an error unless
.Fl d
is given, in which case they are fetched with
.Xr wget 1 .
.It
Verify the
.Va sha256sums
of the sources.
Skipped with
.Fl ic .
.It
Stop if the package is up to date: it exists and no source file is
newer than it.
The recipe itself is not compared; after editing it, raise
.Va release
or remove the package with
.Fl x .
.It
Run the first
.Fn shell
hook.
If it fails, the second
.Fn shell
hook runs to clean up and nothing is built.
.It
Create the work directory, then run
.Fn extract
or unpack the sources automatically, then
.Fn patch .
.It
Run
.Fn build
and
.Fn post_build .
.It
Strip binaries, compress manual pages with
.Xr gzip 1 ,
remove libtool
.Pa .la
files and write the package metadata.
.It
Create the package archive.
.It
Check the package against
.Pa .footprint ;
see
.Sx FOOTPRINT .
.It
Sign the port if the footprint check passed; see
.Sx SIGNATURE VERIFICATION .
.It
Run the second
.Fn shell
hook.
If the build failed at an earlier step, it runs right then, so the
first hook's setup is always undone.
.It
With
.Fl r ,
install the package with
.Xr addpkg 8 .
.El
.Pp
The hooks are described in
.Xr MAKEPKG 5 .
.Pp
Options are single letters and may be combined in one argument, as in
.Fl dw .
The letters
.Cm x ,
.Cm u ,
.Cm i
and
.Cm o
start a group: every letter after them in the same argument belongs to
that group, so
.Fl xdf
removes downloads and the footprint, and
.Fl ic
ignores checksums.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl b
Build in the full lockbox, as if the recipe set
.Li lockbox=(yes) ;
see
.Xr lockbox 7 .
.It Fl c
Print a
.Va sha256sums
array for the sources to standard output.
.It Fl d
Download missing sources before building.
.It Fl e
Unpack the sources into a fresh work directory and stop.
Same as
.Fl oe .
.It Fl f
Print the footprint of the built package to standard output.
.It Fl g Ar file
Use the configuration
.Ar file
instead of
.Pa /etc/mkpkg.conf ,
both for the
.Ev MKPKG_*
settings and in the hooks that source it.
A relative
.Ar file
is taken relative to the directory
.Nm
is started in.
.It Fl h , Fl Fl help
Print a usage summary.
.It Fl i Ns Op Ar bcfs
Ignore one or more checks; the build still runs:
.Bl -tag -width Ds
.It Cm b
Do not use the lockbox, neither the full lockbox of
.Fl b
or
.Li lockbox=(yes)
nor the per-command form.
.It Cm c
Do not verify
.Va sha256sums .
.It Cm f
Sign even if the footprint does not match.
.It Cm s
Do not verify the port signature before building, and do not sign
after it.
.El
.It Fl o Ns Ar d
Download missing sources and stop.
.It Fl o Ns Ar e
Unpack the sources into a fresh work directory and stop.
.It Fl p
Print the public key from the recipe's
.Fn signify
block.
.It Fl r Ar root
After a successful build, install the package into
.Ar root
with
.Xr addpkg 8 .
If another version of the package is installed there, it is upgraded
with
.Fl u ;
if the same version is installed,
.Xr addpkg 8
refuses.
.It Fl s
Verify the port signature and stop.
.It Fl u Ns Op Ar cfsp
Update port files.
The letters combine, and run in this order:
.Cm p ,
.Cm c ,
then with
.Cm s
the build if one is needed,
.Cm f ,
and signing last, so the signature covers what the others wrote.
.Bl -tag -width Ds
.It Cm c
Rewrite the
.Va sha256sums
array in the recipe from the sources on disk.
.It Cm f
Rewrite
.Pa .footprint
from the built package.
.It Cm s
Sign the port.
The sources are checked first as for a build: missing downloads are an
error unless
.Fl d
is given, and the
.Va sha256sums
are verified unless
.Fl ic
is given.
The package is built if it is not up to date.
Signing is refused if the footprint does not match, unless
.Cm f
or
.Fl if
is also given, and fails if there is no secret key.
.It Cm p
Write a
.Fn signify
block with the public key belonging to the secret key into the recipe,
replacing any existing one.
The public key is looked for next to the secret key, with
.Pa .sec
replaced by
.Pa .pub ,
then in
.Pa /etc/ports/keys/ .
.El
.It Fl v , Fl Fl version
Print the version.
.It Fl w
Keep the work directory after the build.
Given twice,
.Fl ww
resumes: the existing work directory is used as it is,
.Fn extract
and
.Fn patch
are skipped and
.Fn build
runs again.
Neither
.Pa work/src
nor
.Pa work/pkg
is cleaned first.
Resuming needs the work directory of an earlier
.Fl w
run, so it does not work with a tmpfs
.Ev MKPKG_WORK_DIR ,
which is created per process.
.It Fl x Ns Op Ar dfsw
Remove the built package, then stop.
Further letters remove more:
.Bl -tag -width Ds
.It Cm d
Downloaded source files.
Sources saved under a name from
.Va renames
are not found.
.It Cm f
The footprint file.
.It Cm s
The signature file.
.It Cm w
The
.Pa work
directory in the port directory.
.El
.El
.Pp
When several modes are given, only the first of these runs:
.Fl x ,
.Fl f ,
.Fl c ,
.Fl p ,
.Fl s ,
.Fl od ,
.Fl e ,
.Fl u ,
build.
.Sh FOOTPRINT
The footprint is the sorted list of files in the package, with mode,
owner and group, and the target of each symbolic link.
On the first build, when there is no
.Pa .footprint ,
it is created.
.Pp
On later builds a mismatch is printed as
.Dq changed ,
.Dq missing
and
.Dq new
entries.
The package is kept and
.Nm
exits 0, so a long build is never lost to a footprint change; the
package is just not signed.
Review the list, then accept it with
.Fl uf
and sign with
.Fl us .
.Xr addpkg 8
refuses to install a package whose footprint does not match.
.Sh SIGNATURE VERIFICATION
Before every build, and with
.Fl s ,
.Nm
verifies the port in three steps and fails on any of them:
.Bl -enum -offset indent
.It
The key in the recipe's
.Fn signify
block must equal the key of a
.Pa .pub
file in
.Pa /etc/ports/keys/ .
That trusted file is used for the next step, never the key from the
recipe: the recipe and its
.Pa .signature
arrive by the same way, so a key carried in the recipe can only vouch
for itself.
.It
.Xr signify 1
verifies
.Pa .signature
with the trusted key.
This authenticates the checksum list in it.
.It
The
.Li MAKEPKG
line of that list must match the recipe on disk, and the
.Li .footprint
line, when present, the footprint on disk.
Sources are covered by the recipe's
.Va sha256sums .
.El
.Pp
After a build whose footprint check passed, the port is signed if the
recipe has a
.Fn signify
block and a secret key is found:
.Ev MKPKG_SECRET_KEY
from the configuration file or the environment, else
.Pa /etc/ports/keys/rawnix.sec .
Without a key, signing is skipped silently.
After signing,
.Nm
verifies the new signature and warns if it can never pass.
.Pp
The list names the recipe
.Li MAKEPKG
and the footprint
.Li .footprint
whichever files were hashed; see
.Sx LOCKED PORTS .
.Sh LOCKED PORTS
When
.Pa MAKEPKG.lock
exists in the port directory,
.Nm
builds it instead of
.Pa MAKEPKG ,
and uses
.Pa .footprint.lock
and
.Pa .signature.lock
in place of
.Pa .footprint
and
.Pa .signature
for every check, update and signature.
.Xr ports 8
does not sync
.Pa *.lock ,
so upstream updates never touch a locked port's recipe, footprint or
signature.
The lock files are created by
.Ic pkg lock .
.Pp
A fresh lock carries upstream's signature, which still verifies the
unedited recipe.
After editing
.Pa MAKEPKG.lock ,
sign it again with
.Fl us .
To sign with your own key, run
.Fl up
with
.Ev MKPKG_SECRET_KEY
pointing at it, then
.Fl us ,
and install the matching
.Pa .pub
into
.Pa /etc/ports/keys/ .
.Sh ENVIRONMENT
.Nm
exports to every hook:
.Bl -tag -width PKGMK_SOURCE_DIR
.It Ev PKG
The package staging directory,
.Pa work/pkg .
Files installed here end up in the package.
.It Ev SRC
The source directory,
.Pa work/src .
.It Ev PKGMK_SOURCE_DIR
The directory downloads are saved in:
.Ev MKPKG_SOURCE_DIR
if set, otherwise the port directory.
.It Ev name , Ev version , Ev release
From the recipe, as are its
.Va _ Ns Ar custom
variables.
.El
.Pp
With per-command lockbox,
.Fn build
also gets
.Ev MKPKG_WORK_DIR ,
.Ev MKPKG_DEPENDS
and
.Ev MKPKG_MAKEDEPENDS
for
.Xr lbexec 8 .
.Pp
.Nm
itself reads:
.Bl -tag -width PKGMK_SOURCE_DIR
.It Ev MKPKG_DEBUG
If set, trace recipe parsing and run the hooks with
.Ic set -x .
.It Ev MKPKG_SECRET_KEY
Secret key for signing, if not set in the configuration file.
.It Ev PKG_DBDIR
Package database directory for the lockbox, instead of
.Pa /var/lib/pkg .
.It Ev TMPDIR
Directory for temporary files.
Default:
.Pa /dev/shm .
.El
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa MAKEPKG
The recipe; see
.Xr MAKEPKG 5 .
.It Pa .footprint
Expected contents of the package.
.It Pa .signature
Signed checksums of the recipe, footprint, sources and package.
.It Pa .nostrip
Patterns, one per line, for
.Xr grep 1
.Fl f ;
matching files, as paths relative to
.Ev PKG ,
are not stripped.
.It Pa MAKEPKG.lock , .footprint.lock , .signature.lock
A locked port's recipe, footprint and signature.
.It Pa work/
Default work directory.
.It Pa /etc/mkpkg.conf
Configuration; see
.Xr mkpkg.conf 5 .
.It Pa /etc/ports/keys/*.pub
Trusted public keys.
.It Pa /etc/ports/keys/rawnix.sec
Default secret key for signing.
.El
.Sh EXIT STATUS
.Bl -tag -width 3n -compact
.It 0
Success, including a build whose footprint did not match.
.It 1
General error or usage error.
.It 2
The recipe could not be read or is incomplete.
.It 3
A directory is missing or not accessible.
.It 4
A download failed or a source is missing.
.It 5
Unpacking failed.
.It 6
A checksum did not match.
.It 7
The footprint could not be made, or
.Fl us
refused to sign because it did not match.
.It 8
A hook or the build failed.
.It 9
Installing with
.Fl r
failed.
.It 10
Signature verification or signing failed, or
.Fl us
found no secret key.
.El
.Sh EXAMPLES
Build a port from anywhere, downloading its sources:
.Pp
.Dl $ mkpkg /usr/ports/core/zlib -d
.Pp
Accept a changed footprint after a build, then sign:
.Pp
.Dl $ mkpkg -uf && mkpkg -us
.Pp
After a version bump: download, update the checksums, build, accept
the new footprint and sign:
.Pp
.Dl $ mkpkg -od && mkpkg -ucfs
.Pp
Clean everything and rebuild:
.Pp
.Dl $ mkpkg -xdfsw && mkpkg -d
.Sh SEE ALSO
.Xr signify 1 ,
.Xr MAKEPKG 5 ,
.Xr mkpkg.conf 5 ,
.Xr lockbox 7 ,
.Xr addpkg 8 ,
.Xr bulk 8 ,
.Xr lbexec 8 ,
.Xr pkg 8 ,
.Xr ports 8