.\" $OpenBSD: bsd.port.mk.5,v 1.505 2019/01/11 15:49:08 espie Exp $
.\"
.\" Copyright (c) 2000-2008 Marc Espie
.\"
.\" All rights reserved.
.\"
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: January 11 2019 $
.Dt BSD.PORT.MK 5
.Os
.Sh NAME
.Nm bsd.port.mk
.Nd ports tree master Makefile fragment
.Sh SYNOPSIS
.Fd .include <bsd.port.mk>
.Sh DESCRIPTION
.Nm
contains the
.Xr ports 7
tree
.Xr make 1
framework, in the form of documented public targets,
variables and paths.
.Pp
Identifiers beginning with an underscore
are internal-use only and likely to change without
notice.
.Pp
This documentation contains sections covering targets, variables,
diagnostics, and filenames, ordered in alphabetic order, followed
by a section covering the fake framework, a section
explaining flavors and multi-packages, and a section covering
the generation of package information.
.Pp
It ends with sections covering obsolete targets, variables and files,
outlining conversion
methods from older incarnations of the ports tree or from other
.Bx
variants.
.Pp
.Nm
also uses quite a few helper scripts which live under
.Pa ${PORTSDIR}/infrastructure/bin .
.Pp
Binary package details are mostly covered in
.Xr pkg_create 1
for the packing-list details,
and in
.Xr pkg_add 1
for the installation semantics.
.Pp
Common usage such as building every package in
the system is covered by
.Xr ports 7
and
.Xr bulk 8
instead, with
.Xr packages 7
providing an overview of the result.
.Sh TARGETS
.Bl -tag -width Ds
.It Cm {build,run,all,test}-dir-depends
Print all dependencies for a port in order to build it, run it, build and
run it, or to run regression tests.
The output is formatted as package specification pairs, in a form suitable
for
.Xr tsort 1 .
.It Cm full-{build,run,all,test}-depends
Print all dependencies a package depends upon for building, running,
or both, as a list of package names, sorted by dependency order with
.Xr tsort 1 ,
most dependent port first.
.It Cm {build,lib,test,run}-depends-list
Print a list of first level package specifications a port depends as
build dependencies, library dependencies, test dependencies or
run dependencies.
.It Cm print-{build,run}-depends
User convenience target that displays the result of
.Cm full-{build,run}-depends
in a more readable way.
.It Cm {pre,do,post}-*
Most standard targets can be specialized according to a given port's needs.
If defined,
the
.Cm pre-*
hook will be invoked before running the normal action;
the
.Cm do-*
hook will be invoked instead of the normal action;
the
.Cm post-*
hook will be invoked after the normal action.
Specialization hooks exist for
.Cm build ,
.Cm configure ,
.Cm distpatch ,
.Cm extract ,
.Cm fake ,
.Cm gen ,
.Cm install ,
.Cm patch ,
.Cm test .
See individual targets for exceptions.
.It Cm all-lib-depends-args
Process the full
.Ev LIB_DEPENDS
list into a form suitable for
.Xr pkg_create 1 ,
see
.Cm print-package-args .
.It Cm build , Cm all
Default target.
Build the port.
Essentially invoke
.Bd -literal
env -i ${MAKE_ENV} ${MAKE_PROGRAM} ${MAKE_FLAGS} \e
	-f ${MAKE_FILE} ${ALL_TARGET}
.Ed
.It Cm check-register
Introspection target.
Verify from the ports tree, without building anything, that the current
subpackage will register okay
.Po
see
.Ev PLIST_REPOSITORY
.Pc .
.It Cm check-register-all
Apply
.Cm check-register
to all subpackages of the current port.
.It Cm checkpatch
Check that patches would apply cleanly, but do not modify anything.
.It Cm checksum
Compute a
.Xr sha256 1
digest
of ${CHECKSUM_FILES} (files listed in DISTFILES and PATCHFILES) and
check it against ${CHECKSUM_FILE}, normally
.Pa distinfo .
In case of a mismatch, running
.Cm checksum
with
.Ev REFETCH Ns = Ns Cm true
will fetch alternative versions of files keyed on their checksum
fron the
.Ox
main archive site.
.It Cm clean
Clean ports contents.
By default, it will clean the work directory.
It can be invoked as
make clean='[depends build bulk work fake flavors dist install sub package
packages plist]'.
.Bl -tag -width packages
.It Va work
Clean work directory.
.It Va bulk
Clean bulk cookie.
.It Va build
Clean the
.Ev WRKBUILD
directory (only useful if
.Ev SEPARATE_BUILD
is set).
.It Va depends
Recurse into dependencies.
.It Va dist
Clean distribution files.
.It Va fake
Clean fake installation directory.
.It Va flavors
Clean all work directories.
.It Va install
Uninstall package.
.It Va package
Remove all copies of package file.
.It Va plist
Remove registered packing lists of all subpackages.
.It Va sub
With
.Va install
or
.Va package ,
clean subpackages as well.
.It Va packages
Shorthand for
.Sq sub package .
.It Va all
Shorthand for
.Sq work flavors packages plist .
.El
.It Cm clean-depends
Shorthand for
.Ql make clean=depends .
.It Cm configure
Configure the port.
By default,
.Cm configure
creates the ${WRKBUILD} directory (see
.Ev SEPARATE_BUILD ) ,
and runs whatever configuration methods are recorded in
.Ev CONFIGURE_STYLE .
.It Cm distclean
Shorthand for
.Ql make clean=dist .
.It Cm distpatch
Apply distribution patches only.
See
.Cm patch
and
.Ev PATCH_CASES
for details.
.It Cm dump-vars
Dump the values of all relevant variables in a port, prepended with the
port's FULLPKGPATH.
.It Cm extract
Extract the distribution files under
.Pa ${WRKDIR}
(but see
.Ev EXTRACT_ONLY ,
.Ev FIX_EXTRACT_PERMISSIONS
and
.Ev NO_DEPENDS ) .
Refer to
.Ev EXTRACT_CASES
for a complete description.
Do not use
.Cm pre-extract
and
.Cm do-extract
hooks.
.It Cm fake
Do a fake port installation, that is, simulate the port installation under
${WRKINST}.
There is no
.Cm do-fake
and
.Cm post-fake
hooks.
.Cm fake
actually uses
.Cm pre-fake ,
.Cm pre-install ,
.Cm do-install
and
.Cm post-install .
Override
.Cm pre-install ,
.Cm do-install ,
or
.Cm post-install
to change behavior.
Do not touch
.Cm pre-fake
unless you really know what you are doing.
See
.Sx THE FAKE FRAMEWORK
section below.
.It Cm fake-wantlib-args
Check
.Ev WANTLIB
against the list of installed packages and libraries in the ports tree.
See
.Cm print-package-args .
.It Cm fetch
Fetch the list of files in
.Ev DISTFILES
and
.Ev PATCHFILES
using ${FETCH_CMD}.
Files are normally retrieved from the list of sites in
.Ev MASTER_SITES .
.Pp
Appending
.Sq :0
to
.Sq :9
to an entry will let
${FETCH_CMD} retrieve from
.Ev MASTER_SITES0
to
.Ev MASTER_SITES9
instead.
If the rest of the entry parses as
.Sq Ar filename Ns { Ns Ar url Ns } Ns Ar sufx
${FETCH_CMD} will fetch
.Ar url Ns Ar sufx
instead, but store the result as
.Ar filename Ns Ar sufx .
.Pp
Transfers in progress are stored as
.Ar filenamesufx.part
and moved after completion.
.Pp
The ports framework uses
.Pa ${DISTDIR}/${DIST_SUBDIR}
(aliased to
.Pa ${FULLDISTDIR} )
to save the ports distribution files and patch files.
.Pp
If you want to fetch a significant number of distfiles quickly, say
all files relevant to a port,
.Cm dpb Fl F
is more efficient.
.Pp
Use of
.Cm {pre,do,post}-fetch
hooks is forbidden, as this would make mirroring of distfiles very complicated.
.Pp
See
.Ev CHECKSUMFILES ,
.Ev DISTDIR ,
.Ev DISTFILES ,
.Ev DIST_SUBDIR ,
.Ev FETCH_CMD ,
.Ev FETCH_MANUALLY ,
.Ev FETCH_SYMLINK_DISTFILES ,
.Ev FULLDISTDIR ,
.Ev MAKESUMFILES ,
.Ev MASTER_SITES ,
.Ev MASTER_SITES0 , ... ,
.Ev MASTER_SITES9 ,
.Ev PATCHFILES ,
.Ev SUPDISTFILES ,
.Ev REFETCH .
.It Cm fetch-all
Like
.Cm fetch ,
but also fetches
.Ev SUPDISTFILES ,
for use with e.g.,
.Cm makesum .
.It Cm fix-permissions
Ensure permissions are correct when using
.Ev PORTS_PRIVSEP
and/or
.Xr dpb 1 .
.Pp
If necessary, creates directory
.Ev DISTDIR
owned by
.Ev FETCH_USER ,
and creates directories
.Ev LOCKDIR ,
.Ev PACKAGES_REPOSITORY ,
.Ev PLIST_REPOSITORY
and
.Ev WRKOBJDIR
owned by
.Ev BUILD_USER .
.Pp
If these directories already exist,
ownership of their contents is modified to conform to
.Ev PORTS_PRIVSEP
and
.Xr dpb 1
requirements.
.It Cm gen
Generate configure script when needed, either after patching
input files, or from scratch for some ports,
generally using automake, autoconf, autogen and similar gnu tools.
This target only has modules
.Po Ev MODxxx_gen Pc
and a
.Ar do-gen
hooks.
Then adjust timestamps to avoid regeneration during build
.Po
see
.Ev REORDER_DEPENDENCIES
.Pc .
.It Cm generate-readmes
Generate READMEs and rc scripts from
.Pa ${PKGDIR}
into
.Pa ${WRKINST} .
Run after
.Cm fake
and before
.Cm package
or
.Cm update-plist .
Always rerun, as it is cheap enough.
.It Cm index
Top-level target, see
.Xr ports 7 .
.It Cm install-depends
Before package installation, install and verify dependencies constructed from
.Ev RUN_DEPENDS , LIB_DEPENDS ,
and
.Ev WANTLIB .
.It Cm install
Install the package after building.
See the description of
.Sx THE FAKE FRAMEWORK
for the non-intuitive details of the way
.Cm {pre,do,post}-install
hooks are actually used by the ports tree.
.It Cm install-all
Install all packages in a multi-packages port.
.It Cm lib-depends-args
Filter
.Ev LIB_DEPENDS
to keep only entries required by
.Ev WANTLIB ,
and output a list of dependencies suitable for
.Xr pkg_create 1 ,
see
.Cm print-package-args .
.It Cm lib-depends-check
Verify that the
.Ev LIB_DEPENDS
and
.Ev WANTLIB
are accurate for the port.
See
.Cm port-lib-depends-check ,
which is quicker.
.It Cm license-check
Check that
.Ev PERMIT_PACKAGE_*
settings match:
if any dependency has a more restrictive setting, warn about it.
This warning is advisory, because the automated license checking cannot
figure out which ports were used only for building and did not taint
the current port.
.It Cm lock
Manually obtain a lock on a given directory.
Output must be used to update environment variables.
The lock can be released with
.Cm unlock .
Seldom used, see
.Xr ports 7
for details.
.It Cm makesum
Run
.Xr sha256 1
on ${MAKESUMFILES}
that is, files listed in ${DISTFILES}, ${SUPDISTFILES} and ${PATCHFILES},
and store the result in ${CHECKSUM_FILE}, normally
.Pa distinfo .
Also store the lengths of all files for a quick check during
.Cm fetch .
.It Cm no-lib-depends-args
Degenerate form of
.Cm lib-depends-args
that does not do anything.
See
.Cm print-package-args .
.It Cm no-wantlib-args
Degenerate form of
.Cm wantlib-args
that does not do anything.
See
.Cm print-package-args .
.It Cm package
Build a port package (or packages in a
.Ev MULTI_PACKAGES
case) from the fake installation.
Involves creating packaging information from templates
(see
.Ev COMMENT ,
.Ev SUBST_VARS
among others) and invoking
.Xr pkg_create 1
for each package in the
.Ev MULTI_PACKAGES
list.
If the repository already contains up-to-date packages, they are not rebuilt.
If PLIST_REPOSITORY is set, the resulting packaging information is compared
with existing stuff, and saved if new, with loud complaints if it changed
without a REVISION bump.
Arch-independent packages are created in ${PACKAGE_REPOSITORY}/no-arch,
and copied into ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/all as needed.
If ${PERMIT_PACKAGE_FTP} is set to
.Sq Yes ,
copies built packages into ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/ftp, using
hard links if possible.
If ${PERMIT_PACKAGE_CDROM} is set to
.Sq Yes ,
copies built packages into ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cdrom, using
hard links if possible.
.It Cm patch
Apply distribution and
.Ox
specific patches.
Because of historical accident,
.Cm patch
does not follow the exact same scheme other standard targets do.
Namely,
.Cm patch
invokes
.Cm pre-patch
(if defined),
.Cm do-patch ,
and
.Cm post-patch ,
but the default
.Cm do-patch
target invokes
.Cm distpatch
directly.
So, if the
.Cm do-patch
target is overridden, it should still begin by calling
.Ql make distpatch ,
before applying
.Ox
specific patches.
Accordingly, the exact sequence of hooks is:
.Cm pre-patch ,
.Cm do-distpatch ,
.Cm post-distpatch ,
.Cm do-patch ,
.Cm post-patch .
If
.Pa ${PATCHDIR}
exists, the files described under
.Ev PATCH_LIST
will be applied under
.Ev WRKDIST .
.It Cm peek-ftp
Connect to the first site in
.Ev MASTER_SITES ,
in the right directory, and leaves user at
.Xr ftp 1 Ns 's
prompt.
.It Cm pkglocatedb
Top-level target, see
.Xr ports 7 .
.It Cm port-lib-depends-check
Verify that the
.Ev LIB_DEPENDS
and
.Ev WANTLIB
hold all shared libraries used for every package in the port.
See
.Xr library-specs 7 .
This makes use of
.Cm print-plist-with-depends
to avoid actually building the packages, it only needs the
completion of the
.Cm fake
stage, and thus is quicker than
.Cm lib-depends-check ,
unless you already have all binary packages.
.It Cm port-wantlib-args
Resolve
.Ev WANTLIB
against the ports tree itself and system libraries, without looking at built
or installed packages, and writes a list of options suitable for
.Xr pkg_create 1 .
See
.Cm print-package-args .
.It Cm prepare
Before port building, install and verify dependencies constructed from
.Ev BUILD_DEPENDS ,
.Ev LIB_DEPENDS
and
.Ev WANTLIB .
In
.Ev MULTI_PACKAGES
setups,
see
.Sx FLAVORS AND MULTI_PACKAGES .
.It Cm print-package-args
Print all dependency-related information that will be passed as parameters
to
.Xr pkg_create 1 ,
e.g.,
.Fl W Ar wantlib
and
.Fl P Ar depends
lines.
.Pp
Those parameters are generated by
.Cm run-depends-args
for
.Ev RUN_DEPENDENCIES
handling, a form of
.Cm lib-depends-args
for
.Ev LIB_DEPENDS
and
.Ev WANTLIB
interaction,
and a form of
.Cm wantlib-args
for
.Ev WANTLIB
resolution.
.Pp
Variables
.Ev lib_depends_args
and
.Ev wantlib_args
control the exact behavior:
.Ev lib_depends_args
is normally set to
.Cm lib-depends-args ,
but will be set to
.Cm all-lib-depends-args
by
.Cm port-lib-depends-check ,
in order to have access to the full list of LIB_DEPENDS for figuring
out missing WANTLIB.
.Ev wantlib_args
is normally set to
.Cm wantlib-args
but it may be set to
.Cm port-wantlib-args
for introspection purposes,
to
.Cm fake-wantlib-args
to avoid some checks, or to
.Cm no-wantlib-args
to avoid expensive WANTLIB checks entirely.
.It Cm print-update-signature
Print the update signature, as computed using information from the ports tree,
in the same format used for
.Xr pkg_info 1
.Fl S .
.It Cm print-plist
Generate and print a package packing-list from the static information
present in the port.
.It Cm print-plist-all
Iterate over
.Cm print-plist
for all subpackages in a given port.
.It Cm print-plist-all-with-depends
Iterate over
.Cm print-plist-with-depends
for all subpackages in a given port.
.It Cm print-plist-contents
Generate and print package contents from the static information
present in the port.
In contrast with
.Cm print-plist ,
the package contents only consists of files, all tagged with category
markers such as @file.
See
.Xr pkg_create 1 .
.It Cm print-plist-libs
Generate and print the list of static and dynamic libraries present in the port.
See
.Xr pkg_create 1 .
.It Cm print-plist-libs-with-depends
Like
.Cm print-plist-libs ,
but slower.
It also handles
.Ev LIB_DEPENDS ,
.Ev RUN_DEPENDS ,
and
.Ev WANTLIB ,
so that the packing-list has complete dependency information.
.It Cm print-plist-with-depends
Like
.Cm print-plist ,
but slower.
It also handles
.Ev LIB_DEPENDS ,
.Ev RUN_DEPENDS ,
and
.Ev WANTLIB ,
so that the packing-list is complete.
.It Cm rebuild
Force rebuild of the port.
.It Cm regen
Force rebuilding configure scripts using
.Ar gen
steps.
.It Cm reinstall
Force reinstallation of a port, by first cleaning the old installation.
Seldom needed, as
.Cm update
will often do the right thing.
.It Cm repackage
Rebuild the packages of a port after removing existing packages.
.It Cm run-depends-args
Process
.Ev RUN_DEPENDS
and outputs a list of dependencies suitable for
.Xr pkg_create 1 ,
see
.Cm print-package-args .
.It Cm reprepare
Force running the
.Ar prepare
target
again.
.It Cm show
Invoked as make show=name, show the contents of ${name}.
Invoked as make show="name1 name2 ...",
show the contents of ${name1} ${name2} ...,
one variable value per line.
Mostly used from recursive makes, or to know the contents of another
port's variables without guessing wrongly.
.It Cm show-fake-size
Print the size of ${WRKINST}.
Used by some options of
.Xr dpb 1 ,
suitable for
.Ev BULK_TARGETS .
.It Cm show-indexed
Similar to
.Cm show .
Invoked as make show-indexed=name, show the contents of ${name${SUBPACKAGE}},
or ${name} if the variable
.Ev name
is not
.Ev SUBPACKAGE
dependent.
.It Cm show-prepare-results
Print the list of actual installed packages found out by
.Cm prepare .
.It Cm show-prepare-test-results
Print the list of actual installed packages found out by
.Cm prepare
and
.Cm test-depends .
.It Cm show-required-by
Print the list of
.Xr pkgpath 7
for all ports that will be affected by the
current port changing.
Works by walking the list of dependencies, in reverse.
.It Cm show-run-depends
Print all running dependencies for a port, one per-line, without duplicates.
.It Cm subpackage
Build a port package.
Exactly like
.Cm package ,
but affects only one single subpackage in multi-packages ports.
.It Cm show-size
Prints the size of the work directory.
Used by some options of
.Xr dpb 1 ,
suitable for
.Ev BULK_TARGETS .
.It Cm subupdate
Update an existing installation to a newer package, exactly
like
.Cm update ,
but affects only one single subpackage in multi-packages ports.
.It Cm test
Run regression tests for the port.
Essentially depend on a correct build and invoke
.Bd -literal
env -i ${ALL_TEST_ENV} ${MAKE_PROGRAM} ${ALL_TEST_FLAGS} \e
	-f ${MAKE_FILE} ${TEST_TARGET} ${TEST_LOG}
.Ed
.Pp
If a port needs some other ports installed to run regression tests,
use
.Ev TEST_DEPENDS .
If a port needs special configuration or build options to enable regression
testing, define a
.Sq test
.Ev FLAVOR .
.It Cm test-depends
Before running regression tests, Install and verify dependencies
constructed from
.Ev TEST_DEPENDS .
.It Cm unlock
Manually release a lock on a given directory.
See
.Cm lock .
.It Cm update-patches
Create or update patches for a port, using
.Xr update-patches 1 .
See
.Ev EDIT_PATCHES .
.It Cm update
Update an existing installation to a newer package:
scan the installation for a package with the same
.Ev FULLPKGPATH ,
and update it using
.Sq pkg_add -r
if a newer package is available.
In multi-packages ports, all relevant packages are updated.
See
.Ev UPDATE_COOKIES_DIR
and
.Ev FORCE_UPDATE
as well.
.It Cm update-or-install
Update an installed package or perform a fresh installation,
by using
.Sq pkg_add -r .
Handles one single package in multi-packages ports.
See
.Ev UPDATE_COOKIES_DIR
and
.Ev FORCE_UPDATE
as well.
.It Cm update-or-install-all
Update installed packages or perform a fresh installation,
by using
.Sq pkg_add -r .
Handles all packages in multi-packages ports.
See
.Ev UPDATE_COOKIES_DIR
and
.Ev FORCE_UPDATE
as well.
.It Cm update-plist
Update the packing lists for a port, using the fake installation and the
existing packing lists.
.Cm update-plist
should produce a mostly correct
.Pa PLIST
file, handling GNU
.Xr info 1
files, setuid files, and empty directories.
It moves an existing file to
.Pa PLIST.orig .
If the generated list includes files and directories that shouldn't be
included, comment these like this:
.Bd -literal
@comment unwanted-file
@comment unwanted-dir/
.Ed
.Pp
Subsequent calls to
.Cm update-plist
will automatically recognize and handle such lines correctly.
.Pp
.Cm update-plist
may not handle flavor and multi-packages situations correctly yet, so beware.
.It Cm verbose-show
Similar to
.Cm show ,
except that it prefixes each value with the variable name, e.g.,
.Li VAR=value .
Also note that it does not show undefined variables, contrary to
.Cm show
which outputs blank lines for these.
.It Cm wantlib-args
Call
.Cm port-wantlib-args
and
.Cm fake-wantlib-args
and compare the results, errors out in case of discrepancies.
See
.Cm print-package-args .
.El
.Sh VARIABLES
Note that some variables are marked as
.Sq User settings ,
which means that individual ports should not modify them,
and that some variables are marked as
.Sq read-only ,
which means that they shouldn't ever be changed.
In a
.Ev MULTI_PACKAGES
setup, some variables have settings specific to a given subpackage.
See
.Sx FLAVORS AND MULTI_PACKAGES .
.Bl -tag -width Ds
.It Ev show
Invoked as make show=name, show the contents of ${name}.
Invoked as make show="name1 name2 ...", show the contents of
${name1} ${name2} ...,
one variable value per line.
.It Ev ALL_FAKE_FLAGS
Flags passed to ${MAKE} invocations during the fake process.
Equals
.Li ${MAKE_FLAGS} ${DESTDIRNAME}=${WRKINST} ${FAKE_FLAGS} .
Read-only.
.It Ev ALL_TEST_ENV
Environment passed to test.
Equals
.Li ${MAKE_ENV} ${TEST_ENV} .
Read-only.
.It Ev ALL_TEST_FLAGS
Flags passed to ${MAKE} invocations during test.
Equals
.Li ${MAKE_FLAGS} ${TEST_FLAGS} .
Read-only.
.It Ev ALL_TARGET
Target used to build software.
Default is
.Sq all .
Can be set to empty, to yield a package's default target.
.It Ev APM_ARCHS
Set to the list of
.Xr apm 4
architectures.
Read-only.
Use with
.Ev ONLY_FOR_ARCHS .
.It Ev ARCH
Current machine architecture.
Read-only.
.It Ev AUTOCONF
Location of the autoconf binary if needed.
Defaults to autoconf (though autoreconf might be more appropriate).
.It Ev AUTOCONF_DIR
Where to invoke autoconf if ${CONFIGURE_STYLE} includes autoconf.
Defaults to ${WRKSRC}.
.\" AUTOCONF_DIR should probably be a list, and be renamed to AUTOCONF_DIRS ?
.It Ev AUTOCONF_ENV
Environment values that should be passed to all runs of autoconf, automake
and related tools.
Specifically, version numbers and PATH.
Automatically set as soon as
.Ev CONFIGURE_STYLE
is gnu or higher.
.It Ev AUTOCONF_VERSION
Starting with
.Ox 3.3 ,
several versions of autoconf may coexist peacefully.
The main autoconf script is a shell wrapper in the
.Pa devel/metaauto
package, and similarly for automake.
Setting
.Ev AUTOCONF_VERSION
along with
.Ev CONFIGURE_STYLE
set to autoconf is the correct way to specify which one to use.
.Ev AUTOCONF_VERSION
defaults to 2.13.
If autoconf must be run manually,
.Ev MODGNU_AUTOCONF_DEPENDS
can be used to specify what packages to depend upon.
.It Ev AUTOHEADER
Location of the autoheader binary.
Defaults to autoheader.
.It Ev AUTOMAKE_VERSION
Several versions of automake may coexist peacefully.
.Ev AUTOMAKE_VERSION
must be set before trying to run automake.
Defaults to 1.4.
Note that even if
.Ev CONFIGURE_STYLE
includes automake,
automake should still be run manually during the right
.Cm configure
stage.
.It Ev AUTOUPDATE
Location of the autoupdate binary.
Defaults to autoupdate.
.It Ev BASE_PKGPATH
Full
.Xr pkgpath 7
to the current port, taking flavors into account.
See also
.Ev BUILD_PKGPATH ,
which also includes pseudo-flavors.
Read-only.
.It Ev BASELOCALSTATEDIR
User settings.
Base location for system-wide state directory.
Defaults to
.Pa ${VARBASE} .
See
.Ev LOCALSTATEDIR .
.It Ev BASESYSCONFDIR
User settings.
Base location for system-wide configuration files.
Defaults to
.Pa /etc .
See
.Ev SYSCONFDIR .
.It Ev BATCH
User settings.
Set to
.Sq Yes
to avoid ports that require user-interaction.
Use in conjunction with
.Ev INTERACTIVE
to simplify bulk-package builds.
.Pq See IGNORE .
.It Ev BE_ARCHS
Set to the list of big-endian architectures.
Read-only.
Use with
.Ev NOT_FOR_ARCHS
and
.Ev ONLY_FOR_ARCHS .
.It Ev BUILD_DEPENDS
List of other ports the current port needs to build correctly.
Each item has the form
.Sq [pkgspec:]pkgpath[:target] .
.Sq target
defaults to
.Sq install .
The package installed must conform to the
.Sq pkgspec ,
which is by default obtained from the dependent
.Sq pkgpath
.Po
see
.Ev PKGSPEC
.Pc .
If no installation is involved, the infrastructure will still check
that the directory would provide a package conforming to the
.Sq pkgspec .
.Sq pkgpath
is set relative to ${PORTSDIR},
see
.Xr pkgpath 7
for details.
Build dependencies are checked before the
.Cm extract
stage during
.Cm prepare .
.Pp
Build dependencies with a
.Cm patch ,
.Cm configure
or
.Cm build
target will be processed in a subdirectory of the working directory,
specifically, in ${WRKDIR}/some/directory,
with
.Pa some/directory
the directory part of the
.Sq pkgpath .
.It Ev BUILD_ONCE
User settings.
Defaults to
.Sq \&No .
Set to
.Sq Yes
during bulk builds.
.Pp
When
.Ev BUILD_ONCE
is set to
.Sq Yes ,
all
.Ev PSEUDO_FLAVORS
matching
.Sq no_*
will be disabled, unless the special pseudo-flavor
.Sq bootstrap
is also set.
.Pp
This is a bulk build optimisation, automatically set by
.Xr dpb 1 :
to avoid rebuilding the same package several times, a full bulk build will
strip most ports of pseudo-packages variations that remove subpackages.
.Pp
For instance, an individual package may depend on
.Pa databases/db/v4,no_java,no_tcl ,
to avoid bringing a jdk in during a quick build.
Nevertheless, during a full bulk build,
.Pa databases/db/v4
will only be built once, as the pseudo-flavor will be automatically removed.
.Pp
However, the extra
.Sq bootstrap
rule is needed to take build cycles into account.
For instance, the
.Pa x11/gnome/gvfs,-goa
subpackage depends on gnome-online-accounts, which in turn requires
.Pa x11/gnome/gvfs,-main
to build (through its dependencies).
So
.Pa x11/gnome/gvfs
has
.Li PSEUDO_FLAVORS = no_smb no_goa bootstrap
and the GNOME build first builds
.Pa x11/gnome/gvfs,no_smb,no_goa,bootstrap,-main
which is later used to rebuild
.Pa x11/gnome/gvfs .
.It Ev BUILD_PKGPATH
Full
.Xr pkgpath 7
to the current port, taking flavors and pseudo-flavors
into account.
See also
.Ev BASE_PKGPATH ,
which doesn't include pseudo-flavors.
Mostly useful to write dependencies for subpackages like this:
.Li "LIB_DEPENDS-foo=${BUILD_PKGPATH}"
and avoid starting to build a package with some other flavor combination.
See
.Xr pkgpath 7
on the subject of
.Sq pkgpath normalisation .
Read-only.
.It Ev BUILD_PACKAGES
The actual list of packages that will be built, once architecture problems
and pseudo-flavors have been taken into account.
See
.Sx FLAVORS AND MULTI_PACKAGES .
.It Ev BROKEN
Define only for broken ports, set to reason the port is broken.
See also
.Ev NO_IGNORE ,
.Ev TRY_BROKEN .
.It Ev BUILD_USER
User to switch to when using
.Ev PORTS_PRIVSEP ,
defaults to
.Sq _pbuild .
.It Ev BROKEN-<arch>
Define only for ports broken on a given architecture.
Distinct from
.Ev ONLY_FOR_ARCHS
and
.Ev NOT_FOR_ARCHS ,
which are used to mark ports for which support for some architectures
does not exist at all, or is completely obsolete.
.It Ev BSD_INSTALL_{PROGRAM,SCRIPT,DATA,MAN}[_DIR]
Macros passed to make and configure invocations.
Set based on corresponding INSTALL_* variables.
.It Ev BULK
User settings.
If set to
.Sq Yes ,
all successful package builds and installations will clean
their working directories, after invoking
any targets mentioned in BULK_TARGETS,
and commands mentioned in BULK_DO.
Can be set on a per-${PKGPATH} basis.
For instance, setting BULK_misc/screen=No
will override any BULK=Yes passed on the command line.
If set to
.Sq Auto ,
it will apply to dependencies, but not to the current port itself.
See
.Ev BULK_COOKIES_DIR .
Defaults to
.Sq Auto .
.It Ev BULK_COOKIES_DIR
User settings.
Used to store cookies for successful bulk-package builds, defaults to
.Pa ${PORTSDIR}/bulk/${MACHINE_ARCH} .
.It Ev BULK_DO
Commands to run after each bulk package build before cleaning up the
working directory.
Empty defaults.
Can be set on a per-${PKGPATH} basis, e.g.,
BULK_DO_${PKGPATH}=...
.It Ev BULK_FLAGS
Flags to pass to build each target in
.Ev BULK_TARGETS .
.It Ev BULK_TARGETS
Targets to run after each bulk package build before cleaning up the
working directory.
Empty defaults.
Can be set on a per-${PKGPATH} basis, e.g.,
BULK_TARGETS_${PKGPATH}=...
.It Ev BZIP2
Name of the bzip2 binary.
.It Ev CATEGORIES
List of descriptive categories into which this port falls.
Mandatory.
One entry must match the current pkgpath:
.Pa devel/gmake
must belong to the
.Sq devel
category.
See
.Cm link-categories ,
.Cm unlink-categories .
.It Ev CCACHE_DIR
Sets the cache directory used when
.Ev USE_CCACHE
is set to yes.
Defaults to ${WRKOBJDIR}/.ccache.
.It Ev CCACHE_ENV
Sets additional environment variables when
.Ev USE_CCACHE
is set to yes.
For instance, to enable verbose logging, set
CCACHE_ENV="CCACHE_LOGFILE=/tmp/ccache.log"
.It Ev CDIAGFLAGS
Flags appended to
.Ev CFLAGS
if
.Ev WARNINGS
is set.
.It Ev CFLAGS
Default flags passed to the compiler for building.
Many ports ignore it.
See also
.Ev COPTS ,
.Ev CDIAGFLAGS .
.It Ev CHECK_LIB_DEPENDS
User settings.
If set to
.Sq Yes ,
every package build will verify that shared libraries are correctly
registered.
This is essentially the same as running
.Ql make lib-depends-check
after each package build.
Defaults to
.Sq \&No ,
as this can be a big performance hit.
.It Ev CHECKSUMFILES
List of all files that need to be retrieved by
.Cm fetch ,
with
.Ev DIST_SUBDIR
prepended and with the master site selection extension removed.
Read-only.
See also
.Ev MAKESUMFILES .
.It Ev CHECKSUM_FILE
Location for this port's checksums, used by
.Cm checksum ,
and
.Cm makesum .
Defaults to
.Pa distinfo .
.It Ev CHECKSUM_PACKAGES
User settings.
Choose whether or not to checksum packages while building.
Deposits result in
.Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cksums/${FULLPKGNAME}.sha256 .
Can be set to
.Sq Yes
to compute a checksum for all packages,
.Sq cdrom
to compute it only for
.Ev PERMIT_PACKAGE_CDROM
packages
or to
.Sq ftp
to compute it only for
.Ev PERMIT_PACKAGE_FTP
packages.
Defaults to
.Sq no ,
which does not compute a checksum at all.
.It Ev CHOSEN_COMPILER
Read-only.
Compiler suite chosen by the
.Ev COMPILER
mechanism.
Set to
.Sq irrelevant
to disable
.Ev COMPILER .
.It Ev CLEANDEPENDS
If set to
.Sq Yes ,
the
.Cm clean
target will also clean dependencies.
Can be overridden on a per-${PKGPATH} basis,
by setting CLEANDEPENDS_${PKGPATH}.
.It Ev COMMENT
Short (no more than 60 characters) description of the port, used for
the package and the INDEX.
It should not start with an uppercase letter unless semantically
significant.
.It Ev COMMENT-foo
Same as COMMENT but used for sub package -foo in a multi-package setup.
.It Ev COMMENT-vanilla
Same as COMMENT but used for a flavored package, if the non-flavored comment
is inappropriate.
.It Ev COMMENT-foo-vanilla
Same as COMMENT but used for a sub-, flavored package.
.It Ev COMES_WITH
The first release where the port was made part of the standard
distribution.
If the current
.Ox
version is >= this version then a notice
will be displayed instead of the port being built.
.It Ev COMPILER
Select preferred compiler.
First element in the list that matches will be chosen.
.Bl -tag -width ports-gccxx
.It base-gcc
gcc 4.2 compiler from base
.It base-clang
clang compiler from base
.It gcc3
gcc 3 compiler from base
.It ports-gcc
gcc 4.9 compiler from ports
(heeds
.Ev MODGCC4_ARCHS
from the module)
.It ports-clang
clang compiler from ports
(heeds
.Ev MODCLANG_ARCHS
from the module)
.El
.Pp
The first compiler that matches criteria will be chosen.
On clang-based architectures, even though gcc is still compiled in base,
.Sq base-gcc
never matches.
.Pp
Defaults to base compilers, e.g.,
.Sq base-clang base-gcc gcc3 .
.Pp
Common reasons for explicitly setting
.Ev COMPILER
will most often be C++11 support, thread-local-storage support (emulated),
atomic operations on some arches, sometimes assembler support, ABI
compatibility with dependent/depending ports, or plain old internal compiler
errors.
.Pp
With
.Ev COMPILER
in effect,
.Ev MODGCC4_ARCHS
and
.Ev MODCLANG_ARCHS
default to
.Sq ${GCC49_ARCHS}
and
.Sq ${LLVM_ARCHS}
respectively.
.Pp
.Ev ONLY_FOR_ARCHS
will also be set if applicable.
.It Ev COMPILER_LANGS
The value of
.Ev COMPILER_LANGS
will be added to the respective module's supported langs.
Defaults to
.Sq c c++ .
Only
.Sq c
and
.Sq c++
are supported by this mechanism.
.Sq fortran
or
.Sq java
still need old modules annotations, so that it's possible
to select, e.g.,
.Sq gfortran
from gcc 4.9 while having clang from base.
See also
.Ev CHOSEN_COMPILER .
.It Ev COMPILER_LINKS
Used by
.Nm
and compiler
.Ev MODULES
to build scripts in
.Pa ${WRKDIR}/bin
to force setting compiler flags
.Po
.Fl B
is required for clang to find
.Pa ${WRKDIR}/bin/ld
as used by
.Ev USE_WXNEEDED
.Pc
and call
.Ev COMPILER_WRAPPER
if used.
.It Ev COMPILER_WRAPPER
External program used to "wrap" compilers.
Populated automatically by
.Ev USE_CCACHE
or can be set explicitly for other purposes (e.g. distcc).
.It Ev CONFIG_SITE_LIST
Used when
.Li CONFIGURE_STYLE=gnu ,
or with
.Li MODULES += gnu .
List of
.Pa config.site
fragments that will speed up gnu-configure, and prevent it from
preferring various gnu programs, unless
.Ev BUILD_DEPENDS
explicitly ask for them.
Read-only, available for debugging purposes.
.It Ev CLANG_ARCHS, GCC3_ARCHS , GCC4_ARCHS
List of architectures using Clang, GCC 3.3.6 or GCC 4.2.1 as the base compiler.
Read-only.
Use with
.Ev NOT_FOR_ARCHS
or
.Ev ONLY_FOR_ARCHS
to limit ports to architectures where they compile.
.It Ev CONFIGURE_ARGS
Arguments to pass to configure script.
Defaults are empty, except for
GNU-style configure, where prefix and sysconfdir are set.
.It Ev CONFIGURE_ENV
Basic environment passed to configure script (path and libtool setup).
GNU-style configure adds a lot more variables.
.It Ev CONFIGURE_SCRIPT
Set to name of script invoked by the
.Cm configure
target, if appropriate.
Should be either an absolute path, or relative to ${WRKSRC}.
.It Ev CONFIGURE_STYLE
Set to style of configuration that needs to happen.
.Pp
If
.Sq perl ,
assume
.Xr perl 1 Ns 's
.Xr ExtUtils::MakeMaker 3p
style.
Add
.Sq modbuild
to enable
.Xr Module::Build 3p ,
.Sq modbuild tiny
to enable
.Xr Module::Build::Tiny 3p ,
or
.Sq modinst
for
.Xr Module::Install 3p
style.
.Pp
If
.Sq gnu ,
assume
GNU configure style.
Add
.Sq dest
if port does not handle DESTDIR correctly, and needs to be configured to
add DESTDIR to prefixes
.Po
see also
.Ev DESTDIRNAME
.Pc .
Add
.Sq old
if port is an older autoconf port that does not recognize --sysconfdir.
Add
.Sq autoconf
if autoconf needs to be rerun first,
but set
.Sq no-autoheader
to prevent autoheader from running.
Add
.Sq automake
if automake may need to be rerun.
Otherwise, automake will be explicitly disabled.
Note that automake is never run automatically.
In order to use it,
.Ev CONFIGURE_STYLE
should include
.Sq automake
and there should be a
.Cm {pre,do}-configure
target running automake.
.Pp
If
.Sq imake ,
assume port configures using X11 ports Imakefile framework.
Add
.Sq noman
if port has no man pages the Imakefile should try installing.
.Pp
If
.Sq simple ,
there is a configure script, but it does not fit the normal GNU configure
conventions.
.Pp
Extensions may be defined by specific MODULES.
See
.Xr port-modules 5
for details.
.It Ev COPTS
User settings.
Supplementary options appended to ${CFLAGS} for building.
Since most ports ignore the COPTS convention, they are actually told to use
${CFLAGS} ${COPTS} as CFLAGS.
.It Ev CXXDIAGFLAGS
Flags appended to
.Ev CXXFLAGS
if
.Ev WARNINGS
is set.
.It Ev CXXFLAGS
Default flags passed to the C++ compiler for building.
Many ports ignore it.
.It Ev CXXOPTS
User settings.
Supplementary options appended to ${CXXFLAGS} for building.
.It Ev DESTDIR
See
.Ev DESTDIRNAME .
.It Ev DESTDIRNAME
Name of variable to set to ${WRKINST} while faking.
Usually DESTDIR.
To be used in the rare cases where a port heeds DESTDIR in a few
directories and needs to be configured with
.Sq gnu dest ,
so that those few directories do not get in the way.
.It Ev DISTDIR
User settings.
Directory where all ports distribution files and patchfiles are stashed.
Defaults to
.Pa ${PORTSDIR}/distfiles .
Override if distribution files are stored elsewhere.
Always use
.Ev FULLDISTDIR
to refer to ports' distribution files location, as it takes an eventual
.Ev DIST_SUBDIR
into account.
.It Ev DISTFILES
The main port's distribution files (the actual software source, except
for binary-only ports).
Will be retrieved from the MASTER_SITES (see
.Cm fetch ) ,
checksummed and extracted (see
.Cm checksum ,
.Cm extract ) .
.Ev DISTFILES
normally holds a list of files, possibly with
.Sq :0
to
.Sq :9
appended to select a different
.Ev MASTER_SITES .
.Pp
Each entry may optionally be of the form
.Sq Ar filename Ns { Ns Ar url Ns } Ns Ar sufx
to deal with sites that only offer archives as weird urls, doing the transfer
of
.Ar url Ns Ar sufx
into result file
.Ar filename Ns Ar sufx .
For instance, if
.Bd -literal
DISTFILES = minetest-{minetest/archive/}${V}${EXTRACT_SUFX}
.Ed
.Pp
then
.Cm fetch
will retrieve from url
.Sq minetest/archive/${V}${EXTRACT_SUFX}
into
.Sq minetest-${V}${EXTRACT_SUFX} .
.Pp
If ${DISTFILES} varies depending on
.Ev FLAVORS
or architecture, use
.Ev SUPDISTFILES
to ensure distfiles mirroring and
.Cm makesum
proper operation.
.It Ev DISTNAME
Name used to identify the port.
See
.Ev DISTFILES
and
.Ev PKGNAME .
.It Ev DISTORIG
Suffix used by
.Cm distpatch
to rename original files.
Defaults to
.Pa .bak.orig .
Distinct from
.Pa .orig
to avoid confusing
.Cm update-patches .
.It Ev DIST_SUBDIR
Optional subdirectory of ${DISTDIR} where the current port's distribution
files and patchfiles will be located.
See target
.Cm fetch .
.It Ev DPB
Set by the Distributed Ports Builder to only get the information it needs
from
.Cm dump-vars .
.It Ev DPB_PROPERTIES
Annotations for the Distributed Ports Builder.
See
.Xr dpb 1
for semantics.
.It Ev DUMMY_PACKAGE
If defined,
.Nm
will provide dummy values for variables mandatory for a minimally functional
port.
Used by various pieces of the ports tree to perform introspection and get to
.Nm Ns 's
variables.
.It Ev ECHO_MSG
User settings.
Used to display
.Sq ===> Configuring for foo
and similar informative messages.
Override to turn off, for instance.
.It Ev ECHO_REORDER
User settings.
Set it to
.Sq echo
to see
.Ev REORDER_DEPENDENCIES
actions.
Silent by default.
.It Ev EDIT_PATCHES
User settings.
If set to
.Sq \&No ,
.Cm update-patches
will not open changed files in an editor.
.It Ev EPOCH
Epoch number of the current package.
Defaults to empty (no need for numbering changes), then
numbering starts at 0.
Gets automatically incorporated into
.Ev FULLPKGNAME
as
.Sq v${EPOCH}
to form a full package-name conforming to
.Xr packages-specs 7 .
.It Ev ERRORS
List of errors found while parsing the port's Makefile.
Display the errors before making any target, and if any error starts with
.Qq Fatal: ,
do not make anything.
For instance:
.Bd -literal -offset indent
\&.if !defined(COMMENT)
ERRORS+="Fatal: Missing comment"
\&.endif
.Ed
Porter can add to
.Ev ERRORS ,
for instance to flag erroneous combinations of
.Ev FLAVORS
(but see
.Ev ONLY_FOR_ARCHS
.Ev NOT_FOR_ARCHS
and
.Ev BROKEN
for other common issues).
.It Ev EXTRACT_CASES
In the normal extraction stage (when
.Ev EXTRACT_ONLY
is not empty), this is the contents of a case statement, used to extract files.
Fragments are automatically appended to extract tar, xz and zip
archives, so that the default case is more or less equivalent to the
following shell fragment:
.Bd -literal
set -e
cd ${WRKDIR}
for archive in ${EXTRACT_ONLY}
do
    case $$archive in
	*.tar.xz|*.tar.lzma)
	  xzcat ${FULLDISTDIR}/$$archive| tar xf -;;
	*.tar.lz)
	  lunzip -c ${FULLDISTDIR}/$$archive| tar xf -;;
	*.zip)
	  unzip -q ${FULLDISTDIR}/$$archive -d ${WRKDIR};;
	*.tar.bz2|*.tbz2|*.tbz)
	  bzip2 -dc ${FULLDISTDIR}/$$archive| tar xf -;;
	*.shar.gz|*.shar.Z|*.sh.Z|*.sh.gz)
	  gzcat ${FULLDISTDIR}/$$archive | /bin/sh;;
	*.shar|*.sh)
	  /bin/sh ${FULLDISTDIR}/$$archive;;
	*.tar)
	  tar xf ${FULLDISTDIR}/$$archive;;
	*)
	  gzip -dc ${FULLDISTDIR}/$$archive | tar xf -;;
    esac
done
.Ed
.It Ev EXTRACT_ONLY
Set to the list of distfiles to actually extract if some distfiles
should not be extracted during the
.Cm do-extract
stage.
Defaults to all distfiles, can even be set to empty.
.It Ev EXTRACT_SUFX
Used to set DISTFILES default value to ${DISTNAME}${EXTRACT_SUFX}.
The decompression tool needed will be automatically added as
.Ev BUILD_DEPENDS .
Default value is .tar.gz.
.It Ev FAKE_FLAGS
Extra flags passed to ${MAKE_PROGRAM} during the
fake invocation.
Empty by default.
Also see
.Ev ALL_FAKE_FLAGS .
.It Ev FAKE_SETUP
List of environment values normally set during fake invocations.
Exposed so that modules may provide their own
.Cm do-install .
Read-only,
see
.Sx THE FAKE FRAMEWORK
section for details.
.It Ev FAKE_TARGET
Target built by ${MAKE_PROGRAM} on fake invocation.
Defaults to ${INSTALL_TARGET}.
.It Ev FAKEOBJDIR
User settings.
If non empty, used as a base for the fake area.
The real fake directory ${WRKINST} is created there.
Can be set on a per-${PKGPATH} basis.
For instance, setting FAKEOBJDIR_www/mozilla=/tmp/obj
will affect only the mozilla port.
.It Ev FETCH_CMD
User settings.
Command used to fetch distribution files for this port.
Defaults to
.Xr ftp 1 .
Can be used to go through excessively paranoid firewalls.
Note that
.Ev FETCH_CMD
should support
.Fl C
and
.Fl o Ar dest .
.It Ev FETCH_MANUALLY
Some ports' distfiles cannot be fetched automatically for licensing reasons.
In this case, set
.Ev FETCH_MANUALLY
to a list of strings that will be displayed, one per line, e.g.,
.Bd -literal
FETCH_MANUALLY= "You must fetch foo-1.0.tgz"
FETCH_MANUALLY+="from http://www.fubar.com/ manually,"
FETCH_MANUALLY+="after reading and agreeing to the license."
.Ed
Behaves like
.Ev IS_INTERACTIVE
if some distribution files are missing.
.It Ev FETCH_PACKAGES
User settings, defaults to
.Sq \&No .
Set to
.Xr pkg_add 1
options.
Instruct the
.Cm package
target to download packages missing from the repository from locations in
${PKG_PATH} and place them into
.Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cache/ ,
only building them if no suitable packages are found.
For instance,
.Bd -literal -offset indent
make FETCH_PACKAGES=
.Ed
.Pp
to use without any options, or
.Bd -literal -offset indent
make FETCH_PACKAGES=-Dsnap
.Ed
.Pp
to use close to release.
.It Ev FILESDIR
Location of other files related to the current port.
Default: files.
.It Ev FETCH_USER
User to use to fetch distfiles when using
.Ev PORTS_PRIVSEP ,
defaults to
.Sq _pfetch .
.It Ev FIX_EXTRACT_PERMISSIONS
If
.Sq Yes ,
restore contents of
.Pa ${WRKDIR}
to world-readable at the end of
.Cm extract .
Used for some distfile contents which have paranoid permissions for no reason.
Defaults to
.Sq \&No .
.It Ev FLAVOR
The port's current options.
Set by the user, and tested by the port to activate wanted functionalities.
.It Ev FLAVORS
List of all flavors keywords a port may match.
Used to sort
.Ev FLAVOR
into a canonical order to build the package name,
or to select the packing-list, and as a quick validity check.
See also
.Ev PSEUDO_FLAVORS .
.It Ev FLAVOR_EXT
Canonical list of flavors being set for the current build, dash-separated.
See
.Ev FULLPKGNAME .
.It Ev FORCE_UPDATE
User settings.
If set to
.Sq Yes ,
the
.Cm update
target will always update an installed package,
as soon as its signature differs,
and all dependencies that install packages will
also force an update.
If set to
.Sq hard ,
the
.Cm update
target will also update installed packages even when the signature
did not change.
.It Ev FULLDISTDIR
Complete path to directory where ${DISTFILES} and ${PATCHFILES} will be
located, to be used in hand-crafted extraction targets.
Read-only.
.It Ev FULLPKGNAME
Full name of the created package, taking flavors into account.
Defaults to ${PKGNAME}${FLAVOR_EXT}.
See also
.Ev EPOCH
and
.Ev REVISION .
.It Ev FULLPKGPATH
Path to the current port's directory, relative to ${PORTSDIR},
including flavors and subpackages.
See
.Xr pkgpath 7 .
.It Ev GH_*
Support for GitHub-hosted projects.
Leave empty for non hosted projects.
Yields a suitable default for
.Ev MASTER_SITES_GITHUB
and
.Ev DISTNAME .
.It Ev GH_ACCOUNT
Account name of the GitHub user hosting the project.
.It Ev GH_COMMIT
SHA1 commit id to fetch.
It is an error to specify ${GH_COMMIT} when ${GH_TAGNAME} is specified.
.It Ev GH_PROJECT
Name of the project on GitHub.
.It Ev GH_TAGNAME
Name of the tag to download.
Setting ${GH_TAGNAME} to master is invalid
and will throw an error.
${WRKDIST} is auto-generated based on the
${GH_TAGNAME} if specified, otherwise ${GH_COMMIT} will be used to generate
${WRKDIST}.
.It Ev GMAKE
Location of the GNU make binary, if needed.
Defaults to gmake.
.It Ev HOMEPAGE
URL to the homepage of the software, if applicable.
.It Ev IGNORE
For ignored ports, set to the reasons for which the port is ignored.
If non-empty, most common targets that do something (e.g.,
.Cm fetch ,
.Cm build ,
.Cm install No ... )
will be ignored.
See also
.Ev BATCH ,
.Ev BROKEN ,
.Ev FETCH_MANUALLY ,
.Ev IGNORE_IS_FATAL ,
.Ev IGNORE_SILENT ,
.Ev INTERACTIVE ,
.Ev IS_INTERACTIVE ,
.Ev NOT_FOR_ARCHS ,
.Ev NO_IGNORE ,
.Ev ONLY_FOR_ARCHS .
.It Ev IGNORE_IS_FATAL
User settings.
If set to
.Sq Yes ,
ignored ports will become fatal errors.
.It Ev IGNORE_SILENT
User settings.
If set to
.Sq Yes ,
do not print anything when ignoring a port.
.It Ev INSTALL_{PROGRAM,SCRIPT,DATA,MAN}[_DIR]
Macros to use to install a program, a script, data, or a man page (or the
corresponding directory), respectively.
.It Ev INSTALL_TARGET
Target invoked to install the software, during fake installation.
Default is
.Sq install .
.It Ev INTERACTIVE
User settings.
Set to
.Sq Yes
to skip all non-interactive ports.
Used in conjunction with
.Ev BATCH
to simplify bulk-package builds.
.It Ev IS_INTERACTIVE
Set to
.Sq Yes
if port needs human interaction to build.
Porters should strive to minimize
.Ev IS_INTERACTIVE
ports, by using
.Ev FLAVORS
for multiple choice ports, and by postponing human intervention
to package installation time.
.It Ev LE_ARCHS
Set to the list of little-endian architectures.
Read-only.
Use with
.Ev NOT_FOR_ARCHS
and
.Ev ONLY_FOR_ARCHS .
.It Ev LIB_DEPENDS
List of packages used by a port for its library dependencies.
Each item has the form
.Sq [pkgspec:]pkgpath .
Similar to
.Ev BUILD_DEPENDS
and
.Ev RUN_DEPENDS ,
but with specific rules:
.Ev LIB_DEPENDS
always turn into
.Ev BUILD_DEPENDS
.Po
but see
.Sx FLAVORS AND MULTI PACKAGES
.Pc .
.Pp
.Ev LIB_DEPENDS
is also used as a run-time dependency, and recorded in the package as
such, if any of the libraries mentioned in
.Ev WANTLIB
is a shared library that originates within the dependent port.
.Pp
See
.Xr library-specs 7
for more details.
.It Ev lib_depends_args
Controls the behavior of
.Xr pkg_create 1
related targets, see
.Cm print-package-args
for details.
.It Ev LIBCXX
List of standard C++ libraries for the base compiler.
Read-only.
Use in
.Ev WANTLIB .
.It Ev LIBTOOL
Location of the libtool binary.
Default:
.Pa /usr/bin/libtool .
.It Ev LIBTOOL_FLAGS
Arguments to pass to libtool.
If USE_LIBTOOL is set, the environment variable LIBTOOL is set
to ${LIBTOOL} ${LIBTOOL_FLAGS}.
.It Ev LLVM_ARCHS
Set to the list of architectures where LLVM/Clang could be used,
e.g., via lang/clang port module, see
.Xr port-modules 5 .
Read-only.
Use with
.Ev NOT_FOR_ARCHS
or
.Ev ONLY_FOR_ARCHS .
.It Ev LOCALBASE
where other ports have already been installed.
Default:
.Pa /usr/local .
.It Ev LOCALSTATEDIR
Location for this port's state directory, should always be derived
from
.Ev BASELOCALSTATEDIR ,
which defaults to
.Pa /var .
Passed to gnu configure scripts.
.It Ev LOCKDIR
User settings.
Defaults to
.Pa ${WRKOBJDIR}/locks .
If set, points to a local directory common for all instances of
concurrent ports builds.
.It Ev LOCK_CMD
Expands to a command that will acquire a lock, namely
.Xr portlock 1 .
See also
.Xr ports 7 .
.It Ev LOCK_VERBOSE
User settings.
Defaults to
.Sq \&No .
Set to
.Sq Yes
to show every acquire/release lock operation.
.It Ev LP64_ARCHS
Set to the list of 64-bit architectures.
Read-only.
Use with
.Ev NOT_FOR_ARCHS .
.It Ev MAINTAINER
Email address with full name of the port's maintainer.
Defaults to
.Mt ports@openbsd.org .
.It Ev MAKE_ENV
Environment variables passed to make invocations and tests.
Sets at least PATH, PREFIX, LOCALBASE, X11BASE, CFLAGS, TRUEPREFIX, DESTDIR,
and the BSD_INSTALL_* macros.
.It Ev MAKE_FLAGS
Flags used for all make invocations, except for the
.Cm fake
stage, which adds
.Ev FAKE_FLAGS
(see
.Ev ALL_FAKE_FLAGS )
and for the
.Cm test
stage, which adds
.Ev TEST_FLAGS
(see
.Ev ALL_TEST_FLAGS ) .
.It Ev MAKE_FILE
Name of the Makefile used for ports building.
Defaults to Makefile.
Used after changing directory to ${WRKBUILD}.
.It Ev MAKE_PROGRAM
The make program that is used for building the port.
Set to ${MAKE} or ${GMAKE} depending on USE_GMAKE.
Read-only.
.It Ev MAKEFILE_LIST
Introspection variable, see
.Xr make 1 .
.It Ev MAKESUMFILES
List of all files that need to be retrieved by
.Cm fetch-all ,
with
.Ev DIST_SUBDIR
prepended and with master site selection extension removed.
Read-only.
See also
.Ev CHECKSUMFILES .
.It Ev MASTER_SITE_BACKUP
User settings.
List of sites to try after normal master sites.
Normally includes ${MASTER_SITE_OPENBSD} and ${MASTER_SITE_FREEBSD}.
.It Ev MASTER_SITE_*
Lists of standard sites to retrieve files from, refer to
.Pa ${PORTSDIR}/infrastructure/db/network.conf .
.It Ev MASTER_SITES
List of primary locations from which distribution files and patchfiles are
retrieved.
See the
.Cm fetch
target for details.
Defaults to ${MASTER_SITES_GITHUB} for GitHub-hosted projects,
see
.Ev GH_* .
See
.Xr ports 7
for user configuration.
.It Ev MASTER_SITES0 , ... , MASTER_SITES9
Supplementary locations from which distribution files and patchfiles are
retrieved.
.It Ev MESSAGE
File recorded in the package and displayed during installation.
Defaults to ${PKGDIR}/MESSAGE if this file exists.
Leave empty if no message is needed.
.It Ev MISSING_FILES
When
.Ev FETCH_MANUALLY
is set,
.Ev MISSING_FILES
will contain the list of missing distfiles or patchfiles that need to
be fetched manually.
Read-only.
.It Ev MTREE_FILE
.Xr mtree 8
specification used during
.Ar fake .
Replaced by direct use of
.Xr mkdir 1
now that
.Ar fake
no longer happens as root.
.It Ev MODGNU_CONFIG_GUESS_DIRS
If a port uses config.guess outside WRKSRC, the directories
containing the other copies must be set here.
.It Ev MODPERL_ADJ_FILES
If any files have a Perl shebang line, which needs to be replaced
with
.Dq #!/usr/bin/perl ,
list them in
.Ev MODPERL_ADJ_FILES .
File paths here should be relative to
.Ev WRKSRC .
These files are patched automatically at the end of
.Cm pre-configure .
.It Ev MODPERL_BIN_ADJ
Shell fragment to patch the Perl interpreter path in executable scripts.
Used by
.Ev MODPERL_ADJ_FILES .
.It Ev MODPERL_BUILD_TARGET
Normal content of
.Cm do-build
when
.Ev CONFIGURE_STYLE
uses perl.
Provided as a separate variable if a port wants to override
.Cm do-build
for its own reasons.
.It Ev MODPERL_INSTALL_TARGET
Likewise for
.Cm do-install .
.It Ev MODPERL_TEST_TARGET
Likewise for
.Cm do-test .
.It Ev MODULES
External modules mechanism, documented separately.
Modules such as
.Sq imake
and
.Sq gnu
are normally included automatically with the right
.Ev CONFIGURE_STYLE .
Note that it is possible to
.Li CONFIGURE_STYLE = simple ,
.Li MODULES += gnu
to just get the effects of
.Ev CONFIG_SITE
and
.Ev MODGNU_CONFIG_GUESS_DIRS
along with the default
.Ev TEST_TARGET ,
in case the normal GNU configure script was wrapped in a separate script that
takes different arguments.
See
.Xr port-modules 5 .
.It Ev MULTI_PACKAGES
Set to a list of subpackage extensions for ports that create multiple packages.
See
.Sx FLAVORS AND MULTI_PACKAGES
below.
Especially read the part about
.Ev ONLY_FOR_ARCHS
when some of the packages only exist for some architectures.
.It NO_ARCH
Location for arch-independent packages.
Defaults to
.Sq no-arch .
Normally, packages are generated under ${PACKAGE_REPOSITORY}/${MACHINE_ARCH},
except for packages where PKG_ARCH=*, which end up under
${PACKAGE_REPOSITORY}/${NO_ARCH}.
.It Ev NOT_FOR_ARCHS
List of architectures on which this port does not build.
See also
.Ev ONLY_FOR_ARCHS .
.It Ev NO_BUILD
Set to
.Sq Yes
if port does not need any build stage.
.It Ev NO_CCACHE
Set to
.Sq Yes
to prevent ccache from being used when building a certain port,
even when
.Ev USE_CCACHE
is set.
.It Ev NO_CHECKSUM
Set to
.Sq Yes
by
.Xr dpb 1
to avoid
.Cm checksum
entirely,
as
.Xr dpb 1
already deals with checksums internally.
.It Ev NO_DEPENDS
User settings.
Don't verify build of dependencies.
Do not use in any ports Makefile.
This is only meant as a user convenience when, e.g., you just want to browse
through a given port's source and do not wish to trigger the build of
dependencies.
.It Ev NO_IGNORE
User settings.
If set to
.Sq Yes ,
avoid ignoring a port for the usual reasons.
Use, for instance, for fetching all distribution files, or for fixing a
broken port.
See also
.Ev IGNORE
and
.Ev TRY_BROKEN .
.It Ev NO_TEST
Port does not have any regression tests.
Only set to
.Sq Yes
for ports with no regression test.
It should be left alone for ports with empty regression tests, and for
ports with failing tests.
That way, if a subsequent update of a port acquires actual regression tests,
they will be picked up automatically.
.It Ev ONLY_FOR_ARCHS
List of architectures on which this port builds.
Can hold both processor-specific information (e.g., powerpc), and more
specific model information (e.g., macppc).
This is subpackage dependent.
Read the corresponding part of
.Sx FLAVORS AND MULTI_PACKAGES
if some subpackages should only be built on some architectures.
.It Ev OSREV
Revision number of
.Ox .
Read-only.
.It Ev PACKAGE_REPOSITORY
User settings.
Location for built packages.
Defaults to
.Pa ${PORTSDIR}/packages .
See
.Cm package
for details.
.It Ev PATCH
Command to use to apply all patches.
Defaults to
.Pa /usr/bin/patch .
.It Ev PATCHORIG
Suffix used by
.Cm patch
to rename original files, and
.Cm update-patches
to re-generate
.Pa ${PATCHDIR}/${PATCH_LIST}
by looking for files using this suffix.
Defaults to
.Pa .orig .
For a port that already contains
.Pa .orig
files in the ${DISTFILES},
set this to something else, such as
.Pa .pat.orig .
See also
.Cm distpatch ,
.Ev DISTORIG .
.It Ev PATCH_CASES
In the normal
.Cm distpatch
stage (when
.Ev PATCHFILES
is not empty), this is the contents of a case statement, used to apply
distribution patches.
Fragments are automatically appended to handle gzip'ed, bzip'ed and lzip'ed
patches, so that the default case is more or less equivalent to the following
shell fragment:
.Bd -literal
set -e
cd ${FULLDISTDIR}
for patchfile in ${_LIST_PATCHFILES}
do
    case $$patchfile in
	*.bz2)
	  bzip2 -dc $$patchfile | ${PATCH} ${PATCH_DIST_ARGS};;
	*.lz)
	  lunzip -c $$patchfile | ${PATCH} ${PATCH_DIST_ARGS};;
	*.Z|*.gz)
	  gzcat $$patchfile | ${PATCH} ${PATCH_DIST_ARGS};;
	*)
	  ${PATCH} ${PATCH_DIST_ARGS} <$$patchfile;;
    esac
done
.Ed
.It Ev PATCHDIR
Location for patches applied by the
.Cm patch
target.
Default:
.Pa patches .
.It Ev PATCHFILES
Files to fetch from the master sites like
.Ev DISTFILES ,
but serving a different purpose, as they hold distribution patches that
will be applied at the
.Cm patch
stage.
See also
.Ev SUPDISTFILES .
.It Ev PATCH_ARGS
Full list of options used while applying port's patches.
.It Ev PATCH_CHECK_ONLY
Set to
.Sq Yes
by the
.Cm checkpatch
target.
Don't touch unless the default
.Cm checkpatch
target needs to be redefined.
Ideally, user-defined patch subtargets ought to test checkpatch.
In practice, they don't.
.It Ev PATCH_DEBUG
If set to
.Sq Yes ,
the
.Cm patch
stage will output extra debug information.
This is the default.
.It Ev PATCH_DIST_ARGS
Full list of options used while applying distribution patches.
.It Ev PATCH_DIST_STRIP
Patch option used to strip directory levels while applying distribution
patches.
Defaults to -p0 .
.It Ev PATCH_LIST
Wildcard pattern of patches to select under ${PATCHDIR}.
Defaults to patch-*.
Note that filenames ending in .orig, or ~ are never applied.
Note that
.Ev PATCH_LIST
can hold absolute pathnames, for instance to share patches among similar
ports:
.Bd -literal
PATCH_LIST=${PORTSDIR}/x11/kde/libs2/patches/p-* patch-*
.Ed
.It Ev PATCH_STRIP
Patch option used to strip directory levels while applying port's patches.
Defaults to -p0 .
.It Ev PERMIT_DISTFILES_FTP , PERMIT_PACKAGE_CDROM , PERMIT_PACKAGE_FTP
Set to
.Sq Yes
if package or distribution files can be allowed on FTP sites or CD-ROM without
legal issues.
Set to reason not to otherwise.
PERMIT_* lines in the Makefile should be preceded with a comment explaining
details about licensing and patents issues the port may have.
Porters must be very thorough in their checks.
In case of doubt, ask.
.Pp
If
.Ev PERMIT_PACKAGE_CDROM
is set to
.Sq Yes ,
.Ev PERMIT_PACKAGE_FTP
and
.Ev PERMIT_DISTFILES_FTP
will default to
.Sq Yes .
.Pp
If
.Ev PERMIT_PACKAGE_FTP
is set to
.Sq Yes ,
.Ev PERMIT_DISTFILES_FTP
will default to
.Sq Yes .
.It Ev PKG_ADD
User settings.
Path to
.Xr pkg_add 1
command, with possible options.
.It Ev PKG_ARCH
Comma-separated list of architectures on which this package may install.
Defaults to ${MACHINE_ARCH},${ARCH}.
Use * for arch-independent packages.
.It Ev PKG_ARGS
Special arguments to pass to
.Xr pkg_create 1 ,
in addition to the default ones.
For mips64 and pic libraries, see
.Sx THE GENERATION OF PACKAGE INFORMATION .
.It Ev PKG_CREATE
User settings.
Path to
.Xr pkg_create 1
command, with possible options.
.It Ev PKG_CREATE_NO_CHECKS
Porters switch.
Set to
.Sq Yes
to avoid checking the ports tree when solving
.Ev WANTLIB
.Po
see
.Cm wantlib-args
.Pc .
May result in bogus packages that mix
.Cm @depends
lines obtained from
the ports tree with
.Cm @wantlib
lines that come from the installed system.
Set to
.Sq Warn
to have the differences printed as a warning instead of an error
.Po
the default
.Pc .
.It Ev PKG_DBDIR
User settings.
Path to package installation records.
Defaults to
.Pa /var/db/pkg .
.It Ev PKG_DELETE
User settings.
Path to
.Xr pkg_delete 1
command, with possible options.
.It Ev PKG_INFO
User settings.
Path to
.Xr pkg_info 1
command, with possible options.
.It Ev PKG_TMPDIR
See
.Xr pkg_add 1 .
Normally points to
.Pa /var/tmp ,
as per default.
.It Ev PORTHOME
Setting of env variable
.Ev HOME
for most shell invocations.
Default will trip ports that try to write into $HOME while building.
.It Ev PORTPATH
Path used by most shell invocations.
Don't override unless really needed.
.It Ev PORTSDIR
Root of the ports tree (default:
.Pa /usr/ports ) .
.It Ev PORTSDIR_PATH
Path used by dependencies and
.Pa bsd.port.subdir.mk
to look up package specifications.
Defaults to
.Pa ${PORTSDIR}:${PORTSDIR}/mystuff .
.It Ev PORTS_PRIVSEP
If set to
.Sq Yes ,
will build ports as
.Ev BUILD_USER
and fetch distfiles
as
.Ev FETCH_USER .
.Pp
To work fully, this does require the ports tree
to be world-readable, and
.Pa ${WRKDIR}
to be world-readable as well
.Po
.Cm update-patches
and friends won't work otherwise
.Pc .
.Pp
Meant to use in concert with
.Xr dpb 1 ,
which uses the same permissions
.Po
see
.Sq THE SECURITY MODEL OF DPB
in
.Xr dpb 1
.Pc .
.Pp
Basically,
.Ev BUILD_USER
must be able to write into
.Pa ${WRKOBJDIR} , ${PACKAGE_REPOSITORY} , ${PLIST_REPOSITORY}
and
.Ev FETCH_USER
must be able to write into
.Pa ${DISTDIR} .
The directories and permissions can be set correctly using
.Cm fix-permissions .
.Pp
The regular user must be allowed to execute commands as
.Ev BUILD_USER
and
.Ev FETCH_USER .
Running commands as another user can be achieved with
.Xr doas 1
by setting
.Ev SUDO=doas
in
.Xr mk.conf 5
and using the following minimal
.Xr doas.conf 5 :
.Bd -literal -offset indent
permit keepenv nopass solene as _pbuild
permit keepenv nopass solene as _pfetch
.Ed
.Pp
Note that this also means that
.Xr doas 1
must be configured to work within the chroot
created by
.Xr proot 1 .
.Pp
As
.Xr dpb 1
does its own privilege dropping when run as root,
it will automatically override
.Ev PORTS_PRIVSEP .
.Pp
User settings, defaults to
.Sq \&No .
.It Ev PKGDIR
Location for packaging information (packing list, port description, messages).
.Cm update-plist
may create it.
Must be a valid directory.
Default: pkg.
.It Ev PKGFILE
Full path to the created package for the given subpackage.
Read-only.
.It Ev PKGFILES
Full path to all created packages.
Read-only.
.It Ev PKGNAME
Name of the created package.
Default is ${DISTNAME}.
This does not take flavors into account.
See
.Ev FULLPKGNAME
for that.
Specific revisions and epoch changes should be
handled by
.Ev REVISION
and
.Ev EPOCH
instead.
.It Ev PKGNAMES
Read-only.
List of all package names generated by the port, with
.Ev FLAVORS
and
.Ev BUILD_PACKAGES
taken into account.
Mostly used as
.Ql make show=PKGNAMES
to verify that bumped package names are correct.
.It Ev PKGNAME-foo
Package name for sub-package foo, if the default value
of ${PKGNAME}${SUBPACKAGE} is not appropriate.
.It Ev PKGPATH
Path to the current port's directory, relative to ${PORTSDIR}.
Read-only.
.It Ev PKGPATHS
Read-only.
List of all package paths generated by the port, with
.Ev FLAVORS
and
.Ev MULTI_PACKAGES
taken into account.
Order matches
.Ev PKGNAMES
exactly.
.It Ev PKGSPEC
Default package spec for using this port as a dependency.
Defaults to
.Sq stem-* ,
derived from the
.Ev FULLPKGNAME .
Do not override without very good reasons,
namely software that coexist as different incompatible versions with the
same stem, e.g., already a mess.
.It Ev PKGSTEM
Base for the package name without any version number.
Used in
.Pa READMEs
file names and actual contents, can be overridden for ports
with branches, like php, e.g.,
.Li PKGSTEM-main = php-5.6
.It Ev PLIST_DB
Deprecated, see
.Ev PLIST_REPOSITORY .
.It Ev PLIST_REPOSITORY
User settings.
Base directory used to save generated packing-lists, as persistent information.
Packing-lists are processed by a script,
.Xr register-plist 1 ,
which complains when packing-lists change without a
.Ev REVISION
bump.
It also knows enough about package version numbers when something in the
package or its dependencies goes backward, thus catching
.Ev EPOCH
issues.
This directory is never cleaned during normal operation.
.Ql make clean=plist
should only ever be used during debugging by port maintainers.
Defaults to
.Pa ${PORTSDIR}/plist
.Po
plists actually get saved into
.Pa ${PLIST_REPOSITORY}/${MACHINE_ARCH}
.Pc .
If set to empty, will not register anything: very much unsafe.
.It Ev PORTS_BUILD_XENOCARA_TOO
EXPERIMENTAL.
Set to
.Sq Yes
to build xenocara through ports.
This is highly experimental and not recommended.
.It Ev PORTROACH
Controls the behavior of
.Pa misc/portroach
as documented in detail at
.Lk http://jasperla.github.io/portroach/docs/portroach-portconfig.txt .
.It Ev PREFIX
Base directory for the current port installation.
Usually ${LOCALBASE}, though some ports may elect a location under
.Pa ${VARBASE} ,
and some multi-package ports may install under several locations.
Additionally, firmware files generally install under
.Pa ${BASESYSCONFDIR} .
.It Ev PREPARE_CHECK_ONLY
Build settings.
Prevent the
.Cm prepare
stage from installing anything, let it just check dependencies, and
handle [:target] dependencies.
Mostly used by
.Xr dpb 1 ,
which already installs everything before running
.Cm prepare .
.It Ev PROGRESS_METER
User settings.
Defaults to
.Sq Yes .
Forces commands like
.Xr ftp 1
and
.Xr pkg_create 1
to use their progress-meter even in the absence of a terminal.
.It Ev PROPERTIES
List of properties specific to a given machine architecture.
Most often obtained through
.Xr bsd.port.arch.mk 5 .
These can be checked like this
.Bd -literal -offset indent
\&.include <bsd.port.arch.mk>
\&.if ${PROPERTIES:Mapm}
# then add build options specific to apm arches
\&...
\&.if !${PROPERTIES:Mlp64}
# build options specific to lp32 arches
\&...
.Ed
For
.Ev MULTI_PACKAGES
setup, use of
.Ev ONLY_FOR_ARCHS-sub
and
.Ev BUILD_PACKAGES
is generally preferred (and simpler).
Possible properties include
.Bl -tag -width mono
.It apm
architecture possesses suspend (apm) support.
.It be
architecture is big-endian.
.It gccN
gccN architecture.
.It le
architecture is little-endian.
.It lp64
lp64 architecture.
.It llvm
there is
.Pa lang/llvm
support on this architecture.
.It mono
there is
.Pa lang/mono
support on this architecture.
.El
.It Ev PSEUDO_FLAVOR
List of flavors in
.Ev FLAVOR
that are actually pseudo-flavors.
Only for introspection purposes.
Read-only.
.It Ev PSEUDO_FLAVORS
Extra list of flavors that do not register in package names, but are still
used to control build logic, and work directory names.
Its only use should be for disabling part of a multi-packages build,
for instance:
.Bd -literal
FLAVOR=no_gnome make package
.Ed
.Pp
Pseudo-flavors should be named as
.Sq no_something
to disable the build of subpackage
.Sq -something
.Po
and possibly some others, by restricting
.Ev BUILD_PACKAGES
.Pc .
Pseudo-flavors should always be handled through
.Xr bsd.port.arch.mk 5 .
A pseudo-flavor can remove several subpackages through the following
construct.
.Bd -literal -offset indent
# pseudo-flavor no_gui will also remove gtk and gtk3
MULTI_PACKAGES = -main -gtk -gtk3 -gui
# ...
\&.include <bsd.port.arch.mk>

# remove extra build components
\&.if !${BUILD_PACKAGES:M-gui}
BUILD_PACKAGES := ${BUILD_PACKAGES:N-gtk:N-gtk3}
\&.endif

# normal configure setup, e.g.,
\&.if ${BUILD_PACKAGES:M-gtk}
# ...
.Ed
.Pp
Caveat: creation of a separate working directory is mandatory for a
pseudo-flavor.
If, at a later time, a full build with all subpackages is required,
all the work will need to be done again.
.Pp
See also
.Ev BUILD_ONCE .
.It Ev RCDIR
Location for daemon startup scripts.
Defaults to
.Pa /etc/rc.d .
Do not change.
.It Ev REFETCH
User settings.
If set to true,
.Cm checksum
will analyze ${CHECKSUM_FILE}, and try retrieving files with the correct
checksum off
.Lk https://ftp.openbsd.org ,
in the directory
.Pa /pub/OpenBSD/distfiles/$cipher/$value/$file .
.It Ev REORDER_DEPENDENCIES
Points to a list of files that specify inter-dependencies for
.Xr make 1 .
If defined, each line of the file is either a comment (starting with #)
or a pair of two files: most_recent older.
At the end of
.Cm post-patch ,
.Xr touch 1
will be used to ensure those files are put in the proper order.
The files are assumed to be under
.Pa ${WRKSRC} .
The notation /file can be used to ask for a recursive search, e.g.,
to make sure that all Makefile.in are up to date.
See
.Pa ${PORTSDIR}/infrastructure/mk/automake.dep
for an example.
.It Ev REPORT_PROBLEM
See
.Xr ports 7 .
.It Ev REPORT_PROBLEM_LOGFILE
See
.Xr ports 7 .
.It Ev REVISION
Revision number of the current package.
Defaults to empty (very first package), then
numbering starts at 0.
Gets automatically incorporated into
.Ev FULLPKGNAME
as
.Sq p${REVISION}
to form a full package-name conforming to
.Xr packages-specs 7 .
.It Ev RUN_DEPENDS
Specification of ports this port needs installed to be functional.
Same format as
.Ev LIB_DEPENDS .
The corresponding packages will be built right before the
.Cm install
stage, and
.Xr pkg_add 1
will take care of installing them.
.It Ev SEPARATE_BUILD
Many GNU configure ports can be built in a directory distinct from the
place they were unpacked.
For some specific ports, this is even mandatory.
Set to
.Sq yes
or
.Sq simple
if this is the case.
The ports infrastructure will generate a separate ${WRKBUILD} directory
in which the port will be configured and built.
Wipe ${WRKBUILD} to start anew, but skipping the extract/patch stage.
.It Ev SETENV
Normally set to
.Li /usr/bin/env -i .
Prepended to every command invocation that requires a clean environment.
Do not override.
.It Ev SHARED_LIBS
List of shared libraries that the port may build, as a list of the form
.Sq libname
.Sq libversion .
Used to set variables of the form
.Ev LIBlibname_VERSION
that are then used for substitution by
.Xr pkg_create 1 .
The porter is responsible for making sure the port uses those version numbers
when shared libraries are built.
.Pp
The intent is that the
.Ox
ports system must have control over shared library versions because of global
changes that may require bumping the major version of every shared library in
the system, or simply because the third party programmers do not understand
the rules for shared library versions, thus breaking the update mechanism.
For that reason it is advised to set libversion to 0.0 when first importing a
port.
.Pp
Porters of software using libtool should make sure
.Ev MAKE_FLAGS
get propagated to the libtool invocations.
This should be enough in most cases.
.It Ev SKIPDIR
See
.Xr ports 7 .
.It Ev STATIC_PLIST
Normally set to
.Sq yes .
Can be set to no for ports that do not have a static plist.
Do not change without a very good reason.
Note that the only good reason to not have a static plist is for ports such
as
.Pa databases/ports-readmes
which actually build a bunch of files depending on the current ports tree.
This breaks all introspection mechanisms within the ports tree, including
.Pa databases/pkglocatedb
which will not include that port.
.It Ev STARTAFTER
See
.Xr ports 7 .
.It Ev STARTDIR
See
.Xr ports 7 .
.It Ev SUBPACKAGE
Set to the subpackage suffix when building a package in a multi-package port.
Read-only.
Used to test for dependencies or to adjust the package name.
.It Ev SUBST_CMD
A command that can be used to perform
.Ev SUBST_VARS
substitution on arbitrary files.
In normal mode,
.Pp
.Dl ${SUBST_CMD} file1 file2 ...
.Pp
will substitute files in place, creating backup copies of them.
In copy mode,
.Pp
.Dl ${SUBST_CMD} -c src1 dest1 src2 dest2
.Pp
will copy files over while performing the substitution, as suitable for
copying template files over from
.Pa ${FILESDIR}
to
.Pa ${PREFIX} ,
for instance.
This uses
.Xr pkg_subst 1
with suitable parameters.
Read-only.
.Pp
${SUBST_CMD}
can be used like
.Xr install 1 :
.Dl ${SUBST_CMD} Oo Fl g Ar group Oc Oo Fl o Ar owner Oc Oo Fl m Ar mode Oc file...
to set file
.Ar owner ,
.Ar group
and/or
.Ar mode .
.Pp
Note that
.Ev SUBST_CMD
is not really appropriate when variables have subpackage variations, like
.Ev PREFIX
or
.Ev FULLPKGNAME .
Use the appropriate
.Ev SUBST_CMD-sub
instead.
.It Ev SUBST_CMD-sub
.Ev SUBST_CMD
with subpackage-dependent semantics, like packing-list substitution.
It will substitute the right variable depending on the desired subpackage,
e.g.,
.Ev SUBST_CMD-foo
will substitute the value of
.Ev FULLPKGNAME-foo
for
.Li ${FULLPKGNAME} .
.It Ev SUBST_DATA , SUBST_MAN , SUBST_PROGRAM
Specialized versions of
.Ev SUBST_CMD
that use
.Fl c
and appropriate owner/group/mode for data, manpages and programs respectively.
.It Ev SUBST_VARS
Make variables whose values get substituted to create the actual package
information.
Always holds
.Ev ARCH ,
.Ev BASE_PKGPATH ,
.Ev FLAVOR_EXT ,
.Ev FULLPKGNAME ,
.Ev HOMEPAGE ,
.Ev LOCALBASE ,
.Ev MACHINE_ARCH ,
.Ev MAINTAINER ,
.Ev PREFIX ,
.Ev PKGSTEM ,
.Ev RCDIR ,
.Ev SYSCONFDIR ,
.Ev TRUEPREFIX ,
and
.Ev X11BASE .
The special construct
.Sq ${FLAVORS}
can be used in the packing-list to specify the current list of dash
separated flavors the port is compiled with (useful for cross-dependencies
in
.Ev MULTI_PACKAGES ) .
Add other
variables as needed.
.Pp
.Ev TRUEPREFIX
is never passed to
.Xr pkg_create 1
as it is identical to
.Ev PREFIX .
.Pp
By default,
.Xr update-plist 1
is run with the following options:
.Bd -literal -offset indent
update-plist -i ARCH -i BASE_PKGPATH -i FULLPKGNAME
-i FULLPKGPATH -i LOCALSTATEDIR -i MACHINE_ARCH
-s BASE_PKGPATH -s LOCALBASE -s LOCALSTATEDIR -s PREFIX
-s RCDIR -s SYSCONFDIR -s X11BASE
.Ed
.It Ev SUDO
User settings.
If set to
.Xr doas 1
in
.Xr mk.conf 5 ,
the ports tree will only invoke root's privileges for the parts that
really require it.
.It Ev SUPDISTFILES
Supplementary files that need to be retrieved under some specific
circumstances.
For instance, a port might need architecture-specific files.
.Ev SUPDISTFILES
should hold a list of all distribution files and patchfiles that are not
always needed, so that a mirror will be able to grab all files, or that
.Cm makesum
will work.
Having an overlap between
.Ev SUPDISTFILES
and
.Ev DISTFILES ,
.Ev PATCHFILES
is admissible, and in fact, expected, as it is much simpler to build
an error-free list of files to retrieve in that way.
See the xanim port for an example.
.It Ev SYSCONFDIR
Location for this port's configuration files, should always be derived
from
.Ev BASESYSCONFDIR ,
which defaults to
.Pa /etc .
Passed to gnu configure scripts and substituted in PLISTs.
.It Ev TAR
Name of the tar binary.
.It Ev TARGETS
Read-only.
Set to the list of special targets for a port
.Po
.Cm {pre,do,post}-*
and module hooks
.Pc .
Used by introspection tools such as the sqlports package.
.It Ev TEMPLATES
Base location for the templates used in the
.Cm readmes
target.
User settings.
Defaults to
.Pa ${PORTSDIR}/infrastructure/templates .
.It Ev TEST_DEPENDS
See
.Ev BUILD_DEPENDS
for specification.
Test dependencies are only checked if the
.Cm test
stage is invoked.
.It Ev TEST_ENV
Additional environment variables passed to tests.
Empty by default.
.It Ev TEST_FLAGS
Extra flags passed to ${MAKE_PROGRAM} to run the regression tests.
Empty by default.
.It Ev TEST_IS_INTERACTIVE
Set to
.Sq Yes
if port needs human interaction to run its tests, or set to
.Sq X11
if the tests need an active X11 display to work.
.It Ev TEST_LOG
Command used to log the results of regression tests to TEST_LOGFILE.
Read-only.
.It Ev TEST_LOGFILE
Log file containing the results of regression tests.
.It Ev TEST_TARGET
Target to run regression tests.
Defaults to
.Sq regress ,
except for
.Sq perl
and
.Sq gnu
.Ev CONFIGURE_STYLE ,
which default to
.Sq test
and
.Sq check ,
respectively.
.It Ev TRUEPREFIX
Read-only.
Mostly the same as ${PREFIX}, except it never gets ${DESTDIR} prepended
during
.Cm fake .
Refer to
.Sx THE FAKE FRAMEWORK
section for details.
.It Ev TRY_BROKEN
User settings.
If set to
.Sq Yes ,
don't set
.Ev IGNORE
for
.Ev BROKEN
ports, so that we will attempt to build them.
.It Ev UNLOCK_CMD
User settings.
If set, expands to a command that will release a lock.
This lock will reside in
.Pa ${LOCKDIR} .
.It Ev UNMESSAGE
File recorded in the package and displayed during deinstallation.
Defaults to ${PKGDIR}/UNMESSAGE if this file exists.
Leave empty if no message is needed.
.It Ev UNZIP
Name of the unzip binary.
.It Ev UPDATE_COOKIES_DIR
User settings.
Used to store cookies for package updates and defaults to
.Pa ${PORTSDIR}/update/${MACHINE_ARCH} .
If set to empty, will revert to a file under
.Pa ${WRKDIR} .
.It Ev UPDATE_PLIST_ARGS
Tweaks to
.Xr update-plist 1
behavior for some specific ports, such as variable handling.
.It Ev UPDATE_PLIST_OPTS
User settings.
User options added to
.Xr update-plist 1 ,
mostly
.Fl v
for now.
.It Ev USE_CCACHE
User settings.
Set to
.Sq Yes
to use ccache when building ports.
Adds a build dependency on devel/ccache, and sets up the build
environment so that it is used.
.It Ev USE_GMAKE
Set to
.Sq Yes
if GNU make (${GMAKE}) is needed for correct behavior of this port.
.It Ev USE_GROFF
Set to
.Sq Yes
to use groff to build manpages.
This sets groff as a build dependency, and also tells
.Xr pkg_create 1
to format manpages behind the scene using groff while building packages.
.It Ev USE_LIBTOOL
Defaults to
.Sq Yes .
Set to
.Sq gnu
if the base
.Xr libtool 1
is insufficient and GNU libtool is required.
Set to
.Sq \&No
to disable the use of
.Xr libtool 1
entirely; this should not be set under normal circumstances.
Adds dependencies if necessary, and passes LIBTOOL environment variable to
scripts invocations.
.Pp
Many ports using GNU autoconf need an m4 file from the GNU libtool package
but otherwise work with base
.Xr libtool 1 .
In those cases do not set
.Ev USE_LIBTOOL ,
instead just set
.Li BUILD_DEPENDS = devel/libtool .
.It Ev USE_MFS
Set to
.Sq Yes
to build ports under an MFS filesystem
(see
.Xr mount_mfs 8 ) .
Mostly for use by
.Xr dpb 1
and not intended to be a user setting.
See
.Ev WRKOBJDIR_MFS
for configuration.
.It Ev USE_WXNEEDED
If set to
.Sq Yes ,
writes a wrapper script to ${WRKDIR}/bin/ld in
.Cm patch
to request that the linker adds an OPENBSD_WXNEEDED ELF section.
Use when a port requires memory mappings that are both executable
and writable and cannot be modified to avoid this.
.It Ev USE_X11
Normally, presence of ${X11BASE} is enforced by default for building ports.
But there is an experimental way to hook the xenocara build into
.Xr dpb 1 ,
which requires knowing whether a port requires X11 to already
be there.
.Pp
The infrastructure mostly sets
.Ev USE_X11
automatically based on
.Ev WANTLIB
values, there are a few ports (about 20) that require X11 components without
any library telltale.
.It Ev VARBASE
User settings.
Base location for ports that install stuff outside of
.Pa ${LOCALBASE} .
Defaults to
.Pa /var .
.It Ev WANTLIB
List of library specifications that a package will need.
May include system and X11 libraries.
See
.Xr library-specs 7
for more details.
.Pp
As a special extension,
.Ev WANTLIB
may include absolute paths, e.g.,
.Pa ${LOCALBASE}/lib/expat=4
to distinguish between base libraries and port libraries.
Use with caution, this is very seldom needed.
.It Ev wantlib_args
Controls the behavior of
.Xr pkg_create 1
related targets, see
.Cm print-package-args
for details.
.It Ev WARNINGS
User settings.
If set to
.Sq Yes ,
add
.Ev CDIAGFLAGS
to
.Ev CFLAGS
and
.Ev CXXDIAGFLAGS
to
.Ev CXXFLAGS .
.It Ev WRKBUILD
Subdirectory of ${WRKDIR} where the actual build occurs.
Defaults to ${WRKSRC}, unless
.Ev SEPARATE_BUILD
is involved, in which case it is set to an appropriate value.
.It Ev WRKCONF
Subdirectory of ${WRKDIR} where the actual configure set occurs.
Defaults to ${WRKBUILD}.
.It Ev WRKDIR
Location where all port activity occurs.
Apart from the actual port, may
hold all kinds of cookies that checkpoint the port's build.
Read-only.
Note that WRKDIR may be a symbolic link.
During ports building,
.Pa ${WRKDIR}/bin
is put at the front of the
.Ev PATH .
.It Ev WRKDIR_LINKNAME
Name of a symbolic link to create within the port directory which will
point to the port's ${WRKDIR}.
Deprecated.
.It Ev WRKDIST
Subdirectory of ${WRKDIR} in which the distribution files normally unpack.
Base for all patches.
Defaults to
.Pa ${WRKDIR}/${DISTNAME} .
Note that WRKDIST may be a symbolic link, if set to ${WRKDIR}.
.It Ev WRKSRC
Subdirectory of ${WRKDIR} where the actual source is.
Base for configuration (default: ${WRKDIST}).
Note that WRKSRC may be a symbolic link, if set to ${WRKDIR}.
.It Ev WRKINST
Subdirectory of ${WRKDIR} where port normally installs (see the
.Cm fake
target).
.It Ev WRKOBJDIR
Used as a base for the actual port working directory.
Defaults to
.Pa ${PORTSDIR}/pobj .
The real working directory ${WRKDIR} is created there.
Can be set on a per-${PKGPATH} basis.
For instance, setting WRKOBJDIR_www/mozilla=/tmp/obj
will affect only the mozilla port.
If explicitly unset (WRKOBJDIR=), the working directory is
created within the port directory.
.It Ev WRKOBJDIR_MFS
Alternate location for the port working directory.
The intent is to use an MFS based filesystem for small ports with
.Xr dpb 1 .
Active when
.Ev USE_MFS
is
.Sq Yes .
Defaults to
.Pa /tmp/pobj .
.It Ev X11BASE
Where X11 has been installed.
Default:
.Pa /usr/X11R6 .
.It Ev XAUTHORITY
Points to a suitable authority file for X11 interactive regression tests.
Defaults to
.Pa ${HOME}/.xauthority .
.It Ev XMKMF
Invocation of xmkmf for a
.Li CONFIGURE_STYLE=imake
port.
Defaults to xmkmf -a -DPorts.
The -DPorts is specific to
.Ox
and is always appended.
.It Ev YACC
Name of yacc program to pass to GNU-configure, defaults to yacc.
GNU-configure would always try to use bison otherwise, which leads to
unreproducible builds.
Set to bison if needed.
.El
.Sh DIAGNOSTICS
Note that some of these messages are actually emitted by some other external
commands, but grouped here for convenience: easier to look for in
.Xr dpb 1 Ns 's
logs.
.Bl -diag
.It "/bin/sh: cd .../pkg - No such file or directory"
Emitted during
.Cm generate-readmes .
.Pa ${PKGDIR}
must point to an existing directory, so that
.Nm
can be certain there are no
.Pa MESSAGEs
or
other files pertinent to the package.
.It "Discovered old directory in ..."
This message comes from
.Xr update-plist 1 .
A directory was found in the PLIST that used to be needed but is no longer,
because it's now accounted for through dependencies.
Indicates the old directory has been removed.
.It "Error: change in plist between ..."
Error message comes from
.Xr register-plist 1 .
.It "Error: duplicate item in packing-list"
Error message comes from
.Xr pkg_create 1 ,
and will result from incorrect packing-lists, such as including several
fragments with the same file, or having incorrect
.Ev PKG_ARGS-sub .
.It "Error: Libraries in packing-lists...and libraries from installed packages don't match"
The ports tree and the installed packages are out-of-sync.
Mixing library information from both sources might produce packages that can't
be installed elsewhere.
Cleanest fix is to update the out-of-date source (e.g., update the ports tree,
or build and install new packages).
Developers may use
.Ev PKG_CREATE_NO_CHECKS
instead, assuming they understand the implications.
See
.Cm print-package-args Pq Cm wantlib-args
for details.
.It "Fatal: can't flavor a SUBDIR"
A dependency mentions top_subdir,flavor.
Flavor would then be ignored, as it is only applied to individual ports.
.It "Fatal: can't subpackage a SUBDIR"
A dependency mentions top_subdir,-sub.
Subpackage would then be ignored, as it is only applied to individual ports.
.It "Fatal: flavor should never start with a digit"
This would utterly confuse
.Xr pkg_add 1 .
See
.Xr packages-specs 7 .
.It "Fatal: inclusion of <file> from <file>"
.Pa bsd.port.mk
or
.Pa bsd.port.subdir.mk
has been included from a
.Ev MODULE
or from
.Pa Makefile.inc ,
resulting in a double inclusion.
This would lead to weird results, such as
.Ev PKG_ARGS
being defined twice.
.It "Fatal: SUBPACKAGES should always begin with -: <offending list>"
That is the only way to differentiate between
.Ev FLAVOR
and
.Ev SUBPACKAGE
in
.Xr pkgpath 7
specifications.
.It "Fatal: building ports requires correctly installed X11"
All file sets of the base OS, including xenocara, must be installed
before building ports.
.It "Fatal: /usr/local/lib/X11/app-defaults should exist and be a symlink"
/usr/local/lib/X11/app-defaults is distributed as a symlink in the
xshare*.tgz file set.
If xenocara was not fully installed before packages were added, it may
have been created as a directory instead.
.It "Fatal: the licensing info for <pkgname> is incomplete..."
Every port must have explicit defines of all
.Ev PERMIT_*
values.
.It "Fatal: Use 'env FLAVOR=flavor make' instead"
Arguments specified after
.Xr make 1
are hardcoded for all recursive sub-makes, and very difficult to override.
Thus,
.Ev FLAVOR
must be specified in the environment instead.
.It "Fatal: Use 'env SUBPACKAGE=-sub make' instead"
Arguments specified after
.Xr make 1
are hardcoded for all recursive sub-makes, and very difficult to override.
Thus,
.Ev SUBPACKAGE
must be specified in the environment instead.
.It "ldconfig: <dir>: No such file or directory"
Usually produced by
.Xr pkg_add 1
running
.Xr ldconfig 8 .
Some tools such as GNU libtool will add directories living under
.Pa ${WRKINST}
to the shared library path during the
.Cm fake
stage.
Of course,
.Xr ldconfig 8
will later complain after the directory no longer exists.
The bogus tool should be fixed to conform to
.Ox
usage.
.It LIB_DEPENDS <spec> not needed for <FULLPKGPATH>
There doesn't seem to be any WANTLIB to match the given LIB_DEPENDS.
Thus, the LIB_DEPENDS won't turn into a @depends line in the created package.
This is often because of confusion between LIB_DEPENDS and RUN_DEPENDS:
RUN_DEPENDS is needed for dlopen'd libraries.
.Pp
Might be intentional sometimes, if some compile flavors create static binaries,
for instance.
Also, will happen for multi-packages, where one sets LIB_DEPENDS to have
a given build dependency (and corresponding WANTLIB for a given SUBPACKAGE).
.Pp
See
.Cm print-package-args Pq Cm lib-depends-args
for details.
.It "Warning: FULLPKGNAME-sub defined but not FULLPKGPATH-sub"
.Ev FULLPKGNAME-sub
has been explicitly defined by the port, instead of relying on the default,
but no value of
.Ev FULLPKGPATH-sub
has been given.
This is often an error.
.It "Warning: symlink(s) point to non existent file."
Warning message comes from
.Xr pkg_create 1 .
The symlink resides in the fake area, under
.Pa ${WRKINST} .
This is only a warning because the symlink may point to a run-time dependency,
which obviously won't exist under
.Pa ${WRKINST}
at the time
.Ql make package
is run.
.It "Warning: @option no-default-conflict with no @conflict"
Warning message comes from
.Xr pkg_create 1 .
Most packages that waive "default-conflict" will have explicit conflict markers
instead.
Otherwise, the package will only conflict with the exact same version, with
some possible
.Ev REVISION
bumps.
Any other version or
.Ev FLAVOR
won't conflict.
This is generally an error, apart from very few ports like
.Pa devel/autoconf/* .
.It "groff produced empty result for <manpage>..."
Warning message comes from
.Xr pkg_create 1 .
Manpages are automatically formatted with
.Xr groff 1
if
.Ev USE_GROFF
is set.
The above message denotes an actual problem while formatting the page,
which should be addressed.
In the meantime,
.Xr pkg_create 1
still produces a package, but leaves the manpage unformatted, in the hope
that something will be able to make sense of it.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa ../Makefile.inc
Common Makefile fragment for a set of ports, included automatically.
.It Pa /cdrom/distfiles
Default path to a CD-ROM (or other media) full of distribution files.
.It Pa ${PORTSDIR}/distfiles
Default setup of ${DISTDIR}.
.It Pa ${DISTDIR}
Cache of all distribution files.
.It Pa distinfo
Checksum file.
Holds the output of
.Xr cksum 1 ,
using
.Xr sha256 1
for the port's ${DISTFILES} and ${PATCHFILES},
as well as the sizes of these files.
.It Pa ${DISTDIR}/${CHECKSUMFILES}
Cache of normal distribution files for a given port.
.It Pa ${DISTDIR}/${MAKESUMFILES}
Cache of all distribution files for a given port.
.It Pa ${PKGDIR}/DESCR
Description for the port.
Variables such as ${HOMEPAGE} and ${MAINTAINER} will be expanded
(see SUBST_VARS).
Multi-package ports will use DESCR${SUBPACKAGE}.
.It Pa ${PKGDIR}/README
.Ox
specific documentation for a port, that will be installed as
.Pa ${LOCALBASE}/share/doc/pkg-readmes/${PKGSTEM}
at the end of
.Cm fake .
Variables from
.Ev SUBST_VARS
will be expanded.
Multi-package ports will use
.Pa README${SUBPACKAGE} .
.It Pa ${PKGDIR}/<foo>.rc
Startup script for <foo>.
Will be installed as
.Ar ${RCDIR}/<foo>
at the end of
.Cm fake .
Variables from
.Ev SUBST_VARS
will be expanded.
.It Pa ${PORTSDIR}/packages/${MACHINE_ARCH}
Default setup of ${PACKAGE_REPOSITORY}.
.It Pa ${PACKAGE_REPOSITORY}/no-arch
Location of arch-independent packages.
.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/all
Location of all built packages.
.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cache
Location of packages retrieved through the network.
.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cksums
Location of checksums, see
.Ev CHECKSUM_PACKAGES .
.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cdrom
Location of packages suitable for the CD.
.It Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/ftp
Location of packages suitable for FTP.
.It Pa ${PORTSDIR}/bulk/${MACHINE_ARCH}
Default setup of ${BULK_COOKIES_DIR}.
.It Pa ${PORTSDIR}/update/${MACHINE_ARCH}
Default setup of ${UPDATE_COOKIES_DIR}.
.It Pa ${PORTSDIR}/mystuff
Extra directory used to store local ports before committing them.
All depend targets will normally look there after the normal lookup fails.
See
.Ev PORTSDIR_PATH .
.El
.Sh THE FAKE FRAMEWORK
The
.Cm fake
target is used to install the port in a private directory first, ready for
packaging by the
.Cm package
target, so that the actual installation will use the package.
.Pp
Essentially,
.Cm fake
invokes a real install process after tweaking a few variables.
.Pp
.Cm fake
first creates a skeleton tree under ${WRKINST}, using
.Xr mkdir 1
.Fl p .
.Pp
A
.Cm pre-fake
target may be used to complete that skeleton tree.
For instance, a few ports may need supplementary stuff to be present (as
it would be installed if the port's dependencies were present).
.Pp
If
.Cm {pre,do,post}-install
overrides are present, they are used with some
important changes, listed in
.Ev FAKE_SETUP :
.Bd -literal -offset indent
TRUEPREFIX=${PREFIX}
PREFIX=${WRKINST}${PREFIX}
${DESTDIRNAME}=${WRKINST}
.Ed
.Pp
Essentially, old install targets work transparently, except for a need to
change
.Ev PREFIX
to
.Ev TRUEPREFIX
for symbolic links and similar path lookups.
Specific traditional post install work can be simply removed, as it will
be taken care of by the package itself (for instance, ldconfig, or
texinfo's install-info).
.Pp
If no
.Cm do-install
override is present, the port is installed using
.Bd -literal -offset 2n
env -i ${MAKE_ENV} ${FAKE_SETUP} ${MAKE_PROGRAM} ${ALL_FAKE_FLAGS} -f ${MAKE_FILE} ${FAKE_TARGET}
.Ed
.Pp
Note that this does set both PREFIX and ${DESTDIRNAME}.
If a port's Makefile both heeds ${DESTDIRNAME},
and references PREFIX explicitly,
FAKE_FLAGS may rectify the problem by setting PREFIX=${PREFIX}
(which will do the right thing, since ${PREFIX} is a
.Xr make 1
construct which will not be seen by the shell).
.Pp
${FAKE_FLAGS} is used to set variables on
.Xr make 1
command line, which will override the port Makefile contents.
Thus, a port that mentions DESTDIR= does not need any patch to work with fake.
.Pp
Files such as
.Pa ${PKGDIR}/README*
or
.Pa ${PKGDIR}/*.rc
get copied to
.Pa ${WRKINST}
right after the end of
.Cm fake ,
during
.Cm generate-readmes
(see the
.Sx FILES
section above for details).
.Sh FLAVORS AND MULTI_PACKAGES
Starting with
.Ox 2.7 ,
each port can generate distinct packages through two orthogonal mechanisms:
.Ev FLAVORS
and
.Ev MULTI_PACKAGES .
.Pp
The current
.Ev MULTI_PACKAGES
mechanism was introduced after
.Ox 4.0 .
.Pp
The arch-dependent part was refined after
.Ox 5.0 .
.Pp
If a port can be compiled with several options, these options
should be turned into
.Ev FLAVORS .
The port maintainer will set
.Ev FLAVORS
to be the list of possible options in the Makefile.
When building the port, the package builder will set
.Li "FLAVOR='option1 option2...'"
to build a specific flavor of the port.
The Makefile should test the value of FLAVOR as follows:
.Bd -literal -offset indent
FLAVOR?=
\&.if ${FLAVOR:Moption1}
# what to do if option1
\&.endif
\&.if ${FLAVOR:Moption2}
# what to do if option2
\&.endif
.Ed
.Pp
.Nm
takes care of a few details, such as generating a distinct work directory for
each flavor, or creating a FULLPKGNAME by adding a dash separated list of
flavors to the base package name.
The order in which
.Ev FLAVOR
is specified does not matter: this dash separated list will be
reordered to match the ordering of
.Ev FLAVORS .
.Pp
It is an error to specify an option in
.Ev FLAVOR
that does not appear in
.Ev FLAVORS ,
to prevent misspellings.
.Pp
In bulk package building, flavors can be specified as a comma
separated list after the package directory, e.g., SUBDIR+=vim,no_x11
.Po
see
.Xr pkgpath 7
.Pc
.Pp
Finally, package information will use templates with the canonical package
extension if they are available: if FLAVOR='option1 option2' and both
COMMENT and COMMENT-option1-option2 are available, COMMENT-option1-option2 will
be used.
.Pp
If one build of a port can generate several distinct packages, set
.Ev MULTI_PACKAGES
accordingly.
Each extension of a
.Ev MULTI_PACKAGES
name should start with a dash, so that they cannot be confused with
.Ev FLAVORS .
In dependency checking and bulk builds, a subpackage can be
specified after a comma, e.g.,
.Li SUBDIR+=quake,-server .
.Ev MULTI_PACKAGES
only affects the actual package building step (and the
.Cm describe
step, since a
.Ev MULTI_PACKAGES
port will produce several descriptions).
.Pp
If
.Ev MULTI_PACKAGES
is set, the packaging stage happens once for every
subpackage, using subpackage-specific variables.
For instance, if
.Li MULTI_PACKAGES=-main -lib -server ,
.Ev PKG_ARCH-main ,
.Ev PKG_ARCH-lib
and
.Ev PKG_ARCH-server
will be used for the subpackages respectively called
.Ev FULLPKGNAME-main ,
.Ev FULLPKGNAME-lib
and
.Ev FULLPKGNAME-server .
.Pp
All package information is also derived from
templates with SUBPACKAGE appended.
In the preceding example, the packing-list template for FULLPKGNAME-lib
must be in PLIST-lib.
.Pp
The following variables are subpackage dependent:
.Ev COMMENT ,
.Ev PKG_ARCH ,
.Ev PERMIT_PACKAGE_FTP ,
.Ev PERMIT_PACKAGE_CDROM ,
.Ev PKGFILE ,
.Ev PKGNAME ,
.Ev PKGSTEM ,
.Ev FULLPKGNAME ,
.Ev REVISION ,
.Ev EPOCH ,
.Ev FULLPKGPATH ,
.Ev RUN_DEPENDS ,
.Ev WANTLIB ,
.Ev LIB_DEPENDS ,
.Ev IGNORE ,
.Ev ONLY_FOR_ARCHS ,
.Ev NOT_FOR_ARCHS ,
.Ev PKG_ARGS ,
.Ev PREFIX ,
.Ev CATEGORIES ,
.Ev MESSAGE ,
.Ev UNMESSAGE ,
.Ev DESCR ,
.Ev PLIST ,
.Ev STATIC_PLIST ,
.Ev PKGSPEC .
.Pp
The usual non-MULTI_PACKAGES variables are simply used as default values
for all subpackages.
So, if you set
.Li "PKG_ARCH=*"
.Li "PKG_ARCH-main=i386"
then
.Ev PKG_ARCH-lib
and
.Ev PKG_ARCH-server
will both be
.Sq * .
.Pp
.Ev WANTLIB
and
.Ev LIB_DEPENDS
are special.
At the beginning of the build, during
.Cm prepare ,
all build dependencies will be checked,
which includes
.Ev LIB_DEPENDS ,
.Ev WANTLIB
for every subpackage.
As an exception, any
.Ev LIB_DEPENDS-sub
that references the current port will be ignored as a build dependency,
in order to avoid recursion.
.Pp
.Ev FULLPKGPATH
and
.Ev FULLPKGNAME
are special as well.
You must set
.Ev PKGNAME-sub
or
.Ev FULLPKGNAME-sub
for each subpackage, but
.Ev FULLPKGPATH-sub
is set automatically to the right value.
In very rare cases, one may override
.Ev FULLPKGPATH-sub .
(for instance, if one specific subpackage is not affected by option
settings that affect other subpackages, e.g., for include files packs).
.Pp
In terms of using the port, quite a few targets will have a subpackage
specific subtarget:
invoking
.Cm package
is the same as invoking
.Cm subpackage
for all subpackages,
invoking
.Cm install-all
is the same as invoking
.Cm install
for all subpackages,
and invoking
.Cm update
is the same as invoking
.Cm subupdate
for all subpackages.
.Pp
.Ev ONLY_FOR_ARCHS
and
.Ev NOT_FOR_ARCHS
interact with
.Ev MULTI_PACKAGES
and
.Ev IGNORE .
The infrastructure will automatically filter subpackages
that are not suitable for the current architecture.
Thus,
.Ev MULTI_PACKAGES
should always list all subpackages,
even things not buildable on the current architecture,
for indexing purposes.
.Pp
Starting with
.Ox 5.1 ,
.Xr bsd.port.arch.mk 5
should be used to simplify the handling of
.Ev MULTI_PACKAGES
in arch-dependent setups:
.Pp
Make sure
.Ev MULTI_PACKAGES ,
.Ev ONLY_FOR_ARCHS* ,
and
.Ev PSEUDO_FLAVORS
are defined correctly, then
.Bd -literal -offset indent
\&.include <bsd.port.arch.mk>
.Ed
.Pp
This will compute
.Ev BUILD_PACKAGES ,
the list of actual subpackages to build with the current setup,
by taking arch constraints and pseudo-flavors into account.
Then test
.Ev BUILD_PACKAGES
to set up the right configuration, e.g., to check if
.Ev SUBPACKAGE
.Ar -mono
should be built:
.Bd -literal -offset indent
\&.if ${BUILD_PACKAGES:M-mono}
.Ed
.Pp
The
.Pa lang/gcc/4.9
or
.Pa print/poppler
ports should provide examples of proper use.
.Pp
Note that
.Xr dpb 1
will break if all subpackages are not properly listed.
.Sh THE GENERATION OF PACKAGE INFORMATION
Starting after
.Ox 4.1
all package information is processed directly by
.Xr pkg_create 1
from templates in ${PKG_DIR}.
.Pp
.Bl -bullet -compact
.It
If not overridden by the user, determine which set of templates to use,
depending on the current SUBPACKAGE and FLAVOR information.
Set PLIST${SUBPACKAGE}, DESCR${SUBPACKAGE}, COMMENT${SUBPACKAGE}, MESSAGE${SUBPACKAGE}, UNMESSAGE${SUBPACKAGE} accordingly.
.It
Generate the actual DESCR, and if needed, MESSAGE, UNMESSAGE,
from the templates in ${DESCR}, ${MESSAGE}, ${UNMESSAGE}, by
substituting the variables in ${SUBST_VARS}, and by substituting
${FLAVORS} with the canonical flavor extension for this port,
e.g., if
.Li FLAVORS=no_map gfx qt2 ,
if
.Li FLAVOR=gfx no_map ,
this is
.Sq -no_map-gfx .
.It
Generate the actual PLIST from the template ${PLIST},
by inserting fragments
and applying the same variable substitutions as other package information.
.El
.Pp
Note that ${COMMENT} is currently not substituted, to speed up
.Cm describe
generation.
.Pp
To avoid substitution, variables can be escaped as follows:
.Li "$\e{PREFIX}"
.Pp
If
.Ev FLAVORS
lists flv, then constructs such as the line
.Li "%%flv%%"
or
.Li "!%%flv%%"
in the packing-list template trigger the inclusion of
.Pa ${PKGDIR}/PFRAG.flv${SUBPACKAGE}
or
.Pa ${PKGDIR}/PFRAG.no-flv${SUBPACKAGE} .
Other fragments can be defined by simply adding
.Li "-Dfrag=1"
or
.Li "-Dfrag=0"
to
.Ev PKG_ARGS .
.Pp
If libraries are built using
.Pa bsd.lib.mk ,
special care should be taken for mips64* architectures,
which do not ever build
.Pa *pic.a
files (all mips code is pic already).
.Nm
automatically adds
.Li "-Dno_mips64=1"
or
.Li "-Dno_mips64=0"
to
.Ev PKG_ARGS ,
and the porter only needs to provide the appropriate fragment.
.Pp
.Xr pkg_add 1
now calls
.Xr ldconfig 8
directly, provided dynamic libraries have been annotated with
.Li "@lib libthingy.so.5.0" .
Adding new directories to the dynamic loader cache has been
deprecated.
It is often better to let libraries be visible as a link
under ${LOCALBASE}.
Having a separate directory is enough to trick
.Xr ld 1
into grabbing the right version.
Libraries used only for
.Xr dlopen 3
do not need to be visible.
Some programs will prefer to use rpath to find their own libraries.
.Pp
The special
.Cm update-plist
target does a fairly good job of automatically generating the PLIST.
.Pp
If
.Ev PLIST_REPOSITORY
points to a directory, all packing-lists from packages generated by
.Xr pkg_create 1
during the
.Cm package
stage are saved in
.Pa ${PLIST_REPOSITORY}/${MACHINE_ARCH}
by a script:
.Pa ${PORTSDIR}/infrastructure/bin/register-plist .
This script strips some irrelevant information and normalizes the
packing-list somehow, and compares it to existing information, looking
for relevant changes.
Since a package name must always be changed when the packing-list changes,
any attempt to replace a packing-list of a given name with a different
packing-list will be flagged as an error.
.Pp
In
.Ev MULTI_PACKAGES
mode, there must be separate COMMENT, DESCR, and PLIST
templates for each SUBPACKAGE (and optional distinct MESSAGE, UNMESSAGE
files in a similar way).
This contrasts with the
.Ev FLAVORS
situation, where all these files will automatically default to the
non-flavor version if there is no flavor-specific file around.
.Sh OBSOLETE TARGETS
.Bl -tag -width Ds
.It Cm addsum
Used for direct fiddling with
.Pa distinfo ,
made obsolete by the correct use of
.Ev SUPDISTFILES .
.It Cm cdrom-packages , ftp-packages
Links are now created during the
.Cm package
target.
.It Cm depends-list
Renamed into
.Cm full-build-depends .
.It Cm describe
Prints a one-line index entry of the port.
.Cm dump-vars
provides much more accurate information, and the indexing role
has been taken over by the
.Pa sqlports
and
.Pa portslist
packages.
.It Cm {build,run,lib}-depends
The dependency mechanism now meshes
.Ev BUILD_DEPENDS , LIB_DEPENDS , RUN_DEPENDS, WANTLIB
and
.Ev MULTI_PACKAGES .
Refer to
.Cm prepare , install-depends , test-depends .
.It Cm {pre,do}-extract
Don't override.
Set
.Ev EXTRACT_ONLY
to nothing and override
.Cm post-extract
instead.
.It Cm {pre,do,post}-fetch
These prevented bulk mechanisms from running properly.
.It Cm {pre,do,post}-package
There is no port that requires special treatment during packaging,
as
.Cm {pre,do,post}-install
should take care of every necessity.
.It Cm fetch-list , mirror-distfiles , fetch-makefile , mirror-maker , mirror-maker-fetch
Use
.Cm dpb Fl F
instead, see
.Xr mirroring-ports 7 .
.It Cm obj
Starting with
.Ox 3.3 ,
using
.Ev WRKOBJDIR
no longer creates a symlink between the current directory and
a subdirectory of ${WRKOBJDIR}, so
.Cm obj
is no longer applicable.
.It Cm print-depends
Use
.Cm print-build-depends
and
.Cm print-run-depends
instead.
.It Cm print-depends-list
Renamed into
.Cm print-build-depends .
.It Cm print-package-depends
Renamed into
.Cm print-run-depends .
.It Cm print-package-signature
Renamed into
.Cm print-update-signature .
.It Cm readme , readmes
replaced by the
.Pa databases/ports-readmes
port, using the Template Toolkit
.Po
.Pa textproc/p5-Template
.Pc
instead of hand-coded substitutions.
.El
.Sh OBSOLETE VARIABLES
.Bl -tag -width Ds
.It Ev BIN_PACKAGES
Old user settings.
The infrastructure always trusts the repository to contain correct packages.
So, if the package name did not change and if it exists in the repository,
it will not be rebuilt without manual user action.
.It Ev CATn
List of formatted manpages, per section.
.It Ev CATPREFIX
Location for storing formatted manpages.
Derived directly from
.Ev PREFIX .
.It Ev CDROM_PACKAGES
Old user settings.
Base location where packages suitable for a CD-ROM (see
PERMIT_PACKAGE_CDROM) will be placed.
Now hardwired to
.Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/cdrom .
.It Ev COMMENT
Used to be the name of the comment file for a package.
It now holds the comment itself.
Some magic has been put in to allow for a seamless transition.
.It Ev CONFIGURE_SHARED
Used to default to --enable-shared or --disable-shared, depending on whether
the architecture supported shared libraries.
.It Ev DESCR_SRC
From
.Nx .
This is DESCR.
.Ox
does not give a specific name to the generated file.
It is not recommended to try to access it directly.
.It Ev EXTRACT_AFTER_ARGS
Was used to cobble together the normal extraction command, as
${EXTRACT_CMD} ${EXTRACT_BEFORE_ARGS} ${EXTRACT_AFTER_ARGS}.
Use
.Ev EXTRACT_CASES
instead.
.It Ev EXTRACT_BEFORE_ARGS
Likewise, use
.Ev EXTRACT_CASES
instead.
.It Ev EXTRACT_CMD
Likewise, use
.Ev EXTRACT_CASES
instead.
.It Ev FETCH_BEFORE_ARGS , FETCH_AFTER_ARGS
Set
.Ev FETCH_CMD
to point to a script that does any required special treatment instead.
.It Ev FETCH_DEPENDS
Used to specify dependencies that were needed to fetch files.
It is much easier to mirror locally weird distribution files.
.It Ev FTP_PACKAGES
User settings.
Base location where packages suitable for FTP (see
PERMIT_PACKAGE_FTP) will be placed.
Now hardwired to
.Pa ${PACKAGE_REPOSITORY}/${MACHINE_ARCH}/ftp .
.It Ev GNU_CONFIGURE
Use
.Ev CONFIGURE_STYLE
instead.
.It Ev HAS_CONFIGURE
Use
.Ev CONFIGURE_STYLE
instead.
.It Ev IGNOREFILES
Set to the list of files that can't be checksummed.
All uses of it have led to postponing the correct action: talking
to the software author and getting him to provide versioned archives.
.It Ev MANn
List of unformatted manpages, per section.
.It Ev MANPREFIX
Location for storing unformatted manpages.
Derived directly from
.Ev PREFIX .
.It Ev MASTERDIR
From
.Fx .
Used to organize a collection of ports that share most files.
.Ox
uses a single port with flavors or multi-packages to produce
package variations instead.
.It Ev MASTER_SITE_SUBDIR
Contents were used to replace
.Sq %SUBDIR%
in all
.Ev MASTER_SITES
variables.
Since
.Sq %SUBDIR%
almost always occur at the end of the directory,
the simpler
.Li ${VARIABLE:=subdir/}
construct is now used instead
.Po
taken from
.Nx
.Pc .
.It Ev MD5_FILE
Use
.Ev CHECKSUM_FILE
instead.
.It Ev MIRROR_DISTFILE
Use
.Ev PERMIT_DISTFILES_FTP
to determine which files can be mirrored instead.
See
.Xr mirroring-ports 7 .
.It Ev NEED_VERSION
Used to set a requirement on a specific revision of
.Nm
needed by a port.
No longer needed as
.Nm
should always be kept up to date.
.It Ev NO_CONFIGURE
If ${CONFIGURE_SCRIPT} does not exist, no automatic configuration will
be done anyway.
.It Ev NO_DESCRIBE
All ports should generate a description.
.It Ev NO_EXTRACT
Set EXTRACT_ONLY= instead.
.It Ev NO_INSTALL_MANPAGES
Use
.Ev CONFIGURE_STYLE
instead.
.It Ev NO_MTREE
Starting with
.Ox 2.7 ,
the operating system installation script runs the /usr/local specification
globally, instead of embedding it in each package.
So packages no longer record an
.Xr mtree 8
specification.
Use an explicit
.Sq @exec
command if needed.
.It Ev NO_PACKAGE
All ports should generate a package, preferably before install.
.It Ev NO_PATCH
The absence of a patches directory does the same.
Use PATCHDIR and PATCH_LIST if patches need to be changed dynamically.
.It Ev NO_SHARED_ARCHS
Used to be set to the list of platforms that did not support shared libraries.
No such architectures remain.
.It Ev NO_SHARED_LIBS
Used to be set to
.Sq Yes
if platform did not support shared libraries.
.It Ev NO_WRKDIR
All ports should have a working directory, as this is necessary to store
cookies and keep state.
.It Ev NO_WRKSUBDIR
The same functionality is obtained by setting WRKDIST=${WRKDIR} .
.It Ev NOCLEANDEPENDS
Use CLEANDEPENDS instead.
.It Ev NOMANCOMPRESS
.Fx
ships with compressed man pages, and uses this variable to control
that behavior.
.It Ev OBJMACHINE
Starting with
.Ox 3.3 ,
setting
.Ev WRKOBJDIR
creates the whole
.Ev WRKDIR
hierarchy under ${WRKOBJDIR}, so
.Ev OBJMACHINE
is no longer useful.
.It Ev OLD_WRKDIR_NAME
Used to be a base name for
.Ev WRKDIR
in the old scheme without
.Ev WRKOBJDIR .
.It Ev OPSYS
The operating system.
This ports tree is only used on
.Ox .
.It Ev OPSYS_VER
Use
.Ev OSREV
instead.
.It Ev PACKAGES
Base location for packages built, everything is based on
.Ev PACKAGE_REPOSITORY
now.
.It Ev PACKAGING
Used to be set during package creation, so that the port would test it
to tweak some settings at this point.
All its effects are now achieved through
.Ev MULTI_PACKAGES .
.It Ev PATCH_SITES
.Ev PATCHFILES
used to be retrieved from a separate site list.
For greater flexibility, all files are now retrieved from
.Ev MASTER_SITES ,
.Ev MASTER_SITES0 , ... ,
.Ev MASTER_SITES9 ,
using a
.Sq :0
to
.Sq :9
extension to the file name, e.g.,
.Bd -literal -offset indent
PATCHFILES=foo.diff.gz
PATCH_SITES=ftp://ftp.zoinx.org/pub/
.Ed
.Pp
becomes
.Bd -literal -offset indent
PATCHFILES=foo.diff.gz:0
MASTER_SITES0=ftp://ftp.zoinx.org/pub/
.Ed
.It Ev PERMIT_DISTFILES_CDROM
The
.Ox
project does not ship distfiles on cdrom.
Concentrate on real questions instead, make sure
.Ev PERMIT_PACKAGE_CDROM
is set correctly.
.It Ev PKG_CMD
Replaced by
.Ev PKG_CREATE .
.It Ev PKGREPOSITORY
Old user settings.
See
.Ev PACKAGE_REPOSITORY .
.It Ev PKGREPOSITORYBASE
Old user settings.
See
.Ev PACKAGE_REPOSITORY .
.It Ev PLIST_SRC
From
.Nx .
This is PLIST.
.Ox
does not give a specific name to the generated file.
It is not recommended to try to access them directly.
.It Ev PKGNAME
Used to refer to the full package name, has been superseded by
.Ev FULLPKGNAME-foo ,
for
.Ev SUBPACKAGE
-foo .
.Ev PKGNAME
now holds the package name, not taking multi-packages or flavors
into account.
Most ports are not concerned by this change.
.It Ev PLIST_SUBST
From
.Nx
and
.Fx .
Use SUBST_VARS instead.
.Ox
does not allow general substitutions of the form VAR=value, but uses
only a list of variables instead.
Most package files gets transformed, instead of only the packing list.
.It Ev PREFERRED_CIPHERS
Allowing user change of cryptographic digest is dangerous.
.It Ev RECURSIVE_FETCH_LIST
No longer needed with modern
.Xr mirroring-ports 7 .
.It Ev RESTRICTED
Port has cryptographic issues.
.Ox
focuses on
.Ev PERMIT_PACKAGE_{FTP,CDROM}
instead.
.It Ev SED_PLIST
Old pipeline for creating packing-lists at the ports level.
Necessary functionality has been integrated directly into
.Xr pkg_create 1 .
.It Ev SIGNING_PARAMETERS
Old user settings.
There is no longer any benefit to signing packages during creation.
.It Ev SCRIPTDIR
Old location for scripts related to the current port.
There is no reason for the semantic distinction, use
.Ev FILESDIR
for those.
.It Ev SCRIPTS_ENV
Used to contain the environment for invoking various scripts.
.Ev CONFIGURE_ENV
and
.Ev MAKE_ENV
are enough.
.It Ev SHARED_ONLY
Had to be set to
.Sq Yes
if port could only be built on architectures with shared libraries.
.It Ev USE_AUTOCONF
Use
.Ev CONFIGURE_STYLE
instead.
.It Ev USE_BZIP2
The framework will automatically detect the presence of
.Pa .tar.bz2
files to extract.
See also
.Ev BZIP2 , EXTRACT_CASES ,
and
.Ev EXTRACT_SUFX .
.It Ev USE_IMAKE
Use
.Ev CONFIGURE_STYLE
instead.
.It Ev USE_ZIP
The framework will automatically detect the presence of
.Pa .zip
files to extract.
See also
.Ev ZIP , EXTRACT_CASES ,
and
.Ev EXTRACT_SUFX .
.It Ev VARNAME
Use make show=name instead of make show VARNAME=name.
.It Ev WRKPKG
Directory used to build package information from the templates under
.Pa ${PKGDIR} .
This information is now built on the fly by
.Xr pkg_create 1 .
.El
.Sh OBSOLETE FILES
.Bl -tag -width Ds
.It Pa {files,patches,pkg}.${ARCH}
Offensive to introspection, makes it impossible to build a decent sqlports
on a given arch.
Hasn't been used for a long time, and there are lots of mechanisms such as
.Ev PKG_ARGS
and fragment substitution, or
.Ev PATCH_LIST
to achieve similar results.
.It Pa Makefile.${ARCH}
Likewise, offensive to introspection too.
.It Pa ${FILESDIR}/md5
Renamed to
.Pa distinfo
to match other
.Bx ,
and save directories.
.It Pa ${SCRIPTDIR}/{pre,do,post}-*
Identical functionality can be obtained through a
.Cm {pre,do,post}-*
target, invoking the script manually if necessary.
.It Pa ${SCRIPTDIR}/configure
No longer invoked automatically.
Just inline the instructions in
.Cm do-configure
in the Makefile, or put the script in ${FILESDIR} and
invoke it.
.It Pa ${PKGDIR}/COMMENT
Use COMMENT variable instead.
.It Pa ${PKGDIR}/DEINSTALL*
Use @unexec annotations in the packing-list instead.
.It Pa ${PKGDIR}/INSTALL*
Use @exec annotations in the packing-list instead.
.It Pa ${PKGDIR}/PLIST.{noshared,no-shared,shared}
Packaging list fragments to handle platforms that did not support
shared libraries.
.It Pa ${PKGDIR}/PLIST.sed
Use PLIST directly.
Until revision 1.295,
.Nm
did not substitute variables in the packing list unless this special form
was used.
.It Pa ${PKGDIR}/REQ*
Old requirement script.
Was mostly unused anyway.
.It Pa /usr/share/mk/bsd.port.mk
Original location of
.Nm .
The current file lives under
.Pa ${PORTSDIR}/infrastructure/mk/bsd.port.mk ,
whereas
.Pa /usr/share/mk/bsd.port.mk
is just a stub.
.It Pa {scripts,files,patches}.${OPSYS}
The
.Ox
ports tree focuses on robustness, not on being portable to other operating
systems.
In any case, portability should not need to depend on operating
system dependent patches.
.It Pa /usr/local/etc
Used by
.Fx
to marshall system configuration files.
All
.Ox
system configuration files are located in
.Pa /etc ,
or in a subdirectory of
.Pa /etc .
.El
.Sh SEE ALSO
.Xr ftp 1 ,
.Xr pkg_add 1 ,
.Xr pkg_create 1 ,
.Xr OpenBSD::Intro 3p ,
.Xr bsd.port.arch.mk 5 ,
.Xr mk.conf 5 ,
.Xr port-modules 5 ,
.Xr library-specs 7 ,
.Xr mirroring-ports 7 ,
.Xr packages-specs 7 ,
.Xr pkgpath 7 ,
.Xr ports 7
.Sh HISTORY
The ports mechanism originally came from
.Fx .
A lot of additions were taken from
.Nx
over the seminal years.
.Pp
Since 1998, the framework has been systematically cleaned-up and reorganized
to remove bugs.
New features have been carefully introduced, trying hard to avoid
inconsistencies.
.Pp
.Ev FLAVORS ,
.Ev MULTI_PACKAGES ,
.Ev SEPARATE_BUILD
and FAKE are
.Ox
improvements.
Most recent additions do not come from another
.Bx .
.\" Voluntarily undocumented:
.\" AUTOCONF_ENV: probably not needed anyway, should be internal.
.Sh BUGS AND LIMITATIONS
.Ev LOCALBASE ,
.Ev X11BASE ,
.Ev BASESYSCONFDIR ,
.Ev VARBASE
and
.Ev PREFIX
are not heeded consistently.
Using anything but the default values has not been heavily tested.
Some ports may not build if you change them.