svn commit: r51244 - in head/en_US.ISO8859-1/books/porters-handbook: . flavors order special
Mathieu Arnold
mat at FreeBSD.org
Thu Nov 30 15:45:52 UTC 2017
Author: mat
Date: Thu Nov 30 15:45:49 2017
New Revision: 51244
URL: https://svnweb.freebsd.org/changeset/doc/51244
Log:
Add a Flavors chapter.
Added:
head/en_US.ISO8859-1/books/porters-handbook/flavors/
head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml (contents, props changed)
Modified:
head/en_US.ISO8859-1/books/porters-handbook/Makefile
head/en_US.ISO8859-1/books/porters-handbook/book.xml
head/en_US.ISO8859-1/books/porters-handbook/chapters.ent
head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml
head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/Makefile
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/Makefile Thu Nov 30 14:49:53 2017 (r51243)
+++ head/en_US.ISO8859-1/books/porters-handbook/Makefile Thu Nov 30 15:45:49 2017 (r51244)
@@ -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
Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/book.xml Thu Nov 30 14:49:53 2017 (r51243)
+++ head/en_US.ISO8859-1/books/porters-handbook/book.xml Thu Nov 30 15:45:49 2017 (r51244)
@@ -70,6 +70,7 @@
&chap.slow-porting;
&chap.makefiles;
&chap.special;
+ &chap.flavors;
&chap.plist;
&chap.pkg-files;
&chap.testing;
Modified: head/en_US.ISO8859-1/books/porters-handbook/chapters.ent
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/chapters.ent Thu Nov 30 14:49:53 2017 (r51243)
+++ head/en_US.ISO8859-1/books/porters-handbook/chapters.ent Thu Nov 30 15:45:49 2017 (r51244)
@@ -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">
Added: head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml Thu Nov 30 15:45:49 2017 (r51244)
@@ -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>
Modified: head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml Thu Nov 30 14:49:53 2017 (r51243)
+++ head/en_US.ISO8859-1/books/porters-handbook/order/chapter.xml Thu Nov 30 15:45:49 2017 (r51244)
@@ -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>
Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Thu Nov 30 14:49:53 2017 (r51243)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Thu Nov 30 15:45:49 2017 (r51244)
@@ -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>
@@ -3651,6 +3652,23 @@ SOCKETS_USE= PHP=sockets
</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
distinguish packages for different Python versions.
@@ -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>
@@ -3717,6 +3794,8 @@ CATEGORIES= devel
MAINTAINER= john at doe.tld
COMMENT= Python sample module
+
+RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR}
USES= python
USE_PYTHON= autoplist distutils
More information about the svn-doc-all
mailing list