1.\" $OpenBSD: port-modules.5,v 1.50 2010/04/08 16:35:21 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 8 2010 $ 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 APM_ARCHS , 312.Ev ARCH , 313.Ev DISTDIR , 314.Ev LOCALBASE , 315.Ev LP64_ARCHS , 316.Ev NO_DEPENDS , 317.Ev NO_SHARED_ARCHS , 318.Ev NO_SHARED_LIBS , 319.Ev PKGPATH , 320.Ev PORTSDIR , 321.Ev USE_X11 , 322.Ev X11BASE . 323Note that this is only relevant for tests. 324It is perfectly okay to define variables or targets that depend on the 325basic ports framework without having to care whether that variable is 326already defined, since 327.Xr make 1 328performs lazy evaluation. 329.Sh CORE MODULES DOCUMENTATION 330The following modules are available. 331.Bl -tag -width do-configure 332.It apache-module 333.It converters/libiconv 334.It cpan 335For perl ports coming from CPAN. 336Wrapper around the normal perl module that fetches the file from 337the correct location depending on DISTNAME, and sets a default 338PKGNAME. 339Also affects REGRESS_DEPENDS, CONFIGURE_STYLE, PKG_ARCH, and CATEGORIES. 340.Pp 341Some CPAN modules are only indexed by author, set CPAN_AUTHOR=ID 342to locate the right directory. 343.Pp 344User settings: set CPAN_REPORT to Yes, CPAN_REPORT_DB to a valid directory, 345and CPAN_REPORT_FROM to a valid email address to automate the reporting 346of regress tests to CPAN. 347.It devel/cmake 348.It devel/gconf2 349A link from 350.Xr gconftool-2 1 351to 352.Xr true 1 353will be put at the front of the path. 354Sets CONFIGURE_ARGS, BUILD_DEPENDS and RUN_DEPENDS. 355According to the values of MODGCONF2_LIBDEP, sets LIB_DEPENDS. 356User settings: set MODGCONF2_SCHEMAS_DIR to the directory name under 357${LOCALBASE}/share/schemas/ where schemas files will be installed. 358.It devel/gettext 359.It devel/pmk 360Sets CONFIGURE_SCRIPT, CONFIGURE_ARGS and MODPMK_configure. 361It appends 362.Pa devel/pmk 363to BUILD_DEPENDS. 364.It devel/scons 365Adds 366.Pa devel/scons 367to BUILD_DEPENDS. 368Sets MODSCONS_BIN and MODSCONS_ENV. 369Also defines an overridable MODSCONS_FLAGS. 370It provides a do-build and do-install target that can be overridden in the 371port Makefile. 372.It devel/waf 373Adds 374.Pa devel/waf 375to BUILD_DEPENDS, 376.Pa lang/python 377to MODULES, and provides do-configure, do-build, do-install and 378post-install targets. 379do-build, do-install and post-install can be overridden in the port 380Makefile. 381.It gcc3 382If USE_GCC3=No (defined by 383.Pa /usr/share/mk/bsd.own.mk ) , 384and architecture is in MODGCC3_ARCHES, then the gcc 3.3.6 385compilers will be put at the front of the path. 386By default, only C language support is included by this module. 387If other languages are needed, they must be listed in MODGCC3_LANGS 388(e.g. c++, g77). 389.It gcc4 390If USE_GCC4=No (the default), and architecture is in 391MODGCC4_ARCHES, then the gcc 4.2 compilers will be put at the front of 392the path. 393By default, only C language support is included by this module. 394If other languages are needed, they must be listed in MODGCC4_LANGS 395(e.g. c++, fortran). 396.It gnu 397This module is documented in the main 398.Xr bsd.port.mk 5 399manpage. 400.It imake 401This module is documented in the main 402.Xr bsd.port.mk 5 403manpage. 404.It java 405Set MODJAVA_VER=x.y to use exactly the JDK x.y, MODJAVA_VER=x.y+ to 406use any x.y or higher version. 407Set MODJAVA_JRERUN=Yes if the port only needs the JRE at runtime. 408The module sets JAVA_HOME, ONLY_FOR_ARCHS, MODJAVA_RUN_DEPENDS, and 409appends to BUILD_DEPENDS and RUN_DEPENDS. 410It heeds NO_BUILD. 411.It lang/ghc 412Sets ONLY_FOR_ARCHS, MODGHC_VERSION, BUILD_DEPENDS, and RUN_DEPENDS. 413.It lang/lua 414Appends to RUN_DEPENDS and CATEGORIES. 415Also appends to BUILD_DEPENDS, 416unless NO_BUILD has been set to Yes. 417.It lang/mono 418Sets ONLY_FOR_ARCHS, CONFIGURE_ENV, MAKE_FLAGS, MODMONO_BUILD_DEPENDS 419and MODMONO_RUN_DEPENDS. 420If MODMONO_DEPS is set to Yes, 421.Pa lang/mono 422is appended to BUILD_DEPENDS and RUN_DEPENDS. 423If USE_NANT is defined, NANT and NANT_FLAGS are set, 424.Pa devel/nant 425is appended to BUILD_DEPENDS and the do-build and do-install targets are 426provided to use nant for building 427.Pq can be overridden in the port Makefile . 428DLLMAP_FILES defines in which files the module will substitute hardcoded 429shared library versions using a post-configure target. 430.It lang/ocaml 431Sets OCAML_VERSION, MODOCAML_NATIVE. 432Appends to BUILD_DEPENDS and MAKE_ENV. 433This also selects a %%native%% plist fragment depending on whether 434the architecture supports native compilation or not. 435.It lang/python 436Sets MODPY_VERSION, MODPY_BIN, MODPY_INCDIR, MODPY_LIBDIR, MODPY_SITEPKG, 437MODPY_SETUP, MODPY_LIB_DEPENDS, MODPY_RUN_DEPENDS, MODPY_BUILD_DEPENDS. 438Appends to RUN_DEPENDS unless MODPY_RUNDEP is set to No. 439MODPY_VERSION is the default version used by all python modules. 440Ports which use the setuptools module should set MODPY_SETUPTOOLS to Yes. 441All ports that generate egg-info files should set MODPY_EGG_VERSION 442to the version string used by the port's setup.py setup() function. 443Extra arguments to the build and install commands can be passed via 444MODPY_DISTUTILS_BUILDARGS and MODPY_DISTUTILS_INSTALLARGS. 445Also affects CATEGORIES, MAKE_ENV, CONFIGURE_ENV, SHARED_ONLY, and SUBST_VARS. 446May affect the regress target. 447.It lang/ruby 448Sets MODRUBY_REV, RUBY, MODRUBY_RUN_DEPENDS, MODRUBY_LIB_DEPENDS, 449MODRUBY_LIBDIR, MODRUBY_DOCDIR, MODRUBY_EXAMPLEDIR, MODRUBY_ARCH. 450Appends to BUILD_DEPENDS, RUN_DEPENDS, CATEGORIES and SUBST_VARS. 451.It lang/tcl 452Sets MODTCL_VERSION, MODTCL_BIN, MODTCL_INCDIR, MODTCL_LIBDIR, 453MODTCL_BUILD_DEPENDS, MODTCL_RUN_DEPENDS, MODTCL_LIB, MODTCL_LIB_DEPENDS, 454and MODTCL_CONFIG. 455MODTCL_VERSION is the default version used by all Tcl ports and 456may be overridden. 457Provides MODTCL_TCLSH_ADJ and MODTCL_WISH_ADJ shell fragments to 458patch the interpreter path in executable scripts. 459Also affects CATEGORIES and SUBST_VARS. 460.It perl 461This module is documented in the main 462.Xr bsd.port.mk 5 463manpage. 464.It textproc/intltool 465Sets MODINTLTOOL_OVERRIDE. 466.Pa textproc/intltool 467is added to BUILD_DEPENDS. 468MODINTLTOOL_OVERRIDE changes the paths of INTLTOOL_EXTRACT, INTLTOOL_MERGE and 469INTLTOOL_UPDATE to use the installed versions of intltool-extract, 470intltool-merge and intltool-update, instead of the version's packages into the 471distfile of the port using this module. 472Also affects CONFIGURE_ENV, MAKE_ENV and MAKE_FLAGS by appending 473MODINTLTOOL_OVERRIDE to them. 474.It www/drupal5 475.It www/drupal6 476.It www/pear 477.It www/plone 478Sets MODPLONE_VERSION and MODZOPE_VERSION. 479MODPLONE_VERSION is the default version used by all Plone ports and may be overridden. 480It appends 481.Pa www/plone 482to RUN_DEPENDS and also sets NO_REGRESS to Yes. 483.It www/zope 484.It x11/gnome 485Sets DESKTOP_FILES, EXTRACT_SUFX, MODGNOME_HELP_FILES, MODGNOME_BUILD_DEPENDS, 486MODGNOME_RUN_DEPENDS and USE_GMAKE. 487EXTRACT_SUFX defaults to .tar.bz2. 488Also affects CATEGORIES. 489If CONFIGURE_STYLE is set to either gnu or autoconf 490--disable-silent-rules and --disable-shave 491is appended to CONFIGURE_ARGS. 492If DESKTOP_FILES=Yes, a dependency on 493.Pa devel/desktop-file-utils 494is appended 495to MODGNOME_RUN_DEPENDS. 496If MODGNOME_HELP_FILES=Yes, then 497.Pa x11/gnome/yelp 498is appended to MODGNOME_RUN_DEPENDS and 499.Pa x11/gnome/doc-utils 500is appended to MODGNOME_BUILD_DEPENDS. 501This option is to be used when .xml GNOME help files are installed into 502.Pa share/gnome/help/ . 503Unless NO_BUILD=Yes, USE_LIBTOOL is set to Yes and 504.Pa textproc/intltool 505is appended to MODULES. 506.Pp 507MASTER_SITES and DISTNAME are built using GNOME_PROJECT and 508GNOME_VERSION. 509.It x11/gnustep 510.It x11/kde 511.It x11/qt2 512.It x11/qt3 513.It x11/qt4 514.It x11/tk 515Sets MODTK_VERSION, MODTK_BIN, MODTK_INCDIR, MODTK_LIBDIR, 516MODTK_BUILD_DEPENDS, MODTK_RUN_DEPENDS, MODTK_LIB, MODTK_LIB_DEPENDS, 517and MODTK_CONFIG. 518MODTK_VERSION is the default version used by all Tk ports and 519may be overridden. 520Automatically adds the lang/tcl module, provides a default 521MODTCL_VERSION to match MODTK_VERSION, and affects CATEGORIES, 522SUBST_VARS, and USE_X11. 523Note the MODTCL_WISH_ADJ shell fragment in the lang/tcl module. 524.It x11/xfce4 525Sets DIST_SUBDIR, EXTRACT_SUFX, CONFIGURE_STYLE, 526CONFIGURE_ENV, USE_X11 and USE_GMAKE. 527If DESKTOP_FILES is set to yes, it adds 528.Pa devel/desktop-file-utils 529to RUN_DEPENDS. 530Unless XFCE_NO_SRC is set, USE_LIBTOOL is set to yes and 531.Pa devel/gettext 532and 533.Pa textproc/intltool 534are added to MODULES. 535Also affects CATEGORIES. 536.Pp 537Xfce ports can be divided into five categories: core libraries and 538applications, goodies, artwork, thunar plugins, and panel plugins. 539HOMEPAGE, MASTER_SITES and DISTNAME are built using XFCE_VERSION (which 540defaults to XFCE_DESKTOP_VERSION if not set) and either XFCE_PROJECT, 541XFCE_GOODIE, XFCE_ARTWORK, THUNAR_PLUGIN or XFCE_PLUGIN. 542One of the latter has to be provided by the port Makefile. 543.El 544.Sh SEE ALSO 545.Xr make 1 , 546.Xr bsd.port.mk 5 , 547.Xr ports 7 548