path: root/documentation/content/en/books/porters-handbook/flavors/_index.adoc

---
title: Chapter 7. Flavors
prev: books/porters-handbook/special
next: books/porters-handbook/plist
description: Flavors are a way to have multiple variations of a port
tags: ["Ports", "Flavors", "introduction", "how-to", "guide"]
showBookMenu: true
weight: 7
path: "/books/porters-handbook/"
---

[[flavors]]
= Flavors
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 7
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/porters-handbook/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

[[flavors-intro]]
== 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.

[[flavors-using]]
== Using FLAVORS

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

[TIP]
====
It can help simplify the logic of the [.filename]#Makefile# to also define `FLAVOR` as:

[.programlisting]
....
FLAVOR?=	${FLAVORS:[1]}
....
====

[IMPORTANT]
====
To distinguish flavors from options, which are always uppercase letters, flavor names can _only_ contain lowercase letters, numbers, and the underscore `_`.
====

[[flavors-using-ex1]]
.Basic Flavors Usage
[example]
====
If a port has a "lite" slave port, the slave port can be removed, and the port can be converted to flavors with:

[.programlisting]
....
FLAVORS=	default lite
lite_PKGNAMESUFFIX=	-lite
[...]
.if ${FLAVOR:U} != lite
[enable non lite features]
.endif
....

====

[[flavors-using-ex2]]
.Another Basic Flavors Usage
[example]
====
If a port has a `-nox11` slave port, the slave port can be removed, and the port can be converted to flavors with:

[.programlisting]
....
FLAVORS=	x11 nox11
FLAVOR?=	${FLAVORS:[1]}
nox11_PKGNAMESUFFIX=	-nox11
[...]
.if ${FLAVOR} == x11
[enable x11 features]
.endif
....

====

[[flavors-using-ex3]]
.More Complex Flavors Usage
[example]
====
Here is a slightly edited excerpt of what is present in package:devel/libpeas[], a port that uses the <<flavors-auto-python,Python flavors>>.
With the default Python 2 and 3 versions being 2.7 and 3.6, it will automatically get `FLAVORS=py27 py36`

[.programlisting]
....
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 man: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 [.filename]#${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 <<flavors-using-helpers,helper>>.
====

[[flavors-using-helpers]]
=== Flavors Helpers

To make the [.filename]#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`


[[flavors-helpers-ex1]]
.Flavor Specific `PKGNAME`
[example]
====
As all packages must have a different package name, flavors must change theirs, using `_flavor__PKGNAMEPREFIX` and `_flavor__PKGNAMESUFFIX` makes this easy:

[.programlisting]
....
FLAVORS=	normal lite
lite_PKGNAMESUFFIX=	-lite
....

====

[[flavors-auto-php]]
== `USES=php` and Flavors

When using crossref:uses[uses-php,`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.

[[flavors-auto-php-ex1]]
.Simple `USES=php` Extension
[example]
====
This will generate package for all the supported versions:

[.programlisting]
....
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:

[.programlisting]
....
PORTNAME=	some-ext
PORTVERSION=	0.0.1
PKGNAMEPREFIX=	${PHP_PKGNAMEPREFIX}

USES=		php:ext
IGNORE_WITH_PHP=	72
....

====

[[flavors-auto-php-app]]
=== 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.

[IMPORTANT]
====
PHP applications that are flavorized _must_ append `PHP_PKGNAMESUFFIX` to their package names.
====

[[flavors-auto-php-app-ex1]]
.Flavorizing a PHP Application
[example]
====
Adding Flavors support to a PHP application is straightforward:

[.programlisting]
....
PKGNAMESUFFIX=	${PHP_PKGNAMESUFFIX}

USES=	php:flavors
....

====

[TIP]
====
When adding a dependency on a PHP flavored port, use `@${PHP_FLAVOR}`.
_Never_ use `FLAVOR` directly.
====

[[flavors-auto-python]]
== `USES=python` and Flavors

When using crossref:uses[uses-python,`python`] and `USE_PYTHON=distutils`,
the port will automatically have `FLAVORS` filled in with the Python versions it supports.

[[flavors-auto-python-ex1]]
.Simple `USES=python`
[example]
====
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:

[.programlisting]
....
USES=	python
USE_PYTHON=	distutils
....

Will get these flavors: `py27`, and `py36`.

[.programlisting]
....
USES=	python
USE_PYTHON=	distutils allflavors
....

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

[[flavors-auto-python-ex2]]
.`USES=python` with Version Requirements
[example]
====
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:

[.programlisting]
....
USES=	python:-3.5
USE_PYTHON=	distutils
....

Will get this flavor: `py27`.

[.programlisting]
....
USES=	python:-3.5
USE_PYTHON=	distutils allflavors
....

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

[.programlisting]
....
USES=	python:3.4+
USE_PYTHON=	distutils
....

Will get this flavor: `py36`.

[.programlisting]
....
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..

[[flavors-auto-python-ex3]]
.For a Port Not Using `distutils`
[example]
====
If the default Python 3 version is 3.6, the following will set `PY_FLAVOR` to `py36`:

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

USES=	python:3.5+
....

====

[[flavors-auto-lua]]
== `USES=lua` and Flavors

When using crossref:uses[uses-lua,`lua:module`] or crossref:uses[uses-lua,`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 crossref:special[using-lua,Using Lua] for further information.