Index: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml (revision 46688) +++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml (revision 46689) @@ -1,4665 +1,4710 @@ Special Considerations This section explains the most common things to consider when creating a port. Staging bsd.port.mk expects ports to work with a stage directory. This means that a port must not install files directly to the regular destination directories (that is, under PREFIX, for example) but instead into a separate directory from which the package is then built. In many cases, this does not require root privileges, making it possible to build packages as an unprivileged user. With staging, the port is built and installed into the stage directory, STAGEDIR. A package is created from the stage directory and then installed on the system. Automake tools refer to this concept as DESTDIR, but in &os;, DESTDIR has a different meaning (see ). When a port still requires system-wide privileges in order to run the stage and package targets, this line must be added to the Makefile: NEED_ROOT= yes The vast majority of ports do not really need to be root. It can mostly be avoided by using USES=uidfix, and from time to time by slightly patching the port's Makefiles. Meta ports, or ports that do not install files themselves but only depend on other ports, must avoid needlessly extracting the &man.mtree.8; to the stage directory. This is the basic directory layout of the package, and these empty directories will be seen as orphans. To prevent &man.mtree.8; extraction, add this line: NO_MTREE= yes Staging is enabled by prepending STAGEDIR to paths used in the pre-install, do-install, and post-install targets (see the examples through the book). Typically, this includes PREFIX, ETCDIR, DATADIR, EXAMPLESDIR, MANPREFIX, DOCSDIR, and so on. Directories should be created as part of the post-install target. Avoid using absolute paths whenever possible. When creating a symlink, STAGEDIR is prepended to the target path only. For example: ${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so The source path ${PREFIX}/lib/libfoo.so.42 looks fine but could, in fact, be incorrect. Absolute paths can point to a wrong location, like when a remote file system has been mounted with NFS under a non-root mount point. Relative paths are less fragile, and often much shorter. Ports that install kernel modules must prepend STAGEDIR to their destination, by default /boot/modules. Bundled Libraries This section explains why bundled dependencies are considered bad and what to do about them. Why Bundled Libraries Are Bad Some software requires the porter to locate third-party libraries and add the required dependencies to the port. Other software bundles all necessary libraries into the distribution file. The second approach seems easier at first, but there are some serious drawbacks: This list is loosely based on the Fedora and Gentoo wikis, both licensed under the CC-BY-SA 3.0 license. Security If vulnerabilities are found in the upstream library and fixed there, they might not be fixed in the library bundled with the port. One reason could be that the author is not aware of the problem. This means that the porter must fix them, or upgrade to a non-vulnerable version, and send a patch to the author. This all takes time, which results in software being vulnerable longer than necessary. This in turn makes it harder to coordinate a fix without unnecessarily leaking information about the vulnerability. Bugs This problem is similar to the problem with security in the last paragraph, but generally less severe. Forking It is easier for the author to fork the upstream library once it is bundled. While convenient on first sight, it means that the code diverges from upstream making it harder to address security or other problems with the software. A reason for this is that patching becomes harder. Another problem of forking is that because code diverges from upstream, bugs get solved over and over again instead of just once at a central location. This defeats the idea of open source software in the first place. Symbol collision When a library is installed on the system, it might collide with the bundled version. This can cause immediate errors at compile or link time. It can also cause errors when running the program which might be harder to track down. The latter problem could be caused because the versions of the two libraries are incompatible. Licensing When bundling projects from different sources, license issues can arise more easily, especially when licenses are incompatible. Waste of resources Bundled libraries waste resources on several levels. It takes longer to build the actual application, especially if these libraries are already present on the system. At run-time, they can take up unnecessary memory when the system-wide library is already loaded by one program and the bundled library is loaded by another program. Waste of effort When a library needs patches for &os;, these patches have to be duplicated again in the bundled library. This wastes developer time because the patches might not apply cleanly. It can also be hard to notice that these patches are required in the first place. What to do About Bundled Libraries Whenever possible, use the unbundled version of the library by adding a LIB_DEPENDS to the port. If such a port does not exist yet, consider creating it. Only use bundled libraries if the upstream has a good track record on security and using unbundled versions leads to overly complex patches. In some very special cases, for example emulators, like Wine, a port has to bundle libraries, because they are in a different architecture, or they have been modified to fit the software's use. In that case, those libraries should not be exposed to other ports for linking. Add BUNDLE_LIBS=yes to the port's Makefile. This will tell &man.pkg.8; to not compute provided libraries. Always ask the &a.portmgr; before adding this to a port. Shared Libraries If the port installs one or more shared libraries, define a USE_LDCONFIG make variable, which will instruct a bsd.port.mk to run ${LDCONFIG} -m on the directory where the new library is installed (usually PREFIX/lib) during post-install target to register it into the shared library cache. This variable, when defined, will also facilitate addition of an appropriate @exec /sbin/ldconfig -m and @unexec /sbin/ldconfig -R pair into pkg-plist, so that a user who installed the package can start using the shared library immediately and de-installation will not cause the system to still believe the library is there. USE_LDCONFIG= yes The default directory can be overridden by setting USE_LDCONFIG to a list of directories into which shared libraries are to be installed. For example, if the port installs shared libraries into PREFIX/lib/foo and PREFIX/lib/bar use this in Makefile: USE_LDCONFIG= ${PREFIX}/lib/foo ${PREFIX}/lib/bar Please double-check, often this is not necessary at all or can be avoided through -rpath or setting LD_RUN_PATH during linking (see lang/moscow_ml for an example), or through a shell-wrapper which sets LD_LIBRARY_PATH before invoking the binary, like www/seamonkey does. When installing 32-bit libraries on 64-bit system, use USE_LDCONFIG32 instead. If the software uses autotools, and specifically libtool, add USES=libtool. When the major library version number increments in the update to the new port version, all other ports that link to the affected library must have their PORTREVISION incremented, to force recompilation with the new library version. Ports with Distribution Restrictions or Legal Concerns Licenses vary, and some of them place restrictions on how the application can be packaged, whether it can be sold for profit, and so on. It is the responsibility of a porter to read the licensing terms of the software and make sure that the &os; project will not be held accountable for violating them by redistributing the source or compiled binaries either via FTP/HTTP or CD-ROM. If in doubt, please contact the &a.ports;. In situations like this, the variables described in the next sections can be set. <varname>NO_PACKAGE</varname> This variable indicates that we may not generate a binary package of the application. For instance, the license may disallow binary redistribution, or it may prohibit distribution of packages created from patched sources. However, the port's DISTFILES may be freely mirrored on FTP/HTTP. They may also be distributed on a CD-ROM (or similar media) unless NO_CDROM is set as well. If the binary package is not generally useful, and the application must always be compiled from the source code, use NO_PACKAGE. For example, if the application has configuration information that is site specific hard coded into it at compile time, set NO_PACKAGE. Set NO_PACKAGE to a string describing the reason why the package cannot be generated. <varname>NO_CDROM</varname> This variable alone indicates that, although we are allowed to generate binary packages, we may put neither those packages nor the port's DISTFILES onto a CD-ROM (or similar media) for resale. However, the binary packages and the port's DISTFILES will still be available via FTP/HTTP. If this variable is set along with NO_PACKAGE, then only the port's DISTFILES will be available, and only via FTP/HTTP. Set NO_CDROM to a string describing the reason why the port cannot be redistributed on CD-ROM. For instance, use this if the port's license is for non-commercial use only. <varname>NOFETCHFILES</varname> Files defined in NOFETCHFILES are not fetchable from any of MASTER_SITES. An example of such a file is when the file is supplied on CD-ROM by the vendor. Tools which check for the availability of these files on MASTER_SITES have to ignore these files and not report about them. <varname>RESTRICTED</varname> Set this variable alone if the application's license permits neither mirroring the application's DISTFILES nor distributing the binary package in any way. Do not set NO_CDROM or NO_PACKAGE along with RESTRICTED, since the latter variable implies the former ones. Set RESTRICTED to a string describing the reason why the port cannot be redistributed. Typically, this indicates that the port contains proprietary software and that the user will need to manually download the DISTFILES, possibly after registering for the software or agreeing to accept the terms of an EULA. <varname>RESTRICTED_FILES</varname> When RESTRICTED or NO_CDROM is set, this variable defaults to ${DISTFILES} ${PATCHFILES}, otherwise it is empty. If only some of the distribution files are restricted, then set this variable to list them. <varname>LEGAL_TEXT</varname> If the port has legal concerns not addressed by the above variables, set LEGAL_TEXT to a string explaining the concern. For example, if special permission was obtained for &os; to redistribute the binary, this variable must indicate so. <filename>/usr/ports/LEGAL</filename> and <varname>LEGAL</varname> A port which sets any of the above variables must also be added to /usr/ports/LEGAL. The first column is a glob which matches the restricted distfiles. The second column is the port's origin. The third column is the output of make -VLEGAL. Examples The preferred way to state "the distfiles for this port must be fetched manually" is as follows: .if !exists(${DISTDIR}/${DISTNAME}${EXTRACT_SUFX}) IGNORE= may not be redistributed because of licensing reasons. Please visit some-website to accept their license and download ${DISTFILES} into ${DISTDIR} .endif This both informs the user, and sets the proper metadata on the user's machine for use by automated programs. Note that this stanza must be preceded by an inclusion of bsd.port.pre.mk. Building Mechanisms Building Ports in Parallel The &os; ports framework supports parallel building using multiple make sub-processes, which allows SMP systems to utilize all of their available CPU power, allowing port builds to be faster and more effective. This is achieved by passing -jX flag to &man.make.1; running on vendor code. This is the default build behavior of ports. Unfortunately, not all ports handle parallel building well and it may be required to explicitly disable this feature by adding the MAKE_JOBS_UNSAFE=yes variable. It is used when a port is known to be broken with -jX. <command>make</command>, <command>gmake</command>, <command>fmake</command>, and <command>imake</command> Several differing make implementations exist. Ported software often requires a particular implementation, like GNU make, known in &os; as gmake, or fmake, the legacy &os; make. If the port uses GNU make, add gmake to USES. If the legacy &os; make is needed, add fmake there. MAKE_CMD can be used to reference the specific command configured by the USES setting in the port's Makefile. In rare cases when more than one make implementation is listed in USES, the variables GMAKE (for the GNU version) or FMAKE (for the legacy &os; version) are available. Only use MAKE_CMD within the application Makefiles in WRKSRC to call the make implementation expected by the ported software. If the port is an X application that uses imake to create Makefiles from Imakefiles, set USES= imake.. See the USES=imake section of for more details. If the port's source Makefile has something other than all as the main build target, set ALL_TARGET accordingly. The same goes for install and INSTALL_TARGET. <command>configure</command> Script If the port uses the configure script to generate Makefile from Makefile.in, set GNU_CONFIGURE=yes. To give extra arguments to the configure script (the default argument is --prefix=${PREFIX} --infodir=${PREFIX}/${INFO_PATH} --mandir=${MANPREFIX}/man --build=${CONFIGURE_TARGET}), set those extra arguments in CONFIGURE_ARGS. Extra environment variables can be passed using CONFIGURE_ENV. Variables for Ports That Use <command>configure</command> Variable Means GNU_CONFIGURE The port uses configure script to prepare build. HAS_CONFIGURE Same as GNU_CONFIGURE, except default configure target is not added to CONFIGURE_ARGS. CONFIGURE_ARGS Additional arguments passed to configure script. CONFIGURE_ENV Additional environment variables to be set for configure script run. CONFIGURE_TARGET Override default configure target. Default value is ${MACHINE_ARCH}-portbld-freebsd${OSREL}.
Using <command>cmake</command> For ports that use CMake, define USES= cmake, or USES= cmake:outsource to build in a separate directory (see below). Variables for Ports That Use <command>cmake</command> Variable Means CMAKE_ARGS Port specific CMake flags to be passed to the cmake binary. CMAKE_BUILD_TYPE Type of build (CMake predefined build profiles). Default is Release, or Debug if WITH_DEBUG is set. CMAKE_ENV Environment variables to be set for the cmake binary. Default is ${CONFIGURE_ENV}. CMAKE_SOURCE_PATH Path to the source directory. Default is ${WRKSRC}.
Variables the Users Can Define for <command>cmake</command> Builds Variable Means CMAKE_VERBOSE Enable verbose build output. Default not set, unless BATCH or PACKAGE_BUILDING are set. CMAKE_NOCOLOR Disables colour build output. Default not set, unless BATCH or PACKAGE_BUILDING are set.
CMake supports these build profiles: Debug, Release, RelWithDebInfo and MinSizeRel. Debug and Release profiles respect system *FLAGS, RelWithDebInfo and MinSizeRel will set CFLAGS to -O2 -g and -Os -DNDEBUG correspondingly. The lower-cased value of CMAKE_BUILD_TYPE is exported to PLIST_SUB and must be used if the port installs *.cmake depending on the build type (see deskutils/strigi for an example). Please note that some projects may define their own build profiles and/or force particular build type by setting CMAKE_BUILD_TYPE in CMakeLists.txt. To make a port for such a project respect CFLAGS and WITH_DEBUG, the CMAKE_BUILD_TYPE definitions must be removed from those files. Most CMake-based projects support an out-of-source method of building. The out-of-source build for a port can be requested by using the :outsource suffix. When enabled, CONFIGURE_WRKSRC, BUILD_WRKSRC and INSTALL_WRKSRC will be set to ${WRKDIR}/.build and this directory will be used to keep all files generated during configuration and build stages, leaving the source directory intact. <literal>USES= cmake</literal> Example This snippet demonstrates the use of CMake for a port. CMAKE_SOURCE_PATH is not usually required, but can be set when the sources are not located in the top directory, or if only a subset of the project is intended to be built by the port. USES= cmake:outsource CMAKE_SOURCE_PATH= ${WRKSRC}/subproject Using <command>scons</command> If the port uses SCons, define USE_SCONS=yes. Variables for Ports That Use <command>scons</command> Variable Means SCONS_ARGS Port specific SCons flags passed to the SCons environment. SCONS_BUILDENV Variables to be set in system environment. SCONS_ENV Variables to be set in SCons environment. SCONS_TARGET Last argument passed to SCons, similar to MAKE_TARGET.
To make third party SConstruct respect everything that is passed to SCons in SCONS_ENV (that is, most importantly, CC/CXX/CFLAGS/CXXFLAGS), patch SConstruct so build Environment is constructed like this: env = Environment(**ARGUMENTS) It may be then modified with env.Append and env.Replace. Using GNU Autotools Introduction The various GNU autotools provide an abstraction mechanism for building a piece of software over a wide variety of operating systems and machine architectures. Within the Ports Collection, an individual port can make use of these tools via a simple construct: USE_AUTOTOOLS= tool[:env] ... At the time of writing, tool can be one of autoconf, autoheader, automake, aclocal, libtoolize. It can also be one the older legacy of autoconf213, autoheader213, automake14, aclocal14. env is used to specify that the environmental variables are needed. It also adds a build dependency on the tool. The relevant tool is not ran as part of the run-autotools target. Multiple tools can be specified at once, either by including them all on a single line, or using the += Makefile construct. <command>libtool</command> and <command>libtoolize</command> Ports shipping with their own copy of libtool (search for a file named ltmain.sh) need to have USES=libtool. If a port has USE_AUTOTOOLS=libtoolize it probably also needs USES=libtool. See the USES=libtool section in for more details. <filename>libltdl.so</filename> Some ports make use of the libltdl.so library package, which is part of the libtool suite. Use of this library does not automatically necessitate the use of libtool itself. If the port needs libltdl.so, add a dependency on it: LIB_DEPENDS= libltdl.so:${PORTSDIR}/devel/libltdl <command>autoconf</command> and <command>autoheader</command> Some ports do not contain a configure script, but do contain an autoconf template in configure.ac. Use these assignments to let autoconf create the configure script, and also have autoheader create template headers for use by the configure script. USE_AUTOTOOLS= autoconf[:env] and USE_AUTOTOOLS= autoheader which also implies the use of autoconf. The additional optional variables AUTOCONF_ARGS and AUTOHEADER_ARGS can be overridden by the port Makefile if specifically requested. Most ports are unlikely to need this. See bsd.autotools.mk for further details. <command>automake</command> and <command>aclocal</command> Some packages only contain Makefile.am. These have to be converted into Makefile.in using automake, and the further processed by configure to generate an actual Makefile. Similarly, packages occasionally do not ship with an included aclocal.m4, again required to build the software. This can be achieved with aclocal, which scans configure.ac or configure.in. aclocal has a similar relationship to automake as autoheader does to autoconf, described in the previous section. aclocal implies the use of automake, thus we have: USE_AUTOTOOLS= automake[:env] and USE_AUTOTOOLS= aclocal As with autoconf and autoheader, both automake and aclocal have optional argument variables, AUTOMAKE_ARGS and ACLOCAL_ARGS respectively, which may be overridden by the port Makefile if required. Using GNU <literal>gettext</literal> Basic Usage If the port requires gettext, set USES= gettext, and the port will inherit a dependency on libintl.so from devel/gettext. Other values for gettext usage are listed in USES=gettext. A rather common case is a port using gettext and configure. Generally, GNU configure should be able to locate gettext automatically. USES= gettext GNU_CONFIGURE= yes If it ever fails to, hints at the location of gettext can be passed in CPPFLAGS and LDFLAGS as follows: USES= gettext CPPFLAGS+= -I${LOCALBASE}/include LDFLAGS+= -L${LOCALBASE}/lib GNU_CONFIGURE= yes Optional Usage Some software products allow for disabling NLS. For example, through passing to configure. In that case, the port must use gettext conditionally, depending on the status of the NLS option. For ports of low to medium complexity, use this idiom: GNU_CONFIGURE= yes OPTIONS_DEFINE= NLS OPTIONS_SUB= yes NLS_USES= gettext NLS_CONFIGURE_ENABLE= nls .include <bsd.port.mk> Or using the older way of using options: GNU_CONFIGURE= yes OPTIONS_DEFINE= NLS .include <bsd.port.options.mk> .if ${PORT_OPTIONS:MNLS} USES+= gettext PLIST_SUB+= NLS="" .else CONFIGURE_ARGS+= --disable-nls PLIST_SUB+= NLS="@comment " .endif .include <bsd.port.mk> The next item on the to-do list is to arrange so that the message catalog files are included in the packing list conditionally. The Makefile part of this task is already provided by the idiom. It is explained in the section on advanced pkg-plist practices. In a nutshell, each occurrence of %%NLS%% in pkg-plist will be replaced by @comment  if NLS is disabled, or by a null string if NLS is enabled. Consequently, the lines prefixed by %%NLS%% will become mere comments in the final packing list if NLS is off; otherwise the prefix will be just left out. Then insert %%NLS%% before each path to a message catalog file in pkg-plist. For example: %%NLS%%share/locale/fr/LC_MESSAGES/foobar.mo %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo In high complexity cases, more advanced techniques may be needed, such as dynamic packing list generation. Handling Message Catalog Directories There is a point to note about installing message catalog files. The target directories for them, which reside under LOCALBASE/share/locale, must not be created and removed by a port. The most popular languages have their respective directories listed in PORTSDIR/Templates/BSD.local.dist. The directories for many other languages are governed by the devel/gettext port. Consult its pkg-plist and see whether the port is going to install a message catalog file for a unique language. Using <application>Perl</application> If MASTER_SITES is set to CPAN, the correct subdirectory is usually selected automatically. If the default subdirectory is wrong, CPAN/Module can be used to change it. MASTER_SITES can also be set to the old MASTER_SITE_PERL_CPAN, then the preferred value of MASTER_SITE_SUBDIR is the top-level hierarchy name. For example, the recommended value for p5-Module-Name is Module. The top-level hierarchy can be examined at cpan.org. This keeps the port working when the author of the module changes. The exception to this rule is when the relevant directory does not exist or the distfile does not exist in that directory. In such case, using author's id as MASTER_SITE_SUBDIR is allowed. The CPAN:AUTHOR macro can be used, which will be translated to the hashed author directory. For example, CPAN:AUTHOR will be converted to authors/id/A/AU/AUTHOR. When a port needs Perl support, it must set USES=perl5 with the optional USE_PERL5 described in the perl5 USES description. Read-Only Variables for Ports That Use <application>Perl</application> Read only variables Means PERL The full path of the Perl 5 interpreter, either in the system or installed from a port, but without the version number. Use this when the software needs the path to the Perl interpreter. To replace #!lines in scripts, use USES=shebangfix. PERL_VERSION The full version of Perl installed (for example, 5.8.9). PERL_LEVEL The installed Perl version as an integer of the form MNNNPP (for example, 500809). PERL_ARCH Where Perl stores architecture dependent libraries. Defaults to ${ARCH}-freebsd. PERL_PORT Name of the Perl port that is installed (for example, perl5). SITE_PERL Directory name where site specific Perl packages go. This value is added to PLIST_SUB.
Ports of Perl modules which do not have an official website must link to cpan.org in the WWW line of pkg-descr. The preferred URL form is http://search.cpan.org/dist/Module-Name/ (including the trailing slash). Do not use ${SITE_PERL} in dependency declarations. Doing so assumes that perl5.mk has been included, which is not always true. Ports depending on this port will have incorrect dependencies if this port's files move later in an upgrade. The right way to declare Perl module dependencies is shown in the example below. Perl Dependency Example p5-IO-Tee>=0.64:${PORTSDIR}/devel/p5-IO-Tee For Perl ports that install manual pages, the macro PERL5_MAN3 can be used inside pkg-plist. For example, lib/perl5/5.14/man/man3/AnyEvent::I3.3.gz can be replaced with %%PERL5_MAN3%%/AnyEvent::I3.3.gz There are no PERL5_MANx macros for the other sections (x in 1, 2 and 4 to 9) because those get installed in the regular directories. Using X11 X.Org Components The X11 implementation available in The Ports Collection is X.Org. If the application depends on X components, set USE_XORG to the list of required components. Available components, at the time of writing, are: bigreqsproto compositeproto damageproto dmx dmxproto dri2proto dri3proto evieproto fixesproto fontcacheproto fontenc fontsproto fontutil glproto ice inputproto kbproto libfs oldx pciaccess pixman presentproto printproto randrproto recordproto renderproto resourceproto scrnsaverproto sm trapproto videoproto x11 xau xaw xaw6 xaw7 xbitmaps xcb xcmiscproto xcomposite xcursor xdamage xdmcp xevie xext xextproto xf86bigfontproto xf86dgaproto xf86driproto xf86miscproto xf86rushproto xf86vidmodeproto xfixes xfont xfontcache xft xi xinerama xineramaproto xkbfile xkbui xmu xmuu xorg-macros xorg-server xp xpm xprintapputil xprintutil xproto xproxymngproto xrandr xrender xres xscrnsaver xshmfence xt xtrans xtrap xtst xv xvmc xxf86dga xxf86misc xxf86vm. Always up-to-date list can be found in /usr/ports/Mk/bsd.xorg.mk. The Mesa Project is an effort to provide free OpenGL implementation. To specify a dependency on various components of this project, use USE_GL. Valid options are: egl, gl, glesv2, glew, glu, glut, glw and linux. For backwards compatibility, the value of yes maps to glu. <varname>USE_XORG</varname> Example USE_XORG= xrender xft xkbfile xt xaw USE_GL= glu Variables for Ports That Use X USES= imake The port uses imake. XMKMF Set to the path of xmkmf if not in the PATH. Defaults to xmkmf -a.
Using X11-Related Variables # Use some X11 libraries USE_XORG= x11 xpm Ports That Require Motif If the port requires a Motif library, define USES= motif in the Makefile. Default Motif implementation is x11-toolkits/open-motif. Users can choose x11-toolkits/lesstif instead by setting WANT_LESSTIF in their make.conf. MOTIFLIB will be set by motif.mk to reference the appropriate Motif library. Please patch the source of the port to use ${MOTIFLIB} wherever the Motif library is referenced in the original Makefile or Imakefile. There are two common cases: If the port refers to the Motif library as -lXm in its Makefile or Imakefile, substitute ${MOTIFLIB} for it. If the port uses XmClientLibs in its Imakefile, change it to ${MOTIFLIB} ${XTOOLLIB} ${XLIB}. Note that MOTIFLIB (usually) expands to -L/usr/local/lib -lXm -lXp or /usr/local/lib/libXm.a, so there is no need to add -L or -l in front. X11 Fonts If the port installs fonts for the X Window System, put them in LOCALBASE/lib/X11/fonts/local. Getting a Fake <envar>DISPLAY</envar> with Xvfb Some applications require a working X11 display for compilation to succeed. This pose a problem for machines that operate headless. When this variable is used, the build infrastructure will start the virtual framebuffer X server. The working DISPLAY is then passed to the build. See USES=display for the possible arguments. USES= display Desktop Entries Desktop entries (a Freedesktop standard) provide a way to automatically adjust desktop features when a new program is installed, without requiring user intervention. For example, newly-installed programs automatically appear in the application menus of compatible desktop environments. Desktop entries originated in the GNOME desktop environment, but are now a standard and also work with KDE and Xfce. This bit of automation provides a real benefit to the user, and desktop entries are encouraged for applications which can be used in a desktop environment. Using Predefined <filename>.desktop</filename> Files Ports that include predefined *.desktop must include those files in pkg-plist and install them in the $LOCALBASE/share/applications directory. The INSTALL_DATA macro is useful for installing these files. Updating Desktop Database If a port has a MimeType entry in its portname.desktop, the desktop database must be updated after install and deinstall. To do this, define USES= desktop-file-utils. Creating Desktop Entries with <varname>DESKTOP_ENTRIES</varname> Desktop entries can be easily created for applications by using DESKTOP_ENTRIES. A file named name.desktop will be created, installed, and added to pkg-plist automatically. Syntax is: DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify The list of possible categories is available on the Freedesktop website. StartupNotify indicates whether the application is compatible with startup notifications. These are typically a graphic indicator like a clock that appear at the mouse pointer, menu, or panel to give the user an indication when a program is starting. A program that is compatible with startup notifications clears the indicator after it has started. Programs that are not compatible with startup notifications would never clear the indicator (potentially confusing and infuriating the user), and must have StartupNotify set to false so the indicator is not shown at all. Example: DESKTOP_ENTRIES= "ToME" "Roguelike game based on JRR Tolkien's work" \ "${DATADIR}/xtra/graf/tome-128.png" \ "tome -v -g" "Application;Game;RolePlaying;" \ false Using GNOME The &os;/GNOME project uses its own set of variables to define which GNOME components a particular port uses. A comprehensive list of these variables exists within the &os;/GNOME project's homepage. Using Qt Ports That Require Qt The Ports Collection provides support for Qt 4 and Qt 5 frameworks with USE_QTx, where x is 4 or 5. Set USE_QTx to the list of required Qt components (libraries, tools, plugins). The Qt 4 and Qt 5 frameworks are quite similar. The main difference is the set of supported components. The Qt framework exports a number of variables which can be used by ports, some of them listed below: Variables Provided to Ports That Use Qt QT_PREFIX Set to the path where Qt was installed (${LOCALBASE}). QMAKE Full path to qmake binary. LRELEASE Full path to lrelease utility. MOC Full path to moc. RCC Full path to rcc. UIC Full path to uic. QT_INCDIR Qt include directory. QT_LIBDIR Qt libraries path. QT_PLUGINDIR Qt plugins path.
When using the Qt framework, these settings are deployed: CONFIGURE_ARGS+= --with-qt-includes=${QT_INCDIR} \ --with-qt-libraries=${QT_LIBDIR} \ --with-extra-libs=${LOCALBASE}/lib \ --with-extra-includes=${LOCALBASE}/include CONFIGURE_ENV+= QTDIR="${QT_PREFIX}" QMAKE="${QMAKE}" \ MOC="${MOC}" RCC="${RCC}" UIC="${UIC}" \ QMAKESPEC="${QMAKESPEC}" PLIST_SUB+= QT_INCDIR=${QT_INCDIR_REL} \ QT_LIBDIR=${QT_LIBDIR_REL} \ QT_PLUGINDIR=${QT_PLUGINDIR_REL} Some configure scripts do not support the arguments above. To suppress modification ofCONFIGURE_ENV and CONFIGURE_ARGS, set QT_NONSTANDARD. Component Selection Individual Qt tool and library dependencies must be specified in USE_QTx. Every component can be suffixed with _build or _run, the suffix indicating whether the dependency on the component is at buildtime or runtime. If unsuffixed, the component will be depended on at both build- and runtime. Usually, library components are specified unsuffixed, tool components are mostly specified with the _build suffix and plugin components are specified with the _run suffix. The most commonly used components are listed below (all available components are listed in _USE_QT_ALL, _USE_QT4_ONLY, and _USE_QT5_ONLY in /usr/ports/Mk/bsd.qt.mk): Available Qt Library Components Name Description core core library (Qt 5 only) corelib core library (Qt 4 only) dbus Qt DBus library gui graphical user interface library network network library opengl Qt OpenGL library script script library sql SQL library testlib unit testing library webkit Qt WebKit library xml Qt XML library
To determine the libraries an application depends on, run ldd on the main executable after a successful compilation. Available Qt Tool Components Name Description qmake Makefile generator/build utility buildtools build tools (moc, rcc), needed for almost every Qt application (Qt 5 only) linguisttools localization tools: lrelease, lupdate (Qt 5 only) linguist localization tools: lrelease, lupdate (Qt 4 only) moc meta object compiler, needed for almost every Qt application at buildtime (Qt 4 only) rcc resource compiler, needed if the application comes with *.rc or *.qrc files (Qt 4 only) uic user interface compiler, needed if the application comes with *.ui files, in practice, every Qt application with a GUI (Qt 4 only)
Available Qt Plugin Components Name Description iconengines SVG icon engine plugin, needed if the application ships SVG icons (Qt 4 only) imageformats plugins for TGA, TIFF, and MNG image formats
Selecting Qt 4 Components In this example, the ported application uses the Qt 4 graphical user interface library, the Qt 4 core library, all of the Qt 4 code generation tools and Qt 4's Makefile generator. Since the gui library implies a dependency on the core library, corelib does not need to be specified. The Qt 4 code generation tools moc, uic and rcc, as well as the Makefile generator qmake are only needed at buildtime, thus they are specified with the _build suffix: USE_QT4= gui moc_build qmake_build rcc_build uic_build Using <command>qmake</command> If the application provides a qmake project file (*.pro), define USES= qmake along with USE_QTx. Note that USES= qmake already implies a build dependency on qmake, therefore the qmake component can be omitted from USE_QTx. Similar to CMake, qmake supports out-of-source builds, which can be enabled by specifying the outsource argument (see USES= qmake example). Variables for Ports That Use <command>qmake</command> Variable Means QMAKE_ARGS Port specific qmake flags to be passed to the qmake binary. QMAKE_ENV Environment variables to be set for the qmake binary. The default is ${CONFIGURE_ENV}. QMAKE_SOURCE_PATH Path to qmake project files (.pro). The default is ${WRKSRC} if an out-of-source build is requested, empty otherwise.
<literal>USES= qmake</literal> Example This snippet demonstrates the use of qmake for a Qt 4 port: USES= qmake:outsource USE_QT4= moc_build For a Qt 5 port: USES= qmake:outsource USE_QT5= buildtools_build Qt applications are often written to be cross-platform and often X11/Unix is not the platform they are developed on, which in turn leads to certain loose ends, like: Missing additional include paths. Many applications come with system tray icon support, but neglect to look for includes and/or libraries in the X11 directories. To add directories to qmake's include and library search paths via the command line, use: QMAKE_ARGS+= INCLUDEPATH+=${LOCALBASE}/include \ LIBS+=-L${LOCALBASE}/lib Bogus installation paths. Sometimes data such as icons or .desktop files are by default installed into directories which are not scanned by XDG-compatible applications. editors/texmaker is an example for this - look at patch-texmaker.pro in the files directory of that port for a template on how to remedy this directly in the qmake project file. Using KDE KDE 4 Variable Definitions If the application depends on KDE 4, set USE_KDE4 to the list of required components. _build and _run suffixes can be used to force components dependency type (for example, baseapps_run). If no suffix is set, a default dependency type will be used. To force both types, add the component twice with both suffixes (for example, automoc4_build automoc4_run). The most commonly used components are listed below (up-to-date components are documented at the top of /usr/ports/Mk/bsd.kde4.mk): Available KDE 4 Components Name Description kdehier Hierarchy of common KDE directories kdelibs KDE core libraries kdeprefix If set, port will be installed into ${KDE4_PREFIX} automoc4 Build tool to automatically generate moc files akonadi Storage server for KDE PIM data soprano Library for Resource Description Framework (RDF) strigi Strigi desktop search library libkcddb KDE CDDB (compact disc database) library libkcompactdisc KDE library for interfacing with audio CDs libkdeedu Libraries used by educational applications libkdcraw KDE LibRaw library libkexiv2 KDE Exiv2 library libkipi KDE Image Plugin Interface libkonq Konqueror core library libksane KDE SANE ("Scanner Access Now Easy") library pimlibs Personal information management libraries kate Advanced text editor framework marble Virtual globe and world atlas okular Universal document viewer korundum KDE Ruby bindings perlkde KDE Perl bindings pykde4 KDE Python bindings pykdeuic4 PyKDE user interface compiler smokekde KDE SMOKE libraries
KDE 4 ports are installed into KDE4_PREFIX. This is achieved by specifying the kdeprefix component, which overrides the default PREFIX. The ports, however, respect any PREFIX set via the MAKEFLAGS environment variable and/or make arguments. Currently KDE4_PREFIX is identical to the default PREFIX, ${LOCALBASE}. <varname>USE_KDE4</varname> Example This is a simple example for a KDE 4 port. USES= cmake:outsource instructs the port to utilize CMake, a configuration tool widely used by KDE 4 projects (see for detailed usage). USE_KDE4 brings dependency on KDE libraries and makes port using automoc4 at build stage. Required KDE components and other dependencies can be determined through configure log. USE_KDE4 does not imply USE_QT4. If a port requires some Qt 4 components, specify them in USE_QT4. USES= cmake:outsource USE_KDE4= kdelibs kdeprefix automoc4 USE_QT4= moc_build qmake_build rcc_build uic_build Using Java Variable Definitions If the port needs a Java™ Development Kit (JDK™) to either build, run or even extract the distfile, then define USE_JAVA. There are several JDKs in the ports collection, from various vendors, and in several versions. If the port must use one of these versions, define which one. The most current version, and &os; default is java/openjdk6. Variables Which May be Set by Ports That Use Java Variable Means USE_JAVA Define for the remaining variables to have any effect. JAVA_VERSION List of space-separated suitable Java versions for the port. An optional "+" allows specifying a range of versions (allowed values: 1.5[+] 1.6[+] 1.7[+]). JAVA_OS List of space-separated suitable JDK port operating systems for the port (allowed values: native linux). JAVA_VENDOR List of space-separated suitable JDK port vendors for the port (allowed values: freebsd bsdjava sun openjdk). JAVA_BUILD When set, add the selected JDK port to the build dependencies. JAVA_RUN When set, add the selected JDK port to the run dependencies. JAVA_EXTRACT When set, add the selected JDK port to the extract dependencies.
Below is the list of all settings a port will receive after setting USE_JAVA: Variables Provided to Ports That Use Java Variable Value JAVA_PORT The name of the JDK port (for example, java/openjdk6). JAVA_PORT_VERSION The full version of the JDK port (for example, 1.6.0). Only the first two digits of this version number are needed, use ${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}. JAVA_PORT_OS The operating system used by the JDK port (for example, 'native'). JAVA_PORT_VENDOR The vendor of the JDK port (for example, 'openjdk'). JAVA_PORT_OS_DESCRIPTION Description of the operating system used by the JDK port (for example, 'Native'). JAVA_PORT_VENDOR_DESCRIPTION Description of the vendor of the JDK port (for example, 'OpenJDK BSD Porting Team'). JAVA_HOME Path to the installation directory of the JDK (for example, '/usr/local/openjdk6'). JAVAC Path to the Java compiler to use (for example, '/usr/local/openjdk6/bin/javac'). JAR Path to the jar tool to use (for example, '/usr/local/openjdk6/bin/jar' or '/usr/local/bin/fastjar'). APPLETVIEWER Path to the appletviewer utility (for example, '/usr/local/openjdk6/bin/appletviewer'). JAVA Path to the java executable. Use this for executing Java programs (for example, '/usr/local/openjdk6/bin/java'). JAVADOC Path to the javadoc utility program. JAVAH Path to the javah program. JAVAP Path to the javap program. JAVA_KEYTOOL Path to the keytool utility program. JAVA_N2A Path to the native2ascii tool. JAVA_POLICYTOOL Path to the policytool program. JAVA_SERIALVER Path to the serialver utility program. RMIC Path to the RMI stub/skeleton generator, rmic. RMIREGISTRY Path to the RMI registry program, rmiregistry. RMID Path to the RMI daemon program rmid. JAVA_CLASSES Path to the archive that contains the JDK class files, ${JAVA_HOME}/jre/lib/rt.jar.
Use the java-debug make target to get information for debugging the port. It will display the value of many of the previously listed variables. Additionally, these constants are defined so all Java ports may be installed in a consistent way: Constants Defined for Ports That Use Java Constant Value JAVASHAREDIR The base directory for everything related to Java. Default: ${PREFIX}/share/java. JAVAJARDIR The directory where JAR files is installed. Default: ${JAVASHAREDIR}/classes. JAVALIBDIR The directory where JAR files installed by other ports are located. Default: ${LOCALBASE}/share/java/classes.
The related entries are defined in both PLIST_SUB (documented in ) and SUB_LIST. Building with Ant When the port is to be built using Apache Ant, it has to define USE_ANT. Ant is thus considered to be the sub-make command. When no do-build target is defined by the port, a default one will be set that runs Ant according to MAKE_ENV, MAKE_ARGS and ALL_TARGET. This is similar to the USES= gmake mechanism, which is documented in . Best Practices When porting a Java library, the port has to install the JAR file(s) in ${JAVAJARDIR}, and everything else under ${JAVASHAREDIR}/${PORTNAME} (except for the documentation, see below). To reduce the packing file size, reference the JAR file(s) directly in the Makefile. Use this statement (where myport.jar is the name of the JAR file installed as part of the port): PLIST_FILES+= %%JAVAJARDIR%%/myport.jar When porting a Java application, the port usually installs everything under a single directory (including its JAR dependencies). The use of ${JAVASHAREDIR}/${PORTNAME} is strongly encouraged in this regard. It is up the porter to decide whether the port installs the additional JAR dependencies under this directory or uses the already installed ones (from ${JAVAJARDIR}). When porting a &java; application that requires an application server such as www/tomcat7 to run the service, it is quite common for a vendor to distribute a .war. A .war is a Web application ARchive and is extracted when called by the application. Avoid adding a .war to pkg-plist. It is not considered best practice. An application server will expand war archive, but not clean it up properly if the port is removed. A more desirable way of working with this file is to extract the archive, then install the files, and lastly add these files to pkg-plist. TOMCATDIR= ${LOCALBASE}/apache-tomcat-7.0 WEBAPPDIR= myapplication post-extract: @${MKDIR} ${WRKDIR}/${PORTDIRNAME} @${TAR} xf ${WRKDIR}/myapplication.war -C ${WRKDIR}/${PORTDIRNAME} do-install: cd ${WRKDIR} && \ ${INSTALL} -d -o ${WWWOWN} -g ${WWWGRP} ${TOMCATDIR}/webapps/${PORTDIRNAME} @cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME} Regardless of the type of port (library or application), the additional documentation is installed in the same location as for any other port. The JavaDoc tool is known to produce a different set of files depending on the version of the JDK that is used. For ports that do not enforce the use of a particular JDK, it is therefore a complex task to specify the packing list (pkg-plist). This is one reason why porters are strongly encouraged to use PORTDOCS. Moreover, even if the set of files that will be generated by javadoc can be predicted, the size of the resulting pkg-plist advocates for the use of PORTDOCS. The default value for DATADIR is ${PREFIX}/share/${PORTNAME}. It is a good idea to override DATADIR to ${JAVASHAREDIR}/${PORTNAME} for Java ports. Indeed, DATADIR is automatically added to PLIST_SUB (documented in ) so use %%DATADIR%% directly in pkg-plist. As for the choice of building Java ports from source or directly installing them from a binary distribution, there is no defined policy at the time of writing. However, people from the &os; Java Project encourage porters to have their ports built from source whenever it is a trivial task. All the features that have been presented in this section are implemented in bsd.java.mk. If the port needs more sophisticated Java support, please first have a look at the bsd.java.mk Subversion log as it usually takes some time to document the latest features. Then, if the needed support that is lacking would be beneficial to many other Java ports, feel free to discuss it on the &a.java;. Although there is a java category for PRs, it refers to the JDK porting effort from the &os; Java project. Therefore, submit the Java port in the ports category as for any other port, unless the issue is related to either a JDK implementation or bsd.java.mk. Similarly, there is a defined policy regarding the CATEGORIES of a Java port, which is detailed in . Web Applications, Apache and PHP Apache Variables for Ports That Use Apache USE_APACHE The port requires Apache. Possible values: yes (gets any version), 22, 24, 22-24, 22+, etc. The default APACHE version is 22. More details are available in ports/Mk/bsd.apache.mk and at wiki.freebsd.org/Apache/. APXS Full path to the apxs binary. Can be overridden in the port. HTTPD Full path to the httpd binary. Can be overridden in the port. APACHE_VERSION The version of present Apache installation (read-only variable). This variable is only available after inclusion of bsd.port.pre.mk. Possible values: 22, 24. APACHEMODDIR Directory for Apache modules. This variable is automatically expanded in pkg-plist. APACHEINCLUDEDIR Directory for Apache headers. This variable is automatically expanded in pkg-plist. APACHEETCDIR Directory for Apache configuration files. This variable is automatically expanded in pkg-plist.
Useful Variables for Porting Apache Modules MODULENAME Name of the module. Default value is PORTNAME. Example: mod_hello SHORTMODNAME Short name of the module. Automatically derived from MODULENAME, but can be overridden. Example: hello AP_FAST_BUILD Use apxs to compile and install the module. AP_GENPLIST Also automatically creates a pkg-plist. AP_INC Adds a directory to a header search path during compilation. AP_LIB Adds a directory to a library search path during compilation. AP_EXTRAS Additional flags to pass to apxs.
Web Applications Web applications must be installed into PREFIX/www/appname. This path is available both in Makefile and in pkg-plist as WWWDIR, and the path relative to PREFIX is available in Makefile as WWWDIR_REL. The user and group of web server process are available as WWWOWN and WWWGRP, in case the ownership of some files needs to be changed. The default values of both are www. Use WWWOWN?= myuser and WWWGRP?= mygroup if the port needs different values. This allows the user to override them easily. Do not depend on Apache unless the web app explicitly needs Apache. Respect that users may wish to run a web app on different web server than Apache. PHP Variables for Ports That Use PHP USE_PHP The port requires PHP. The value yes adds a dependency on PHP. The list of required PHP extensions can be specified instead. Example: pcre xml gettext DEFAULT_PHP_VER Selects which major version of PHP will be installed as a dependency when no PHP is installed yet. Default is 5. Possible values: 4, 5 IGNORE_WITH_PHP The port does not work with PHP of the given version. Possible values: 4, 5 USE_PHPIZE The port will be built as a PHP extension. USE_PHPEXT The port will be treated as a PHP extension, including installation and registration in the extension registry. USE_PHP_BUILD Set PHP as a build dependency. WANT_PHP_CLI Want the CLI (command line) version of PHP. WANT_PHP_CGI Want the CGI version of PHP. WANT_PHP_MOD Want the Apache module version of PHP. WANT_PHP_SCR Want the CLI or the CGI version of PHP. WANT_PHP_WEB Want the Apache module or the CGI version of PHP.
PEAR Modules Porting PEAR modules is a very simple process. Add USES=pear to the port's Makefile. The framework will install the relevant files in the right places and automatically generate the plist at install time. Example Makefile for PEAR Class PORTNAME= Date PORTVERSION= 1.4.3 CATEGORIES= devel www pear MAINTAINER= example@domain.com COMMENT= PEAR Date and Time Zone Classes USES= pear .include <bsd.port.mk> <application>Horde</application> Modules In the same way, porting Horde modules is a simple process. Add USES=horde to the port's Makefile. The framework will install the relevant files in the right places and automatically generate the plist at install time. The USE_HORDE_BUILD and USE_HORDE_RUN variables can be used to add buildtime and runtime dependencies on other Horde modules. See Mk/Uses/horde.mk for a complete list of available modules. Example Makefile for <application>Horde</application> Module PORTNAME= Horde_Core PORTVERSION= 2.14.0 CATEGORIES= devel www pear MAINTAINER= horde@FreeBSD.org COMMENT= Horde Core Framework libraries OPTIONS_DEFINE= KOLAB SOCKETS KOLAB_DESC= Enable Kolab server support SOCKETS_DESC= Depend on sockets PHP extension USES= horde USE_PHP= session USE_HORDE_BUILD= Horde_Role USE_HORDE_RUN= Horde_Role Horde_History Horde_Pack \ Horde_Text_Filter Horde_View KOLAB_USE= HORDE_RUN=Horde_Kolab_Server,Horde_Kolab_Session SOCKETS_USE= PHP=sockets .include <bsd.port.mk> Using Python The Ports Collection supports parallel installation of multiple Python versions. Ports must use a correct python interpreter, according to the user-settable PYTHON_VERSION. Most prominently, this means replacing the path to python executable in scripts with the value of PYTHON_CMD. Ports that install files under PYTHON_SITELIBDIR must use the pyXY- package name prefix, so their package name embeds the version of Python they are installed into. PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX} Most Useful Variables for Ports That Use Python USES=python The port needs Python. The minimal required version can be specified with values such as 2.7+. Version ranges can also be specified by separating two version numbers with a dash: USES=python:3.2-3.3 USE_PYTHON=distutils Use Python distutils for configuring, compiling, and installing. This is required when the port comes with setup.py. This overrides the do-build and do-install targets and may also override do-configure if GNU_CONFIGURE is not defined. USE_PYTHON=autoplist Create the packaging list automatically. This also requires USE_PYTHON=distutils to be set. USE_PYTHON=concurrent The port will use an unique prefix, typically PYTHON_PKGNAMEPREFIX for certain directories, such as EXAMPLESDIR and DOCSDIR and also will append a suffix, the python version from PYTHON_VER, to binaries and scripts to be installed. This allows ports to be installed for different Python versions at the same time, which otherwise would install conflicting files. PYTHON_PKGNAMEPREFIX Used as a PKGNAMEPREFIX to distinguish packages for different Python versions. Example: py27- PYTHON_SITELIBDIR Location of the site-packages tree, that contains installation path of Python (usually LOCALBASE). PYTHON_SITELIBDIR can be very useful when installing Python modules. PYTHONPREFIX_SITELIBDIR The PREFIX-clean variant of PYTHON_SITELIBDIR. Always use %%PYTHON_SITELIBDIR%% in pkg-plist when possible. The default value of %%PYTHON_SITELIBDIR%% is lib/python%%PYTHON_VERSION%%/site-packages PYTHON_CMD Python interpreter command line, including version number. PYNUMERIC Dependency line for numeric extension. PYNUMPY Dependency line for the new numeric extension, numpy. (PYNUMERIC is deprecated by upstream vendor). PYXML Dependency line for XML extension (not needed for Python 2.0 and higher as it is also in base distribution).
A complete list of available variables can be found in /usr/ports/Mk/Uses/python.mk. Makefile for a Simple <application>Python</application> Module PORTNAME= sample PORTVERSION= 1.2.3 CATEGORIES= devel MAINTAINER= john@doe.tld COMMENT= Python sample module USES= python USE_PYTHON= autoplist distutils .include <bsd.port.mk> Some Python applications claim to have DESTDIR support (which would be required for staging) but it is broken (Mailman up to 2.1.16, for instance). This can be worked around by recompiling the scripts. This can be done, for example, in the post-build target. Assuming the Python scripts are supposed to reside in PYTHONPREFIX_SITELIBDIR after installation, this solution can be applied: (cd ${STAGEDIR}${PREFIX} \ && ${PYTHON_CMD} ${PYTHON_LIBDIR}/compileall.py \ -d ${PREFIX} -f ${PYTHONPREFIX_SITELIBDIR:S;${PREFIX}/;;}) This recompiles the sources with a path relative to the stage directory, and prepends the value of PREFIX to the file name recorded in the byte-compiled output file by -d. -f is required to force recompilation, and the :S;${PREFIX}/;; strips prefixes from the value of PYTHONPREFIX_SITELIBDIR to make it relative to PREFIX. Using <application>Tcl/Tk</application> The Ports Collection supports parallel installation of multiple Tcl/Tk versions. Ports should try to support at least the default Tcl/Tk version and higher with USES=tcl. It is possible to specify the desired version of tcl by appending :xx, for example, USES=tcl:85. The Most Useful Read-Only Variables for Ports That Use <application>Tcl/Tk</application> TCL_VER chosen major.minor version of Tcl TCLSH full path of the Tcl interpreter TCL_LIBDIR path of the Tcl libraries TCL_INCLUDEDIR path of the Tcl C header files TK_VER chosen major.minor version of Tk WISH full path of the Tk interpreter TK_LIBDIR path of the Tk libraries TK_INCLUDEDIR path of the Tk C header files
See the USES=tcl and USES=tk of for a full description of those variables. A complete list of those variables is available in /usr/ports/Mk/Uses/tcl.mk. Using Emacs This section is yet to be written. Using Ruby Useful Variables for Ports That Use Ruby Variable Description USE_RUBY The port requires Ruby. USE_RUBY_EXTCONF The port uses extconf.rb to configure. USE_RUBY_SETUP The port uses setup.rb to configure. RUBY_SETUP Set to the alternative name of setup.rb. Common value is install.rb.
This table shows the selected variables available to port authors via the ports infrastructure. These variables are used to install files into their proper locations. Use them in pkg-plist as much as possible. Do not redefine these variables in the port. Selected Read-Only Variables for Ports That Use Ruby Variable Description Example value RUBY_PKGNAMEPREFIX Used as a PKGNAMEPREFIX to distinguish packages for different Ruby versions. ruby19- RUBY_VERSION Full version of Ruby in the form of x.y.z[.p]. 1.9.3.484 RUBY_SITELIBDIR Architecture independent libraries installation path. /usr/local/lib/ruby/site_ruby/1.9 RUBY_SITEARCHLIBDIR Architecture dependent libraries installation path. /usr/local/lib/ruby/site_ruby/1.9/amd64-freebsd10 RUBY_MODDOCDIR Module documentation installation path. /usr/local/share/doc/ruby19/patsy RUBY_MODEXAMPLESDIR Module examples installation path. /usr/local/share/examples/ruby19/patsy
A complete list of available variables can be found in /usr/ports/Mk/bsd.ruby.mk. Using SDL USE_SDL is used to autoconfigure the dependencies for ports which use an SDL based library like devel/sdl12 and graphics/sdl_image. These SDL libraries for version 1.2 are recognized: sdl: devel/sdl12 console: devel/sdl_console gfx: graphics/sdl_gfx image: graphics/sdl_image mixer: audio/sdl_mixer mm: devel/sdlmm net: net/sdl_net pango: x11-toolkits/sdl_pango sound: audio/sdl_sound ttf: graphics/sdl_ttf These SDL libraries for version 2.0 are recognized: sdl: devel/sdl20 gfx: graphics/sdl2_gfx image: graphics/sdl2_image mixer: audio/sdl2_mixer net: net/sdl2_net ttf: graphics/sdl2_ttf Therefore, if a port has a dependency on net/sdl_net and audio/sdl_mixer, the syntax will be: USE_SDL= net mixer The dependency devel/sdl12, which is required by net/sdl_net and audio/sdl_mixer, is automatically added as well. Using USE_SDL with entries for SDL 1.2, it will automatically: Add a dependency on sdl12-config to BUILD_DEPENDS Add the variable SDL_CONFIG to CONFIGURE_ENV Add the dependencies of the selected libraries to LIB_DEPENDS Using USE_SDL with entries for SDL 2.0, it will automatically: Add a dependency on sdl2-config to BUILD_DEPENDS Add the variable SDL2_CONFIG to CONFIGURE_ENV Add the dependencies of the selected libraries to LIB_DEPENDS To check whether an SDL library is available, use WANT_SDL: WANT_SDL= yes .include <bsd.port.pre.mk> .if ${HAVE_SDL:Mmixer}!="" USE_SDL+= mixer .endif .include <bsd.port.post.mk> Using <application>wxWidgets</application> This section describes the status of the wxWidgets libraries in the ports tree and its integration with the ports system. Introduction There are many versions of the wxWidgets libraries which conflict between them (install files under the same name). In the ports tree this problem has been solved by installing each version under a different name using version number suffixes. The obvious disadvantage of this is that each application has to be modified to find the expected version. Fortunately, most of the applications call the wx-config script to determine the necessary compiler and linker flags. The script is named differently for every available version. Majority of applications respect an environment variable, or accept a configure argument, to specify which wx-config script to call. Otherwise they have to be patched. Version Selection To make the port use a specific version of wxWidgets there are two variables available for defining (if only one is defined the other will be set to a default value): Variables to Select <application>wxWidgets</application> Versions Variable Description Default value USE_WX List of versions the port can use All available versions USE_WX_NOT List of versions the port cannot use None
The available wxWidgets versions and the corresponding ports in the tree are: Available <application>wxWidgets</application> Versions Version Port 2.4 x11-toolkits/wxgtk24 2.6 x11-toolkits/wxgtk26 2.8 x11-toolkits/wxgtk28
The versions starting from 2.5 also come in Unicode version and are installed by a slave port named like the normal one plus a -unicode suffix, but this can be handled with variables (see ). The variables in can be set to one or more of these combinations separated by spaces: <application>wxWidgets</application> Version Specifications Description Example Single version 2.4 Ascending range 2.4+ Descending range 2.6- Full range (must be ascending) 2.4-2.6
There are also some variables to select the preferred versions from the available ones. They can be set to a list of versions, the first ones will have higher priority. Variables to Select Preferred <application>wxWidgets</application> Versions Name Designed for WANT_WX_VER the port WITH_WX_VER the user
Component Selection There are other applications that, while not being wxWidgets libraries, are related to them. These applications can be specified in WX_COMPS. These components are available: Available <application>wxWidgets</application> Components Name Description Version restriction wx main library none contrib contributed libraries none python wxPython (Python bindings) 2.4-2.6 mozilla wxMozilla 2.4 svg wxSVG 2.6
The dependency type can be selected for each component by adding a suffix separated by a semicolon. If not present then a default type will be used (see ). These types are available: Available <application>wxWidgets</application> Dependency Types Name Description build Component is required for building, equivalent to BUILD_DEPENDS run Component is required for running, equivalent to RUN_DEPENDS lib Component is required for building and running, equivalent to LIB_DEPENDS
The default values for the components are detailed in this table: Default <application>wxWidgets</application> Dependency Types Component Dependency type wx lib contrib lib python run mozilla lib svg lib
Selecting <application>wxWidgets</application> Components This fragment corresponds to a port which uses wxWidgets version 2.4 and its contributed libraries. USE_WX= 2.4 WX_COMPS= wx contrib Unicode The wxWidgets library supports Unicode since version 2.5. In the ports tree both versions are available and can be selected with these variables: Variables to Select Unicode in <application>wxWidgets</application> Versions Variable Description Designed for WX_UNICODE The port works only with the Unicode version the port WANT_UNICODE The port works with both versions but prefers the Unicode one the port WITH_UNICODE The port will use the Unicode version the user WITHOUT_UNICODE The port will use the normal version if supported (when WX_UNICODE is not defined) the user
Do not use WX_UNICODE for ports that can use both Unicode and normal versions. If the port needs to use Unicode by default, define WANT_UNICODE instead. Detecting Installed Versions To detect an installed version, define WANT_WX. If it is not set to a specific version then the components will have a version suffix. HAVE_WX will be filled after detection. Detecting Installed <application>wxWidgets</application> Versions and Components This fragment can be used in a port that uses wxWidgets if it is installed, or an option is selected. WANT_WX= yes .include <bsd.port.pre.mk> .if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.4) USE_WX= 2.4 CONFIGURE_ARGS+= --enable-wx .endif This fragment can be used in a port that enables wxPython support if it is installed or if an option is selected, in addition to wxWidgets, both version 2.6. USE_WX= 2.6 WX_COMPS= wx WANT_WX= 2.6 .include <bsd.port.pre.mk> .if defined(WITH_WXPYTHON) || !empty(PORT_OPTIONS:MWXPYTHON) || !empty(HAVE_WX:Mpython) WX_COMPS+= python CONFIGURE_ARGS+= --enable-wxpython .endif Defined Variables These variables are available in the port (after defining one from ). Variables Defined for Ports That Use <application>wxWidgets</application> Name Description WX_CONFIG The path to the wxWidgets wx-config script (with different name) WXRC_CMD The path to the wxWidgets wxrc program (with different name) WX_VERSION The wxWidgets version that is going to be used (for example, 2.6) WX_UNICODE If not defined but Unicode is going to be used then it will be defined
Processing in <filename>bsd.port.pre.mk</filename> Define WX_PREMK to be able to use the variables right after including bsd.port.pre.mk. When defining WX_PREMK, then the version, dependencies, components and defined variables will not change if modifying the wxWidgets port variables after including bsd.port.pre.mk. Using <application>wxWidgets</application> Variables in Commands This fragment illustrates the use of WX_PREMK by running the wx-config script to obtain the full version string, assign it to a variable and pass it to the program. USE_WX= 2.4 WX_PREMK= yes .include <bsd.port.pre.mk> .if exists(${WX_CONFIG}) VER_STR!= ${WX_CONFIG} --release PLIST_SUB+= VERSION="${VER_STR}" .endif The wxWidgets variables can be safely used in commands when they are inside targets without the need of WX_PREMK. Additional <command>configure</command> Arguments Some GNU configure scripts cannot find wxWidgets with just the WX_CONFIG environment variable set, requiring additional arguments. WX_CONF_ARGS can be used for provide them. Legal Values for <varname>WX_CONF_ARGS</varname> Possible value Resulting argument absolute --with-wx-config=${WX_CONFIG} relative --with-wx=${LOCALBASE} --with-wx-config=${WX_CONFIG:T}
Using <application>Lua</application> This section describes the status of the Lua libraries in the ports tree and its integration with the ports system. Introduction There are many versions of the Lua libraries and corresponding interpreters, which conflict between them (install files under the same name). In the ports tree this problem has been solved by installing each version under a different name using version number suffixes. The obvious disadvantage of this is that each application has to be modified to find the expected version. But it can be solved by adding some additional flags to the compiler and linker. Version Selection A port using Lua only needs to have this line: USES= lua If a specific version of Lua is needed, instructions on how to select it are given in the USES=lua part of . Defined Variables These variables are available in the port. Variables Defined for Ports That Use <application>Lua</application> Name Description LUA_VER The Lua version that is going to be used (for example, 5.1) LUA_VER_STR The Lua version without the dots (for example, 51) LUA_PREFIX The prefix where Lua (and components) is installed LUA_SUBDIR The directory under ${PREFIX}/bin, ${PREFIX}/share and ${PREFIX}/lib where Lua is installed LUA_INCDIR The directory where Lua and tolua header files are installed LUA_LIBDIR The directory where Lua and tolua libraries are installed LUA_MODLIBDIR The directory where Lua module libraries (.so) are installed LUA_MODSHAREDIR The directory where Lua modules (.lua) are installed LUA_PKGNAMEPREFIX The package name prefix used by Lua modules LUA_CMD The path to the Lua interpreter LUAC_CMD The path to the Lua compiler
Using <command>iconv</command> After 2013-10-08 (254273), &os;  10-CURRENT and newer versions have a native iconv in the operating system. On earlier versions, converters/libiconv was used as a dependency. For software that needs iconv, define USES=iconv. &os; versions before 10-CURRENT on 2013-08-13 (254273) do not have a native iconv. On these earlier versions, a dependency on converters/libiconv will be added automatically. When a port defines USES=iconv, these variables will be available: Variable name Purpose Value before &os; 10-CURRENT 254273 (2013-08-13) Value after &os; 10-CURRENT 254273 (2013-08-13) ICONV_CMD Directory where the iconv binary resides ${LOCALBASE}/bin/iconv /usr/bin/iconv ICONV_LIB ld argument to link to libiconv (if needed) -liconv (empty) ICONV_PREFIX Directory where the iconv implementation resides (useful for configure scripts) ${LOCALBASE} /usr ICONV_CONFIGURE_ARG Preconstructed configure argument for configure scripts --with-libiconv-prefix=${LOCALBASE} (empty) ICONV_CONFIGURE_BASE Preconstructed configure argument for configure scripts --with-libiconv=${LOCALBASE} (empty) These two examples automatically populate the variables with the correct value for systems using converters/libiconv or the native iconv respectively: Simple <command>iconv</command> Usage USES= iconv LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB} <command>iconv</command> Usage with <command>configure</command> USES= iconv CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG} As shown above, ICONV_LIB is empty when a native iconv is present. This can be used to detect the native iconv and respond appropriately. Sometimes a program has an ld argument or search path hardcoded in a Makefile or configure script. This approach can be used to solve that problem: Fixing Hardcoded <literal>-liconv</literal> USES= iconv post-patch: @${REINPLACE_CMD} -e 's/-liconv/${ICONV_LIB}/' ${WRKSRC}/Makefile In some cases it is necessary to set alternate values or perform operations depending on whether there is a native iconv. bsd.port.pre.mk must be included before testing the value of ICONV_LIB: Checking for Native <command>iconv</command> Availability USES= iconv .include <bsd.port.pre.mk> post-patch: .if empty(ICONV_LIB) # native iconv detected @${REINPLACE_CMD} -e 's|iconv||' ${WRKSRC}/Config.sh .endif .include <bsd.port.post.mk> Using Xfce - USE_XFCE is used to - autoconfigure the dependencies for ports which use an Xfce - based library or application like - x11-toolkits/libxfce4gui - and x11-wm/xfce4-panel. + Ports that need Xfce libraries or + applications set USES=xfce. - These Xfce libraries and applications are - recognized: + Specific Xfce library and + application dependencies are set with values assigned to + USE_XFCE. They are defined in + /usr/ports/Mk/Uses/xfce.mk. The possible + values are: - - - libexo: x11/libexo - + + Values of <varname>USE_XFCE</varname> - - libgui: x11-toolkits/libxfce4gui - + + garcon - - libutil: x11/libxfce4util - + + sysutils/garcon + + - - libmcs: x11/libxfce4mcs - + + libexo - - mcsmanager: sysutils/xfce4-mcs-manager - + + x11/libexo + + - - panel: x11-wm/xfce4-panel - + - - thunar: x11-fm/thunar - + libgui - - wm: x11-wm/xfce4-wm - + + x11-toolkits/libxfce4gui + + - - xfdev: dev/xfce4-dev-tools - - + + libmenu - These additional parameters are recognized: + + x11/libxfce4menu + + - - - configenv: Use this if the port requires a special - modified CONFIGURE_ENV to find its - required libraries. + + libutil - -I${LOCALBASE}/include -L${LOCALBASE}/lib + + x11/libxfce4util + + - gets added to CPPFLAGS to - CONFIGURE_ENV. - - + + panel - Therefore, if a port has a dependency on - sysutils/xfce4-mcs-manager - and requires the special CPPFLAGS in its configure - environment, the syntax will be: + + x11-wm/xfce4-panel + + - USE_XFCE= mcsmanager configenv + + thunar + + + x11-fm/thunar + + + + + xfconf + + + x11/xfce4-conf + + + + + + <varname>USES=xfce</varname> Example + + USES= xfce +USE_XFCE= libmenu + + + + Using Xfce's Own GTK3 Widgets + + In this example, the ported application uses the + GTK3-specific widgets x11/libxfce4menu and x11/xfce4-conf. + + USES= xfce:gtk3 +USE_XFCE= libmenu xfconf + + + + Xfce components included this + way will automatically include any dependencies they need. It + is no longer necessary to specify the entire list. If the + port only needs x11-wm/xfce4-panel, use: + + USES= xfce +USE_XFCE= panel + + There is no need to list the components x11-wm/xfce4-panel needs itself like + this: + + USES= xfce +USE_XFCE= libexo libmenu libutil panel + + However, Xfce components and + non-Xfce dependencies of the port + must be included explicitly. Do not count on an + Xfce component to provide a + sub-dependency other than itself for the main port. + Using Mozilla Variables for Ports That Use Mozilla USE_GECKO Gecko backend the port can handle. Possible values: libxul (libxul.so), seamonkey (libgtkembedmoz.so, deprecated, must not be used any more). USE_FIREFOX The port requires Firefox as a runtime dependency. Possible values: yes (get default version), 40, 36, 35. Default dependency is on version 40. USE_FIREFOX_BUILD The port requires Firefox as a buildtime dependency. Possible values: see USE_FIREFOX. This automatically sets USE_FIREFOX and assigns the same value. USE_SEAMONKEY The port requires SeaMonkey as a runtime dependency. Possible values: yes (get default version), 20, 11 (deprecated, must not be used any more). Default dependency is on version 20. USE_SEAMONKEY_BUILD The port requires SeaMonkey as a buildtime dependency. Possible values: see USE_SEAMONKEY. This automatically sets USE_SEAMONKEY and assigns the same value. USE_THUNDERBIRD The port requires Thunderbird as a runtime dependency. Possible values: yes (get default version), 31, 30 (deprecated, must not be used any more). Default dependency is on version 31. USE_THUNDERBIRD_BUILD The port requires Thunderbird as a buildtime dependency. Possible values: see USE_THUNDERBIRD. This automatically sets USE_THUNDERBIRD and assigns the same value.
A complete list of available variables can be found in /usr/ports/Mk/bsd.gecko.mk. Using Databases Variables for Ports Using Databases Variable Means USE_BDB If variable is set to yes, add dependency on databases/db5 port. The variable may also be set to values: 48, 5 or 6. It is possible to declare a range of acceptable values, USE_BDB=48+ will find the highest installed version, and fall back to 4.8 if nothing else is installed. WANT_BDB_VER will always build this port with a specific version of the Berkely DB. INVALID_BDB_VER can be used to specify a version that cannot be used. USE_MYSQL If the variable is set to yes, add a dependency on the databases/mysql56-client port. An associated variable, WANT_MYSQL_VER, may be set to values such as 51, 55, or 60. Additionally to specify use of Percona, use 56p, or for MariaDB, use 53m, 55m or 100m. USE_PGSQL If set to yes, add dependency on databases/postgresql93-client port. An associated variable, WANT_PGSQL_VER, may be set to values such as 84, 90, 91, 92, 93 or 94. It is possible to declare a minimum or maximum value; WANT_PGSQL_VER= 90+ will cause the port to depend on a minimum version of 9.0. USE_SQLITE If set to yes, add dependency on databases/sqlite3 port. The variable may also be set to 3 or 2, to add a dependency on 3.x or 2.x, respectively.
More details are available in bsd.database.mk. Starting and Stopping Services (<literal>rc</literal> Scripts) rc.d scripts are used to start services on system startup, and to give administrators a standard way of stopping, starting and restarting the service. Ports integrate into the system rc.d framework. Details on its usage can be found in the rc.d Handbook chapter. Detailed explanation of the available commands is provided in &man.rc.8; and &man.rc.subr.8;. Finally, there is an article on practical aspects of rc.d scripting. With a mythical port called doorman, which needs to start a doormand daemon. Add the following to the Makefile: USE_RC_SUBR= doormand Multiple scripts may be listed and will be installed. Scripts must be placed in the files subdirectory and a .in suffix must be added to their filename. Standard SUB_LIST expansions will be ran against this file. Use of the %%PREFIX%% and %%LOCALBASE%% expansions is strongly encouraged as well. More on SUB_LIST in the relevant section. As of &os; 6.1-RELEASE, local rc.d scripts (including those installed by ports) are included in the overall &man.rcorder.8; of the base system. An example simple rc.d script to start the doormand daemon: #!/bin/sh # $FreeBSD$ # # PROVIDE: doormand # REQUIRE: LOGIN # KEYWORD: shutdown # # Add these lines to /etc/rc.conf.local or /etc/rc.conf # to enable this service: # # doormand_enable (bool): Set to NO by default. # Set it to YES to enable doormand. # doormand_config (path): Set to %%PREFIX%%/etc/doormand/doormand.cf # by default. . /etc/rc.subr name=doormand rcvar=doormand_enable load_rc_config $name : ${doormand_enable:="NO"} : ${doormand_config="%%PREFIX%%/etc/doormand/doormand.cf"} command=%%PREFIX%%/sbin/${name} pidfile=/var/run/${name}.pid command_args="-p $pidfile -f $doormand_config" run_rc_command "$1" Unless there is a very good reason to start the service earlier, or it runs as a particular user (other than root), all ports scripts must use: REQUIRE: LOGIN If the startup script launches a daemon that must be shutdown, the following will trigger a stop of the service on system shutdown: KEYWORD: shutdown If the script is not starting a persistent service this is not necessary. For optional configuration elements the "=" style of default variable assignment is preferable to the ":=" style here, since the former sets a default value only if the variable is unset, and the latter sets one if the variable is unset or null. A user might very well include something like: doormand_flags="" in their rc.conf.local, and a variable substitution using ":=" would inappropriately override the user's intention. The _enable variable is not optional, and must use the ":" for the default. Pre-Commit Checklist Before contributing a port with an rc.d script, and more importantly, before committing one, please consult this checklist to be sure that it is ready. The devel/rclint port can check for most of these, but it is not a substitute for proper review. If this is a new file, does it have a .sh extension? If so, that must be changed to just file.in since rc.d files may not end with that extension. Does the file have a $FreeBSD$ tag? Do the name of the file (minus .in), the PROVIDE line, and $name all match? The file name matching PROVIDE makes debugging easier, especially for &man.rcorder.8; issues. Matching the file name and $name makes it easier to figure out which variables are relevant in rc.conf[.local]. It is also a policy for all new scripts, including those in the base system. Is the REQUIRE line set to LOGIN? This is mandatory for scripts that run as a non-root user. If it runs as root, is there a good reason for it to run prior to LOGIN? If not, it must run after so that local scrips can be loosely grouped to a point in &man.rcorder.8; after most everything in the base is already running. Does the script start a persistent service? If so, it must have KEYWORD: shutdown. Make sure there is no KEYWORD: &os; present. This has not been necessary or desirable for years. It is also an indication that the new script was copy/pasted from an old script, so extra caution must be given to the review. If the script uses an interpreted language like perl, python, or ruby, make certain that command_interpreter is set appropriately, for example, for Perl, by adding PERL=${PERL} to SUB_LIST and using %%PERL%%. Otherwise, &prompt.root; service name stop will probably not work properly. See &man.service.8; for more information. Have all occurrences of /usr/local been replaced with %%PREFIX%%? Do the default variable assignments come after load_rc_config? Are there default assignments to empty strings? They should be removed, but double-check that the option is documented in the comments at the top of the file. Are things that are set in variables actually used in the script? Are options listed in the default name_flags things that are actually mandatory? If so, they must be in command_args. The option is a red flag (pardon the pun) here, since it is usually the option to “daemonize” the process, and therefore is actually mandatory. name_flags must never be included in command_args (and vice versa, although that error is less common). Does the script execute any code unconditionally? This is frowned on. Usually these things must be dealt with through a start_precmd. All boolean tests must use the checkyesno function. No hand-rolled tests for [Yy][Ee][Ss], etc. If there is a loop (for example, waiting for something to start) does it have a counter to terminate the loop? We do not want the boot to be stuck forever if there is an error. Does the script create files or directories that need specific permissions, for example, a pid that needs to be owned by the user that runs the process? Rather than the traditional &man.touch.1;/&man.chown.8;/&man.chmod.1; routine, consider using &man.install.1; with the proper command line arguments to do the whole procedure with one step. Adding Users and Groups Some ports require a particular user account to be present, usually for daemons that run as that user. For these ports, choose a unique UID from 50 to 999 and register it in ports/UIDs (for users) and ports/GIDs (for groups). The unique identification should be the same for users and groups. Please include a patch against these two files when requiring a new user or group to be created for the port. Then use USERS and GROUPS in Makefile, and the user will be automatically created when installing the port. USERS= pulse GROUPS= pulse pulse-access pulse-rt The current list of reserved UIDs and GIDs can be found in ports/UIDs and ports/GIDs. Ports That Rely on Kernel Sources Some ports (such as kernel loadable modules) need the kernel source files so that the port can compile. Here is the correct way to determine if the user has them installed: USES= kmod Apart from this check, the kmod feature takes care of most items that these ports need to take into account. Index: head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml (revision 46688) +++ head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml (revision 46689) @@ -1,1411 +1,1418 @@ Values of <varname>USES</varname> Values of <varname>USES</varname> Feature Arguments Description ada (none), 47, 49, 5 Depends on an Ada-capable compiler, and sets CC accordingly. Defaults to a gcc 4.9 based compiler, use :47 to use the older gcc 4.7 based one and :5 to use the newer gcc 5 based one. autoreconf (none), build Runs autoreconf. It encapsulates the aclocal, autoconf, autoheader, automake, autopoint, and libtoolize commands. Each command applies to ${CONFIGURE_WRKSRC}/configure.ac or its old name, ${CONFIGURE_WRKSRC}/configure.in. If configure.ac defines subdirectories with their own configure.ac using AC_CONFIG_SUBDIRS, autoreconf will recursively update those as well. The :build argument only adds build time dependencies on those tools but does not run autoreconf. blaslapack (none), atlas, netlib (default), gotoblas, openblas Adds dependencies on Blas / Lapack libraries. bison (none), build, run, both Uses devel/bison By default, with no arguments or with the build argument, it implies bison is a build-time dependency, run implies a run-time dependency, and both implies both run-time and build-time dependencies. charsetfix (none) Prevents the port from installing charset.alias. This must be installed only by converters/libiconv. CHARSETFIX_MAKEFILEIN can be set to a path relative to WRKSRC if charset.alias is not installed by ${WRKSRC}/Makefile.in. cmake (none), outsource, run Uses CMake for configuring and building. With the outsource argument, an out-of-source build will be performed. With the run argument, a run-time dependency is registered. For more information see . compiler (none), c++0x, c++11-lang, gcc-c++11-lib, c++11-lib, c11, openmp, nestedfct, features Determines which compiler to use based on any given wishes. Use c++11-lang if the port needs a C++11-capable compiler, gcc-c++11-lib if the port needs the g++ compiler with a C++11 library, and c++11-lib if the port also needs a C++11-ready standard library. If the port needs a compiler understanding C++0X, C11, OpenMP, or nested functions, the corresponding parameters can be used. Use features to request a list of features supported by the default compiler. After including bsd.port.pre.mk the port can inspect the results using these variables: COMPILER_TYPE: the default compiler on the system, either gcc or clang ALT_COMPILER_TYPE: the alternative compiler on the system, either gcc or clang. Only set if two compilers are present in the base system. COMPILER_VERSION: the first two digits of the version of the default compiler. ALT_COMPILER_VERSION: the first two digits of the version of the alternative compiler, if present. CHOSEN_COMPILER_TYPE: the chosen compiler, either gcc or clang COMPILER_FEATURES: the features supported by the default compiler. It currently lists the C++ library. cpe (none) Include Common Platform Enumeration (CPE) information in package manifest as a CPE 2.3 formatted string. See the CPE specification for details. To add CPE information to a port, follow these steps: Search for the official CPE entry for the software product either by using the NVD's CPE search engine or in the official CPE dictionary (warning, very large XML file). Do not ever make up CPE data. Add cpe to USES and compare the result of make -V CPE_STR to the CPE dictionary entry. Continue one step at a time until make -V CPE_STR is correct. If the product name (second field, defaults to PORTNAME) is incorrect, define CPE_PRODUCT. If the vendor name (first field, defaults to CPE_PRODUCT) is incorrect, define CPE_VENDOR. If the version field (third field, defaults to PORTVERSION) is incorrect, define CPE_VERSION. If the update field (fourth field, defaults to empty) is incorrect, define CPE_UPDATE. If it is still not correct, check Mk/Uses/cpe.mk for additional details, or contact the &a.ports-secteam;. Derive as much as possible of the CPE name from existing variables such as PORTNAME and PORTVERSION. Use variable modifiers to extract the relevant portions from these variables rather than hardcoding the name. Always run make -V CPE_STR and check the output before committing anything that changes PORTNAME or PORTVERSION or any other variable which is used to derive CPE_STR. cran (none), auto-plist Uses the Comprehensive R Archive Network. Specify auto-plist to automatically generate pkg-plist. desktop-file-utils (none) Uses update-desktop-database from devel/desktop-file-utils. An extra post-install step will be run without interfering with any post-install steps already in the port Makefile. A line with @desktop-file-utils will be added to the plist. desthack (none) Changes the behavior of GNU configure to properly support DESTDIR in case the original software does not. display (none), ARGS Set up a virtual display environment. If the environment variable DISPLAY is not set, then Xvfb is added as a build dependency, and CONFIGURE_ENV is extended with the port number of the currently running instance of Xvfb. The ARGS parameter defaults to install and controls the phase around which to start and stop the virtual display. dos2unix (none) The port has files with line endings in DOS format which need to be converted. Three variables can be set to control which files will be converted. The default is to convert all files, including binaries. See for examples. DOS2UNIX_REGEX: match file names based on a regular expression. DOS2UNIX_FILES: match literal file names. DOS2UNIX_GLOB: match file names based on a glob pattern. drupal 6, 7, module, theme Automate installation of a port that is a Drupal theme or module. Use with the version of Drupal that the port is expecting. For example, USES=drupal:6,module says that this port creates a Drupal 6 module. A Drupal 7 theme can be specified with USES=drupal:7,theme. execinfo (none) Add a library dependency on devel/libexecinfo if libexecinfo.so is not present in the base system. fakeroot (none) Changes some default behaviour of build systems to allow installing as a user. fam (none), fam, gamin Uses a File Alteration Monitor as a library dependency, either devel/fam or devel/gamin. End users can set WITH_FAM_SYSTEM to specify their preference. fmake (none) Uses devel/fmake as a build-time dependency. fonts (none) Adds a runtime dependency on tools needed to register fonts, and add an @fcfontsdir ${FONTSDIR} entry to the plist. FONTSDIR defaults to ${PREFIX}/lib/X11/fonts/${FONTNAME} and FONTNAME to ${PORTNAME}. fortran gcc (default), ifort Uses the Fortran compiler from either GNU or Intel. fuse (none) The port will depend on the FUSE library and handle the dependency on the kernel module depending on the version of &os;. gecko libxul (default), firefox, seamonkey, thunderbird, build, XY, XY+ Add a dependency on different gecko based applications. If libxul is used, it is the only argument allowed. When the argument is not libxul, the firefox, seamonkey, or thunderbird arguments can be used, along with optional build and XY/XY+ version arguments. gettext (none) Deprecated. Will include both gettext-runtime and gettext-tools. gettext-runtime (none), lib (default), build, run Uses devel/gettext-runtime. By default, with no arguments or with the lib argument, implies a library dependency on libintl.so. build and run implies, respectively a build-time and a run-time dependency on gettext. gettext-tools (none), build (default), run Uses devel/gettext-tools. By default, with no argument, or with the build argument, a build time dependency on msgfmt is registered. With the run argument, a run-time dependency is registered. gmake (none), lite Uses devel/gmake, or devel/gmake-lite if the lite argument is used, as a build-time dependency and sets up the environment to use gmake as the default make for the build. gperf (none) Add a buildtime dependency on devel/gperf if gperf is not present in the base system. gssapi (none), base (default), heimdal, mit, flags, bootstrap Handle dependencies needed by consumers of the GSS-API. Only libraries that provide the Kerberos mechanism are available. By default, or set to base, the GSS-API library from the base system is used. Can also be set to heimdal to use security/heimdal, or mit to use security/krb5. When the local Kerberos installation is not in LOCALBASE, set HEIMDAL_HOME (for heimdal) or KRB5_HOME (for krb5) to the location of the Kerberos installation. These variables are exported for the ports to use: GSSAPIBASEDIR GSSAPICPPFLAGS GSSAPIINCDIR GSSAPILDFLAGS GSSAPILIBDIR GSSAPILIBS GSSAPI_CONFIGURE_ARGS The flags option can be given alongside base, heimdal, or mit to automatically add GSSAPICPPFLAGS, GSSAPILDFLAGS, and GSSAPILIBS to CFLAGS, LDFLAGS, and LDADD, respectively. For example, use base,flags. The bootstrap option is a special prefix only for use by security/krb5 and security/heimdal. For example, use bootstrap,mit. Typical Use OPTIONS_SINGLE= GSSAPI OPTIONS_SINGLE_GSSAPI= GSSAPI_BASE GSSAPI_HEIMDAL GSSAPI_MIT GSSAPI_NONE GSSAPI_BASE_USES= gssapi GSSAPI_BASE_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_HEIMDAL_USES= gssapi:heimdal GSSAPI_HEIMDAL_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_MIT_USES= gssapi:mit GSSAPI_MIT_CONFIGURE_ON= --with-gssapi=${GSSAPIBASEDIR} ${GSSAPI_CONFIGURE_ARGS} GSSAPI_NONE_CONFIGURE_ON= --without-gssapi horde (none) Add buildtime and runtime dependencies on devel/pear-channel-horde. Other Horde dependencies can be added with USE_HORDE_BUILD and USE_HORDE_RUN. See for more information. iconv (none), lib, build, patch, translit, wchar_t Uses iconv functions, either from the port converters/libiconv as a build-time and run-time dependency, or from the base system on 10-CURRENT after a native iconv was committed in 254273. By default, with no arguments or with the lib argument, implies iconv with build-time and run-time dependencies. build implies a build-time dependency, and patch implies a patch-time dependency. If the port uses the WCHAR_T or //TRANSLIT iconv extensions, add the relevant arguments so that the correct iconv is used. For more information see . imake (none), env, notall, noman Add devel/imake as a build-time dependency and run xmkmf -a during the configure stage. If the env argument is given, the configure target is not set. If the flag is a problem for the port, add the notall argument. If xmkmf does not generate a install.man target, add the noman argument. kmod (none) Fills in the boilerplate for kernel module ports, currently: Add kld to CATEGORIES. Set SSP_UNSAFE. Set IGNORE if the kernel sources are not found in SRC_BASE. Define KMODDIR to /boot/modules by default, add it to PLIST_SUB and MAKE_ENV, and create it upon installation. If KMODDIR is set to /boot/kernel, it will be rewritten to /boot/modules. This prevents breaking packages when upgrading the kernel due to /boot/kernel being renamed to /boot/kernel.old in the process. Handle cross-referencing kernel modules upon installation and deinstallation, using @kld. lha (none) Set EXTRACT_SUFX to .lzh libtool (none), keepla, build Patches libtool scripts. This must be added to all ports that use libtool. The keepla argument can be used to keep .la files. Some ports do not ship with their own copy of libtool and need a build time dependency on devel/libtool, use the :build argument to add such dependency. lua (none), XY+, XY, build, run Adds a dependency on Lua. By default this is a library dependency, unless overridden by the build or run option. The default version is 5.2, unless set by the XY parameter (for example, 51 or 52+). makeinfo build (default), run, both Add the corresponding dependencies on makeinfo. makeself (none) Indicates that the distribution files are makeself archives and sets the appropriate dependencies. metaport (none) Sets the following variables to make it easier to create a metaport: MASTER_SITES, DISTFILES, EXTRACT_ONLY, NO_BUILD, NO_INSTALL, NO_MTREE, NO_ARCH. mono (none) Adds a dependency on the Mono (currently only C#) framework by setting the appropriate dependencies. motif (none) Uses x11-toolkits/open-motif as a library dependency. End users can set WANT_LESSTIF for the dependency to be on x11-toolkits/lesstif instead of x11-toolkits/open-motif. ncurses (none), base, port Uses ncurses, and causes some useful variables to be set. ninja (none) Uses ninja to build the port. End users can set NINJA_VERBOSE for verbose output. objc (none) Add objective C dependencies (compiler, runtime library) if the base system does not support it. openal al, soft (default), si, alut Uses OpenAL. The backend can be specified, with the software implementation as the default. The user can specify a preferred backend with WANT_OPENAL. Valid values for this knob are soft (default) and si. pathfix (none) Look for Makefile.in and configure in the port's associated sources and fix common paths to make sure they respect the &os; hierarchy. If the port uses automake, set PATHFIX_MAKEFILEIN to Makefile.am if needed. pear (none) Adds a dependency on devel/pear. It will setup default behavior for software using the PHP Extension and Application Repository. See for more information. perl5 (none) Depends on Perl. These variables can be set: PERL_VERSION: Full version of Perl to use, or the default if not set PERL_ARCH: Directory name of architecture dependent libraries, defaults to mach PERL_PORT: Name of the Perl port to be installed, the default is derived from PERL_VERSION SITE_PERL: Directory name for site specific Perl packages USE_PERL5: Phases in which to use Perl, can be extract, patch, build, install, or run. It can also be configure, modbuild, or modbuildtiny when Makefile.PL, Build.PL, or the Module::Build::Tiny flavor of Build.PL is required. It defaults to build run. pgsql (none), X.Y, X.Y+, X.Y- Provide support for PostgreSQL. Maintainer can set version required. Minimum and maximum versions can be specified; for example, 9.0-, 8.4+. Add PostgreSQL component dependency, using WANT_PGSQL=component[:target]. for example, WANT_PGSQL=server:configure pltcl plperl For the full list use make -V _USE_PGSQL_DEP. pkgconfig (none), build (default), run, both Uses devel/pkgconf. With no arguments or with the build argument, it implies pkg-config as a build-time dependency. run implies a run-time dependency and both implies both run-time and build-time dependencies. pure (none), ffi Uses lang/pure. Largely used for building related pure ports. With the ffi argument, it implies devel/pure-ffi as a run-time dependency. python (none), X.Y, X.Y+, -X.Y, X.Y-Z.A, build, run Uses Python. A supported version or version range can be specified. If Python is only needed at build or run time, it can be set as a build or run dependency with build or run. See for more information. qmail (none), build, run, both, vars Uses mail/qmail. With the build argument, it implies qmail as a build-time dependency. run implies a run-time dependency. Using no argument or the both argument implies both run-time and build-time dependencies. vars will only set QMAIL variables for the port to use. qmake (none), norecursive, outsource Uses QMake for configuring. For more information see . readline (none), port Uses readline as a library dependency, and sets CPPFLAGS and LDFLAGS as necessary. If the port argument is used or if readline is not present in the base system, add a dependency on devel/readline scons (none) Provide support for the use of devel/scons shared-mime-info (none) Uses update-mime-database from misc/shared-mime-info. This uses will automatically add a post-install step in such a way that the port itself still can specify there own post-install step if needed. It also add an @shared-mime-info entry to the plist. shebangfix (none) A lot of software uses incorrect locations for script interpreters, most notably /usr/bin/perl and /bin/bash. This fixes shebang lines in scripts listed in SHEBANG_FILES. Currently Bash, Java, Ksh, Perl, PHP, Python, Ruby, Tcl, and Tk are supported by default. To support another interpreter, set SHEBANG_LANG, lua_OLD_CMD and lua_CMD. For example SHEBANG_LANG=lua, then lua_OLD_CMD=/usr/bin/lua and lua_CMD=${LOCALBASE}/bin/lua. tar (none), Z, bz2, bzip2, lzma, tbz, tgz, txz, xz Set EXTRACT_SUFX to .tar, .tar.Z, .tar.bz2, .tar.bz2, .tar.lzma, .tbz, .tgz, .txz or .tar.xz respectively. tcl PORT Add a dependency on Tcl. The PORT parameter can be either tcl or tk. Either a version or wrapper dependency can be appended using PORT:version or PORT:wrapper. The version can be empty, one or more exact version numbers (currently 84, 85, or 86), or a minimal version number (currently 84+, 85+ or 86+). A build- or run-time only dependency can be specified using PORT,build or PORT,run. After including bsd.port.pre.mk the port can inspect the results using these variables: TCL_VER: chosen major.minor version of Tcl TCLSH: full path of the Tcl interpreter TCL_LIBDIR: path of the Tcl libraries TCL_INCLUDEDIR: path of the Tcl C header files TK_VER: chosen major.minor version of Tk WISH: full path of the Tk interpreter TK_LIBDIR: path of the Tk libraries TK_INCLUDEDIR: path of the Tk C header files tk Same as arguments for tcl Small wrapper when using both Tcl and Tk. The same variables are returned as when using Tcl. twisted (none), ARGS Add a dependency on twistedCore. The list of required components can be specified as a value of this variable. ARGS can be one of: build: add twistedCore or any specified component as build dependency. run: add twistedCore or any specified component as run dependency. Besides build and run, one or more other supported twisted components can be specified. Supported values are listed in Uses/twisted.mk. uidfix (none) Changes some default behavior (mostly variables) of the build system to allow installing this port as a normal user. Try this in the port before adding NEED_ROOT=yes uniquefiles (none), dirs Make files or directories 'unique', by adding a prefix or suffix. If the dirs argument is used, the port needs a prefix (a only a prefix) based on UNIQUE_PREFIX for standard directories DOCSDIR, EXAMPLESDIR, DATADIR, WWWDIR, ETCDIR. These variables are available for ports: UNIQUE_PREFIX: The prefix to be used for directories and files. Default: ${PKGNAMEPREFIX}. UNIQUE_PREFIX_FILES: A list of files that need to be prefixed. Default: empty. UNIQUE_SUFFIX: The suffix to be used for files. Default: ${PKGNAMESUFFIX}. UNIQUE_SUFFIX_FILES: A list of files that need to be suffixed. Default: empty. webplugin (none), ARGS Automatically create and remove symbolic links for each application that supports the webplugin framework. ARGS can be one of: gecko: support plug-ins based on Gecko native: support plug-ins for Gecko, Opera, and WebKit-GTK linux: support Linux plug-ins all (default, implicit): support all plug-in types (individual entries): support only the browsers listed These variables can be adjusted: WEBPLUGIN_FILES: No default, must be set manually. The plug-in files to install. WEBPLUGIN_DIR: The directory to install the plug-in files to, default PREFIX/lib/browser_plugins/WEBPLUGIN_NAME. Set this if the port installs plug-in files outside of the default directory to prevent broken symbolic links. WEBPLUGIN_NAME: The final directory to install the plug-in files into, default PKGBASE. xfce (none), gtk3 - Provide support for Xfce - related ports. See for - details. + + Provide support for Xfce + related ports. See for + details. + + The gtk3 argument specifies that + the port requires GTK3 + features provided by x11/libxfce4menu. + zip (none), infozip Indicates that the distribution files use the ZIP compression algorithm. For files using the InfoZip algorithm the infozip argument must be passed to set the appropriate dependencies. zope (none) Uses www/zope. Mostly used for building zope related ports. ZOPE_VERSION can be used by a port to indicate that a specific version of zope shall be used.