os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add a Flavors chapter.

Browse source
This commit is contained in:
Mathieu Arnold 2017-11-30 15:45:49 +00:00
parent dafaec8fca
commit 098072f72f
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=51244
6 changed files with 416 additions and 1 deletions
en_US.ISO8859-1/books/porters-handbook
Makefilebook.xmlchapters.ent
flavors
chapter.xml
order
chapter.xml
special
chapter.xml

1
en_US.ISO8859-1/books/porters-handbook/Makefile
View file

@ -25,6 +25,7 @@ SRCS+= new-port/chapter.xml
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

1
en_US.ISO8859-1/books/porters-handbook/book.xml
View file

@ -70,6 +70,7 @@
&chap.slow-porting;
&chap.makefiles;
&chap.special;
&chap.flavors;
&chap.plist;
&chap.pkg-files;
&chap.testing;

1
en_US.ISO8859-1/books/porters-handbook/chapters.ent
View file

@ -16,6 +16,7 @@
<!ENTITY chap.slow-porting SYSTEM "slow-porting/chapter.xml">
<!ENTITY chap.makefiles SYSTEM "makefiles/chapter.xml">
<!ENTITY chap.special SYSTEM "special/chapter.xml">
<!ENTITY chap.flavors SYSTEM "flavors/chapter.xml">
<!ENTITY chap.plist SYSTEM "plist/chapter.xml">
<!ENTITY chap.pkg-files SYSTEM "pkg-files/chapter.xml">
<!ENTITY chap.testing SYSTEM "testing/chapter.xml">

319
en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml Normal file
View file

@ -0,0 +1,319 @@
<?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 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 <quote>lite</quote> version with
only basic features and minimal dependencies.</para>
</sect1>
<sect1 xml:id="flavors-using">
<title>Using FLAVORS</title>
<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
lowercase letters, numbers, and the underscore
<literal>_</literal>.</para>
</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>
<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
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>

14
en_US.ISO8859-1/books/porters-handbook/order/chapter.xml
View file

@ -373,6 +373,20 @@
</itemizedlist>
</sect1>
<sect1 xml:id="porting-order-flavors">
<title>Flavors</title>
<para>This block is optional.</para>
<para>Start this section with defining <varname>FLAVORS</varname>.
Continue with the possible Flavors helpers. See <xref
linkend="flavors-using"/> for more Information.</para>
<para>Constructs setting variables not available as helpers using
<literal>.if ${FLAVOR:U} == foo</literal> should go in their
respective sections below.</para>
</sect1>
<sect1 xml:id="porting-order-uses">
<title><varname>USES</varname> and
<varname>USE_<replaceable>x</replaceable></varname></title>

81
en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
View file

@ -3627,7 +3627,8 @@ SOCKETS_USE= PHP=sockets
<buildtarget>do-install</buildtarget> targets and may
also override <buildtarget>do-configure</buildtarget>
if <varname>GNU_CONFIGURE</varname> is not
defined.</entry>
defined. Additionally, it implies
<literal>USE_PYTHON=flavors</literal>.</entry>
</row>
<row>
@ -3650,6 +3651,23 @@ SOCKETS_USE= PHP=sockets
otherwise would install conflicting files.</entry>
</row>
<row>
<entry><literal>USE_PYTHON=flavors</literal></entry>
<entry>The port does not use distutils but still supports
multiple Python versions. <varname>FLAVORS</varname>
will be set to the supported Python versions. See <xref
linkend="flavors-auto-python"/> for more
information.</entry>
</row>
<row>
<entry><literal>USE_PYTHON=optsuffix</literal></entry>
<entry>If the current Python version is not the default
one, the port will have gain
<literal>PKGNAMESUFFIX=${PYTHON_PKGNAMESUFFIX}</literal>.
Only useful with flavors.</entry>
</row>
<row>
<entry><varname>PYTHON_PKGNAMEPREFIX</varname></entry>
<entry>Used as a <varname>PKGNAMEPREFIX</varname> to
@ -3681,7 +3699,15 @@ SOCKETS_USE= PHP=sockets
<entry>Python interpreter command line, including
version number.</entry>
</row>
</tbody>
</tgroup>
</table>
<table frame="none" xml:id="using-python-variables-helpers">
<title>Python Module Dependency Helpers</title>
<tgroup cols="2">
<tbody>
<row>
<entry><varname>PYNUMERIC</varname></entry>
<entry>Dependency line for numeric extension.</entry>
@ -3700,6 +3726,41 @@ SOCKETS_USE= PHP=sockets
Python 2.0 and higher as it is also in base
distribution).</entry>
</row>
<row>
<entry><varname>PY_ENUM34</varname></entry>
<entry>Conditionnal dependency on
<package>devel/py-enum34</package> depending on the
Python version.</entry>
</row>
<row>
<entry><varname>PY_ENUM_COMPAT</varname></entry>
<entry>Conditionnal dependency on
<package>devel/py-enum-compat</package> depending on the
Python version.</entry>
</row>
<row>
<entry><varname>PY_PATHLIB</varname></entry>
<entry>Conditionnal dependency on
<package>devel/py-pathlib</package> depending on the
Python version.</entry>
</row>
<row>
<entry><varname>PY_IPADDRESS</varname></entry>
<entry>Conditionnal dependency on
<package>net/py-ipaddress</package> depending on the
Python version.</entry>
</row>
<row>
<entry><varname>PY_FUTURES</varname></entry>
<entry>Conditionnal dependency on
<package>devel/py-futures</package> depending on the
Python version.</entry>
</row>
</tbody>
</tgroup>
</table>
@ -3707,6 +3768,22 @@ SOCKETS_USE= PHP=sockets
<para>A complete list of available variables can be found in
<filename>/usr/ports/Mk/Uses/python.mk</filename>.</para>
<important>
<para>All dependencies to <application>Python</application>
ports using <link
linkend="flavors-auto-python"><application>Python</application>
flavors</link> (either with
<literal>USE_PYTHON=distutils</literal> or
<literal>USE_PYTHON=flavors</literal>) must have the Python
flavor appended to their origin using
<literal>@${PY_FLAVOR}</literal>. See <xref
linkend="python-Makefile"/>.</para>
<para>If the port in question is also using Python flavors, it
can simply use <literal>@${FLAVOR}</literal> as its content
will be the same.</para>
</important>
<example xml:id="python-Makefile">
<title>Makefile for a Simple <application>Python</application>
Module</title>
@ -3718,6 +3795,8 @@ CATEGORIES= devel
MAINTAINER= john@doe.tld
COMMENT= Python sample module
RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR}
USES= python
USE_PYTHON= autoplist distutils