6.3. Building Mechanisms
Prev | Chapter 6. Special Considerations | Next

## 6.3. Building Mechanisms

### 6.3.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. Unfortunately, not all ports handle parallel building well. Therefore it is required to explicitly enable this feature by adding `MAKE_JOBS_SAFE=yes` somewhere below the dependency declaration section of the `Makefile`.

Another option for controlling this feature from the maintainer's point of view is the `MAKE_JOBS_UNSAFE=yes` variable. It is used when a port is known to be broken with `-jX` and a user forces the use of multi processor compilations for all ports in `/etc/make.conf` with the `FORCE_MAKE_JOBS=yes` variable.

### 6.3.2. `make`, `gmake`, and `imake`

If your port uses GNU make, set `USE_GMAKE=yes`.

Table 6.1. Variables for Ports Related to gmake

Variable | Means
--- | ---
`USE_GMAKE` | The port requires `gmake` to build.
`GMAKE` | The full path for `gmake` if it is not in the `PATH`.

If your port is an X application that creates `Makefile` files from `Imakefile` files using imake, then set `USE_IMAKE=yes`. 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.3.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.2. Variables for Ports That Use `configure`

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}`.

### 6.3.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.3. Variables for Ports That Use `cmake`

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 `cmake` binary. Default is `${CONFIGURE_ENV}`.
`CMAKE_SOURCE_PATH` | Path to the source directory. Default is `${WRKSRC}`.

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.3.5. Using `scons`

If your port uses SCons, define `USE_SCONS=yes`.

Table 6.4. Variables for Ports That Use `scons`

Variable | Means
--- | ---
`SCONS_ARGS` | Port specific SCons flags passed to the SCons environment.
`SCONS_BUILDENV` | Variables to be set in system environment.
`SCONS_ENV` | Variables to be set in SCons environment.
`SCONS_TARGET` | Last argument passed to SCons, similar to `MAKE_TARGET`.

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

env = Environment(**ARGUMENTS)

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

Prev | Up | Next
6.2. Ports with Distribution Restrictions | Home | 6.4. Using GNU Autotools

This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.