Changeset View
Standalone View
en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
- This file was added.
<?xml version="1.0" encoding="iso-8859-1"?> | |||||
<!-- | |||||
The FreeBSD Documentation Project | |||||
$FreeBSD$ | |||||
--> | |||||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink= | |||||
"http://www.w3.org/1999/xlink" version="5.0" xml:id="flavors"> | |||||
<title>Flavors</title> | |||||
<sect1 xml:id="flavors-intro"> | |||||
<title>An Introduction to Flavors</title> | |||||
<para>Flavors are a way to have multiple variants of a port. The | |||||
port is built multiple times, with variations. For example, a | |||||
wblock: This is redundant.
```<emphasis>Flavors</emphasis> provide a way to have more than one… | |||||
port can have a normal version, and a lite version.</para> | |||||
emasteUnsubmitted Done Inline ActionsMaybe comment briefly on what a "normal" and "lite" option means - perhaps something like "a normal version, and a lite version with fewer features and dependencies." emaste: Maybe comment briefly on what a "normal" and "lite" option means - perhaps something like "a… | |||||
wblockUnsubmitted Not Done Inline Actionsport can have a normal version with standard options, and a <quote>lite</quote> version with fewer options and features so it is smaller in size. Is this a good example? I mean, it seems like the typical use of flavors is to have more than one variant of a port installed at the same time. Like having (sigh) py27-setuptools, py34-setuptools, and py36-setuptools. wblock: ```port can have a normal version with standard options, and a <quote>lite</quote>
version with… | |||||
</sect1> | |||||
Done Inline ActionsI would put this single-sentence paragraph into the previous one. bcr: I would put this single-sentence paragraph into the previous one. | |||||
<sect1 xml:id="flavors-using"> | |||||
<title>Using FLAVORS</title> | |||||
wblockUnsubmitted Not Done Inline ActionsI would not make Flavors all uppercase here. The title is about using the feature, not the make variable. I think. If it really is about the make variable, be explicit about that: <title>Using the <varname>FLAVORS</varname> Variable</title> wblock: I would not make Flavors all uppercase here. The title is about using the feature, not the… | |||||
<para>To declare a port having multiple flavors, add | |||||
<varname>FLAVORS</varname> to its <filename>Makefile</filename>. | |||||
The first flavor in <varname>FLAVORS</varname> is the default | |||||
flavor.</para> | |||||
<important> | |||||
<para>Flavor names can <emphasis>only</emphasis> contain | |||||
adamwUnsubmitted Done Inline ActionsI'd reinforce this: To distinguish flavors from options, which are always uppercase letters, f[lavor names can <emphasis>only</emphasis> contain...] adamw: I'd reinforce this:
To distinguish flavors from options, which are always uppercase letters, f… | |||||
wblockUnsubmitted Not Done Inline ActionsGood, but flip it so the restrictions are first and then the reason. <para>Flavor names are <emphasis>only</emphasis> allowed to contain wblock: Good, but flip it so the restrictions are first and then the reason.
```<para>Flavor names are… | |||||
lowercase letters, numbers, and the underscore | |||||
<literal>_</literal>.</para> | |||||
wblockUnsubmitted Not Done Inline Actions<literal>_</literal>. This makes them visibly different from the values for options, which are upper case only.</para> wblock: ```<literal>_</literal>. This makes them visibly different from the values for options, which… | |||||
</important> | |||||
<example xml:id="flavors-using-ex1"> | |||||
<title>Basic Flavors Usage</title> | |||||
<para>If a port has a <quote>lite</quote> slave port, the slave | |||||
port can be removed, and the port can be converted to flavors | |||||
with:</para> | |||||
<programlisting>FLAVORS= normal lite | |||||
lite_PKGNAMESUFFIX= -lite | |||||
[...] | |||||
.if ${FLAVOR:U} != lite | |||||
[enable non lite features] | |||||
.endif</programlisting> | |||||
</example> | |||||
<example xml:id="flavors-using-ex2"> | |||||
<title>More Complex Flavors Usage</title> | |||||
<para>Here is a slightly edited exceprt of what is present in | |||||
<package role="port">devel/libpeas</package>, a port that | |||||
uses the <link | |||||
linkend="flavors-auto-python"><application>Python</application> | |||||
flavors</link>. With the default | |||||
<application>Python</application> 2 and 3 versions being 2.7 | |||||
and 3.6, it will automatically get <literal>FLAVORS=py27 | |||||
py36</literal></para> | |||||
<programlisting>USES= gnome python | |||||
USE_PYTHON= flavors <co xml:id="flavors-using-ex2-use"/> | |||||
.if ${FLAVOR:Upy27:Mpy2*} <co xml:id="flavors-using-ex2-if"/> | |||||
USE_GNOME= pygobject3 <co xml:id="flavors-using-ex2-pygobject3"/> | |||||
CONFIGURE_ARGS+= --enable-python2 --disable-python3 | |||||
BUILD_WRKSRC= ${WRKSRC}/loaders/python <co xml:id="flavors-using-ex2-build2"/> | |||||
INSTALL_WRKSRC= ${WRKSRC}/loaders/python <co xml:id="flavors-using-ex2-install2"/> | |||||
.else # py3* | |||||
USE_GNOME+= py3gobject3 <co xml:id="flavors-using-ex2-py3gobject3"/> | |||||
CONFIGURE_ARGS+= --disable-python2 --enable-python3 \ | |||||
ac_cv_path_PYTHON3_CONFIG=${LOCALBASE}/bin/python${PYTHON_VER}-config <co xml:id="flavors-using-ex2-ac_cv"/> | |||||
BUILD_WRKSRC= ${WRKSRC}/loaders/python3 <co xml:id="flavors-using-ex2-build3"/> | |||||
INSTALL_WRKSRC= ${WRKSRC}/loaders/python3 <co xml:id="flavors-using-ex2-install3"/> | |||||
.endif | |||||
py34_PLIST= ${.CURDIR}/pkg-plist-py3 <co xml:id="flavors-using-ex2-plist34"/> | |||||
py35_PLIST= ${.CURDIR}/pkg-plist-py3 <co xml:id="flavors-using-ex2-plist35"/> | |||||
py36_PLIST= ${.CURDIR}/pkg-plist-py3 <co xml:id="flavors-using-ex2-plist36"/></programlisting> | |||||
<calloutlist> | |||||
<callout arearefs="flavors-using-ex2-use"> | |||||
<para>This port does not use | |||||
<literal>USE_PYTHON=distutils</literal> but needs | |||||
<application>Python</application> flavors anyway.</para> | |||||
</callout> | |||||
<callout arearefs="flavors-using-ex2-if"> | |||||
<para>To guard against <varname>FLAVOR</varname> being | |||||
empty, use the FLAVOR:U &man.make.1; construct, but as | |||||
this is testing for the default flavor, we have to test | |||||
that <varname>FLAVOR</varname> is undefined, or that | |||||
<varname>FLAVOR</varname> matches <literal>py2*</literal>, | |||||
this can be done by using the argument to | |||||
<literal>:U</literal> that will be returned if the | |||||
variable is undefined.</para> | |||||
</callout> | |||||
emasteUnsubmitted Done Inline ActionsThis paragraph is confusing to me emaste: This paragraph is confusing to me | |||||
adamwUnsubmitted Done Inline ActionsI agree. I'd simplify it like this: To guard against <varname>FLAVOR</varname> being empty, which would cause a &man.make.1 error, use <literal>${FLAVOR:U}</literal> in string comparisons instead of <literal>${FLAVOR}</literal>. adamw: I agree. I'd simplify it like this:
To guard against <varname>FLAVOR</varname> being empty… | |||||
wblockUnsubmitted Not Done Inline ActionsFLAVOR must have a defined value before flavor-specific processing can start. Using the <literal>:U</literal> &man.make.1; feature simplifies this. If the variable is empty, the value it is compared to is assigned to it. (I'm not certain if this is a correct explanation.) wblock: FLAVOR must have a defined value before flavor-specific processing can start. Using the… | |||||
<callout arearefs="flavors-using-ex2-pygobject3 | |||||
flavors-using-ex2-py3gobject3"> | |||||
<para>The <application>Gnome</application> | |||||
<application>Python</application> gobject3 bindings have | |||||
two different names, one for | |||||
<application>Python</application> 2, pygobject3 and one | |||||
for <application>Python</application> 3, | |||||
py3gobject3.</para> | |||||
</callout> | |||||
<callout arearefs="flavors-using-ex2-build2 | |||||
flavors-using-ex2-install2 flavors-using-ex2-build3 | |||||
flavors-using-ex2-install3"> | |||||
<para>The <command>configure</command> script has to run in | |||||
<filename>${WRKSRC}</filename>, 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.</para> | |||||
</callout> | |||||
<callout arearefs="flavors-using-ex2-ac_cv"> | |||||
<para>Hint about the correct | |||||
<application>Python</application> 3 config script | |||||
path name.</para> | |||||
</callout> | |||||
<callout arearefs="flavors-using-ex2-plist34 | |||||
flavors-using-ex2-plist35 flavors-using-ex2-plist36"> | |||||
<para>The packing list is different when the built with | |||||
<application>Python</application> 3. As there are three | |||||
possible <application>Python</application> 3 versions, set | |||||
<varname>PLIST</varname> for all three using the <link | |||||
linkend="flavors-using-helpers">helper</link>.</para> | |||||
</callout> | |||||
</calloutlist> | |||||
</example> | |||||
<sect2 xml:id="flavors-using-helpers"> | |||||
<title>Flavors Helpers</title> | |||||
<para>To make <filename>Makefile</filename> easier to write, a | |||||
adamwUnsubmitted Done Inline ActionsAdd "the" To make the <filename>Makefile</filename> adamw: Add "the"
To make the <filename>Makefile</filename> | |||||
few flavors helpers exist.</para> | |||||
<para>This list of helpers will set their variable:</para> | |||||
<itemizedlist> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_PKGNAMEPREFIX</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_PKGNAMESUFFIX</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_PLIST</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_DESCR</varname></para> | |||||
</listitem> | |||||
</itemizedlist> | |||||
<para><varname>This list of helpers will append to their variable:</varname></para> | |||||
<itemizedlist> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_CONFLICTS</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_CONFLICTS_BUILD</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_CONFLICTS_INSTALL</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_PKG_DEPENDS</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_EXTRACT_DEPENDS</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_PATCH_DEPENDS</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_FETCH_DEPENDS</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_BUILD_DEPENDS</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_LIB_DEPENDS</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_RUN_DEPENDS</varname></para> | |||||
</listitem> | |||||
<listitem> | |||||
<para><varname><replaceable>flavor</replaceable>_TEST_DEPENDS</varname></para> | |||||
</listitem> | |||||
</itemizedlist> | |||||
<example xml:id="flavors-helpers-ex1"> | |||||
<title>Flavor Specific <varname>PKGNAME</varname></title> | |||||
<para>As all packages must have a different package name, | |||||
flavors must change theirs, using | |||||
<varname><replaceable>flavor</replaceable>_PKGNAMESUFFIX</varname> | |||||
and | |||||
<varname><replaceable>flavor</replaceable>_PKGNAMESUFFIX</varname> | |||||
makes this easy:</para> | |||||
<programlisting>FLAVORS= normal lite | |||||
lite_PKGNAMESUFFIX= -lite</programlisting> | |||||
</example> | |||||
</sect2> | |||||
</sect1> | |||||
<sect1 xml:id="flavors-auto"> | |||||
<title>Flavors Auto-Activation</title> | |||||
<sect2 xml:id="flavors-auto-python"> | |||||
<title><literal>USES=python</literal> and Flavors</title> | |||||
<para>When using <link | |||||
linkend="uses-python"><literal>USES=python</literal></link> | |||||
and <literal>USE_PYTHON=distutils</literal>, the port will | |||||
automatically have <varname>FLAVORS</varname> filled in with | |||||
the <application>Python</application> versions it | |||||
supports.</para> | |||||
<example xml:id="flavors-auto-python-ex1"> | |||||
<title>Simple <literal>USES=python</literal></title> | |||||
<para>Supposing the current <application>Python</application> | |||||
supported versions are 2.7, 3.4, 3.5, and 3.6, and the | |||||
default <application>Python</application> 2 and 3 versions | |||||
are 2.7 and 3.6, a port with:</para> | |||||
<programlisting>USES= python | |||||
USE_PYTHON= distutils</programlisting> | |||||
<para>Will get these flavors: <literal>py27</literal>, and | |||||
<literal>py36</literal>.</para> | |||||
<programlisting>USES= python | |||||
USE_PYTHON= distutils allflavors</programlisting> | |||||
<para>Will get these flavors: <literal>py27</literal>, | |||||
<literal>py34</literal>, <literal>py35</literal> and | |||||
<literal>py36</literal>.</para> | |||||
</example> | |||||
<example xml:id="flavors-auto-python-ex2"> | |||||
<title><literal>USES=python</literal> with Version | |||||
Requirements</title> | |||||
<para>Supposing the current <application>Python</application> | |||||
supported versions are 2.7, 3.4, 3.5, and 3.6, and the | |||||
default <application>Python</application> 2 and 3 versions | |||||
are 2.7 and 3.6, a port with:</para> | |||||
<programlisting>USES= python:-3.5 | |||||
USE_PYTHON= distutils</programlisting> | |||||
<para>Will get these flavors: <literal>py27</literal>, | |||||
<literal>py34</literal>, and <literal>py35</literal>.</para> | |||||
<programlisting>USES= python:3.4+ | |||||
USE_PYTHON= distutils</programlisting> | |||||
<para>Will get these flavors: <literal>py36</literal>.</para> | |||||
<programlisting>USES= python:3.4+ | |||||
USE_PYTHON= distutils allflavors</programlisting> | |||||
<para>Will get these flavors: <literal>py34</literal>, | |||||
<literal>py35</literal>, and <literal>py36</literal>.</para> | |||||
</example> | |||||
<para><varname>PY_FLAVOR</varname> will be available to depend | |||||
on the correct version of <application>Python</application> | |||||
modules. This is most useful for ports that are not | |||||
<application>Python</application> modules and do not have | |||||
<application>Python</application> flavors but do use | |||||
<command>python</command> for some part of their | |||||
operations.</para> | |||||
<example xml:id="flavors-auto-python-ex3"> | |||||
<title>For a Port Not Using | |||||
<literal>distutils</literal></title> | |||||
<para>If the default <application>Python</application> 3 | |||||
version is 3.6, the following will set | |||||
<varname>PY_FLAVOR</varname> to | |||||
<literal>py36</literal>:</para> | |||||
<programlisting>RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}mutagen>0:audio/py-mutagen@${PY_FLAVOR} | |||||
USES= python:3.5+</programlisting> | |||||
</example> | |||||
</sect2> | |||||
</sect1> | |||||
</chapter> |
This is redundant.