6.4. Building Mechanisms

6.4.1. Building Ports in Parallel

The FreeBSD 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 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.

6.4.2. make, gmake, fmake, and imake

Several differing make implementations exist. Ported software often requires a particular implementation, like GNU make, known in FreeBSD as gmake, or fmake, the legacy FreeBSD make.

If the port uses GNU make, add gmake to USES. If the legacy FreeBSD 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 FreeBSD version) are available. Most ports should only use MAKE_CMD within the application Makefiles in WRKSRC to call the make implementation expected by the ported software.

If your port is an X application that creates Makefile files from Imakefile files using imake, then set USES= imake. This will cause the configure stage to automatically do an xmkmf -a. If the -a flag is a problem for your port, set XMKMF=xmkmf. If the port uses imake but does not understand the install.man target, NO_INSTALL_MANPAGES=yes should be set.

If your port's source Makefile has something else than all as the main build target, set ALL_TARGET accordingly. Same goes for install and INSTALL_TARGET.

6.4.3. configure Script

If your port uses the configure script to generate Makefile files from Makefile.in files, set GNU_CONFIGURE=yes. If you want 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 variable.

Table 6.1. Variables for Ports That Use configure
VariableMeans
GNU_CONFIGUREThe port uses configure script to prepare build.
HAS_CONFIGURESame as GNU_CONFIGURE, except default configure target is not added to CONFIGURE_ARGS.
CONFIGURE_ARGSAdditional arguments passed to configure script.
CONFIGURE_ENVAdditional environment variables to be set for configure script run.
CONFIGURE_TARGETOverride default configure target. Default value is ${MACHINE_ARCH}-portbld-freebsd${OSREL}.

6.4.4. Using cmake

For ports that use CMake, define USES= cmake, or USES= cmake:outsource to build in a separate directory (see below).

Table 6.2. Variables for Ports That Use cmake
VariableMeans
CMAKE_ARGSPort specific CMake flags to be passed to the cmake binary.
CMAKE_BUILD_TYPEType of build (CMake predefined build profiles). Default is Release, or Debug if WITH_DEBUG is set.
CMAKE_ENVEnvironment variables to be set for the cmake binary. Default is ${CONFIGURE_ENV}.
CMAKE_SOURCE_PATHPath to the source directory. Default is ${WRKSRC}.

Table 6.3. Variables the Users can define for cmake builds
VariableMeans
CMAKE_VERBOSEEnable verbose build output. Default not set, unless BATCH or PACKAGE_BUILDING are set.
CMAKE_NOCOLORDisables colour build output. Default not set, unless BATCH or PACKAGE_BUILDING are set.

CMake supports the following 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 the PLIST_SUB and should be used if port installs *.cmake files 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 files. In order 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.

Example 6.1. USES= cmake Example

The following 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

6.4.5. Using scons

If your port uses SCons, define USE_SCONS=yes.

Table 6.4. Variables for Ports That Use scons
VariableMeans
SCONS_ARGSPort specific SCons flags passed to the SCons environment.
SCONS_BUILDENVVariables to be set in system environment.
SCONS_ENVVariables to be set in SCons environment.
SCONS_TARGETLast argument passed to SCons, similar to MAKE_TARGET.

To make third party SConstruct respect everything that is passed to SCons in SCONS_ENV (that is, most importantly, CC/CXX/CFLAGS/CXXFLAGS), patch the SConstruct so build Environment is constructed like this:

env = Environment(**ARGUMENTS)

It may be then modified with env.Append and env.Replace.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.