BSD.PORT.MK(5)            OpenBSD Programmer's Manual           BSD.PORT.MK(5)

NAME
     bsd.port.mk - ports tree master Makefile fragment

SYNOPSIS
     #include <bsd.port.mk>

DESCRIPTION
     bsd.port.mk holds all the standard routines used by the ports tree.  Some
     variables and targets are for its internal use only.  The rest is docu-
     mented here.

     Other BSD variants, as well as older versions of bsd.port.mk, include
     other targets and variables.  Conversion methods are outlined here.

     This is still incomplete; some variables and targets are not yet docu-
     mented.  Mostly because undocumented stuff has fuzzy semantics, and it
     hasn't been decided yet how to define it.

TARGETS
     addsum        Complete the ${CHECKSUM_FILE} record of checksums with
                   files that have been added since makesum. Complain if any-
                   thing does not match.

     build, all    Default target.  Build the port.  Essentially invoke

                   env -i ${MAKE_ENV} ${MAKE_PROGRAM} ${MAKE_FLAGS} \

                           -f ${MAKE_FILE} ${ALL_TARGET}

     checkpatch    Debugging version of the patch target that simulates invok-
                   ing patch(1).

     checksum      Check distribution archives and distribution patches con-
                   trol sum against the results recorded in ${CHECKSUM_FILE},
                   using the cryptographic signature utilities listed in
                   ${PREFERRED_CIPHERS}.  Normally ${ALLFILES} are check-
                   summed, unless IGNOREFILES is set to a list of files to ig-
                   nore.  Invoking checksum with REFETCH=true will try to
                   fetch a version of with mismatched checksums off the OpenB-
                   SD main archive site.

     clean         Clean ports contents.  By default, it will clean the work
                   directory.  It can be invoked as make clean='[depends work
                   fake flavors dist install sub package packages]'.

                   work      Clean work directory.

                   depends   Recurse into dependencies.

                   flavors   Clean all work directories.

                   dist      Clean distfiles.

                   install   Uninstall package.

                   package   Remove package file.

                   sub       With install or package, clean subpackages as
                             well.

                   packages  Short-hand for `sub package'.



     configure     Configure the port.  Might be a void operation.  Unless
                   overridden, configure creates the ${WRKBUILD} directory
                   (see SEPARATE_BUILD), runs ${SCRIPTDIR}/configure if it ex-
                   ists, and runs whatever configuration methods are recorded
                   in CONFIGURE_STYLE.

     distpatch     Apply distribution patches only.

     do-patch      Override for the default behavior of patch. It is usually
                   better to override post-patch, as patch needs to invoke
                   distpatch directly for historical reasons.

     extract       Extract the distfiles under ${WRKDIST} (but see
                   EXTRACT_ONLY). Refer to EXTRACT_CASES for a complete de-
                   scription.

     fake          Do a fake port installation, that is, simulate the port in-
                   stallation under ${WRKINST}.  Described in a separate sec-
                   tion below.

     fetch         Fetch the distfiles and patchfiles.  Each file of the
                   DISTFILES and PATCHFILES lists is retrieved, if necessary,
                   from the list of sites in MASTER_SITES, with %SUBDIR% sub-
                   stituted with MASTER_SITE_SUBDIR. If a filename ends with a
                   `:0' to `:9' extension, it will be retrieved from
                   MASTER_SITES0 to MASTER_SITES9 instead.  The ports frame-
                   work uses ${DISTDIR}/${DIST_SUBDIR} (aliased to
                   ${FULLDISTDIR}) to cache the ports distribution files and
                   patch files.  Note that this framework is also used by mir-
                   roring scripts, which will also retrieve SUPDISTFILES, to
                   fill with supplementary distribution files which are not
                   needed for every configuration.  See ALLFILES, CDROM_SITE,
                   DISTDIR, DISTFILES, DIST_SUBDIR, FETCH_SYMLINK_DISTFILES,
                   FULL_DISTDIR, MASTER_SITES, MASTER_SITES0, ...,
                   MASTER_SITES9, PATCH_FILES, SUPDISTFILES, REFETCH.

     makesum       Create the ${CHECKSUM_FILE} list of recorded checksums by
                   running the cryptographic fingerprints sha1, md5 and rmd160
                   on ${ALLFILES} minus ${IGNOREFILES}.

     patch         Apply distribution and OpenBSD specific patches.  Because
                   of historical accident, patch does not follow the exact
                   same scheme other standard targets do.  Namely, patch in-
                   vokes pre-patch (if defined), do-patch, and post-patch, but
                   the default do-patch target recurses through distpatch So,
                   if the do-patch target is overridden, it should still begin
                   by calling make distpatch, before applying OpenBSD specific
                   patches.  See distpatch for the distribution patches-spe-
                   cific description.  If ${PATCHDIR} exists, the files de-
                   scribed under PATCH_LIST will be applied under WRKDIST.

     rebuild       Force rebuild of the port.

     regress       Run regression tests for the port.  Essentially depend on a
                   correct build and invoke

                   env -i ${MAKE_ENV} ${MAKE_PROGRAM} ${REGRESS_FLAGS} \

                           -f ${MAKE_FILE} ${REGRESS_TARGET}
                   If a port needs some other ports installed to run regres-
                   sion tests, use REGRESS_DEPENDS. If a port needs special
                   configuration or build options to enable regression test-
                   ing, define a `regress' FLAVOR.

     show          Invoked as show=name, show the contents of ${name}.  Mostly
                   used from recursive makes, or to know the contents of an-
                   other port's variables without guessing wrong.

VARIABLES
     show          Invoked as make show=name, show the contents of variable
                   name.

     ALLFILES      List of all files that need to be retrieved by fetch, with
                   master site selection extension removed.  Read-only.

     ALL_TARGET    Target used to build software.  Default is `all'. Can be
                   set to empty, to yield a package's default target.

     ARCH          Current machine architecture (read-only).

     AUTOCONF      Location of the autoconf binary if needed.  Defaults to au-
                   toconf (though make autoreconf might be more appropriate).

     AUTOCONF_DIR  Where to invoke autoconf if ${CONFIGURE_STYLE} includes au-
                   toconf.  Defaults to ${WRKSRC}.

     BSD_INSTALL_{PROGRAM,SCRIPT,DATA,MAN}[_DIR]
                   Macros passed to make and configure invocations.  Set based
                   on corresponding INSTALL_* variables.

     BUILD_DEPENDS
                   List of other ports the current port needs to build cor-
                   rectly.  Each item has the form
                   `[legacy]:[pkgspec]:directory[,-subpackage][,flavor
                   ...][:target]'. `target' defaults to `install' if it is not
                   specified.  `legacy' used to be a file to check.  The ports
                   tree now uses `pkgspec' instead, as a package that must be
                   installed prior to the build.  `directory' is set relative
                   to ${PORTSDIR}.  `subpackage' is an optional subpackage
                   name, to install instead of the default main package name.
                   `flavor ...' is a comma separated list of flavors.  By de-
                   fault, the dependency will build the default flavor.  Build
                   dependencies are checked at the beginning of the extract
                   stage.

     BZIP2         Name of the bzip2 binary.

     CATEGORIES    List of descriptive categories into which this port falls.
                   Mandatory.  See link-categories, unlink-categories.

     CDROM_PACKAGES
                   Base location where packages suitable for a CDROM (see PER-
                   MIT_PACKAGE_CDROM) will be placed (default: ${PORTS-
                   DIR}/cdrom-packages/${ARCH})

     CDROM_SITE    Path to a local database that holds distribution files
                   (usually a CD-Rom or other similar media), used to retrieve
                   distribution files before going to the network.  Defaults
                   to /cdrom/distfiles if this path exists.  Distribution
                   files are still copied or linked (see
                   FETCH_SYMLINK_DISFILES) into DISTDIR if they are found un-
                   der CDROM_SITE.

     CFLAGS        Default flags passed to the compiler for building.  Many
                   ports ignore it.  See also COPTS.

     CHECKSUM_FILE
                   Location for this port checksums, used by addsum, checksum,
                   and makesum. Defaults to ${FILESDIR}/md5.

     CLEANDEPENDS  If set to `Yes' `make clean' will also clean dependencies.

                   Note that distclean never recurses down to dependencies.

     COMMENT       Comment used for the package, and in the INDEX.

     COMMENT-foo   Comment used for sub package foo in a multi-package set up.

     COMMENT-vanilla
                   Comment used for a flavored package, if the non-flavored
                   comment is inappropriate.

     COMMENT-foo-vanilla
                   Comment used for a sub-, flavored package.

     CONFIGURE_ARGS
                   Arguments to pass to configure script.  Defaults are empty,
                   except for gnu-style configure, where prefix and sysconfdir
                   are set.

     CONFIGURE_ENV
                   Basic environment passed to configure script (path and
                   libtool setup).  gnu-style configure adds a lot more vari-
                   ables.

     CONFIGURE_SCRIPT
                   Set to name of script invoked by configure target, if ap-
                   propriate.  Should be relative to ${WRKSRC}.

     CONFIGURE_SHARED
                   Set to --enable-shared or --disable-shared, depending
                   whether the architecture supports shared libraries.  Should
                   be appended to CONFIGURE_ARGS, for ports that build dynamic
                   libraries and whose configure script supports these op-
                   tions.

     CONFIGURE_STYLE
                   Set to style of configuration that needs to happen.  If
                   `perl', assume perl(1) ExtUtils::MakeMaker(3p) style.  If
                   `gnu', assume gnu configure style.  Add `dest' if port does
                   not handle DESTDIR correctly, and needs to be configured to
                   add DESTDIR to prefixes (see also DESTDIRNAME). Add `old'
                   if port is an older autoconf port, that does not recognize
                   --sysconfdir.  Add `autoconf' if autoconf needs to be rerun
                   first.  If `imake', assume port configures using X11 ports
                   Imakefile framework.  Add `noman' if port has no man pages
                   the Imakefile should try installing.  If `simple', there is
                   a configure script, but it does not fit the normal gnu con-
                   figure conventions.

     COPTS         Supplementary options appended to ${CFLAGS} for building.
                   Since most ports ignore the COPTS convention, they are ac-
                   tually told to use ${CFLAGS} ${COPTS} as CFLAGS.

     CXXOPTS       Supplementary options appended to ${CXXFLAGS} for building.

     DEF_UMASK     Correct value of umask for the port to build and package
                   correctly.  Tested against the actual umask at fake time.
                   Default is 022.  Don't override.

     DESTDIRNAME   Name of variable to set to ${WRKINST} while faking.  Usual-
                   ly DESTDIR.  To be used in the rare cases where a port
                   heeds DESTDIR in a few directories and needs to be config-
                   ured with `gnu dest', so that those few directories do not
                   get in the way.

     DISTDIR       Directory where all ports distfiles and patchfiles are
                   stashed.  Defaults to ${PORTSDIR}/distfiles. Override if
                   distfiles are stored elsewhere.  Always use FULLDISTDIR to
                   refer to ports' distfiles location, as it takes an eventual
                   DIST_SUBDIR into account.

     DISTFILES     The main port distribution files (the actual software
                   source, except for binary-only ports).  Will be retrieved
                   from the MASTER_SITES (see fetch), checksummed and extract-
                   ed (see checksum, extract). normally holds a list of files,
                   possibly with :0 DISTFILES normally holds a list of files,
                   possibly with `0' to `9' appended to select a different
                   MASTER_SITES. See also SUPDISTFILES.

     DISTNAME      Name used to identify the port.  See DISTFILES and PKGNAME.

     DISTORIG      Suffix used by distpatch to rename original files.  De-
                   faults to .bak.orig. Distinct from .orig to avoid confusing
                   update-patches.

     DIST_SUBDIR   Optional subdirectory of ${DISTDIR} where the current
                   port's distfiles and patchfiles will be located.  See tar-
                   get fetch.

     ECHO_MSG      Used to display `===> Configuring for foo' and similar in-
                   formative messages.  Override to turn off, for instance.

     ERRORS        List of errors found while parsing the port's Makefile.
                   Display the errors before making any target, and if any er-
                   ror starts with "Fatal:", do not make anything.  For in-
                   stance:

                   .if !defined(COMMENT)
                   ERRORS+="Fatal: Missing comment"
                   .endif

     EXTRACT_CASES
                   In the normal extraction stage (when EXTRACT_ONLY is not
                   empty), this is the contents of a case statement, used to
                   extract files.  Fragments are automatically appended to ex-
                   tract tar and zip archives, so that the default case is
                   equivalent to the following shell fragment:

                   set -e
                   cd ${WRKDIR}
                   for archive in ${EXTRACT_ONLY}
                   do
                       case $$archive in
                           *.zip)
                             unzip -q ${FULLDISTDIR}/$$archive -d ${WRKDIR};;
                           *.tar.bz2)
                             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

     EXTRACT_ONLY  Set if not all ${DISTFILES} should be extracted at do-ex-
                   tract stage.  Default value is ${DISTFILES}.

     EXTRACT_SUFX  Used to set DISTFILES default value to ${DISTNAME}${EX-

                   TRACT_SUFX}.  Default value is .tar.gz.

     FAKE          Automatically set to `Yes' for most ports (and all new
                   ports).  Indicates that the port, using FAKE_FLAGS magic,
                   will properly fake installation into ${WRKINST}, to be
                   packaged and properly installed from the package.  Set to
                   `' in very rare cases, and during port creation.

     FAKE_FLAGS    Flags passed to ${MAKE_PROGRAM} on fake invocation.  By de-
                   fault, ${DESTDIRNAME}=${WRKINST}.

     FETCH_CMD     Command used to fetch distfiles for this port.  Defaults to
                   /usr/bin/ftp. No current port overrides the default.

     FETCH_DEPENDS
                   See BUILD_DEPENDS for specification.  Fetch dependencies
                   are checked at the beginning of the extract stage.

     FETCH_SYMLINK_DISTFILES
                   Set to `Yes' to link distribution files off CDROM_DISTSITE
                   instead of copying them.

     FILESDIR      Location of other files related to the current ports.
                   Holds at least the checksum file, sometimes other files
                   (default: files.${ARCH} or files).

     FLAVOR        The port current options.  Set by the user, and tested by
                   the port to activate wanted functionalities.

     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 validi-
                   ty check.

     FLAVOR_EXT    Canonical list of flavors being set for the current build,
                   dash-separated.  See FULLPKGNAME.

     FTP_PACKAGES  Base location where packages suitable for ftp (see PER-
                   MIT_PACKAGE_FTP) will be placed (default: ${PORTSDIR}/ftp-
                   packages/${ARCH})

     FULLPKGNAME   Full name of the main created package, taking flavors into
                   account.  Defaults to ${PKGNAME}${FLAVOR_EXT}.

     FULLPKGNAME-foo
                   Full package name for sub-package foo, if the default value
                   is not appropriate.

     GMAKE         Location of the gnu make binary, if needed.  Defaults to
                   gmake.

     IGNOREFILES   Set to the list of files that cannot be checksummed.  For
                   use by ports which fetch dynamically generated archives
                   that can't be checksummed.

     LIB_DEPENDS   Libraries this port depends upon.  Each item has the form
                   `lib_specs:[pkgspec]:directory[,-subpackage][,flavor
                   ...][:target]'. Similar to BUILD_DEPENDS, except for
                   `lib_specs', which is a comma-separated list of `lib_spec'
                   of the form: `libname.[version.[subversion]]'. See BUGS AND
                   LIMITATIONS as well.

                   On architectures that use dynamic libraries, LIB_DEPENDS is
                   also used as a running time dependency, and recorded in the

                   package as such.

     FULLDISTDIR   Complete path to directory where ${DISTFILES} and ${PATCH-
                   FILES} will be located, to be used in hand-crafted extrac-
                   tion targets (read-only).

     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).

     INSTALL_TARGET
                   Target invoked to install the software, during fake instal-
                   lation.  Default is `install'.

     IS_INTERACTIVE
                   Set to `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 mul-
                   tiple choice ports, and by postponing human intervention to
                   package installation time.

     LIBTOOL       Location of the libtool binary for ports that set
                   USE_LIBTOOL (default: ${LOCALBASE}/bin/libtool).

     LIBTOOL_FLAGS
                   Arguments to pass to libtool.  If USE_LIBTOOL is set, the
                   environment variable LIBTOOL is set to ${LIBTOOL}
                   ${LIBTOOL_FLAGS}.

     LOCALBASE     where other ports have already been installed (default:
                   /usr/local)

     MAINTAINER    E-mail address with full name of the port's maintainer.
                   Defaults to ports@openbsd.org.

     MAKE_ENV      Environment variables passed to make invocations.  Sets at
                   least PATH, PREFIX, LOCALBASE, X11BASE, CFLAGS, TRUEPREFIX,
                   DESTDIR, and the BSD_INSTALL_* macros.

     MAKE_FLAGS    Flags used for all make invocations, except for the fake
                   stage, which uses FAKE_FLAGS, and for the regress stage,
                   which uses REGRESS_FLAGS.

     MAKE_FILE     Name of the Makefile used for ports building.  Defaults to
                   Makefile.  Used after changing directory to ${WRKBUILD}.

     MAKE_PROGRAM  The make program that is used for building the port.  Set
                   to ${MAKE} or ${GMAKE} depending on USE_GMAKE.  Read-only.

     MESSAGE       File recorded in the package and displayed during installa-
                   tion.  Defaults to ${PKGDIR}/MESSAGE if this file exists.
                   Leave empty if no message is needed.

     MTREE_FILE    mtree(8) specification to check when creating a PLIST with
                   the plist target.  MTREE_FILE can hold a list of file
                   names, to which ${PORTSDIR}/infrastructure/db/fake.mtree is
                   always appended.  These specifications are rooted at
                   ${WRKINST}, and are subject to SUBST_VARS substitution, to
                   ease ${PREFIX} independence.  This feature is primarily in-
                   tended for large, interconnected ports, such as the kde
                   suite, where a base package sets up a large, extra directo-
                   ry hierarchy that would make the manual checking of packing
                   lists tedious.

     MULTI_PACKAGES
                   Set to a list of package extensions for ports that create
                   multiple packages.  See "Flavors and multi-packages" below.

     NEED_VERSION  Specific revision of bsd.port.mk needed by this ports tree.
                   Usually set to the current version of bsd.port.mk when port
                   was built, and updated by port maintainers when needed.

     NOT_FOR_ARCHS
                   List of architectures on which this port does not build.
                   See also ONLY_FOR_ARCHS.

     NO_BUILD      Port does not need any build stage.

     NO_DEPENDS    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 dependen-
                   cies.

     NO_REGRESS    Port does not have any regression tests.

     NO_SHARED_ARCHS
                   Set to the list of platforms that do not support shared li-
                   braries.  Use with NOT_FOR_ARCHS.

     NO_SHARED_LIBS
                   Set to `Yes' if platform does not support shared libraries.
                   To be tested after including bsd.port.mk, if neither
                   PFRAG.shared nor CONFIGURE_SHARED are enough.

     ONLY_FOR_ARCHS
                   List of architectures on which this port builds.  Can hold
                   both processor-specific information (e.g., m68k), and more
                   specific model information (e.g., amiga).

     OPSYS         Always OpenBSD (read-only).

     OPSYS_VER     Revision number of OpenBSD (read-only).

     PACKAGES      Base location for packages built (default: ${PORTS-
                   DIR}/packages/${ARCH}).

     PATCH         Command to use to apply all patches.  Defaults to
                   /usr/bin/patch.

     PATCHORIG     Suffix used by patch to rename original files, and update-
                   patches to re-generate ${PATCHDIR}/${PATCH_LIST} by looking
                   for files using this suffix.  Defaults to .orig. For a port
                   that already contains .orig files in the ${DISTFILES}, set
                   this to something else, such as .pat.orig. See also
                   distpatch, DISTORIG.

     PATCH_CASES   In the normal distpatch stage (when PATCHFILES is not emp-
                   ty), this is the contents of a case statement, used to ap-
                   ply distribution patches.  Fragments are automatically ap-
                   pended to handle gzip'ed and bzip'ed patches, so that the
                   default case is equivalent to the following shell fragment:

                   set -e
                   cd ${FULLDISTDIR}
                   for patchfile in ${_PATCHFILES}
                   do
                       case $$patchfile in
                           *.bz2)
                             bzip2 -dc $$patchfile | ${PATCH} ${PATCH_DIST_ARGS};;
                           *.Z|*.gz)
                             gzcat $$patchfile | ${PATCH} ${PATCH_DIST_ARGS};;
                           *)
                             ${PATCH} ${PATCH_DIST_ARGS} <$$patchfile;;
                       esac
                   done

     PATCHDIR      Location for patches applied by patch target (default:
                   patches.${ARCH} or patches).

     PATCHFILES    Files to fetch from the master sites like DISTFILES, but
                   serving a different purpose, as they hold distribution
                   patches that will be applied at the patch stage.  See also
                   SUPDISTFILES.

     PATCH_ARGS    Full list of options used while applying port's patches.

     PATCH_CHECK_ONLY
                   Set to Yes by the checkpatch target.  Don't touch unless
                   the default checkpatch target needs to be redefined.  Ide-
                   ally, user-defined patch subtargets ought to test check-
                   patch.  In practice, they don't.

     PATCH_DEBUG   If set to `Yes', the patch stage will output extra debug
                   information.

     PATCH_DIST_ARGS
                   Full list of options used while applying distribution
                   patches.

     PATCH_DIST_STRIP
                   Patch option used to strip directory levels while applying
                   distribution patches.  Defaults to -p0 .

     PATCH_LIST    Wildcard pattern of patches to select under ${PATCHDIR}
                   (default: patch-*).  Note that filenames ending in .orig,
                   or ~ are never applied.  Note that PATCH_LIST can hold ab-
                   solute pathnames, for instance to share patches among simi-
                   lar ports:

                   PATCH_LIST=${PORTSDIR}/x11/kde/libs2/patches/p-* patch-*

     PATCH_STRIP   Patch option used to strip directory levels while applying
                   port's patches.  Defaults to -p0 .

     PORTPATH      Path used by most shell invocations.  Don't override unless
                   really needed.

     PORTSDIR      Root of the ports tree (default: /usr/ports).

     PKGDIR        Location for packaging information (packing list, port de-
                   scription, port short description).  Default: pkg.${ARCH}
                   or pkg.

     PKGNAME       Name of the main created package.  Default is ${DISTNAME}
                   for the main package, and ${DISTNAME} for multi-packages
                   ports.  This does not take flavors into account.  See
                   FULLPKGNAME for that.

     PKGNAME-foo   Package name for sub-package foo, if the default value of
                   ${PKGNAME}${SUBPACKAGE} is not appropriate.

     PKGPATH       Path to the current port's directory, relative to ${PORTS-
                   DIR}.  Read-only.

     PREFERRED_CIPHERS
                   List of cryptographic ciphers to use, in order of prefer-
                   ence.  Default is `sha1 rmd160 md5'. The first cipher that

                   matches in ${CHECKSUM_FILE} is verified.

     PREFIX        Base directory for the current port installation.  Usually
                   ${LOCALBASE}, though some ports may elect a location under
                   /var, and some multi-package ports may install under sever-
                   al locations.

     REFETCH       If set to true, checksum will analyze ${CHECKSUM_FILE}, and
                   try retrieving files with the correct checksum off
                   ftp.openbsd.org, in the directory
                   /pub/OpenBSD/distfiles/$cipher/$value/$file.

     REGRESS_DEPENDS
                   See BUILD_DEPENDS for specification.  Regress dependencies
                   are only checked if the regress stage is invoked.

     REGRESS_FLAGS
                   Flags to pass to ${MAKE_PROGRAM} to run the regression
                   tests.  Defaults to ${MAKE_FLAGS}.

     REGRESS_IS_INTERACTIVE
                   Set to `Yes' if port needs human interaction to run its
                   tests.

     REGRESS_TARGET
                   Target to run regression tests.  Defaults to `regress', ex-
                   cept for `perl' and `gnu' CONFIGURE_STYLE, which default to
                   `test' and `check' respectively.

     RUN_DEPENDS   Specification of ports this port needs installed to be
                   functional.  Same format as BUILD_DEPENDS.  The correspond-
                   ing packages will be built at install stage, and pkg_add(1)
                   will take care of installing them.

     SED_PLIST     Pipeline of commands used to create the actual packing list
                   from the PLIST template (usually ${PKGDIR}/PLIST).
                   bsd.port.mk appends to it substitution commands correspond-
                   ing to the port's FLAVOR and variables from SUBST_VARS.
                   ${SED_PLIST} is invoked as a pipeline after inserting
                   PFRAG.shared fragments.

     SCRIPTDIR     Location for scripts related to the current port (default:
                   scripts.${ARCH} or scripts).

     SEPARATE_BUILD
                   Many gnu configure ports can be built in a directory dis-
                   tinct from the place they were unpacked.  For some specific
                   ports, this is even mandatory.  Set to `simple' if this is
                   the case.  The ports infrastructure will generate a sepa-
                   rate ${WRKBUILD} directory in which the port will be con-
                   figured and built.  Wipe ${WRKBUILD} to start anew, but
                   skipping the extract/patch stage.  Set to `concurrent' if
                   the build process does not modify anything under ${WRKSRC}.
                   The build process can then be run concurrently on different
                   architectures.  Set to `flavored' if distinct flavors of
                   the port may share a common source tree.

     SUBPACKAGE    Set to the sub package suffix when building a package in a
                   multi-package port.  Read-only.  Used to test for dependen-
                   cies or to adjust the package name.

     SUBST_VARS    Make variables whole values get substituted to create the
                   actual package information.  Always holds ARCH, HOMEPAGE,
                   PREFIX, and SYSCONFDIR. The special construct `${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 MULTI_PACKAGES). Add other vari-
                   ables as needed.

     SUPDISTFILES  Supplementary files that need to be retrieved under some
                   specific circumstances.  For instance, a port might need
                   architecture-specific files.  SUPDISTFILES should hold a
                   list of all distfiles and patchfiles that are not always
                   needed, so that a mirror will be able to grab all files, or
                   that makesum will work.  Having an overlap between
                   SUPDISTFILES and DISTFILES, 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.

     SYSCONFDIR    Location for ports system configuration files.  Defaults to
                   /etc, should never be set to /usr/local/etc.

     TAR           Name of the tar binary.

     TEMPLATES     Base location for the templates used in the readme target.

     UNZIP         Name of the unzip binary.

     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.

     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.

     WRKDIST       Subdirectory of ${WRKDIR} where the source normally un-
                   packed.  Base for all patches (default: ${WRKDIR}/${DIST-
                   NAME}).  Note that WRKDIST may be a symbolic link, if set
                   to ${WRKDIR}.

     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}.

     WRKPKG        Subdirectory of ${WRKBUILD} where package information gets
                   generated.  Defaults to ${WKRBUILD}/pkg, do not override
                   unless `pkg' conflicts with the port's conventions.

     WRKINST       Subdirectory of ${WRKDIR} where port normally installs (see
                   fake target).

     WRKOBJDIR     If defined, used as a base for the actual port working di-
                   rectory.  The real working directory is created there, and
                   the port ${WRKDIR} is just a link.

     X11BASE       Where X11 has been installed (default: /usr/X11R6).

     USE_GMAKE     Set to `Yes' if gnu make (${GMAKE}) is needed for correct
                   behavior of this port.

     USE_LIBTOOL   Set to `Yes' if libtool is required for correct behavior of
                   this port.  Add correct dependencies, and passes LIBTOOL
                   environment variable to scripts invocations.

     USE_MOTIF     Set to `any' if port works with any version of motif;
                   `lesstif' if port requires lesstif to work; `openmotif' if
                   ports requires openmotif to work.  The `any' setting cre-
                   ates an extra flavor choice of `lesstif'.

     XMKMF         Invocation of xmkmf for CONFIGURE_STYLE=imake port.  De-
                   faults to xmkf -a -DPorts.  The -DPorts is specific to
                   OpenBSD and is always appended.

     YACC          Name of yacc program to pass to gnu-configure, defaults to
                   yacc.  (gnu-configure would always try to use bison other-
                   wise, which leads to unreproducible builds.)  Set to bison
                   if needed.

FILES
     ../Makefile.inc
                Common Makefile fragment for a set of ports, included automat-
                ically.

     /cdrom/distfiles
                Default path to a CD-Rom (or other media) full of distribution
                files.

     Makefile.${ARCH}
                Arch-dependent Makefile fragment, included automatically.

     ${DISTDIR}
                cache of all distribution files.

     ${FILESDIR}/md5
                Checksum file.  Holds the output of md5(1), sha1(1), and
                rmd160(1) for the ports ${DISTFILES} and ${PATCHFILES}.

     ${FULLDISTDIR}/${ALLFILES}
                cache of distribution files for a given port.

     ${PKGDIR}/DESCR
                Description for the port.  Variables such as ${HOMEPAGE} will
                be expanded (see SUBST_VARS).  Multi-package ports will use
                DESCR${SUBPACKAGE}.

     ${PKGDIR}/COMMENT
                Short, one line description of the port, that is displayed by
                pkg_info(1), and appears in ${PORTSDIR}/INDEX. Name will be
                adjusted for flavored and multi-packages ports.

     ${PORTSDIR}/infrastructure/db/fake.mtree
                Specification used for populating ${WRKINST} at the start of
                fake. Use pre-fake if this is incomplete.

OBSOLETE TARGETS
     {pre,do}-extract
                   Don't override.  Set EXTRACT_ONLY to nothing and override
                   post-extract instead.

     fetch-all, fetch-list, mirror-distfiles
                   See mirroring-ports(7) for more efficient and flexible ways
                   to build mirrors.

OBSOLETE VARIABLES
     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.

     DESCR_SRC     From NetBSD. This is DESCR.  OpenBSD does not give a spe-
                   cific name to the generated file.  It is not recommended to


                   try to access them directly.

     EXTRACT_AFTER_ARGS
                   Was used to cobble together the normal extraction command,
                   as ${EXTRACT_CMD} ${EXTRACT_BEFORE_ARGS} ${EXTRACT_AF-
                   TER_ARGS}.  Use EXTRACT_CASES instead.

     EXTRACT_BEFORE_ARGS
                   Likewise, use EXTRACT_CASES instead.

     EXTRACT_CMD   Likewise, use EXTRACT_CASES instead.

     USE_BZIP2     Use EXTRACT_SUFX or EXTRACT_CASES instead.

     USE_ZIP       Use EXTRACT_SUFX or EXTRACT_CASES instead.

     GNU_CONFIGURE
                   Use CONFIGURE_STYLE instead.

     HAS_CONFIGURE
                   Use CONFIGURE_STYLE instead.

     MASTERDIR     From FreeBSD. Used to organize a collection of ports that
                   share most files.  OpenBSD uses a single port with flavors
                   or multi-packages to produce package variations instead.

     MD5_FILE      Use CHECKSUM_FILE instead.

     MIRROR_DISTFILE
                   Use PERMIT_DISTFILES_FTP and PERMIT_DISTFILES_CDROM to de-
                   termine which files can be mirrored instead.  See
                   mirroring-ports(7).

     NO_CONFIGURE  If ${FILESDIR}/configure does not exist, no automatic con-
                   figuration will be done anyway.

     NO_EXTRACT    Set EXTRACT_ONLY= instead.

     NO_INSTALL_MANPAGES
                   Use CONFIGURE_STYLE instead.

     NO_MTREE      Starting with OpenBSD 2.7, the operating system installa-
                   tion script runs the /usr/local specification globally, in-
                   stead of embedding it in each package.  So packages no
                   longer record an mtree(8) specification.  Use an explicit
                   `@exec' command if needed.

     NO_PATCH      The absence of a patches directory does the same.  Use
                   PATCHDIR and PATCH_LIST if patches need to be changed dy-
                   namically.

     NO_WRKDIR     All ports should have a working directory, as this is nec-
                   essary to store cookies and keep state.

     NO_WRKSUBDIR  The same functionality is obtained by setting
                   WRKDIST=${WRKDIR} .

     NOCLEANDEPENDS
                   Use CLEANDEPENDS instead.

     NOMANCOMPRESS
                   FreeBSD ships with compressed man pages, and uses this
                   variable to control that behavior.

     PATCH_SITES   PATCHFILES used to be retrieved from a separate site list.
                   For greater flexibility, all files are now retrieved from
                   MASTER_SITES, MASTER_SITES0, ..., MASTER_SITES9, using a
                   `:0' to `:9' extension to the file name, e.g.,

                         PATCH_FILES=foo.diff.gz
                         PATCH_SITES=ftp://ftp.zoinx.org/pub/

                   becomes

                         PATCH_FILES=foo.diff.gz:0
                         MASTER_SITES0=ftp://ftp.zoinx.org/pub/

     PLIST_SRC     From NetBSD. This is PLIST.  OpenBSD does not give a spe-
                   cific name to the generated file.  It is not recommended to
                   try to access them directly.

     PKGNAME       Used to refer to the full package name, has been superseded
                   by FULLPKGNAME-foo, for SUBPACKAGE -foo .  PKGNAME now
                   holds the package name, not taking multi-packages nor fla-
                   vors into account.  Most ports are not concerned by this
                   change.

     PLIST_SUBST   From NetBSD and FreeBSD. Use SUBST_VARS instead.  OpenBSD
                   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.

     USE_AUTOCONF  Use CONFIGURE_STYLE instead.

     USE_IMAKE     Use CONFIGURE_STYLE instead.

OBSOLETE FILES
     ${SCRIPTDIR}/{pre,do,post}-*
                Identical functionality can be obtained through a
                {pre,do,post}-* target, invoking the script manually if neces-
                sary.

     ${PKGDIR}/PLIST.noshared
                Use PFRAG.shared or PFRAG.no-shared instead.  PLIST.noshared
                was too easy to forget when updating ports.

     ${PKGDIR}/PLIST.sed
                Use PLIST directly.  Until revision 1.295, bsd.port.mk did not
                substitute variables in the packing list unless this special
                form was used.

     /usr/share/mk/bsd.port.mk
                Original location of bsd.port.mk. The current file lives under
                ${PORTSDIR}/infrastructure/mk/bsd.port.mk, whereas
                /usr/share/mk/bsd.port.mk is just a stub.

     {scripts,files,patches}.${OPSYS}
                The OpenBSD 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 patch-
                es.

     /usr/local/etc
                Used by FreeBSD to marshall system configuration files.  All
                OpenBSD system configuration files are located in /etc, or in
                a subdirectory of /etc.

THE FAKE FRAMEWORK
     The 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, fake invokes a real install process after tweaking a few
     variables.

     fake first creates a skeleton tree under ${WRKINST}, using the mtree(8)
     specification ${PORTSDIR}/infrastructure/db/fake.mtree.

     A pre-fake target may be used to complete that skeleton tree.  For in-
     stance, a few ports may need supplementary stuff to be present (as it
     would be installed if the ports' dependencies were present).

     If {pre,do,post}-install overrides are present, they are used with some
     important changes: PREFIX is set to ${WRKINST}${PREFIX}, ${DESTDIRNAME}
     is set to ${WRKINST}, and TRUEPREFIX is set to ${PREFIX}.  Essentially,
     old install targets work transparently, except for a need to change PRE-
     FIX 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 in-
     stall-info).

     If no do-install override is present, the port is installed using

         env -i ${MAKE_ENV}
         PREFIX=${WRKINST}${PREFIX} ${DESTDIRNAME}=${WRKINST} TRUEPREFIX=${PREFIX}
         ${MAKE_PROGRAM} ${FAKE_FLAGS} -f ${MAKE_FILE} ${FAKE_TARGET}

     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 make(1) construct which
     will not be seen by the shell).

     ${FAKE_FLAGS} is used to set variables on 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.

FLAVORS AND MULTI_PACKAGES
     Starting with OpenBSD 2.7, each port can generate several packages
     through two orthogonal mechanisms: FLAVORS and MULTI_PACKAGES.

     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
     FLAVOR='option1 option2...' to build a specific flavor of the port.  The
     Makefile should test the value of FLAVOR as follows:

         FLAVOR?=
         .if ${FLAVOR:L:Moption1}
         # what to do if option1
         .endif
         .if ${FLAVOR:L:Moption2}
         # what to do if option2
         .endif

     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 op-
     tions 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 op-
     tion in FLAVOR that does not appear in FLAVORS.

     In recursive package building, flavors can be specified as a comma sepa-
     rated list after the package directory, e.g., SUBDIR+=vim,no_x11.

     Finally, packing information will use templates with the canonical pack-
     age extension if they are available: if FLAVOR='option1 option2' and both
     COMMENT and COMMENT-option1-option2 are available, COMMENT-option1-op-
     tion2 will be used.
     If a port can generate several useful packages, set MULTI_PACKAGES ac-
     cordingly.  Each extension of a MULTI_PACKAGES name should start with a
     dash, so that they cannot be confused with FLAVORS.  In dependency check-
     ing and recursive builds, a subpackage can be specified after a comma,
     e.g., SUBDIR+=quake,-server.  MULTI_PACKAGES only affects the actual
     package building step (and the describe step, since a MULTI_PACKAGES port
     will produce several descriptions).

     If MULTI_PACKAGES is set, each element of MULTI_PACKAGES triggers a re-
     cursive make package, with SUBPACKAGE set to the right value, and PACKAG-
     ING defined.  For instance, if MULTI_PACKAGES=-lib -server, make package
     will work as follows:

     o   Run make package SUBPACKAGE= PACKAGING=,
     o   Run make package SUBPACKAGE=-lib PACKAGING=-lib,
     o   Run make package SUBPACKAGE=-server PACKAGING=-server,

     The port's Makefile can test the value of SUBPACKAGE to specialize pro-
     cessing for all sub packages.  Note that SUBPACKAGE can also be set for
     dependency checking, so be careful to also test PACKAGING: the build
     stage is shared among all subpackages, and tests often only make sense
     during the packaging stage.  All packing information is derived from tem-
     plates with SUBPACKAGE appended.  In the preceding example, the packing-
     list template for pkgname-foo must be in PLIST-foo.

THE GENERATION OF PACKING INFORMATION
     Starting after OpenBSD 2.7 (around revision 1.300 of bsd.port.mk), all
     packing information is generated from templates in ${PKGDIR}.

     o   If not overridden by the user, determine which set of templates to
         use, depending on the current SUBPACKAGE and FLAVOR information.  Set
         ${PLIST}, ${DESCR}, ${COMMENT}, ${MESSAGE} accordingly.
     o   Detect the existence of ${PKGDIR}/{REQ,INSTALL,DEINSTALL}${SUBPACK-
         AGE}.  Modify PKG_ARGS accordingly, to use the generated files, and
         add dependencies to regenerate the files if the templates change.
     o   Generate the actual DESCR, and if needed, MESSAGE, REQ, INSTALL, DE-
         INSTALL 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 fla-
         vor extension for this port, e.g., if FLAVORS=no_map gfx qt2, if FLA-
         VOR=gfx no_map, this is `-no_map-gfx'.
     o   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 substi-
         tutions as other packing information, and finally handling dynamic
         libraries macros.

     Note that ${COMMENT} is currently not substituted, to speed up describe
     generation.

     To avoid substitution, variables can be escaped as follows: $\{PREFIX}

     Constructs such as the line %%SHARED%% or !%%SHARED%% in the packing-list
     template trigger the inclusion of the ${PKGDIR}/PFRAG.shared${SUBPACKAGE}
     or ${PKGDIR}/PFRAG.no-shared${SUBPACKAGE}.
     Similarly, if FLAVORS lists flav1, then the line %%flav1%% (resp.
     !%%flav1%%) will trigger the inclusion of
     ${PKGDIR}/PFRAG.flav1${SUBPACKAGE} (resp.  ${PKGDIR}/PFRAG.no-
     flav1${SUBPACKAGE}) in the packing-list.  Fragments that cannot be han-
     dled by these simple rules can always be specified in a custom SED_PLIST.

     The constructs DYNLIBDIR(directory) and NEWDYNLIBDIR(directory) should be
     used in ${PKGDIR}/PFRAG.shared${SUBPACKAGE} to register directories that
     hold dynamic libraries (see ldconfig(8)). NEWDYNLIBDIR is meant for di-
     rectories that will go away when the package is deleted.  If possible, it
     should not be used, because users also have to edit rc.conf to add the
     directory.  It is usually better to also let libraries be visible as a
     link under ${LOCALBASE}.  Having a separate directory is enough to trick
     ld(1) into grabbing the right version.  Note that libraries used only for
     dlopen(3) do not need NEWDYNLIDIR.

     The special plist target does a fairly good job of automatically generat-
     ing PLIST and PFRAG.shared fragments.

     In MULTI_PACKAGES mode, there must be separate COMMENT, DESCR, and PLIST
     templates for each SUBPACKAGE (and optional distinct MESSAGE, REQ, IN-
     STALL, DEINSTALL files in a similar way).  This contrasts with the FLA-
     VORS situation, where all these files will automatically default to the
     non-flavor version if there is no flavor-specific file around.

BUGS AND LIMITATIONS
     LOCALBASE, X11BASE and PREFIX are not heeded consistently.  Most of the
     ports tree will probably fall apart if one tries to build/use stuff else-
     where.

     LIB_DEPENDS should only be a BUILD_DEPENDS on architectures without
     shared libraries.  If a RUN_DEPENDS is needed as well, it should be men-
     tionned explicitly.

HISTORY
     The ports mechanism originally came from FreeBSD. A lot of additions were
     taken from NetBSD over the years.

     When the file grew too large, it was cleaned up to restore some of its
     speed and remove a lot of bugs.

     FLAVORS, MULTI_PACKAGES and FAKE are OpenBSD improvements.

SEE ALSO
     packages-specs(7)

OpenBSD 3.0                      June 10 2000                               17
