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 | |||||
port can have a normal version, and a lite version.</para> | |||||
wblock: This is redundant.
```<emphasis>Flavors</emphasis> provide a way to have more than one… | |||||
</sect1> | |||||
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… | |||||
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… | |||||
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> | |||||
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 contain lowercase letters, numbers, and | |||||
the underscore <literal>_</literal>.</para> | |||||
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… | |||||
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… | |||||
</important> | |||||
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… | |||||
<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> | |||||
<sect2 xml:id="flavors-using-helpers"> | |||||
<title>Flavors Helpers</title> | |||||
<para>To make <filename>Makefile</filename> easier to write, a | |||||
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> | |||||
Done Inline ActionsThis paragraph is confusing to me emaste: This paragraph is confusing to me | |||||
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… | |||||
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… | |||||
<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 | |||||
Done Inline ActionsAdd "the" To make the <filename>Makefile</filename> adamw: Add "the"
To make the <filename>Makefile</filename> | |||||
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 Python versions it supports.</para> | |||||
<example xml:id="flavors-auto-python-ex1"> | |||||
<title>Simple <literal>USES=python</literal></title> | |||||
<para>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:</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 | |||||
EXTRA_PYTHON_FLAVORS= py34</programlisting> | |||||
<para>Will get these flavors: <literal>py27</literal>, | |||||
<literal>py34</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 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:</para> | |||||
<programlisting>USES= python:-3.5 | |||||
USE_PYTHON= distutils</programlisting> | |||||
<para>Will get these flavors: <literal>py27</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 | |||||
EXTRA_PYTHON_FLAVORS= py35</programlisting> | |||||
<para>Will get these flavors: <literal>py35</literal>, and | |||||
<literal>py36</literal>.</para> | |||||
</example> | |||||
<para><varname>PY_FLAVOR</varname> 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.</para> | |||||
<example xml:id="flavors-auto-python-ex3"> | |||||
<title>For a Port Not Using | |||||
<literal>distutils</literal></title> | |||||
<para>If the default Python 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.