PORT-MODULES(5) OpenBSD Programmer's Manual PORT-MODULES(5)NAME
port-modules - format and conventions used in port modules
DESCRIPTION
The OpenBSD Ports framework is based on a gigantic makefile named
bsd.port.mk(5).
In order to curb unwieldy growth, parts of the framework that are not
always needed have been set apart in optional files called port modules,
which are retrieved as needed through the MODULES variable of
bsd.port.mk(5).
Some of these modules correspond to basic mechanisms which are not always
needed, such as GNU autoconf, or perl5.
Other modules correspond to shortcuts for using some other ports as
dependencies without needing to hardcode too much, such as libiconv or
the qt ports.
THE MODULES LOOK-UP MECHANISM
The variable MODULES should contain a list of module names. Some core
modules are a single word, all other modules should be ${PKGPATH}. If
the module is some/dir/portname, the ports framework will look for a file
named ${PORTSDIR}/some/dir/portname/portname.port.mk and include it.
Most modules should conform to this syntax. The historic practice of
having a redirection file directly under ${PORTSDIR}/infrastructure/mk is
deprecated for new modules.
Modules may refer to each other. The modules mechanism has specific
recursion handling such that adding MODULES += foo/bar to a module will
work as expected.
NAMING CONVENTIONS
Since there is no actual scope in makefiles, everything defined within a
module will be global to the ports framework, and thus may interfere with
other ports.
As far as possible, all variables and targets belonging to a module named
some/dir/foo should be named MODFOO_* and modfoo_*.
Following the same conventions as bsd.port.mk(5), internal variables and
targets not intended for user consumption should be named _MODFOO_* and
_modfoo_*.
For instance, if a module wants some value to be available for the rest
of the world, it should define MODFOO_VARNAME, with a name matching the
basic infrastructure as far as possible. That is, a port that defines
specific dependencies will usually define MODFOO_WANTLIB,
MODFOO_LIB_DEPENDS, and MODFOO_RUN_DEPENDS, as appropriate.
As an exception to the naming mechanism, some ports have several distinct
versions in the ports tree, say x11/qt3 and x11/qt4. Instead of using
the namespace MODQT3*, variables will usually drop the version suffix and
be simply called MODQT_* so that a port using the module can be switched
from version to version without needing to change everything.
It is highly desirable to define names in both namespaces for such ports,
for example to define both MODQT3_LIB_DEPENDS and MODQT_LIB_DEPENDS.
Normal client ports will use MODQT_LIB_DEPENDS, but a port may
exceptionally import both modules with MODULES += x11/qt3 x11/qt4 and
differentiate between qt3 and qt4 needs with MODQT3_LIB_DEPENDS and
MODQT4_LIB_DEPENDS. See print/poppler for an example.
OVERRIDING TARGET BEHAVIOR
The main framework contains several hooks that allow ports to override
normal behavior. This evolved as an ad-hoc framework, where only hooks
that turned out to be needed were added. If several modules define the
same hook, hook behaviors will be invoked in sequence.
patch There is a post-patch hook that can be activated by
defining MODFOO_post-patch. It will be run right after
post-patch and before REORDER_DEPENDENCIES touches things.
configure There is a pre-configure hook that can be activated by
defining MODFOO_pre-configure. It will be run right after
pre-configure. The normal do-configure behavior is to
invoke all MODFOO_configure contents that are defined in
CONFIGURE_STYLE. By default, configure will do nothing.
Some CONFIGURE_STYLE values, namely perl, gnu, imake,
automake, autoconf, and autoupdate will automatically
import the correct module. User-defined modules must both
add to CONFIGURE_STYLE and import the correct module to
override behavior. Contrary to other hooks, module
behavior is not invoked in addition to do-configure, but as
the normal configure process. If do-configure is
overridden, normal hook processing will not happen.
fake There is a pre-fake hook that can be activated by defining
MODFOO_pre-fake. This will be invoked right after
mtree(8), and before the normal pre-fake behavior.
install There is a pre-install hook that can be activated by
defining MODFOO_pre-install. It will be run right before
installing the package with pkg_add(1).
OVERRIDING VARIABLE BEHAVIOR
Some variables can be overridden by modules. Be very cautious, as this
can make the module difficult to use, or interact badly with other
modules. As a rule, always provide the override as:
VARIABLE ?= value
and provide a module-specific variable with the same value:
MODFOO_VARIABLE = value.
The following variables can be overridden in a relatively safe fashion:
ALL_TARGET, CONFIGURE_SCRIPT, DESTDIRNAME, DIST_SUBDIR, DISTNAME,
DISTFILES, EXTRACT_SUFX, FAKE_FLAGS, FETCH_MANUALLY, HOMEPAGE, IGNORE,
IS_INTERACTIVE, LIBTOOL_FLAGS, MAKE_FILE, MASTER_SITES, MULTI_PACKAGES,
NO_BUILD, NO_REGRESS, PATCH_LIST, PKG_ARCH, PKGNAME*, PREFIX,
REGRESS_TARGET, REGRESS_IS_INTERACTIVE, REORDER_DEPENDENCIES,
SEPARATE_BUILD, SHARED_ONLY, USE_GMAKE, USE_LIBTOOL, USE_MOTIF.
The following variables can be added to in a relatively safe fashion:
BUILD_DEPENDS, CATEGORIES, CONFIGURE_ARGS, CONFIGURE_ENV, ERRORS,
FAKE_FLAGS, FLAVOR, FLAVORS, INSTALL_TARGET, LIB_DEPENDS, MAKE_ENV,
MAKE_FLAGS, PKG_ARGS, PSEUDO_FLAVORS, REGRESS_DEPENDS,
REORDER_DEPENDENCIES, RUN_DEPENDS, SUBST_VARS, WANTLIB.
SPECIFIC MODULE INTERACTIONS
Some modules correspond to extra ports that will be used mostly as
BUILD_DEPENDS or RUN_DEPENDS. Such modules can safely append values
directly to the BUILD_DEPENDS, RUN_DEPENDS, LIB_DEPENDS, and WANTLIB
variables, as long as they also define module-specific variables for all
runtime dependencies.
Simple client ports will use the module directly, and thus inherit extra
build and runtime dependencies.
More sophisticated ports can use MULTI_PACKAGES to select specific
behavior: build-time dependencies will always be needed. Runtime
dependencies will be selected on a subpackage basis, since runtime
dependencies such as LIB_DEPENDS-sub do not inherit the default
LIB_DEPENDS value. The client port's author must only bear in mind that
external modules may add values to the default WANTLIB, LIB_DEPENDS, and
RUN_DEPENDS, and thus that it is not safe to inherit from it blindly.
Modules are imported during
.include <bsd.port.mk>
Thus they can be affected by user choices such as setting a variable to
Yes or No. Modules may make decisions based on documented
MODFOO_BEHAVIOR values.
When modules are processed, only a few bsd.port.mk(5) variables are
already defined. Modules may depend upon the following variables already
having a sane value: APM_ARCHS, ARCH, DISTDIR, LOCALBASE, LP64_ARCHS,
NO_DEPENDS, NO_SHARED_ARCHS, NO_SHARED_LIBS, PKGPATH, PORTSDIR, X11BASE.
Note that this is only relevant for tests. It is perfectly okay to
define variables or targets that depend on the basic ports framework
without having to care whether that variable is already defined, since
make(1) performs lazy evaluation.
CORE MODULES DOCUMENTATION
The following modules are available.
apache-module
converters/libiconv
cpan For perl ports coming from CPAN. Wrapper around the normal
perl module that fetches the file from the correct location
depending on DISTNAME, and sets a default PKGNAME. Also
affects REGRESS_DEPENDS, CONFIGURE_STYLE, PKG_ARCH, and
CATEGORIES.
Some CPAN modules are only indexed by author, set
CPAN_AUTHOR=ID to locate the right directory.
If no HOMEPAGE is defined, it will default to
http://search.cpan.org/dist/${DISTNAME:C/-[^-]*$//}/
User settings: set CPAN_REPORT to Yes, CPAN_REPORT_DB to a
valid directory, and CPAN_REPORT_FROM to a valid email
address to automate the reporting of regress tests to CPAN.
If MODCPAN_EXAMPLES is set, the following variables will be
set. MODCPAN_EXAMPLES_DIST will hold the default directory
in the distfile with example scripts. MODCPAN_EXAMPLES_DIR
will be set to the standard installation directory for
examples. Sets the post-install target if none has been
defined to install the examples, otherwise
MODCPAN_POST_INSTALL should be used as such:
post-install:
...
${MODCPAN_POST_INSTALL}
devel/cmake
devel/gconf2 A link from gconftool-2(1) to true(1) will be put at the
front of the path. Sets CONFIGURE_ARGS, BUILD_DEPENDS and
RUN_DEPENDS. According to the values of MODGCONF2_LIBDEP,
sets LIB_DEPENDS. User settings: set MODGCONF2_SCHEMAS_DIR
to the directory name under ${LOCALBASE}/share/schemas/
where schemas files will be installed.
devel/gettext
devel/pmk Sets CONFIGURE_SCRIPT, CONFIGURE_ARGS and MODPMK_configure.
It appends devel/pmk to BUILD_DEPENDS.
devel/scons Adds devel/scons to BUILD_DEPENDS. Sets MODSCONS_BIN and
MODSCONS_ENV. Also defines an overridable MODSCONS_FLAGS.
It provides a do-build and do-install target that can be
overridden in the port Makefile.
devel/waf Adds devel/waf to BUILD_DEPENDS, lang/python to MODULES,
and provides do-configure, do-build, do-install and post-
install targets. do-build, do-install and post-install can
be overridden in the port Makefile.
fortran Sets MODFORTRAN_LIB_DEPENDS, MODFORTRAN_WANTLIB,
MODFORTRAN_BUILD_DEPENDS. Set MODFORTRAN_COMPILER to `g77'
or `gfortran', depending on what the port requires. The
default is `g77'. The dependencies are chosen according to
COMPILER_VERSION and MODFORTRAN_COMPILER.
gcc3 If COMPILER_VERSION is not gcc3 (defined by
/usr/share/mk/bsd.own.mk), and architecture is in
MODGCC3_ARCHES, then the gcc 3.3.6 compilers will be put at
the front of the path. By default, only C language support
is included by this module. If other languages are needed,
they must be listed in MODGCC3_LANGS (e.g. c++, g77).
gcc4 If COMPILER_VERSION is not gcc4 (defined by
/usr/share/mk/bsd.own.mk), and architecture is in
MODGCC4_ARCHES, then the gcc 4.2 compilers will be put at
the front of the path. By default, only C language support
is included by this module. If other languages are needed,
they must be listed in MODGCC4_LANGS (e.g. c++, fortran).
gnu This module is documented in the main bsd.port.mk(5)
manpage.
imake This module is documented in the main bsd.port.mk(5)
manpage.
java Set MODJAVA_VER=x.y to use exactly the JDK x.y,
MODJAVA_VER=x.y+ to use any x.y or higher version. Set
MODJAVA_JRERUN=Yes if the port only needs the JRE at
runtime. The module sets JAVA_HOME, ONLY_FOR_ARCHS,
MODJAVA_RUN_DEPENDS, and appends to BUILD_DEPENDS and
RUN_DEPENDS. It heeds NO_BUILD.
lang/ghc Sets ONLY_FOR_ARCHS, MODGHC_VER, BUILD_DEPENDS, and
RUN_DEPENDS. The build and further actions are based on
MODGHC_BUILD. It accepts the following values: nort (no
runtime dependency on lang/ghc and hs- prefix will not be
added), cabal (to get the typical Cabal targets defined),
haddock (to generate API documenation using devel/haddock,
register (to create and include register/unregister
scripts), hackage (if the distfiles are available on
Hackage). Also affects CATEGORIES, CONFIGURE_STYLE, and
SUBST_VARS. do-build, do-install and do-regress targets
are provided if the port itself didn't set them. If
register has been set, the PLIST needs to be modified in
order to add the relevant @exec/@unexec lines. This module
will run the Setup script and ensure the documentation will
be built (if haddock has been set), and that the package is
registered as a library useable by lang/ghc (if register
has been set).
lang/lua Sets MODLUA_VERSION, MODLUA_LIBDIR, MODLUA_DATADIR.
Appends to RUN_DEPENDS and CATEGORIES. Also appends to
BUILD_DEPENDS, unless NO_BUILD has been set to Yes. Also
affects PKG_ARCH when SHARED_ONLY is not set or set to No.
lang/mono Sets MODMONO_ONLY_FOR_ARCHS, CONFIGURE_ENV, MAKE_FLAGS,
MODMONO_BUILD_DEPENDS and MODMONO_RUN_DEPENDS. If
MODMONO_DEPS is set to Yes, lang/mono is appended to
BUILD_DEPENDS and RUN_DEPENDS. If USE_NANT is defined,
NANT and NANT_FLAGS are set, devel/nant is appended to
BUILD_DEPENDS and the do-build and do-install targets are
provided to use nant for building (can be overridden in the
port Makefile). DLLMAP_FILES defines in which files the
module will substitute hardcoded shared library versions
using a post-configure target.
lang/ocaml Sets OCAML_VERSION, MODOCAML_NATIVE. Appends to
BUILD_DEPENDS and MAKE_ENV. This also selects a %%native%%
plist fragment depending on whether the architecture
supports native compilation or not.
lang/python Sets MODPY_VERSION, MODPY_BIN, MODPY_INCDIR, MODPY_LIBDIR,
MODPY_SITEPKG, MODPY_SETUP, MODPY_WANTLIB,
MODPY_LIB_DEPENDS, MODPY_RUN_DEPENDS, MODPY_BUILD_DEPENDS,
MODPY_BIN_ADJ and MODPY_ADJ_FILES. Appends to RUN_DEPENDS
unless MODPY_RUNDEP is set to No. Appends to BUILD_DEPENDS
unless MODPY_BUILDDEP is set to No or NO_BUILD is set to
Yes. MODPY_VERSION is the default version used by all
python modules. Ports which use the setuptools module
should set MODPY_SETUPTOOLS to Yes. All ports that
generate egg-info files should set MODPY_EGG_VERSION to the
version string used by the port's setup.py setup()
function. Extra arguments to the build and install
commands can be passed via MODPY_DISTUTILS_BUILDARGS and
MODPY_DISTUTILS_INSTALLARGS. MODPY_BIN_ADJ is a command
that takes filename arguments and replaces the python
shebang line with MODPY_BIN. MODPY_ADJ_FILES is a list of
filenames that will automatically have MODPY_BIN_ADJ called
on them at the end of pre-configure. Also affects
CATEGORIES, MAKE_ENV, CONFIGURE_ENV, SHARED_ONLY, and
SUBST_VARS. May affect the regress target.
lang/ruby Sets MODRUBY_REV, RUBY, RAKE, RSPEC, MODRUBY_RUN_DEPENDS,
MODRUBY_LIB_DEPENDS, MODRUBY_BUILD_DEPENDS,
MODRUBY_ICONV_DEPENDS, MODRUBY_LIBDIR, MODRUBY_DOCDIR,
MODRUBY_EXAMPLEDIR, MODRUBY_ARCH, MODRUBY_REGRESS,
MODRUBY_RUBY_ADJ, MODRUBY_ADJ_FILES, GEM_BIN_SUFFIX,
MODRUBY_LIBREV, MODRUBY_BINREV, MODRUBY_PKGSPEC,
MODRUBY_PKG_PREFIX, MODRUBY_RAKE_DEPENDS,
MODRUBY_RSPEC_DEPENDS, MODRUBY_WANTLIB, MODRUBY_FLAVOR.
RUBY, RAKE, and RSPEC are the path to the ruby, rake, and
rspec binaries. MODRUBY_RUBY_ADJ is a command that takes
filename arguments and replaces the /usr/bin/env ruby
shebang lines with RUBY. MODRUBY_ADJ_FILES is a list of
filename patterns that will automatically have
MODRUBY_RUBY_ADJ called on them during pre-configure.
Appends to CATEGORIES and SUBST_VARS. Appends to
BUILD_DEPENDS unless MODRUBY_BUILDDEP is set to No or
NO_BUILD is set to Yes. Appends to RUN_DEPENDS unless
MODRUBY_RUNDEP is set to No. May affect the regress target
if MODRUBY_REGRESS is used. Supports additional
CONFIGURE_STYLEs, and setting specific CONFIGURE_STYLEs
modifies some additional parameters. The "ruby gem"
CONFIGURE_STYLE should be used for pure ruby gems without C
extensions. This adds PKG_ARCH = * and adds ruby19, rbx,
and jruby FLAVORs to the port, so the same port can build
packages for multiple versions of ruby. The "ruby gem ext"
CONFIGURE_STYLE should be used for ruby gems with C
extensions. This adds SHARED_ONLY = Yes and adds
MODRUBY_LIB_DEPENDS to LIB_DEPENDS and c, m, and
MODRUBY_WANTLIB to WANTLIB. It also adds ruby19 and rbx
FLAVORs to the port. The "ruby extconf" CONFIGURE_STYLE is
similar to the "ruby gem ext" CONFIGURE_STYLE, except that
it is used when the package is not distributed as a ruby
gem. In order for ruby 1.9, rubinius, and jruby packages
to be built from the same port directory, any gem
dependencies specified in the port should use this format:
category/ruby-foo,${MODRUBY_FLAVOR}. Use of a ruby19, rbx,
or jruby FLAVOR causes the FULLPKGNAME to use the FLAVOR
instead of ruby as the package prefix. Specifying
MODRUBY_FLAVOR is necessary so that if you are building a
ruby 1.9 package for the current port, it depends on the
ruby 1.9 package of the dependencies. For ruby gem ports
that can work on both ruby 1.8 and ruby 1.9, any binary
file entries in the PLIST should be appended with
${GEM_BIN_SUFFIX}. This is because the ruby 1.9 gem
binaries are installed with a 19 suffix. make update-plist
tends to remove ${GEM_BIN_SUFFIX}, so be careful when
updating such ports.
lang/tcl Sets MODTCL_VERSION, MODTCL_BIN, MODTCL_INCDIR,
MODTCL_LIBDIR, MODTCL_BUILD_DEPENDS, MODTCL_RUN_DEPENDS,
MODTCL_LIB, MODTCL_LIB_DEPENDS, and MODTCL_CONFIG.
MODTCL_VERSION is the default version used by all Tcl ports
and may be overridden. Provides MODTCL_TCLSH_ADJ and
MODTCL_WISH_ADJ shell fragments to patch the interpreter
path in executable scripts. Also affects CATEGORIES and
SUBST_VARS.
perl This module is documented in the main bsd.port.mk(5)
manpage.
textproc/intltool
Sets MODINTLTOOL_OVERRIDE. textproc/intltool is added to
BUILD_DEPENDS. MODINTLTOOL_OVERRIDE changes the paths of
INTLTOOL_EXTRACT, INTLTOOL_MERGE and INTLTOOL_UPDATE to use
the installed versions of intltool-extract, intltool-merge
and intltool-update, instead of the version's packages into
the distfile of the port using this module. Also affects
CONFIGURE_ENV, MAKE_ENV and MAKE_FLAGS by appending
MODINTLTOOL_OVERRIDE to them.
www/drupal5
www/drupal6
www/horde
www/mozilla Sets PKGNAME, HOMEPAGE, MASTER_SITES, DISTNAME, USE_GMAKE,
ONLY_FOR_ARCHS and SHARED_ONLY. EXTRACT_SUFX defaults to
.tar.bz2.
Adds common dependencies to LIB_DEPENDS, WANTLIB,
RUN_DEPENDS and BUILD_DEPENDS. Sets common CONFIGURE_ARGS,
MAKE_ENV and CONFIGURE_ENV. Sets MOB variable as source
directory and MOZ as target directory within do-install.
Port Makefile has to set MOZILLA_PROJECT, MOZILLA_CODENAME,
MOZILLA_VERSION, MOZILLA_BRANCH, MOZILLA_LIBS and
MOZILLA_DATADIRS variables. Port can also append values to
MOZILLA_SUBST_FILES which contains the list of files to run
SUBST_CMD on during pre-configure, and
MOZILLA_AUTOCONF_DIRS which contains the list of dirs where
AUTOCONF will be run during pre-configure.
www/pear
www/plone Sets MODPLONE_VERSION and MODZOPE_VERSION.
MODPLONE_VERSION is the default version used by all Plone
ports and may be overridden. It appends www/plone to
RUN_DEPENDS and also sets NO_REGRESS to Yes.
www/zope
x11/gnome If both GNOME_PROJECT and GNOME_VERSION are set, this
module defines DISTNAME, VERSION, MASTER_SITES, adds
x11/gnome to CATEGORIES and EXTRACT_SUFX will default to
.tar.bz2 if unset. Unconditionally sets DESKTOP_FILES,
MODGNOME_HELP_FILES, MODGNOME_BUILD_DEPENDS,
MODGNOME_RUN_DEPENDS and USE_GMAKE. If CONFIGURE_STYLE is
set to either gnu or autoconf --disable-silent-rules and
--disable-shave are appended to CONFIGURE_ARGS. If
DESKTOP_FILES=Yes, a dependency on devel/desktop-file-utils
is appended to MODGNOME_RUN_DEPENDS. If
MODGNOME_HELP_FILES=Yes, then x11/gnome/yelp is appended to
MODGNOME_RUN_DEPENDS and x11/gnome/doc-utils is appended to
MODGNOME_BUILD_DEPENDS. This option is to be used when
.xml GNOME help files are installed into share/gnome/help/.
Unless NO_BUILD=Yes, USE_LIBTOOL is set to Yes and
textproc/intltool is appended to MODULES.
x11/gnustep
x11/kde
x11/qt3
x11/qt4
x11/tk Sets MODTK_VERSION, MODTK_BIN, MODTK_INCDIR, MODTK_LIBDIR,
MODTK_BUILD_DEPENDS, MODTK_RUN_DEPENDS, MODTK_LIB,
MODTK_LIB_DEPENDS, and MODTK_CONFIG. MODTK_VERSION is the
default version used by all Tk ports and may be overridden.
Automatically adds the lang/tcl module, provides a default
MODTCL_VERSION to match MODTK_VERSION, and affects
CATEGORIES and SUBST_VARS. Note the MODTCL_WISH_ADJ shell
fragment in the lang/tcl module.
x11/xfce4 Sets DIST_SUBDIR, EXTRACT_SUFX, CONFIGURE_STYLE,
CONFIGURE_ENV and USE_GMAKE. If DESKTOP_FILES is set to
yes, it adds devel/desktop-file-utils to RUN_DEPENDS.
Unless XFCE_NO_SRC is set, USE_LIBTOOL is set to yes and
devel/gettext and textproc/intltool are added to MODULES.
Also affects CATEGORIES.
Xfce ports can be divided into five categories: core
libraries and applications, goodies, artwork, thunar
plugins, and panel plugins. HOMEPAGE, MASTER_SITES and
DISTNAME are built using XFCE_VERSION (which defaults to
XFCE_DESKTOP_VERSION if not set) and either XFCE_PROJECT,
XFCE_GOODIE, XFCE_ARTWORK, THUNAR_PLUGIN or XFCE_PLUGIN.
One of the latter has to be provided by the port Makefile.
SEE ALSOmake(1), bsd.port.mk(5), ports(7)OpenBSD 4.9 December 6, 2010 OpenBSD 4.9
