Index: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml (revision 51144) +++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml (revision 51145) @@ -1,5541 +1,5446 @@ 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 ). No port really needs to be root. It can mostly be avoided by using USES=uidfix. If the port still runs commands like &man.chown.8;, &man.chgrp.1;, or forces owner or group with &man.install.1; then use USES=fakeroot to fake those calls. Some patching of the port's Makefiles will be needed. 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 Metaports should use USES=metaport. It sets up defaults for ports that do not fetch, build, or install anything. 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. Ports that install kernel modules must prepend STAGEDIR to their destination, by default /boot/modules. Handling Symbolic Links When creating a symlink, there are two cases, either the source and target are both within ${PREFIX}. In that case, use ${RLN}. In the other case, if one or both of the paths are outside of ${PREFIX} use ${LN} -s and only prepend ${STAGEDIR} to the target's path. Inside <filename>${PREFIX}</filename>, Create Relative Symbolic Links ${RLN} uses &man.install.1;'s relative symbolic feature which frees the porter of computing the relative path. ${RLN} ${STAGEDIR}${PREFIX}/lib/libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so Will generate: &prompt.user; ls -lF ${STAGEDIR}${PREFIX}/lib lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 libfoo.so@ -> libfoo.so.42 -rwxr-xr-x 1 nobody nobody 15 Aug 3 11:24 libfoo.so.42* When used with paths not in the same directory: ${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/bar ${STAGEDIR}${PREFIX}/bin/bar Will automatically generate the relative symbolic links: &prompt.user; ls -lF ${STAGEDIR}${PREFIX}/bin lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 bar@ -> ../libexec/foo/bar Outside <filename>${PREFIX}</filename>, Create Absolute Symbolic Links When creating a symbolic link outside of ${PREFIX}, the source must not contain ${STAGEDIR}, the target, however, must: ${LN} -sf /var/cache/${PORTNAME} ${STAGEDIR}${PREFIX}/share/${PORTNAME} Will generate: &prompt.user; ls -lF ${STAGEDIRDIR}${PREFIX}/share lrwxr-xr-x 1 nobody nobody 181 Aug 3 11:27 foo@ -> /var/cache/foo 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/mosml 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 color 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 USES=scons. To make third party SConstruct respect everything that is passed to SCons in the environment (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: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: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 poses 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 Introduction This chapter explains the GNOME framework as used by ports. The framework can be loosely divided into the base components, GNOME desktop components, and a few special macros that simplify the work of port maintainers. While developing a port or changing one, please set DEVELOPER=yes in the environment or in /etc/make.conf. This causes the ports framework to enable additional checks. Using <varname>USE_GNOME</varname> Adding this variable to the port allows the use of the macros and components defined in bsd.gnome.mk. The code in bsd.gnome.mk adds the needed build-time, run-time or library dependencies or the handling of special files. GNOME applications under &os; use the USE_GNOME infrastructure. Include all the needed components as a space-separated list. The USE_GNOME components are divided into these virtual lists: basic components, GNOME 3 components and legacy components. If the port needs only GTK3 libraries, this is the shortest way to define it: USE_GNOME= gtk30 USE_GNOME components automatically add the dependencies they need. Please see for an exhaustive list of all USE_GNOME components and which other components they imply and their dependencies. Here is an example Makefile for a GNOME port that uses many of the techniques outlined in this document. Please use it as a guide for creating new ports. # $FreeBSD$ PORTNAME= regexxer DISTVERSION= 0.10 CATEGORIES= devel textproc gnome MASTER_SITES= GNOME MAINTAINER= kwm@FreeBSD.org COMMENT= Interactive tool for performing search and replace operations USES= gettext gmake pathfix pkgconfig tar:xz GNU_CONFIGURE= yes USE_GNOME= gnomeprefix intlhack gtksourceviewmm3 CPPFLAGS+= -I${LOCALBASE}/include LDFLAGS+= -L${LOCALBASE}/lib INSTALLS_ICONS= yes GLIB_SCHEMAS= org.regexxer.gschema.xml .include <bsd.port.mk> The USE_GNOME macro without any arguments does not add any dependencies to the port. USE_GNOME cannot be set after bsd.port.pre.mk. Variables This section explains which macros are available and how they are used. Like they are used in the above example. The has a more in-depth explanation. USE_GNOME has to be set for these macros to be of use. INSTALLS_ICONS GTK+ ports which install Freedesktop-style icons to ${LOCALBASE}/share/icons should use this macro to ensure that the icons are cached and will display correctly. The cache file is named icon-theme.cache. Do not include that file in pkg-plist. This macro handles that automatically. This macro is not needed for Qt, which use a internal method. GLIB_SCHEMAS List of all the glib schema files the port installs. The macro will add the files to the port plist and handle the registration of these files on install and deinstall. The glib schema files are written in XML and end with the gschema.xml extension. They are installed in the share/glib-2.0/schemas/ directory. These schema files contain all application config values with there default settings. The actual database used by the applications is built by glib-compile-schema, which is run by the GLIB_SCHEMAS macro. GLIB_SCHEMAS=foo.gschema.xml Do not add glib schemas to the pkg-plist. If they are listed in pkg-plist, they will not be registered and the applications might not work properly. GCONF_SCHEMAS List all the gconf schema files. The macro will add the schema files to the port plist and will handle their registration on install and deinstall. GConf is the XML-based database that virtually all GNOME applications use for storing their settings. These files are installed into the etc/gconf/schemas directory. This database is defined by installed schema files that are used to generate %gconf.xml key files. For each schema file installed by the port, there be an entry in the Makefile: GCONF_SCHEMAS=my_app.schemas my_app2.schemas my_app3.schemas Gconf schemas are listed in the GCONF_SCHEMAS macro rather than pkg-plist. If they are listed in pkg-plist, they will not be registered and the applications might not work properly. INSTALLS_OMF Open Source Metadata Framework (OMF) files are commonly used by GNOME 2 applications. These files contain the application help file information, and require special processing by ScrollKeeper/rarian. To properly register OMF files when installing GNOME applications from packages, make sure that omf files are listed in pkg-plist and that the port Makefile has INSTALLS_OMF defined: INSTALLS_OMF=yes When set, bsd.gnome.mk automatically scans pkg-plist and adds appropriate @exec and @unexec directives for each .omf to track in the OMF registration database. GNOME Components For further help with a GNOME port, look at some of the existing ports for examples. The &os; GNOME page has contact information if more help is needed. The components are divided into GNOME components that are currently in use and legacy components. If the component supports argument, they are listed between parenthesis in the description. The first is the default. "Both" is shown if the component defaults to adding to both build and run dependencies. GNOME Components Component Associated program Description atk accessibility/atk Accessibility toolkit (ATK) atkmm accessibility/atkmm c++ bindings for atk cairo graphics/cairo Vector graphics library with cross-device output support cairomm graphics/cairomm c++ bindings for cairo dconf devel/dconf Configuration database system (both, build, run) evolutiondataserver3 databases/evolution-data-server Data backends for the Evolution integrated mail/PIM suite gdkpixbuf2 graphics/gdk-pixbuf2 Graphics library for GTK+ glib20 devel/glib20 GNOME core library glib20 glibmm devel/glibmm c++ bindings for glib20 gnomecontrolcenter3 sysutils/gnome-control-center GNOME 3 Control Center gnomedesktop3 x11/gnome-desktop GNOME 3 desktop UI library gsound audio/gsound GObject library for playing system sounds (both, build, run) gtk-update-icon-cache graphics/gtk-update-icon-cache Gtk-update-icon-cache utility from the Gtk+ toolkit gtk20 x11-toolkits/gtk20 Gtk+ 2 toolkit gtk30 x11-toolkits/gtk30 Gtk+ 3 toolkit gtkmm20 x11-toolkits/gtkmm20 c++ bindings 2.0 for the gtk20 toolkit gtkmm24 x11-toolkits/gtkmm24 c++ bindings 2.4 for the gtk20 toolkit gtkmm30 x11-toolkits/gtkmm30 c++ bindings 3.0 for the gtk30 toolkit gtksourceview2 x11-toolkits/gtksourceview2 Widget that adds syntax highlighting to GtkTextView gtksourceview3 x11-toolkits/gtksourceview3 Text widget that adds syntax highlighting to the GtkTextView widget gtksourceviewmm3 x11-toolkits/gtksourceviewmm3 c++ bindings for the gtksourceview3 library gvfs devel/gvfs GNOME virtual file system intltool textproc/intltool Tool for internationalization (also see intlhack) introspection devel/gobject-introspection Basic introspection bindings and tools to generate introspection bindings. Most of the time :build is enough, :both/:run is only need for applications that use introspection bindings. (both, build, run) libgda5 databases/libgda5 Provides uniform access to different kinds of data sources libgda5-ui databases/libgda5-ui UI library from the libgda5 library libgdamm5 databases/libgdamm5 c++ bindings for the libgda5 library libgsf devel/libgsf Extensible I/O abstraction for dealing with structured file formats librsvg2 graphics/librsvg2 Library for parsing and rendering SVG vector-graphic files libsigc++20 devel/libsigc++20 Callback Framework for C++ libxml++26 textproc/libxml++26 c++ bindings for the libxml2 library libxml2 textproc/libxml2 XML parser library (both, build, run) libxslt textproc/libxslt XSLT C library (both, build, run) metacity x11-wm/metacity Window manager from GNOME nautilus3 x11-fm/nautilus GNOME file manager pango x11-toolkits/pango Open-source framework for the layout and rendering of i18n text pangomm x11-toolkits/pangomm c++ bindings for the pango library py3gobject3 devel/py3-gobject3 Python 3, GObject 3.0 bindings pygobject3 devel/py-gobject3 Python 2, GObject 3.0 bindings vte3 x11-toolkits/vte3 Terminal widget with improved accessibility and I18N support
GNOME Macro Components Component Description gnomeprefix Supply configure with some default locations. intlhack Same as intltool, but patches to make sure share/locale/ is used. Please only use when intltool alone is not enough. referencehack This macro is there to help splitting of the API or reference documentation into its own port.
GNOME Legacy Components Component Associated program Description atspi accessibility/at-spi Assistive Technology Service Provider Interface esound audio/esound Enlightenment sound package gal2 x11-toolkits/gal2 Collection of widgets taken from GNOME 2 gnumeric gconf2 devel/gconf2 Configuration database system for GNOME 2 gconfmm26 devel/gconfmm26 c++ bindings for gconf2 gdkpixbuf graphics/gdk-pixbuf Graphics library for GTK+ glib12 devel/glib12 glib 1.2 core library gnomedocutils textproc/gnome-doc-utils GNOME doc utils gnomemimedata misc/gnome-mime-data MIME and Application database for GNOME 2 gnomesharp20 x11-toolkits/gnome-sharp20 GNOME 2 interfaces for the .NET runtime gnomespeech accessibility/gnome-speech GNOME 2 text-to-speech API gnomevfs2 devel/gnome-vfs GNOME 2 Virtual File System gtk12 x11-toolkits/gtk12 Gtk+ 1.2 toolkit gtkhtml3 www/gtkhtml3 Lightweight HTML rendering/printing/editing engine gtkhtml4 www/gtkhtml4 Lightweight HTML rendering/printing/editing engine gtksharp20 x11-toolkits/gtk-sharp20 GTK+ and GNOME 2 interfaces for the .NET runtime gtksourceview x11-toolkits/gtksourceview Widget that adds syntax highlighting to GtkTextView libartgpl2 graphics/libart_lgpl Library for high-performance 2D graphics libbonobo devel/libbonobo Component and compound document system for GNOME 2 libbonoboui x11-toolkits/libbonoboui GUI frontend to the libbonobo component of GNOME 2 libgda4 databases/libgda4 Provides uniform access to different kinds of data sources libglade2 devel/libglade2 GNOME 2 glade library libgnome x11/libgnome Libraries for GNOME 2, a GNU desktop environment libgnomecanvas graphics/libgnomecanvas Graphics library for GNOME 2 libgnomekbd x11/libgnomekbd GNOME 2 keyboard shared library libgnomeprint print/libgnomeprint Gnome 2 print support library libgnomeprintui x11-toolkits/libgnomeprintui Gnome 2 print support library libgnomeui x11-toolkits/libgnomeui Libraries for the GNOME 2 GUI, a GNU desktop environment libgtkhtml www/libgtkhtml Lightweight HTML rendering/printing/editing engine libgtksourceviewmm x11-toolkits/libgtksourceviewmm c++ binding of GtkSourceView libidl devel/libIDL Library for creating trees of CORBA IDL file libsigc++12 devel/libsigc++12 Callback Framework for C++ libwnck x11-toolkits/libwnck Library used for writing pagers and taskslists libwnck3 x11-toolkits/libwnck3 Library used for writing pagers and taskslists orbit2 devel/ORBit2 High-performance CORBA ORB with support for the C language pygnome2 x11-toolkits/py-gnome2 Python bindings for GNOME 2 pygobject devel/py-gobject Python 2, GObject 2.0 bindings pygtk2 x11-toolkits/py-gtk2 Set of Python bindings for GTK+ pygtksourceview x11-toolkits/py-gtksourceview Python bindings for GtkSourceView 2 vte x11-toolkits/vte Terminal widget with improved accessibility and I18N support
Deprecated Components: Do Not Use Component Description HAVE_GNOME Deprecated, do not use. Was used to check if a component was installed. This was used for ports that did not have --enable/--disable switches for their configure script. But the building of parts of a port without a implicit request is discouraged. WANT_GNOME Deprecated, do not use. Was used by ports that needed USE_GNOME for optional dependencies, which where defined after bsd.port.pre.mk. Since USE_GNOME can be used after the inclusion of bsd.port.options.mk, there is little need for this macro any more. pangox-compat pangox-compat has been deprecated and split off from the pango package.
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 USES+=kde:4 and USE_KDE 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 ${KDE_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 KDE_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 KDE_PREFIX is identical to the default PREFIX, ${LOCALBASE}. <varname>USE_KDE</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_KDE 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_KDE does not imply USE_QT4. If a port requires some Qt 4 components, specify them in USE_QT4. USES= cmake:outsource kde:4 USE_KDE= kdelibs kdeprefix automoc4 USE_QT4= moc_build qmake_build rcc_build uic_build Using LXQt Applications depending on LXQt should set USES+= lxqt and set USE_LXQT to the list of required components from the table below Available LXQt Components Name Description buildtools Helpers for additional CMake modules libfmqt Libfm Qt bindings lxqt LXQt core library qtxdg Qt implementation of freedesktop.org XDG specifications
<literal>USE_LXQT</literal> Example This is a simple example, USE_LXQT adds a dependency on LXQt libraries. Required LXQt components and other dependencies can be determined from the configure log. USES= cmake:outsource lxqt tar:xz USE_QT5= buildtools_build qmake_build core dbus widgets USE_LXQT= buildtools libfmqt 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 a particular version, specify it using the JAVA_VERSION variable. The most current version is java/openjdk8, with java/openjdk6 and java/openjdk7 also available. 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. Use WWWOWN and WWWGRP sparingly. Remember that every file the web server can write to is a security risk waiting to happen. Do not depend on Apache unless the web app explicitly needs Apache. Respect that users may wish to run a web application on a web server other than Apache. PHP PHP web applications declare their dependency on it with USES=php. See for more information. 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 DISTVERSION= 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 DISTVERSION= 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 DISTVERSION= 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 Ruby Useful Variables for Ports That Use Ruby Variable Description USE_RUBY Adds build and run dependencies on Ruby. USE_RUBY_EXTCONF The port uses extconf.rb to configure. USE_RUBY_SETUP The port uses setup.rb to configure. RUBY_SETUP Override the name of the setup script from setup.rb. Another 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 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 + 2.8 x11-toolkits/wxgtk24 + role="port">x11-toolkits/wxgtk28 - 2.6 + 3.0 x11-toolkits/wxgtk26 + role="port">x11-toolkits/wxgtk30 - - - 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 + 2.8 Ascending range - 2.4+ + 2.8+ Descending range - 2.6- + 3.0- Full range (must be ascending) - 2.4-2.6 + 2.8-3.0
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 + 2.8-3.0 - - - 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 + USE_WX= 2.8 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 +.if defined(WITH_WX) || !empty(PORT_OPTIONS:MWX) || !empty(HAVE_WX:Mwx-2.8) +USE_WX= 2.8 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. + 2.8. - USE_WX= 2.6 + USE_WX= 2.8 WX_COMPS= wx -WANT_WX= 2.6 +WANT_WX= 2.8 .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 + USE_WX= 2.8 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 Ports that need Xfce libraries or applications set USES=xfce. 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: Values of <varname>USE_XFCE</varname> garcon sysutils/garcon libexo x11/libexo libgui x11-toolkits/libxfce4gui libmenu x11/libxfce4menu libutil x11/libxfce4util panel x11-wm/xfce4-panel 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 Obsolete. Replaced by USES=bdb USE_MYSQL Obsolete. Replaced by USES=mysql USE_PGSQL Obsolete. Replaced by USES=pgsql. USE_SQLITE Obsolete. Replaced by USES=sqlite
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 nor 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. 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. Go Libraries Ports must not package or install Go libs or source code. Only lang/go* should install into GO_SRCDIR and GO_LIBDIR. Go ports must fetch the required deps at the normal fetch time and should only install the programs and things users need, not the things Go developers would need. Ports should (in order of preference): Use vendored dependencies included with the package source. Fetch the versions of deps specified by upstream (in the case of vendor.json or similar). As a last resort (deps are not included nor versions specified exactly) fetch versions of dependencies available at the time of upstream development/release.