1.\" $OpenBSD: port-modules.5,v 1.34 2009/04/06 10:12:08 ajacoutot Exp $ 2.\" 3.\" Copyright (c) 2008 Marc Espie 4.\" 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd $Mdocdate: April 6 2009 $ 28.Dt PORT-MODULES 5 29.Os 30.Sh NAME 31.Nm port-modules 32.Nd format and conventions used in port modules 33.Sh DESCRIPTION 34The 35.Ox 36Ports framework is based on a gigantic makefile named 37.Xr bsd.port.mk 5 . 38.Pp 39In order to curb unwieldy growth, parts of the framework 40that are not always needed have been set apart in optional 41files called 42.Nm port modules , 43which are retrieved as needed through the 44.Ev MODULES 45variable of 46.Xr bsd.port.mk 5 . 47.Pp 48Some of these modules correspond to basic mechanisms which are not 49always needed, such as GNU autoconf, or perl5. 50.Pp 51Other modules correspond to shortcuts for using some other ports as 52dependencies without needing to hardcode too much, such as libiconv or 53the qt ports. 54.Sh THE MODULES LOOK-UP MECHANISM 55The variable 56.Ev MODULES 57should contain a list of module names. 58Some core modules are a single word, all other modules should be 59${PKGPATH}. 60If the module is 61.Pa some/dir/portname , 62the ports framework will look for a file named 63.Pa ${PORTSDIR}/some/dir/portname/portname.port.mk 64and include it. 65.Pp 66Most modules should conform to this syntax. 67The historic practice of having a redirection file directly under 68.Pa ${PORTSDIR}/infrastructure/mk 69is deprecated for new modules. 70.Pp 71Modules may refer to each other. 72The modules mechanism has specific recursion handling such that 73adding 74.Li MODULES += foo/bar 75to a module will work as expected. 76.Sh NAMING CONVENTIONS 77Since there is no actual scope in makefiles, everything defined within 78a module will be global to the ports framework, and thus may interfere 79with other ports. 80.Pp 81As far as possible, all variables and targets belonging to a module named 82.Pa some/dir/foo 83should be named 84.Ev MODFOO_* 85and 86.Ar modfoo_* . 87.Pp 88Following the same conventions as 89.Xr bsd.port.mk 5 , 90internal variables and targets not intended for user consumption should be 91named 92.Ev _MODFOO_* 93and 94.Ar _modfoo_* . 95.Pp 96For instance, if a module wants some value to be available for the rest 97of the world, it should define 98.Ev MODFOO_VARNAME , 99with a name matching the basic infrastructure as far as possible. 100That is, a port that defines specific dependencies will usually 101define 102.Ev MODFOO_WANTLIB , 103.Ev MODFOO_LIB_DEPENDS , 104and 105.Ev MODFOO_RUN_DEPENDS , 106as appropriate. 107.Pp 108As an exception to the naming mechanism, some ports have several distinct 109versions in the ports tree, say 110.Pa x11/qt2 , 111.Pa x11/qt3 , 112and 113.Pa x11/qt4 . 114Instead of using the namespace 115.Ev MODQT2* , 116variables will usually drop the version suffix and be simply called 117.Ev MODQT_* 118so that a port using the module can be switched from version to version 119without needing to change everything. 120.Pp 121It is highly desirable to define names in both namespaces for such ports, 122for example to define both 123.Ev MODQT3_LIB_DEPENDS 124and 125.Ev MODQT_LIB_DEPENDS . 126Normal client ports will use 127.Ev MODQT_LIB_DEPENDS , 128but a port may exceptionally import both modules with 129.Li MODULES += x11/qt3 x11/qt4 130and differentiate between qt3 and qt4 needs with 131.Ev MODQT3_LIB_DEPENDS 132and 133.Ev MODQT4_LIB_DEPENDS . 134See 135.Pa print/poppler 136for an example. 137.Sh OVERRIDING TARGET BEHAVIOR 138The main framework contains several hooks that allow ports to override 139normal behavior. 140This evolved as an ad-hoc framework, where only hooks that turned out 141to be needed were added. 142If several modules define the same hook, hook behaviors will be 143invoked in sequence. 144.Bl -tag -width do-configure 145.It Ar patch 146There is a 147.Ar post-patch 148hook that can be activated by defining 149.Ev MODFOO_post-patch . 150It will be run right after 151.Ar post-patch 152and before 153.Ev REORDER_DEPENDENCIES 154touches things. 155.It Ar configure 156The normal 157.Ar do-configure 158behavior is to invoke all 159.Ev MODFOO_configure 160contents that are defined in 161.Ev CONFIGURE_STYLE . 162By default, 163.Ar configure 164will do nothing. 165Some 166.Ev CONFIGURE_STYLE 167values, namely perl, gnu, imake, automake, autoconf, and autoupdate 168will automatically import the correct module. 169User-defined modules must both add to 170.Ev CONFIGURE_STYLE 171and import the correct module to override behavior. 172Contrary to other hooks, module behavior is not invoked in 173addition to 174.Ar do-configure , 175but as the normal configure process. 176If 177.Ar do-configure 178is overridden, normal hook processing will not happen. 179.It Ar fake 180There is a 181.Ar pre-fake 182hook that can be activated by defining 183.Ev MODFOO_pre-fake . 184This will be invoked right after 185.Xr mtree 8 , 186and before the normal 187.Ar pre-fake 188behavior. 189.It Ar install 190There is a 191.Ar pre-install 192hook that can be activated by defining 193.Ev MODFOO_pre-install . 194It will be run right before installing the package with 195.Xr pkg_add 1 . 196.El 197.Sh OVERRIDING VARIABLE BEHAVIOR 198Some variables can be overridden by modules. 199Be very cautious, as this can make the module difficult to use, 200or interact badly with other modules. 201As a rule, always provide the override as: 202.Pp 203.Dl VARIABLE ?= value 204.Pp 205and provide a module-specific variable with the same value: 206.Pp 207.Dl MODFOO_VARIABLE = value . 208.Pp 209The following variables can be overridden in a relatively safe fashion: 210.Ev ALL_TARGET , 211.Ev CONFIGURE_SCRIPT , 212.Ev DESTDIRNAME , 213.Ev DIST_SUBDIR , 214.Ev DISTNAME , 215.Ev DISTFILES , 216.Ev EXTRACT_SUFX , 217.Ev FAKE_FLAGS , 218.Ev FETCH_MANUALLY , 219.Ev HOMEPAGE , 220.Ev IGNORE , 221.Ev IS_INTERACTIVE , 222.Ev LIBTOOL_FLAGS , 223.Ev MAKE_FILE , 224.Ev MASTER_SITES , 225.Ev MULTI_PACKAGES , 226.Ev NO_BUILD , 227.Ev NO_REGRESS , 228.Ev PATCH_LIST , 229.Ev PKG_ARCH , 230.Ev PKGNAME* , 231.Ev PREFIX , 232.Ev REGRESS_TARGET , 233.Ev REGRESS_IS_INTERACTIVE , 234.Ev REORDER_DEPENDENCIES , 235.Ev SEPARATE_BUILD , 236.Ev SHARED_ONLY , 237.Ev USE_GMAKE , 238.Ev USE_LIBTOOL , 239.Ev USE_MOTIF . 240.Pp 241The following variables can be added to in a relatively safe fashion: 242.Ev BUILD_DEPENDS , 243.Ev CATEGORIES , 244.Ev CONFIGURE_ARGS , 245.Ev CONFIGURE_ENV , 246.Ev ERRORS , 247.Ev FAKE_FLAGS , 248.Ev FLAVOR , 249.Ev FLAVORS , 250.Ev INSTALL_TARGET , 251.Ev LIB_DEPENDS , 252.Ev MAKE_ENV , 253.Ev MAKE_FLAGS , 254.Ev PKG_ARGS , 255.Ev PSEUDO_FLAVORS , 256.Ev REGRESS_DEPENDS , 257.Ev REORDER_DEPENDENCIES , 258.Ev RUN_DEPENDS , 259.Ev SUBST_VARS , 260.Ev WANTLIB . 261.Sh SPECIFIC MODULE INTERACTIONS 262Some modules correspond to extra ports that will be used mostly as 263.Ev BUILD_DEPENDS 264or 265.Ev RUN_DEPENDS . 266Such modules can safely append values directly to the 267.Ev BUILD_DEPENDS , 268.Ev RUN_DEPENDS , 269.Ev LIB_DEPENDS , 270and 271.Ev WANTLIB 272variables, as long as they also define module-specific variables for 273all runtime dependencies. 274.Pp 275Simple client ports will use the module directly, and thus inherit extra 276build and runtime dependencies. 277.Pp 278More sophisticated ports can use 279.Ev MULTI_PACKAGES 280to select specific behavior: build-time dependencies will always be 281needed. 282Runtime dependencies will be selected on a subpackage basis, 283since runtime dependencies such as 284.Ev LIB_DEPENDS-sub 285do not inherit the default 286.Ev LIB_DEPENDS 287value. 288The client port's author must only bear in mind that external modules 289may add values to the default 290.Ev WANTLIB , 291.Ev LIB_DEPENDS , 292and 293.Ev RUN_DEPENDS , 294and thus that it is not safe to inherit from it blindly. 295.Pp 296Modules are imported during 297.Pp 298.Dl .include <bsd.port.mk> 299.Pp 300Thus they can be affected by user choices such as setting a variable 301to Yes or No. 302Modules may make decisions based on documented 303.Ev MODFOO_BEHAVIOR 304values. 305.Pp 306When modules are processed, only a few 307.Xr bsd.port.mk 5 308variables are already defined. 309Modules may depend upon the following variables already having a sane 310value: 311.Ev ARCH , 312.Ev DISTDIR , 313.Ev LOCALBASE , 314.Ev LP64_ARCHS , 315.Ev NO_DEPENDS , 316.Ev NO_SHARED_ARCHS , 317.Ev NO_SHARED_LIBS , 318.Ev PKGPATH , 319.Ev PORTSDIR , 320.Ev USE_X11 , 321.Ev X11BASE . 322Note that this is only relevant for tests. 323It is perfectly okay to define variables or targets that depend on the 324basic ports framework without having to care whether that variable is 325already defined, since 326.Xr make 1 327performs lazy evaluation. 328.Sh CORE MODULES DOCUMENTATION 329The following modules are available. 330.Bl -tag -width do-configure 331.It apache-module 332.It converters/libiconv 333.It cpan 334For perl ports coming from CPAN. 335Wrapper around the normal perl module that fetches the file from 336the correct location depending on DISTNAME, and sets a default 337PKGNAME. 338Also affects REGRESS_DEPENDS, CONFIGURE_STYLE, PKG_ARCH, and CATEGORIES. 339.Pp 340Some CPAN modules are only indexed by author, set CPAN_AUTHOR=ID 341to locate the right directory. 342.Pp 343User settings: set CPAN_REPORT to Yes, CPAN_REPORT_DB to a valid directory, 344and CPAN_REPORT_FROM to a valid email adress to automate the reporting 345of regress tests to CPAN. 346.It devel/cmake 347.It devel/gettext 348.It devel/pmk 349Sets CONFIGURE_SCRIPT, CONFIGURE_ARGS and MODPMK_configure. 350It appends 351.Pa devel/pmk 352to BUILD_DEPENDS. 353.It devel/scons 354.It devel/waf 355Adds 356.Pa devel/waf 357to BUILD_DEPENDS, 358.Pa lang/python 359to MODULES, and provides do-configure, do-build, do-install and 360post-install targets. 361do-build, do-install and post-install can be overridden in the port 362Makefile. 363.It gcc3 364If USE_GCC3=No (defined by 365.Pa /usr/share/mk/bsd.own.mk ) , 366and architecture is in MODGCC3_ARCHES, then the gcc 3.3.6 367compilers will be put at the front of the path. 368By default, only C language support is included by this module. 369If other languages are needed, they must be listed in MODGCC3_LANGS 370(e.g. c++, g77). 371.It gcc4 372If USE_GCC4=No (the default), and architecture is in 373MODGCC4_ARCHES, then the gcc 4.2 compilers will be put at the front of 374the path. 375By default, only C language support is included by this module. 376If other languages are needed, they must be listed in MODGCC4_LANGS 377(e.g. c++, g77). 378.It gnu 379This module is documented in the main 380.Xr bsd.port.mk 5 381manpage. 382.It imake 383This module is documented in the main 384.Xr bsd.port.mk 5 385manpage. 386.It java 387Set MODJAVA_VER=x.y to use exactly the JDK x.y, MODJAVA_VER=x.y+ to 388use any x.y or higher version. 389Set MODJAVA_JRERUN=Yes if the port only needs the JRE at runtime. 390The module sets JAVA_HOME, ONLY_FOR_ARCHS, MODJAVA_RUN_DEPENDS, and 391appends to BUILD_DEPENDS and RUN_DEPENDS. 392It heeds NO_BUILD. 393.It lang/ghc 394Sets ONLY_FOR_ARCHS, MODGHC_VERSION, BUILD_DEPENDS, and RUN_DEPENDS. 395.It lang/lua 396Appends to RUN_DEPENDS and CATEGORIES. 397Also appends to BUILD_DEPENDS, 398unless NO_BUILD has been set to Yes. 399.It lang/mono 400.It lang/ocaml 401Sets OCAML_VERSION, MODOCAML_NATIVE. 402Appends to BUILD_DEPENDS and MAKE_ENV. 403This also selects a %%native%% plist fragment depending on whether 404the architecture supports native compilation or not. 405.It lang/python 406Sets MODPY_VERSION, MODPY_BIN, MODPY_INCDIR, MODPY_LIBDIR, MODPY_SITEPKG, 407MODPY_SETUP, MODPY_LIB_DEPENDS, MODPY_RUN_DEPENDS, MODPY_BUILD_DEPENDS. 408Appends to RUN_DEPENDS unless MODPY_RUNDEP is set to No. 409MODPY_VERSION is the default version used by all python modules. 410Ports which use the setuptools module should set MODPY_SETUPTOOLS to Yes. 411All ports that generate egg-info files should set MODPY_EGG_VERSION 412to the version string used by the port's setup.py setup() function. 413Extra arguments to the build and install commands can be passed via 414MODPY_DISTUTILS_BUILDARGS and MODPY_DISTUTILS_INSTALLARGS. 415Also affects CATEGORIES, MAKE_ENV, SHARED_ONLY, and SUBST_VARS. 416May affect the regress target. 417.It lang/ruby 418Sets MODRUBY_REV, RUBY, MODRUBY_RUN_DEPENDS, MODRUBY_LIB_DEPENDS, 419MODRUBY_LIBDIR, MODRUBY_DOCDIR, MODRUBY_EXAMPLEDIR, MODRUBY_ARCH. 420Appends to BUILD_DEPENDS, RUN_DEPENDS, CATEGORIES and SUBST_VARS. 421.It lang/tcl 422Sets MODTCL_VERSION, MODTCL_BIN, MODTCL_INCDIR, MODTCL_LIBDIR, 423MODTCL_BUILD_DEPENDS, MODTCL_RUN_DEPENDS, MODTCL_LIB_DEPENDS, 424and MODTCL_CONFIG. 425Also affects CATEGORIES and SUBST_VARS. 426.It perl 427This module is documented in the main 428.Xr bsd.port.mk 5 429manpage. 430.It textproc/intltool 431Sets MODINTLTOOL_OVERRIDE. 432.Pa textproc/intltool 433is added to BUILD_DEPENDS. 434MODINTLTOOL_OVERRIDE changes the paths of INTLTOOL_EXTRACT, INTLTOOL_MERGE and 435INTLTOOL_UPDATE to use the installed versions of intltool-extract, 436intltool-merge and intltool-update, instead of the version's packages into the 437distfile of the port using this module. 438Also affects CONFIGURE_ENV, MAKE_ENV and MAKE_FLAGS by appending 439MODINTLTOOL_OVERRIDE to them. 440.It www/drupal5 441.It www/pear 442.It www/plone 443.It www/zope 444.It x11/gnome 445Sets DESKTOP_FILES, EXTRACT_SUFX, MODGNOME_HELP_FILES, MODGNOME_BUILD_DEPENDS, 446MODGNOME_RUN_DEPENDS, and USE_GMAKE. 447EXTRACT_SUFX defaults to .tar.bz2. 448Also affects CATEGORIES. 449If DESKTOP_FILES=Yes, a dependency on 450.Pa devel/desktop-file-utils 451is appended 452to MODGNOME_RUN_DEPENDS. 453If MODGNOME_HELP_FILES=Yes, then 454.Pa x11/gnome/yelp 455is appended to MODGNOME_RUN_DEPENDS and 456.Pa x11/gnome/doc-utils 457is appended to MODGNOME_BUILD_DEPENDS. 458This option is to be used when .xml GNOME help files are installed into 459.Pa share/gnome/help/ . 460Unless NO_BUILD=Yes, USE_LIBTOOL is set to Yes and 461.Pa textproc/intltool 462is appended to MODULES. 463.Pp 464MASTER_SITES and DISTNAME are built using GNOME_PROJECT and 465GNOME_VERSION. 466.It x11/gnustep 467.It x11/kde 468.It x11/qt2 469.It x11/qt3 470.It x11/qt4 471.It x11/tk 472Sets MODTK_VERSION, MODTK_BIN, MODTK_INCDIR, MODTK_LIBDIR, 473MODTK_BUILD_DEPENDS, MODTK_RUN_DEPENDS, MODTK_LIB_DEPENDS, and 474MODTK_CONFIG. 475Automatically adds the lang/tcl module, and affects CATEGORIES, 476SUBST_VARS, and USE_X11. 477.It x11/xfce4 478Sets DIST_SUBDIR, EXTRACT_SUFX, CONFIGURE_STYLE, 479CONFIGURE_ENV, USE_X11 and USE_GMAKE. 480If DESKTOP_FILES is set to yes, it adds 481.Pa devel/desktop-file-utils 482to RUN_DEPENDS. 483Unless XFCE_NO_SRC is set, USE_LIBTOOL is set to yes and 484.Pa devel/gettext 485and 486.Pa textproc/intltool 487are added to MODULES. 488Also affects CATEGORIES. 489.Pp 490Xfce ports can be divided into three categories: core libraries and 491applications, goodies, and panel plugins. 492HOMEPAGE, MASTER_SITES and DISTNAME are built using XFCE_VERSION (which 493defaults to XFCE_DESKTOP_VERSION if not set) and either XFCE_PROJECT, 494XFCE_GOODIE or XFCE_PLUGIN. 495One of the latter has to be provided by the port Makefile. 496.El 497.Sh SEE ALSO 498.Xr make 1 , 499.Xr bsd.port.mk 5 , 500.Xr ports 7 501