Date: Tue, 13 Mar 2018 11:22:49 +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: r51481 - in head/en_US.ISO8859-1/books/porters-handbook: flavors special uses Message-ID: <201803131122.w2DBMn1T053725@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: mat Date: Tue Mar 13 11:22:48 2018 New Revision: 51481 URL: https://svnweb.freebsd.org/changeset/doc/51481 Log: Document PHP flavors, and related PEAR and Horde changes. Sponsored by: Absolight Differential Revision: https://reviews.freebsd.org/D14597 Modified: head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml Tue Mar 13 01:04:26 2018 (r51480) +++ head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml Tue Mar 13 11:22:48 2018 (r51481) @@ -262,6 +262,73 @@ lite_PKGNAMESUFFIX= -lite</programlisting> <sect1 xml:id="flavors-auto"> <title>Flavors Auto-Activation</title> + <sect2 xml:id="flavors-auto-php"> + <title><literal>USES=php</literal> and Flavors</title> + + <para>When using <link linkend="uses-php">USES=php</link> with + one of these arguments, <literal>phpize</literal>, + <literal>ext</literal>, <literal>zend</literal>, or + <literal>pecl</literal>, the port will automatically have + <varname>FLAVORS</varname> filled in with the + <application>PHP</application> versions it supports.</para> + + <note> + <para>All the examples assume the currently supported PHP + versions are 5.6, 7.0, 7.1, and 7.2.</para> + </note> + + <example xml:id="flavors-auto-php-ex1"> + <title>Simple <literal>USES=php</literal> Extension</title> + + <para>This will generate package for all the supported + versions:</para> + + <programlisting>PORTNAME= some-ext +PORTVERSION= 0.0.1 +PKGNAMEPREFIX= ${PHP_PKGNAMEPREFIX} + +USES= php:ext</programlisting> + + <para>This will generate package for all the supported + versions but 7.2:</para> + + <programlisting>PORTNAME= some-ext +PORTVERSION= 0.0.1 +PKGNAMEPREFIX= ${PHP_PKGNAMEPREFIX} + +USES= php:ext +IGNORE_WITH_PHP= 72</programlisting> + </example> + + <sect3 xml:id="flavors-auto-php-app"> + <title>PHP Flavors with PHP Applications</title> + + <para>PHP applications can also be flavorized.</para> + + <para>This allows generating packages for all PHP versions, so + that users can use them with whatever version they need on + their servers.</para> + + <important> + <para>PHP applications that are flavorized + <emphasis>must</emphasis> append + <varname>PHP_PKGNAMESUFFIX</varname> to their package + names.</para> + </important> + + <example xml:id="flavors-auto-php-app-ex1"> + <title>Flavorizing a PHP Application</title> + + <para>Adding Flavors support to a PHP application is + straightforward:</para> + + <programlisting>PKGNAMESUFFIX= ${PHP_PKGNAMESUFFIX} + +USES= php:flavors</programlisting> + </example> + </sect3> + </sect2> + <sect2 xml:id="flavors-auto-python"> <title><literal>USES=python</literal> and Flavors</title> @@ -306,7 +373,7 @@ USE_PYTHON= distutils allflavors</programlisting> <programlisting>USES= python:-3.5 USE_PYTHON= distutils</programlisting> - <para>Will get this flavor: <literal>py27</literal>.</para> + <para>Will get this flavor: <literal>py27</literal>.</para> <programlisting>USES= python:-3.5 USE_PYTHON= distutils allflavors</programlisting> Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Tue Mar 13 01:04:26 2018 (r51480) +++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Tue Mar 13 11:22:48 2018 (r51481) @@ -3631,6 +3631,28 @@ USES= pear .include <bsd.port.mk></programlisting> </example> + <tip> + <para><application>PEAR</application> modules will + automatically be flavorized using <link + linkend="flavors-auto-php"><application>PHP</application> + flavors</link>.</para> + </tip> + + <note> + <para>If a non default <varname>PEAR_CHANNEL</varname> is + used, the build and run-time dependencies will automatically + be added.</para> + </note> + + <important> + <para>PEAR modules do not need to defined + <varname>PKGNAMESUFFIX</varname> it is automatically filled + in using <varname>PEAR_PKGNAMEPREFIX</varname>. If a port + needs to add to <varname>PKGNAMEPREFIX</varname>, it must + also use <varname>PEAR_PKGNAMEPREFIX</varname> to + differentiate between different flavors.</para> + </important> + <sect3 xml:id="php-horde"> <title><application>Horde</application> Modules</title> @@ -3677,6 +3699,14 @@ SOCKETS_USE= PHP=sockets .include <bsd.port.mk></programlisting> </example> + + <tip> + <para>As <application>Horde</application> modules are also + <application>PEAR</application> modules they will also + automatically be flavorized using <link + linkend="flavors-auto-php"><application>PHP</application> + flavors</link>.</para> + </tip> </sect3> </sect2> </sect1> Modified: head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml Tue Mar 13 01:04:26 2018 (r51480) +++ head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml Tue Mar 13 11:22:48 2018 (r51481) @@ -2014,13 +2014,15 @@ USE_MATE= menus:build intlhack</programlisting> <sect1 xml:id="uses-pear"> <title><literal>pear</literal></title> - <para>Possible arguments: (none)</para> + <para>Possible arguments: <literal>env</literal></para> <para>Adds a dependency on <package role="port">devel/pear</package>. It will setup default behavior for software using the <application>PHP</application> - Extension and Application Repository. See <xref - linkend="php-pear"/> for more information.</para> + Extension and Application Repository. Using the + <literal>env</literal> arguments only sets up the + <application>PEAR</application> environment variables. See + <xref linkend="php-pear"/> for more information.</para> </sect1> <sect1 xml:id="uses-perl5"> @@ -2082,7 +2084,8 @@ USE_MATE= menus:build intlhack</programlisting> <literal>build</literal>, <literal>cli</literal>, <literal>cgi</literal>, <literal>mod</literal>, <literal>web</literal>, <literal>embed</literal>, - <literal>pecl</literal></para> + <literal>pecl</literal>, <literal>flavors</literal>, + <literal>noflavors</literal></para> <para>Provide support for <application>PHP</application>. Add a runtime dependency on the default PHP version, <package @@ -2093,7 +2096,7 @@ USE_MATE= menus:build intlhack</programlisting> <term><literal>phpize</literal></term> <listitem> <para>Use to build a <application>PHP</application> - extension.</para> + extension. Enables flavors.</para> </listitem> </varlistentry> @@ -2101,7 +2104,8 @@ USE_MATE= menus:build intlhack</programlisting> <term><literal>ext</literal></term> <listitem> <para>Use to build, install and register a - <application>PHP</application> extension.</para> + <application>PHP</application> extension. Enables + flavors.</para> </listitem> </varlistentry> @@ -2109,7 +2113,7 @@ USE_MATE= menus:build intlhack</programlisting> <term><literal>zend</literal></term> <listitem> <para>Use to build, install and register a Zend - extension.</para> + extension. Enables flavors.</para> </listitem> </varlistentry> @@ -2167,9 +2171,30 @@ USE_MATE= menus:build intlhack</programlisting> <listitem> <para>Provide defaults for fetching <application>PHP</application> extensions from the PECL - repository.</para> + repository. Enables flavors.</para> </listitem> </varlistentry> + + <varlistentry> + <term><literal>flavors</literal></term> + <listitem> + <para>Enable automatic <link + linkend="flavors-auto-php"><application>PHP</application> + flavors</link> generation. Flavors will be generated + for all PHP versions, except the ones present in + <link linkend="uses-php-ignore"><varname>IGNORE_WITH_PHP</varname></link>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>noflavors</literal></term> + <listitem> + <para>Disable automatic <application>PHP</application> + flavors generation. <emphasis>Must only</emphasis> be + used with extensions provided by + <application>PHP</application> itself.</para> + </listitem> + </varlistentry> </variablelist> <para>Variables are used to specify which @@ -2188,25 +2213,14 @@ USE_MATE= menus:build intlhack</programlisting> </listitem> </varlistentry> - <varlistentry> - <term><varname>DEFAULT_PHP_VER</varname></term> - <listitem> - <para>Selects which major version of - <application>PHP</application> will be installed as a - dependency when no <application>PHP</application> is - installed yet. Default is <literal>56</literal>. - Possible values: <literal>55</literal>, - <literal>56</literal>, and <literal>70</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> + <varlistentry xml:id="uses-php-ignore"> <term><varname>IGNORE_WITH_PHP</varname></term> <listitem> <para>The port does not work with - <application>PHP</application> of the given version. - Possible values: <literal>55</literal>, - <literal>56</literal>, and <literal>7</literal>.</para> + <application>PHP</application> of the given version. For + possible values look at the content of + <varname>_ALL_PHP_VERSIONS</varname> in + <filename>Mk/Uses/php.mk</filename>.</para> </listitem> </varlistentry> </variablelist> @@ -2261,6 +2275,51 @@ PHP_MOD_PRIO= 40</programlisting> </listitem> </varlistentry> </variablelist> + + <para>These variables are available to use in + <varname>PKGNAMEPREFIX</varname> or + <varname>PKGNAMESUFFIX</varname>:</para> + + <variablelist> + <varlistentry> + <term><varname>PHP_PKGNAMEPREFIX</varname></term> + <listitem> + <para>Contains + <literal>php<replaceable>XY</replaceable>-</literal> where + <replaceable>XY</replaceable> is the current flavor's PHP + version. Use with PHP extensions and modules.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>PHP_PKGNAMESUFFIX</varname></term> + <listitem> + <para>Contains + <literal>-php<replaceable>XY</replaceable></literal> where + <replaceable>XY</replaceable> is the current flavor's PHP + version. Use with PHP applications.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>PECL_PKGNAMEPREFIX</varname></term> + <listitem> + <para>Contains + <literal>php<replaceable>XY</replaceable>-pecl-</literal> + where <replaceable>XY</replaceable> is the current + flavor's PHP version. Use with + <application>PECL</application> modules.</para> + </listitem> + </varlistentry> + </variablelist> + + <important> + <para>With flavors, all PHP extensions, PECL extensions, PEAR + modules <emphasis>must have</emphasis> a different package + name, so they must all use one of these three variables in + their <varname>PKGNAMEPREFIX</varname> or + <varname>PKGNAMESUFFIX</varname>.</para> + </important> </sect1> <sect1 xml:id="uses-pkgconfig">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201803131122.w2DBMn1T053725>