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 al-
     ways 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 de-
     pendencies 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 re-
     cursion 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/qt2, x11/qt3, and x11/qt4.  Instead
     of using the namespace MODQT2*, 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 exception-
     ally import both modules with MODULES += x11/qt3 x11/qt4 and differenti-
     ate 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 defin-
                   ing MODFOO_post-patch.  It will be run right after post-
                   patch and before REORDER_DEPENDENCIES touches things.

     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, au-
                   tomake, 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 con-
                   figure 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 defin-
                   ing MODFOO_pre-install.  It will be run right before in-
                   stalling 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 mod-
     ules.  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 di-
     rectly to the BUILD_DEPENDS, RUN_DEPENDS, LIB_DEPENDS, and WANTLIB vari-
     ables, as long as they also define module-specific variables for all run-
     time 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 behav-
     ior: 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 al-
     ready defined.  Modules may depend upon the following variables already
     having a sane value: ARCH, DISTDIR, LOCALBASE, LP64_ARCHS, NO_DEPENDS,
     NO_SHARED_ARCHS, NO_SHARED_LIBS, PKGPATH, PORTSDIR, USE_X11, X11BASE.
     Note that this is only relevant for tests.  It is perfectly okay to de-
     fine variables or targets that depend on the basic ports framework with-
     out 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_AU-
                   THOR=ID to locate the right directory.

                   User settings: set CPAN_REPORT to Yes, CPAN_REPORT_DB to a
                   valid directory, and CPAN_REPORT_FROM to a valid email ad-
                   dress to automate the reporting of regress tests to CPAN.

     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.

     gcc3          If USE_GCC3=No (defined by /usr/share/mk/bsd.own.mk), and
                   architecture is in MODGCC3_ARCHES, then the gcc 3.3.6 com-
                   pilers 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 MOD-
                   GCC3_LANGS (e.g. c++, g77).

     gcc4          If USE_GCC4=No (the default), and architecture is in MOD-
                   GCC4_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) man-
                   page.

     imake         This module is documented in the main bsd.port.mk(5) man-
                   page.

     java          Set MODJAVA_VER=x.y to use exactly the JDK x.y, MODJA-
                   VA_VER=x.y+ to use any x.y or higher version.  Set MODJA-
                   VA_JRERUN=Yes if the port only needs the JRE at runtime.
                   The module sets JAVA_HOME, ONLY_FOR_ARCHS, MODJAVA_RUN_DE-
                   PENDS, and appends to BUILD_DEPENDS and RUN_DEPENDS.  It
                   heeds NO_BUILD.

     lang/ghc      Sets ONLY_FOR_ARCHS, MODGHC_VERSION, BUILD_DEPENDS, and
                   RUN_DEPENDS.

     lang/lua      Appends to RUN_DEPENDS and CATEGORIES.  Also appends to
                   BUILD_DEPENDS, unless NO_BUILD has been set to Yes.

     lang/mono

     lang/ocaml    Sets OCAML_VERSION, MODOCAML_NATIVE.  Appends to BUILD_DE-
                   PENDS and MAKE_ENV.  This also selects a %%native%% plist
                   fragment depending on whether the architecture supports na-
                   tive compilation or not.

     lang/python   Sets MODPY_VERSION, MODPY_BIN, MODPY_INCDIR, MODPY_LIBDIR,
                   MODPY_SITEPKG, MODPY_SETUP, MODPY_LIB_DEPENDS, MOD-
                   PY_RUN_DEPENDS, MODPY_BUILD_DEPENDS.  Appends to RUN_DE-
                   PENDS unless MODPY_RUNDEP is set to No.  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_DISTU-
                   TILS_BUILDARGS and MODPY_DISTUTILS_INSTALLARGS.  Also af-
                   fects CATEGORIES, MAKE_ENV, CONFIGURE_ENV, SHARED_ONLY, and
                   SUBST_VARS.  May affect the regress target.

     lang/ruby     Sets MODRUBY_REV, RUBY, MODRUBY_RUN_DEPENDS, MODRU-
                   BY_LIB_DEPENDS, MODRUBY_LIBDIR, MODRUBY_DOCDIR, MODRUBY_EX-
                   AMPLEDIR, MODRUBY_ARCH.  Appends to BUILD_DEPENDS, RUN_DE-
                   PENDS, CATEGORIES and SUBST_VARS.

     lang/tcl      Sets MODTCL_VERSION, MODTCL_BIN, MODTCL_INCDIR, MODTCL_LIB-
                   DIR, 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 over-
                   ridden.  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) man-
                   page.

     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 MOD-
                   INTLTOOL_OVERRIDE to them.

     www/drupal5

     www/drupal6

     www/pear

     www/plone

     www/zope

     x11/gnome     Sets DESKTOP_FILES, EXTRACT_SUFX, MODGNOME_HELP_FILES, MOD-
                   GNOME_BUILD_DEPENDS, MODGNOME_RUN_DEPENDS and USE_GMAKE.
                   EXTRACT_SUFX defaults to .tar.bz2.  Also affects CATE-
                   GORIES.  If CONFIGURE_STYLE is set to either gnu or auto-
                   conf --disable-silent-rules and --disable-shave is appended
                   to CONFIGURE_ARGS.  If DESKTOP_FILES=Yes, a dependency on
                   devel/desktop-file-utils is appended to MODGNOME_RUN_DE-
                   PENDS.  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.

                   MASTER_SITES and DISTNAME are built using GNOME_PROJECT and
                   GNOME_VERSION.

     x11/gnustep

     x11/kde

     x11/qt2

     x11/qt3

     x11/qt4

     x11/tk        Sets MODTK_VERSION, MODTK_BIN, MODTK_INCDIR, MODTK_LIBDIR,
                   MODTK_BUILD_DEPENDS, MODTK_RUN_DEPENDS, MODTK_LIB, MOD-
                   TK_LIB_DEPENDS, and MODTK_CONFIG.  MODTK_VERSION is the de-
                   fault 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 CATE-
                   GORIES, SUBST_VARS, and USE_X11.  Note the MODTCL_WISH_ADJ
                   shell fragment in the lang/tcl module.

     x11/xfce4     Sets DIST_SUBDIR, EXTRACT_SUFX, CONFIGURE_STYLE, CONFIG-
                   URE_ENV, USE_X11 and USE_GMAKE.  If DESKTOP_FILES is set to
                   yes, it adds devel/desktop-file-utils to RUN_DEPENDS.  Un-
                   less 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 li-
                   braries and applications, goodies, artwork, thunar plugins,
                   and panel plugins.  HOMEPAGE, MASTER_SITES and DISTNAME are
                   built using XFCE_VERSION (which defaults to XFCE_DESK-
                   TOP_VERSION if not set) and either XFCE_PROJECT, XFCE_GOOD-
                   IE, XFCE_ARTWORK, THUNAR_PLUGIN or XFCE_PLUGIN.  One of the
                   latter has to be provided by the port Makefile.

SEE ALSO
     make(1), bsd.port.mk(5), ports(7)

OpenBSD 4.7                    October 21, 2009                              6
