Chapter 7. Flavors

7.1. An Introduction to Flavors

Flavors are a way to have multiple variations of a port. The port is built multiple times, with variations.

For example, a port can have a normal version with many features and quite a few dependencies, and a light "lite" version with only basic features and minimal dependencies.

Another example could be, a port can have a GTK flavor and a QT flavor, depending on which toolkit it uses.

7.2. Using FLAVORS

To declare a port having multiple flavors, add FLAVORS to its Makefile. The first flavor in FLAVORS is the default flavor.

It can help simplify the logic of the Makefile to also define FLAVOR as:

FLAVOR?=	${FLAVORS:[1]}

To distinguish flavors from options, which are always uppercase letters, flavor names can only contain lowercase letters, numbers, and the underscore _.

Example 1. Basic Flavors Usage

If a port has a "lite" slave port, the slave port can be removed, and the port can be converted to flavors with:

FLAVORS=	default lite
lite_PKGNAMESUFFIX=	-lite
[...]
.if ${FLAVOR:U} != lite
[enable non lite features]
.endif
Example 2. Another Basic Flavors Usage

If a port has a -nox11 slave port, the slave port can be removed, and the port can be converted to flavors with:

FLAVORS=	x11 nox11
FLAVOR?=	${FLAVORS:[1]}
nox11_PKGNAMESUFFIX=	-nox11
[...]
.if ${FLAVOR} == x11
[enable x11 features]
.endif
Example 3. More Complex Flavors Usage

Here is a slightly edited excerpt of what is present in devel/libpeas, a port that uses the Python flavors. With the default Python 2 and 3 versions being 2.7 and 3.6, it will automatically get FLAVORS=py27 py36

USES=		gnome python
USE_PYTHON=	flavors

.if ${FLAVOR:Upy27:Mpy2*}
USE_GNOME=	pygobject3

CONFIGURE_ARGS+=	--enable-python2 --disable-python3

BUILD_WRKSRC=	${WRKSRC}/loaders/python
INSTALL_WRKSRC=	${WRKSRC}/loaders/python
.else # py3*
USE_GNOME+=	py3gobject3

CONFIGURE_ARGS+=	--disable-python2 --enable-python3 \
			ac_cv_path_PYTHON3_CONFIG=${LOCALBASE}/bin/python${PYTHON_VER}-config

BUILD_WRKSRC=	${WRKSRC}/loaders/python3
INSTALL_WRKSRC=	${WRKSRC}/loaders/python3
.endif

py34_PLIST=	${.CURDIR}/pkg-plist-py3
py35_PLIST=	${.CURDIR}/pkg-plist-py3
py36_PLIST=	${.CURDIR}/pkg-plist-py3

This port does not use USE_PYTHON=distutils but needs Python flavors anyway. To guard against FLAVOR being empty, which would cause a make(1) error, use ${FLAVOR:U} in string comparisons instead of ${FLAVOR}. The Gnome Python gobject3 bindings have two different names, one for Python 2, pygobject3 and one for Python 3, py3gobject3. The configure script has to run in ${WRKSRC}, but we are only interested in building and installing the Python 2 or Python 3 parts of the software, so set the build and install base directories appropriately. Hint about the correct Python 3 config script path name. The packing list is different when the built with Python 3. As there are three possible Python 3 versions, set PLIST for all three using the helper.

7.2.1. Flavors Helpers

To make the Makefile easier to write, a few flavors helpers exist.

This list of helpers will set their variable:

  • _flavor__PKGNAMEPREFIX

  • _flavor__PKGNAMESUFFIX

  • _flavor__PLIST

  • _flavor__DESCR

This list of helpers will append to their variable:

  • _flavor__CONFLICTS

  • _flavor__CONFLICTS_BUILD

  • _flavor__CONFLICTS_INSTALL

  • _flavor__PKG_DEPENDS

  • _flavor__EXTRACT_DEPENDS

  • _flavor__PATCH_DEPENDS

  • _flavor__FETCH_DEPENDS

  • _flavor__BUILD_DEPENDS

  • _flavor__LIB_DEPENDS

  • _flavor__RUN_DEPENDS

  • _flavor__TEST_DEPENDS

Example 4. Flavor Specific PKGNAME

As all packages must have a different package name, flavors must change theirs, using _flavorPKGNAMEPREFIX and _flavorPKGNAMESUFFIX makes this easy:

FLAVORS=	normal lite
lite_PKGNAMESUFFIX=	-lite

7.3. USES=php and Flavors

When using php with one of these arguments, phpize, ext, zend, or pecl, the port will automatically have FLAVORS filled in with the PHP versions it supports.

Example 5. Simple USES=php Extension

This will generate package for all the supported versions:

PORTNAME=	some-ext
PORTVERSION=	0.0.1
PKGNAMEPREFIX=	${PHP_PKGNAMEPREFIX}

USES=		php:ext

This will generate package for all the supported versions but 7.2:

PORTNAME=	some-ext
PORTVERSION=	0.0.1
PKGNAMEPREFIX=	${PHP_PKGNAMEPREFIX}

USES=		php:ext
IGNORE_WITH_PHP=	72

7.3.1. PHP Flavors with PHP Applications

PHP applications can also be flavorized.

This allows generating packages for all PHP versions, so that users can use them with whatever version they need on their servers.

PHP applications that are flavorized must append PHP_PKGNAMESUFFIX to their package names.

Example 6. Flavorizing a PHP Application

Adding Flavors support to a PHP application is straightforward:

PKGNAMESUFFIX=	${PHP_PKGNAMESUFFIX}

USES=	php:flavors

When adding a dependency on a PHP flavored port, use @${PHP_FLAVOR}. Never use FLAVOR directly.

7.4. USES=python and Flavors

When using python and USE_PYTHON=distutils, the port will automatically have FLAVORS filled in with the Python versions it supports.

Example 7. Simple USES=python

Supposing the current Python supported versions are 2.7, 3.4, 3.5, and 3.6, and the default Python 2 and 3 versions are 2.7 and 3.6, a port with:

USES=	python
USE_PYTHON=	distutils

Will get these flavors: py27, and py36.

USES=	python
USE_PYTHON=	distutils allflavors

Will get these flavors: py27, py34, py35 and py36.

Example 8. USES=python with Version Requirements

Supposing the current Python supported versions are 2.7, 3.4, 3.5, and 3.6, and the default Python 2 and 3 versions are 2.7 and 3.6, a port with:

USES=	python:-3.5
USE_PYTHON=	distutils

Will get this flavor: py27.

USES=	python:-3.5
USE_PYTHON=	distutils allflavors

Will get these flavors: py27, py34, and py35.

USES=	python:3.4+
USE_PYTHON=	distutils

Will get this flavor: py36.

USES=	python:3.4+
USE_PYTHON=	distutils allflavors

Will get these flavors: py34, py35, and py36.

PY_FLAVOR is available to depend on the correct version of Python modules. All dependencies on flavored Python ports should use PY_FLAVOR, and not FLAVOR directly..

Example 9. For a Port Not Using distutils

If the default Python 3 version is 3.6, the following will set PY_FLAVOR to py36:

RUN_DEPENDS=	${PYTHON_PKGNAMEPREFIX}mutagen>0:audio/py-mutagen@${PY_FLAVOR}

USES=	python:3.5+

7.5. USES=lua and Flavors

When using lua:module or lua:flavors, the port will automatically have FLAVORS filled in with the Lua versions it supports. However, it is not expected that ordinary applications (rather than Lua modules) should use this feature; most applications that embed or otherwise use Lua should simply use USES=lua.

LUA_FLAVOR is available (and must be used) to depend on the correct version of dependencies regardless of whether the port used the flavors or module parameters.

See Using Lua for further information.


All FreeBSD documents are available for download at https://download.freebsd.org/ftp/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>.