Date: Thu, 30 Nov 2017 15:45:50 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r51244 - in head/en_US.ISO8859-1/books/porters-handbook: . flavors order special Message-ID: <201711301545.vAUFjoTg071854@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@doe.tld COMMENT= Python sample module + +RUN_DEPENDS= ${PYTHON_PKGNAMEPREFIX}six>0:devel/py-six@${PY_FLAVOR} USES= python USE_PYTHON= autoplist distutils
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201711301545.vAUFjoTg071854>