path: root/share/man/man5/bsd.port.mk.5

.\" $OpenBSD: bsd.port.mk.5,v 1.11 2000/07/11 13:06:46 espie Exp $
.\"
.\" Copyright (c) 2000 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 June 10 2000
.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
holds all the standard routines used by the ports tree.  Some variables
and targets are for its internal use only.  The rest is documented here.
.Pp
Other BSD, and older versions of
.Nm
included other targets and variables. Conversion methods are outlined here.
.Pp
This is an incomplete draft, most variables and targets are not yet
documented.
.Sh TARGETS
.Bl -tag -width do-configure
.It Ar build , Ar all
Default target. Build the port. Essentially invoke
.Bd -literal -offset indent
    env -i ${MAKE_ENV} ${MAKE_PROGRAM} ${MAKE_FLAGS} -f ${MAKE_FILE} ${ALL_TARGET}
.Ed
.It Ar configure
Configure the port. Might be a no operation. Unless overridden,
configure creates the ${WRKBUILD} directory (see SEPARATE_BUILD), runs
${SCRIPTDIR}/configure if it exists, and runs whatever configuration
methods are recorded in
.Ev CONFIGURE_STYLE .
.It Ar distpatch
Apply distribution patches only.
.It Ar do-patch
Override for the default behavior of
.Ar patch .
It is usually better to override
.Ar post-patch ,
as
.Ar patch
needs to invoke
.Ar distpatch
directly for historical reasons.
.It Ar extract
Extract the distfiles (but see
.Ev EXTRACT_ONLY ).
.It Ar fake
Do a fake port installation, that is, simulate the port installation under
${WRKINST}.  Described in a separate section below.
.It Ar fetch
Fetch the distfiles and patchfiles.
.It Ar patch
Apply distribution and
.Ox
specific patches.
.It Ar show
Invoked with VARNAME=name, show the contents of VARNAME.  Mostly used from
recursive makes, or to know the contents of another port's variables
without guessing wrong.
.El
.Sh VARIABLES
.Bl -tag -width MASTER_SITES
.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 ARCH
Current machine architecture (read-only).
.It Ev AUTOCONF
Location of the autoconf binary if needed. Defaults to autoconf (though maybe
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 BSD_INSTALL_{PROGRAM,SCRIPT,DATA,MAN}[_DIR]
Macros passed to make and configure invocations. Set based on corresponding
INSTALL_* variables.
.It Ev BUILD_DEPENDS
List of other ports the current port needs to build correctly.
Each item has the form
.Sq file_to_test::directory[:target] .
The double :: is designed to allow wedging a package specification in the
near future.
.Sq target
defaults to
.Sq install
if it is not specified.
.Sq file_to_test
is checked against the current path, or as an absolute
file name. The special name /nonexistent can be used to force a build
dependency (see the ghostscript port for an example).
.Sq directory
is set relative to ${PORTSDIR}.
Build dependencies are checked at the beginning of the extract stage.
.It Ev CDROM_PACKAGES
Base location where packages suitable for a CDROM (see
PERMIT_PACKAGE_CDROM) will be placed
(default: ${PORTSDIR}/cdrom-packages/${ARCH})
.It Ev CFLAGS
Default flags passed to the compiler for building. Many ports ignore it.
See also
.Ev COPTS .
.It Ev CHECKSUM_FILE
Location for this port checksums, used at
.Ar checksum
stage. Defaults to ${FILESDIR}/md5.
.It Ev CLEANDEPENDS
If set to
.Sq Yes
.Sq make clean
will also clean dependencies. Note that distclean  never recurses down to
dependencies.
.It Ev COMMENT
File used as a comment for the package, and in the INDEX. Set to
${PKGDIR}/COMMENT by default (with corrections for multi-packages and flavors).
If COMMENT starts with a dash, this is a literal string instead. This can
be used to leave a stub Makefile for removed ports and have a complete
INDEX entry without needing more files.
.It Ev CONFIGURE_SCRIPT
Set to name of script invoked by
.Ar configure
target, if appropriate. Should be relative to ${WRKSRC}.
.It Ev CONFIGURE_SHARED
Set to --enable-shared or --disable-shared, depending whether the
architecture supports shared libraries.
Append to CONFIGURE_ARGS, for ports that build dynamic libraries and
whose configure script supports those options.
.It Ev CONFIGURE_STYLE
Set to style of configuration that needs to happen.
If
.Sq perl ,
assume
.Xr perl 1
.Xr ExtUtils::MakeMaker 3p
style.
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.
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.
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.
If
.Sq simple ,
there is a configure script, but it does not fit the normal gnu configure
conventions.
.It Ev COPTS
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 DIST_SUBDIR
Optionally subdirectory of ${DISTDIR} where the current port's distfiles
and patchfiles will be located. See target fetch.
.It Ev ECHO_MSG
Used to display
.Sq ===> Configuring for foo
and similar informative messages. Override to turn off, for instance.
.It Ev FAKE
Automatically set to
.Sq Yes
for most ports (and all new ports). Indicates that the port, using
.Ev FAKE_FLAGS
magic, will properly fake installation into ${WRKINST}, to be packaged
and properly installed from the package.  Set to
.Sq No
in very rare cases, and during port creation.
.It Ev FAKE_FLAGS
Flags passed to ${MAKE_PROGRAM} on fake invocation. By default,
DESTDIR=${WRKINST}. If CONFIGURE_STYLE involves gnu, adds
AM_MAKEFLAGS='DESTDIR=${WRKINST}' to take automatic care of recent automaker
recursive issues.
.It Ev FETCH_DEPENDS
See BUILD_DEPENDS for specification.  Fetch dependencies are checked at
the beginning of the extract stage. No current port uses FETCH_DEPENDS.
.It Ev FILESDIR
Location of other files related to the current ports. Holds at least the
checksum file, and sometimes other files (default: files.${ARCH} or files).
.It Ev FLAVOR
The port 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 FLAVOR into
a canonical order to build the package name, or to select the packing-list,
and as a quick validity check.
.It Ev FTP_PACKAGES
Base location where packages suitable for ftp (see
PERMIT_PACKAGE_FTP) will be placed
(default: ${PORTSDIR}/ftp-packages/${ARCH})
.It Ev GMAKE
Location of the gnu make binary, if needed. Defaults to gmake.
.It Ev LIB_DEPENDS
Libraries this port depends upon. Similar to BUILD_DEPENDS, except that
.Sq file_to_test
is replaced by a
.Sq lib_spec
of the form:
.Sq libname.[version.[subversion]] .
See BUGS AND LIMITATIONS as well.
.Pp
On architectures that use dynamic  libraries,
.Ev LIB_DEPENDS
is also used as a running time dependency, and recorded in the package as
such.
.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 INSTALL_{PROGRAM,SCRIPT,DATA,MAN}[_DIR]
Macros to use to install a program, a script, a man page, or data (or the
corresponding directory, respectively).
.It Ev INSTALL_TARGET
Target invoked to install the software, during fake installation.
Default is
.Sq install .
.It Ev IS_INTERACTIVE
Set to
.Sq Yes
if port needs human interaction to build. Usually implies NO_PACKAGE as
well.  Porters should strive to minimize IS_INTERACTIVE ports, by using
FLAVORS for multiple choice ports, and by postponing human intervention
to package installation time.
.It Ev LIBTOOL
Location of the libtool binary for ports that set
.Ev USE_LIBTOOL
(default: ${LOCALBASE}/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 LOCALBASE
where other ports have already been installed (default: /usr/local)
.It Ev MAINTAINER
E-mail address of the port's maintainer. Defaults to ports@openbsd.org.
.It Ev MAKE_ENV
Environment variables passed to make invocations. 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 fake stage, which uses
FAKE_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 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 MTREE_FILE
.Xr mtree 1
specification to check when creating a PLIST with the
.Ar plist
target.  By default,
.Pa ${PORTSDIR}/infrastructure/db/fake.mtree.
.It Ev NEED_VERSION
Specific revision of
.Nm
needed by this ports tree. Usually set to the current version of
.Nm
when port was built, and updated by port maintainers when needed.
.It Ev NO_SHARED_LIBS
Set to
.Sq Yes
if platform does not support shared libraries.  To be tested after
including
.Nm bsd.port.mk ,
if neither PFRAG.SHARED nor CONFIGURE_SHARED are enough.
.It Ev OPSYS
Always OpenBSD (read-only).
.It Ev OPSYS_VER
Revision number of OpenBSD (read-only).
.It Ev PACKAGES
Base location for packages built (default: ${PORTSDIR}/packages/${ARCH}).
.It Ev PATCHDIR
Location for patches applied by patch target (default: patches.${ARCH} or
patches).
.It Ev PATCH_DEBUG
If set to
.Sq Yes ,
the make patch stage will output extra debug information.
.It Ev PATCH_LIST
Wildcard pattern of patches to select under ${PATCHDIR} (default: patch-*).
Note that filenames ending in .orig, or ~ are never applied.
.It Ev PORTPATH
Path used by most shell invocations. Don't override unless really needed.
.It Ev PORTSDIR
Root of the ports tree (default: /usr/ports).
.It Ev PKGDIR
Location for packaging information (packing list, port description, port
short description). Default: pkg.${ARCH} or pkg.
.It Ev PKGNAME
Name of the created package.  Default is ${DISTNAME} for the main package,
and ${DISTNAME}${SUBPACKAGE} for multi-packages ports.  This is automatically
altered to include flavors, so it is unwise to base other variables on it.
.It Ev PREFERRED_CIPHERS
List of cryptographic ciphers to use, in order of preference. Defaults
is
.Sq sha1 rmd160 md5 .
The first cipher that matches in ${CHECKSUM_FILE} is verified.
.It Ev PREFIX
Base directory for the current port installation. Usually ${LOCALBASE},
though some ports may elect a location under /var, and some multi-packages
ports may install under several locations.
.It Ev RUN_DEPENDS
Specification of ports this port needs installed to be functional.
Same format as BUILD_DEPENDS.  The corresponding packages will be built at
.Ar install
stage, and
.Xr pkg_add 1
will take care of installing them.
.It Ev SED_PLIST
Pipeline of commands used to create the actual packing list from the
PLIST template (usually ${PKGDIR}/PLIST).
.Nm
appends to it substitution commands corresponding to the the port's
FLAVOR and variables from SUBST_VARS.
${SED_PLIST} is invoked as a pipeline after inserting PFRAG.shared fragments.
.It Ev SCRIPTDIR
Location for scripts related to the current port (default: scripts.${ARCH}
or scripts).
.It Ev SEPARATE_BUILD
Many gnu configure ports can be built in a directory distinct from the
place they were unpacked.
Set to
.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.
Set to
.Sq concurrent
if the build process does not modify anything under ${WRKSRC}.
The build process can then be run concurrently on different architectures.
Set to
.Sq flavored
if distinct flavors of the port may share a common source tree.
.It Ev SUBPACKAGE
Set to the sub package 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_VARS
Make variables whole values get substituted to create the actual package
information.  Always holds ARCH, HOMEPAGE, and PREFIX. Add other
variables as needed.
.It Ev SYSCONFDIR
Location for ports system configuration files. Defaults to /etc, should
never be set to /usr/local/etc.
.It Ev TEMPLATES
Base location for the templates used in the readme target.
.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.
Ports that need to know the WRKDIR of another port must use
cd that_port_dir && make show VARNAME=WRKDIR  for this.
Note that WRKDIR may be a symbolic link.
.It Ev WRKDIST
Subdirectory of ${WRKDIR} where the source normally unpacked. Base for all
patches (default: ${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 WRKBUILD
Subdirectory of ${WRKDIR} where the actual build occurs. Defaults to
${WRKSRC}, unless SEPARATE_BUILD is involved, in which case it is set
to an appropriate value.
.It Ev WRKPKG
Subdirectory of ${WRKBUILD} where package information gets generated.
Defaults to ${WKRBUILD}/pkg, do not override unless
.Sq pkg
conflicts with the port's conventions.
.It Ev WRKINST
Subdirectory of ${WRKDIR} where port normally installs (see
.Ar fake
target).
.It Ev WRKOBJDIR
If defined, used as a base for the actual port working directory. The real
working directory is created there, and the port ${WRKDIR} is just a link.
.It Ev X11BASE
Where X11 has been installed (default: /usr/X11R6).
.It Ev USE_GMAKE
Set to
.Sq Yes
if gnu make (${GMAKE}) is needed for correct behavior of this port.
.It Ev USE_LIBTOOL
Set to
.Sq Yes
if libtool is required for correct behavior of this port.
Add correct dependencies, and passes LIBTOOL environment variable to
scripts invocations.
.It Ev USE_MOTIF
Set to
.Sq Yes
if lesstif is needed for correct behavior of this port.
.It Ev XMKMF
Invocation of xmkmf for CONFIGURE_STYLE=imake port. Defaults to
xmkf -a -DPorts.  The -DPorts is specific to
.Ox
and is always appended.
.El
.\"
.\"
.\"
.Sh OBSOLETE TARGETS
.Bl -tag -width do-configure
.It Ar {pre,do}-extract
Don't override. Set
.Ev EXTRACT_ONLY
to nothing and override
.Ar post-extract
instead.
.It Ar fetch-list
Use the more powerful
.Ar mirror-maker
and
.Ar fetch-makefile
targets instead.
.El
.Sh OBSOLETE VARIABLES
.Bl -tag -width MASTER_SITES
.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 them directly.
.It Ev GNU_CONFIGURE
Use
.Ev CONFIGURE_STYLE
instead.
.It Ev HAS_CONFIGURE
Use
.Ev CONFIGURE_STYLE
instead.
.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 MD5_FILE
Use
.Ev CHECKSUM_FILE
instead.
.It Ev NO_CONFIGURE
If ${FILESDIR}/configure does not exist, no automatic configuration will
be done anyway.
.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 1
specification.  Use an explicit
.Sq @exec
command if needed.
.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_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 PATCH_SITES
.Ev PATCH_FILES
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
PATCH_FILES=foo.diff.gz
PATCH_SITES=ftp://ftp.zoinx.org/pub/
.Ed
.Pp
becomes
.Bd -literal -offset indent
PATCH_FILES=foo.diff.gz:0
MASTER_SITES0=ftp://ftp.zoinx.org/pub/
.Ed
.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 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 USE_AUTOCONF
Use
.Ev CONFIGURE_STYLE
instead.
.It Ev USE_IMAKE
Use
.Ev CONFIGURE_STYLE
instead.
.El
.\"
.\"
.\"
.Sh FILES
.Bl -tag -width files/md5
.It Pa ../Makefile.inc
Common Makefile fragment for a set of ports, included automatically.
.It Pa Makefile.${ARCH}
Arch-dependent Makefile fragment, included automatically.
.It Pa ${FILESDIR}/md5
Checksum file. Holds the output of
.Xr md5 1 ,
.Xr sha1 1
and
.Xr rmd160 1
for the ports ${DISTFILES} and ${PATCHFILES}.
.It Pa ${PKGDIR}/DESCR
Description for the port. Variables such as ${HOMEPAGE} will be expanded
(see SUBST_VARS). Multi-packages ports will use DESCR${SUBPACKAGE}.
.It Pa ${PKGDIR}/COMMENT
Short, one line description of the port, that is displayed by
.Xr pkg_info 1 ,
and appears in
.Pa ${PORTSDIR}/INDEX .
Name will be adjusted for flavored and multi-packages ports.
.It Pa ${PORTSDIR}/infrastructure/db/fake.mtree
Specification used for populating ${WRKINST} at the start of
.Ar fake .
Use
.Ar pre-fake
if this is incomplete.
.El
.Sh OBSOLETE FILES
.Bl -tag -width files/md5
.It Pa ${SCRIPTDIR}/{pre,do,post}-*
Identical functionality can be obtained through a {pre,do,post}-* target,
invoking the script manually if necessary.
.It Pa ${PKGDIR}/PLIST.noshared
Use PFRAG.shared or PFRAG.no-shared instead.  PLIST.noshared was too easy
to forget when updating ports.
.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 /usr/share/mk/bsd.port.mk
Original location of
.Nm .
The current file lives under ${PORTSDIR}/infrastructure/mk/bsd.port.mk,
whereas /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.
.It Pa /usr/local/etc
Used by
.Fx
to marshall system configuration files. All
.Ox
system configuration files are located in /etc, or in a subdirectory of
/etc.
.El
.\"
.\"
.\"
.Sh THE FAKE FRAMEWORK
The
.Ar fake
target is used to install the port in a private directory first, package
that false installation, so that the real installation will use the
package.

Essentially,
.Ar fake
invokes a real
.Ar install
process after tweaking a few variables.
.Pp
.Ar fake
first creates a skeleton tree under ${WRKINST}, using the
.Xr mtree 1
specification
.Pa ${PORTSDIR}/infrastructure/db/fake.mtree .
.Pp
A
.Ar 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 ports' dependencies were present).
.Pp
If {pre,do,post}-install overrides are present, they are used with some
important changes: PREFIX is set to ${WRKINST}${PREFIX}, DESTDIR is set to
${WRKINST}, and TRUEPREFIX is set to ${PREFIX}.
Essentially, old install targets work transparently, except for a need to
change PREFIX to 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 do-install override is present, the port is installed using
.Bd -literal -indent offset
    env -i ${MAKE_ENV}
    PREFIX=${WRKINST}${PREFIX} DESTDIR=${WRKINST} TRUEPREFIX=${PREFIX}
    ${MAKE_PROGRAM} ${FAKE_FLAGS} -f ${MAKE_FILE} ${FAKE_TARGET}
.Ed
.Pp
Note that this does set both PREFIX and DESTDIR. If a port's Makefile both
heeds DESTDIR, 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
Recursive makes are a problem, and will often need FAKE_FLAGS to be changed
to ensure that the right values are passed down to submakes.
.\"
.\"
.\"
.Sh FLAVORS AND MULTI_PACKAGES
Starting with
.Ox 2.7 ,
each port can generate several packages through two orthogonal mechanims:
FLAVORS and MULTI_PACKAGES.
.Pp
If a port can be compiled with several options, set FLAVORS to the list of
possible options in the Makefile.
When building the port, 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
    FLAVOR?=
    .if ${FLAVOR:L:Moption1}
    # what to do if option1
    .endif
    .if ${FLAVOR:L:Moption2}
    # what to do if option2
    .endif
.Ed
.Pp
.Pa bsd.port.mk
takes care of a few details, such as generating a distinct work directory for
each flavor, or adding a dash separated list of options to the package
name.
The order in which FLAVOR is specified does not matter: the generated list,
called the canonical package extension, matches the ordering of FLAVORS.
Also, it is an error to specify an option in FLAVOR that does not appear
in FLAVORS.
.Pp
In recursive package building, flavors can be specified as a comma
separated list after the package directory, e.g., SUBDIR+=vim,no_x11.
This is not yet supported for dependencies.
.Pp
Finally, packing information will use templates with the canonical package
extension if they are available: if FLAVOR='option1 option2' and both
DESCR and DESCR-option1-option2 are available, DESCR-option1-option2 will
be used.
.Pp
If a port can generate several useful packages, set MULTI_PACKAGES
accordingly.
Each extension of a MULTI_PACKAGES name should start with a dash, so that
they cannot be confused with FLAVORS.
MULTI_PACKAGES only affects the actual package building step (and the
describe step, since a MULTI_PACKAGES port will produce several
descriptions).
.Pp
Apart from the main package, created by default, each element of
MULTI_PACKAGES triggers a recursive make package, with SUBPACKAGE set to the
right value.
For instance, if MULTI_PACKAGES=-lib -server,
make package will work as follows:
.Bl -bullet -compact
.It
Run make package SUBPACKAGE=-lib,
.It
Run make package SUBPACKAGE=-server,
.It
Build the main package, by running make package SUBPACKAGE=''
.El
.Pp
The port's Makefile can test the value of SUBPACKAGE to specialize
processing for all sub packages. All packing information is derived from
templates with SUBPACKAGE appended. In the preceding example, the
packing-list template for pkgname-foo must be in PLIST-foo.
.Pp
It is currently not possible to have a subpackage depend on the main
package, except by inserting an explicit
.Li "@pkgdep"
command into the packing-list.
.Sh THE GENERATION OF PACKING INFORMATION
Starting after
.Ox 2.7
(around revision 1.300 of bsd.port.mk), all packing information is
generated from templates in ${PKGDIR}.

.Bl -bullet -compact
.It
If not overriden by the user, determine which set of templates to use,
depending on the current SUBPACKAGE and FLAVOR information.
Set ${PLIST}, ${DESCR}, ${COMMENT}, ${MESSAGE} accordingly.
.It
Detect the existence of ${PKGDIR}/{REQ,INSTALL,DEINSTALL}${SUBPACKAGE}.
Modify PKG_ARGS accordingly, to use the generated files, and add
dependencies to regenerate the files if the templates change.
.It
Generate the actual DESCR, and if needed, MESSAGE, REQ, INSTALL, DEINSTALL
from the templates in ${DESCR}, ${MESSAGE}, ${PKGDIR}/REQ${SUBPACKAGE},
${PKGDIR}/INSTALL${SUBPACKAGE}, ${PKGDIR}/DEINSTALL${SUBPACKAGE}, by
substituting the variables in ${SUBST_VARS}, and by substituting
${FLAVORS} with the canonical flavor extension for this port,
e.g, if FLAVORS=no_map gfx qt2, if FLAVOR=gfx no_map, this is
.Sq -no_map-gfx .
.It
Generate the actual PLIST from the template ${PLIST},
by inserting shared/no-shared fragments, applying a possible user-supplied
pipeline, merging other fragments, applying the same variable
substitutions as other packing information, and finally handling
dynamic libraries macros.
.El
.Pp
Note that ${COMMENT} is currently not substituted, to speed up
.Ar describe
generation.
.Pp
To avoid substitution, variables can be escaped as follows:
.Li "$\e{PREFIX}"
.Pp
Constructs such as the line
.Li "%%SHARED%%"
or
.Li "%%!SHARED%%"
in the packing-list template trigger the inclusion of the
.Pa ${PKGDIR}/PFRAG.shared${SUBPACKAGE}
or
.Pa ${PKGDIR}/PFRAG.no-shared${SUBPACKAGE} .
.br
Similarly, if FLAVORS lists flav1, then the line
.Li "%%flav1%%"
(resp.
.Li "%%!flav1%%" )
will  trigger the inclusion of
.Pa ${PKGDIR}/PFRAG.flav1${SUBPACKAGE}
(resp.
.Pa ${PKGDIR}/PFRAG.no-flav1${SUBPACKAGE} )
in the packing-list. Fragments that cannot be handled by these simple rules
can always be specified in a custom SED_PLIST.
.Pp
The constructs
.Li "DYNLIBDIR(directory)"
and
.Li "NEWDYNLIBDIR(directory)"
should be used in
.Pa ${PKGDIR}/PFRAG.shared${SUBPACKAGE}
to register directories that hold dynamic libraries (see
.Xr ldconfig 8 ).
.Li "NEWDYNLIBDIR"
is meant for directories that will go away when the package is deleted.
.Pp
The special
.Ar plist
target does a fairly good job of automatically generating PLIST-auto and
PFRAG.shared-auto fragments.
.Pp
In MULTI_PACKAGES mode, there must be separate COMMENT, DESCR, and PLIST
templates for each SUBPACKAGE (and optional distinct MESSAGE, REQ, INSTALL,
DEINSTALL files in a similar way).  This contrasts with the FLAVORS
situation, where all these files will automatically default to the
non-flavor version if there is no flavor-specific file around.
.\"
.\"
.\"
.Sh BUGS AND LIMITATIONS
.Ev LOCALBASE ,
.Ev X11BASE
and
.Ev PREFIX
are not heeded consistently. Most of the ports tree will probably fall
apart if one tries to build/use stuff elsewhere.
.Pp
.Ev LIB_DEPENDS
is automatically both a BUILD_DEPENDS and a RUN_DEPENDS, whereas some
smarter, more intricate mechanism could be designed to minimize dependencies.
.Sh HISTORY
The ports mechanism originally came from
.Fx .
A lot of additions were taken from
.Nx
over the years.
.Pp
When the file grew too large, Marc Espie cleaned it up to restore some of
its speed and remove a lot of bugs.
.Pp
FLAVORS, MULTI_PACKAGES and FAKE are
.Ox
improvements.

.\" Voluntarily undocumented:
.\" AUTOCONF_ENV: probably not needed anyway, should be internal.