Index: en_US.ISO8859-1/books/porters-handbook/Makefile =================================================================== --- en_US.ISO8859-1/books/porters-handbook/Makefile +++ en_US.ISO8859-1/books/porters-handbook/Makefile @@ -25,6 +25,7 @@ SRCS+= quick-porting/chapter.xml SRCS+= slow-porting/chapter.xml SRCS+= makefiles/chapter.xml +SRCS+= flavors/chapter.xml SRCS+= special/chapter.xml SRCS+= plist/chapter.xml SRCS+= pkg-files/chapter.xml Index: en_US.ISO8859-1/books/porters-handbook/book.xml =================================================================== --- en_US.ISO8859-1/books/porters-handbook/book.xml +++ en_US.ISO8859-1/books/porters-handbook/book.xml @@ -70,6 +70,7 @@ &chap.slow-porting; &chap.makefiles; &chap.special; + &chap.flavors; &chap.plist; &chap.pkg-files; &chap.testing; Index: en_US.ISO8859-1/books/porters-handbook/chapters.ent =================================================================== --- en_US.ISO8859-1/books/porters-handbook/chapters.ent +++ en_US.ISO8859-1/books/porters-handbook/chapters.ent @@ -16,6 +16,7 @@ + Index: en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml =================================================================== --- /dev/null +++ en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml @@ -0,0 +1,317 @@ + + + + + + Flavors + + + An Introduction to Flavors + + Flavors are a way to have multiple variants of a port. The + port is built multiple times, with variations. For example, a + port can have a normal version, and a lite version. + + + + Using FLAVORS + + To declare a port having multiple flavors, add + FLAVORS to its Makefile. + The first flavor in FLAVORS is the default + flavor. + + + Flavor names can only contain + lowercase letters, numbers, and the underscore + _. + + + + 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= normal lite +lite_PKGNAMESUFFIX= -lite +[...] +.if ${FLAVOR:U} != lite +[enable non lite features] +.endif + + + + More Complex Flavors Usage + + Here is a slightly edited exceprt 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, use the FLAVOR:U &man.make.1; construct, but as + this is testing for the default flavor, we have to test + that FLAVOR is undefined, or that + FLAVOR matches py2*, + this can be done by using the argument to + :U that will be returned if the + variable is undefined. + + + + 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. + + + + + + Flavors Helpers + + To make 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 + + + + + Flavor Specific <varname>PKGNAME</varname> + + As all packages must have a different package name, + flavors must change theirs, using + flavor_PKGNAMESUFFIX + and + flavor_PKGNAMESUFFIX + makes this easy: + + FLAVORS= normal lite +lite_PKGNAMESUFFIX= -lite + + + + + + Flavors Auto-Activation + + + <literal>USES=python</literal> and Flavors + + When using USES=python + and USE_PYTHON=distutils, the port will + automatically have FLAVORS filled in with + the Python versions it + supports. + + + Simple <literal>USES=python</literal> + + 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. + + + + <literal>USES=python</literal> 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 these flavors: py27, + py34, and py35. + + USES= python:3.4+ +USE_PYTHON= distutils + + Will get these flavors: py36. + + USES= python:3.4+ +USE_PYTHON= distutils allflavors + + Will get these flavors: py34, + py35, and py36. + + + PY_FLAVOR will be available to depend + on the correct version of Python + modules. This is most useful for ports that are not + Python modules and do not have + Python flavors but do use + python for some part of their + operations. + + + For a Port Not Using + <literal>distutils</literal> + + 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+ + + + + Index: en_US.ISO8859-1/books/porters-handbook/order/chapter.xml =================================================================== --- en_US.ISO8859-1/books/porters-handbook/order/chapter.xml +++ en_US.ISO8859-1/books/porters-handbook/order/chapter.xml @@ -373,6 +373,16 @@ + + Flavors + + This block is optional. + + Start this section with defining FLAVORS. + Continue with the possible Flavors helpers. See for more Information. + + <varname>USES</varname> and <varname>USE_<replaceable>x</replaceable></varname> Index: en_US.ISO8859-1/books/porters-handbook/special/chapter.xml =================================================================== --- en_US.ISO8859-1/books/porters-handbook/special/chapter.xml +++ en_US.ISO8859-1/books/porters-handbook/special/chapter.xml @@ -3627,7 +3627,8 @@ do-install targets and may also override do-configure if GNU_CONFIGURE is not - defined. + defined. Additionally, it implies + USE_PYTHON=flavors. @@ -3650,6 +3651,23 @@ otherwise would install conflicting files. + + USE_PYTHON=flavors + The port does not use distutils but still supports + multiple Python versions. FLAVORS + will be set to the supported Python versions. See for more + information. + + + + USE_PYTHON=optsuffix + If the current Python version is not the default + one, the port will have gain + PKGNAMESUFFIX=${PYTHON_PKGNAMESUFFIX}. + Only useful with flavors. + + PYTHON_PKGNAMEPREFIX Used as a PKGNAMEPREFIX to @@ -3681,7 +3699,15 @@ Python interpreter command line, including version number. + + + + + Python Module Dependency Helpers + + + PYNUMERIC Dependency line for numeric extension. @@ -3700,6 +3726,41 @@ Python 2.0 and higher as it is also in base distribution). + + + PY_ENUM34 + Conditionnal dependency on + devel/py-enum34 depending on the + Python version. + + + + PY_ENUM_COMPAT + Conditionnal dependency on + devel/py-enum-compat depending on the + Python version. + + + + PY_PATHLIB + Conditionnal dependency on + devel/py-pathlib depending on the + Python version. + + + + PY_IPADDRESS + Conditionnal dependency on + net/py-ipaddress depending on the + Python version. + + + + PY_FUTURES + Conditionnal dependency on + devel/py-futures depending on the + Python version. +