diff --git a/documentation/content/en/books/porters-handbook/flavors/_index.adoc b/documentation/content/en/books/porters-handbook/flavors/_index.adoc index 46bace6d07..47d78b0dd4 100644 --- a/documentation/content/en/books/porters-handbook/flavors/_index.adoc +++ b/documentation/content/en/books/porters-handbook/flavors/_index.adoc @@ -1,365 +1,364 @@ --- 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 <>. 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]] === 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` +* `__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` - +* `__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: +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.