Date: Mon, 19 Oct 2020 17:41:54 +0000 (UTC) From: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r54612 - in head/en_US.ISO8859-1/books/porters-handbook: flavors special uses Message-ID: <202010191741.09JHfsJX068834@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: carlavilla Date: Mon Oct 19 17:41:54 2020 New Revision: 54612 URL: https://svnweb.freebsd.org/changeset/doc/54612 Log: Update porters handbook for Lua changes Submitted by: andrew_tao173.riddles.org.uk Approved by: mat@ Differential Revision: https://reviews.freebsd.org/D24430 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 Mon Oct 19 15:25:04 2020 (r54611) +++ head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml Mon Oct 19 17:41:54 2020 (r54612) @@ -424,4 +424,28 @@ USE_PYTHON= distutils allflavors</programlisting> USES= python:3.5+</programlisting> </example> </sect1> + + <sect1 xml:id="flavors-auto-lua"> + <title><literal>USES=lua</literal> and Flavors</title> + <para>When using <link + linkend="uses-lua"><literal>USES=lua:module</literal></link> + or <link + linkend="uses-lua"><literal>USES=lua:flavors</literal></link>, + the port will automatically have <varname>FLAVORS</varname> + filled in with the <application>Lua</application> versions it + supports. However, it is not expected that ordinary + applications (rather than <application>Lua</application> + modules) should use this feature; most applications that embed + or otherwise use <application>Lua</application> should simply + use <literal>USES=lua</literal>.</para> + + <para><varname>LUA_FLAVOR</varname> is available (and must be + used) to depend on the correct version of dependencies + regardless of whether the port used the + <literal>flavors</literal> or <literal>module</literal> + parameters.</para> + + <para>See <xref linkend="using-lua" /> for further + information.</para> + </sect1> </chapter> Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Mon Oct 19 15:25:04 2020 (r54611) +++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Mon Oct 19 17:41:54 2020 (r54612) @@ -6390,22 +6390,157 @@ PLIST_SUB+= VERSION="${VER_STR}" application has to be modified to find the expected version. But it can be solved by adding some additional flags to the compiler and linker.</para> + + <para>Applications that use <application>Lua</application> + should normally build for just one version. However, loadable + modules for Lua are built in a separate flavor for each Lua + version that they support, and dependencies on such modules + should specify the flavor using the + <literal>@${LUA_FLAVOR}</literal> suffix on the port + origin.</para> + </sect2> <sect2 xml:id="lua-version"> <title>Version Selection</title> - <para>A port using <application>Lua</application> only needs to - have this line:</para> + <para>A port using <application>Lua</application> should + have a line of this form:</para> <programlisting>USES= lua</programlisting> - <para>If a specific version of Lua is needed, instructions on - how to select it are given in the <link - linkend="uses-lua"><literal>USES=lua</literal></link> part - of <xref linkend="uses"/>.</para> + <para>If a specific version of Lua, or range of versions, is + needed, it can be specified as a parameter in the form + <literal>XY</literal> (which may be used multiple times), + <literal>XY+</literal>, <literal>-XY</literal>, or + <literal>XY-ZA</literal>. The default version of + <application>Lua</application> as set via + <varname>DEFAULT_VERSIONS</varname> will be used if it falls + in the requested range, otherwise the closest requested + version to the default will be used. For example:</para> + + <programlisting>USES= lua:52-53</programlisting> + + <para>Note that no attempt is made to adjust the version + selection based on the presence of any already-installed + <application>Lua</application> version.</para> + + <note> + <para>The <literal>XY+</literal> form of version specification + should not be used without careful consideration; the + <application>Lua</application> API changes to some extent in + every version, and configuration tools like + <application>CMake</application> or + <application>Autoconf</application> will often fail to work + on future versions of <application>Lua</application> until + updated to do so.</para> + </note> </sect2> + <sect2 xml:id="lua-version-config"> + <title>Configuration and Compiler flags</title> + + <para>Software that uses <application>Lua</application> may have + been written to auto-detect the <application>Lua</application> + version in use. In general ports should override this + assumption, and force the use of the specific + <application>Lua</application> version selected as described + above. Depending on the sortware being ported, this might + require any or all of: + </para> + + <itemizedlist> + <listitem> + <para>Using <varname>LUA_VER</varname> as part of a parameter + to the software's configuration script via + <varname>CONFIGURE_ARGS</varname> or + <varname>CONFIGURE_ENV</varname> (or equivalent for other + build systems); + </para> + </listitem> + + <listitem> + <para>Adding <literal>-I${LUA_INCDIR}</literal>, + <literal>-L${LUA_LIBDIR}</literal>, and + <literal>-llua-${LUA_VER}</literal> to <varname>CFLAGS</varname>, + <varname>LDFLAGS</varname>, <varname>LIBS</varname> respectively + as appropriate; + </para> + </listitem> + + <listitem> + <para>Patch the software's configuration or build files to select + the correct version. + </para> + </listitem> + </itemizedlist> + + </sect2> + + <sect2 xml:id="lua-version-flavors"> + <title>Version Flavors</title> + + <para>A port which installs a <application>Lua</application> + module (rather than an application that simply makes use of + <application>Lua</application>) should build a separate + flavor for each supported <application>Lua</application> + version. This is done by adding the <literal>module</literal> + parameter:</para> + + <programlisting>USES= lua:module</programlisting> + + <para>A version number or range of versions can be specified as + well; use a comma to separate parameters.</para> + + <para>Since each flavor must have a different package name, the + variable <varname>LUA_PKGNAMEPREFIX</varname> is provided which + will be set to an appropriate value; the intended usage + is:</para> + + <programlisting>PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX}</programlisting> + + <para>Module ports should normally install files only to + <varname>LUA_MODLIBDIR</varname>, + <varname>LUA_MODSHAREDIR</varname>, + <varname>LUA_DOCSDIR</varname>, and + <varname>LUA_EXAMPLESDIR</varname>, all of which are set up + to refer to version-specific subdirectories. Installing any + other files must be done with care to avoid conflicts between + versions.</para> + + <para>A port (other than a <application>Lua</application> module) + which wishes to build a separate package for each + <application>Lua</application> version should use the + <literal>flavors</literal> parameter:</para> + + <programlisting>USES= lua:flavors</programlisting> + + <para>This operates the same way as the <literal>module</literal> + parameter described above, but without the assumption that the + package should be documented as a <application>Lua</application> + module (so <varname>LUA_DOCSDIR</varname> and + <varname>LUA_EXAMPLESDIR</varname> are not defined by + default). However, the port may choose to define + <varname>LUA_DOCSUBDIR</varname> as a suitable subdirectory name + (usually the port's <varname>PORTNAME</varname> as long as this + does not conflict with the <varname>PORTNAME</varname> of any + module), in which case the framework will define both + <varname>LUA_DOCSDIR</varname> and + <varname>LUA_EXAMPLESDIR</varname>. + </para> + + <para>As with module ports, a flavored port should avoid installing + files that would conflict between versions. Typically this is done + by adding <varname>LUA_VER_STR</varname> as a suffix to program + names (e.g. using + <link linkend="uses-uniquefiles">USES=uniquefiles</link>), and + otherwise using either <varname>LUA_VER</varname> or + <varname>LUA_VER_STR</varname> as part of any other files or + subdirectories used outside of <varname>LUA_MODLIBDIR</varname> + and <varname>LUA_MODSHAREDIR</varname>. + </para> + </sect2> + <sect2 xml:id="lua-defined-variables"> <title>Defined Variables</title> @@ -6439,48 +6574,69 @@ PLIST_SUB+= VERSION="${VER_STR}" </row> <row> - <entry><varname>LUA_PREFIX</varname></entry> - <entry>The prefix where <application>Lua</application> - (and components) is installed</entry> + <entry><varname>LUA_FLAVOR</varname></entry> + <entry>The flavor name corresponding to the selected + <application>Lua</application> version, to be used + for specifying dependencies</entry> </row> <row> - <entry><varname>LUA_SUBDIR</varname></entry> - <entry>The directory under - <filename>${PREFIX}/bin</filename>, - <filename>${PREFIX}/share</filename> and - <filename>${PREFIX}/lib</filename> where - <application>Lua</application> is installed</entry> + <entry><varname>LUA_BASE</varname></entry> + <entry>The prefix that should be used to locate + <application>Lua</application> (and components) that + are already installed</entry> </row> <row> + <entry><varname>LUA_PREFIX</varname></entry> + <entry>The prefix where <application>Lua</application> + (and components) are to be installed by this port</entry> + </row> + + <row> <entry><varname>LUA_INCDIR</varname></entry> <entry>The directory where - <application>Lua</application> and - <application>tolua</application> header files are + <application>Lua</application> header files are installed</entry> </row> <row> <entry><varname>LUA_LIBDIR</varname></entry> <entry>The directory where - <application>Lua</application> and - <application>tolua</application> libraries are + <application>Lua</application> libraries are installed</entry> </row> <row> + <entry><varname>LUA_REFMODLIBDIR</varname></entry> + <entry>The directory where + <application>Lua</application> module libraries + (<filename>.so</filename>) that are already + installed are to be found</entry> + </row> + + <row> + <entry><varname>LUA_REFMODSHAREDIR</varname></entry> + <entry>The directory where + <application>Lua</application> modules + (<filename>.lua</filename>) that are already + installed are to be found</entry> + </row> + + <row> <entry><varname>LUA_MODLIBDIR</varname></entry> <entry>The directory where <application>Lua</application> module libraries - (<filename>.so</filename>) are installed</entry> + (<filename>.so</filename>) are to be installed + by this port</entry> </row> <row> <entry><varname>LUA_MODSHAREDIR</varname></entry> <entry>The directory where <application>Lua</application> modules - (<filename>.lua</filename>) are installed</entry> + (<filename>.lua</filename>) are to be installed + by this port</entry> </row> <row> @@ -6491,18 +6647,96 @@ PLIST_SUB+= VERSION="${VER_STR}" <row> <entry><varname>LUA_CMD</varname></entry> - <entry>The path to the <application>Lua</application> - interpreter</entry> + <entry>The name of the <application>Lua</application> + interpreter (e.g. <literal>lua53</literal>)</entry> </row> <row> <entry><varname>LUAC_CMD</varname></entry> - <entry>The path to the <application>Lua</application> - compiler</entry> + <entry>The name of the <application>Lua</application> + compiler (e.g. <literal>luac53</literal>)</entry> </row> </tbody> </tgroup> </table> + + <para>These additional variables are available for ports that + specified the <literal>module</literal> parameter:</para> + + <table frame="none" xml:id="using-lua-variables-modules"> + <title>Variables Defined for <application>Lua</application> + Module Ports</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><varname>LUA_DOCSDIR</varname></entry> + <entry>the directory to which the module's + documentation should be installed.</entry> + </row> + + <row> + <entry><varname>LUA_EXAMPLESDIR</varname></entry> + <entry>the directory to which the module's + example files should be installed.</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect2> + + <sect2 xml:id="lua-examples"> + <title>Examples</title> + + <example xml:id="lua-app-Makefile"> + <title>Makefile for an application using + <application>Lua</application></title> + + <para>This example shows how to reference a + <application>Lua</application> module required at run + time. Notice that the reference must specify a + flavor.</para> + + <programlisting>PORTNAME= sample +DISTVERSION= 1.2.3 +CATEGORIES= whatever + +MAINTAINER= john@doe.tld +COMMENT= Sample + +RUN_DEPENDS= ${LUA_REFMODLIBDIR}/lpeg.so:devel/lua-lpeg@${LUA_FLAVOR} + +USES= lua + +.include <bsd.port.mk></programlisting> + </example> + + <example xml:id="lua-mod-Makefile"> + <title>Makefile for a simple <application>Lua</application> + module</title> + + <programlisting>PORTNAME= sample +DISTVERSION= 1.2.3 +CATEGORIES= whatever +PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX} + +MAINTAINER= john@doe.tld +COMMENT= Sample + +USES= lua:module + +DOCSDIR= ${LUA_DOCSDIR} + +.include <bsd.port.mk></programlisting> + </example> + </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 Mon Oct 19 15:25:04 2020 (r54611) +++ head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml Mon Oct 19 17:41:54 2020 (r54612) @@ -1969,17 +1969,33 @@ GSSAPI_NONE_CONFIGURE_ON= --without-gssapi</programlis <title><literal>lua</literal></title> <para>Possible arguments: (none), - <literal><replaceable>XY</replaceable>+</literal>, <literal><replaceable>XY</replaceable></literal>, - <literal>build</literal>, <literal>run</literal></para> + <literal><replaceable>XY</replaceable>+</literal>, + <literal>-<replaceable>XY</replaceable></literal>, + <literal><replaceable>XY</replaceable>-<replaceable>ZA</replaceable></literal>, + <literal>module</literal>, <literal>flavors</literal>, + <literal>build</literal>, <literal>run</literal>, + <literal>env</literal></para> <para>Adds a dependency on <application>Lua</application>. By default this is a library dependency, unless overridden by the - <literal>build</literal> or <literal>run</literal> option. The - default version is 5.2, unless set by the - <literal><replaceable>XY</replaceable></literal> parameter (for - example, <literal>51</literal> or - <literal>52+</literal>).</para> + <literal>build</literal> and/or <literal>run</literal> option. + The <literal>env</literal> option prevents the addition of any + dependency, while still defining all the usual variables.</para> + + <para>The default version is set by the usual + <literal>DEFAULT_VERSIONS</literal> mechanism, unless a version or + range of versions is specified as an argument, for + example, <literal>51</literal> or <literal>51-53</literal>.</para> + + <para>Applications using <application>Lua</application> are + normally built for only a single <application>Lua</application> + version. However, library modules intended to be loaded by + <application>Lua</application> code should use the + <literal>module</literal> option to build with multiple + flavors.</para> + + <para>For more information see <xref linkend="using-lua" />.</para> </sect1> <sect1 xml:id="uses-lxqt">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202010191741.09JHfsJX068834>