Page MenuHomeFreeBSD
Files F161281032

D24430.diff
No OneTemporary
Actions

D24430.diff
View Options

Index: head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
+++ head/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
@@ -424,4 +424,28 @@
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>
Index: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
@@ -6390,22 +6390,157 @@
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 @@
</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 @@
<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 &lt;bsd.port.mk&gt;</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 &lt;bsd.port.mk&gt;</programlisting>
+ </example>
+
</sect2>
</sect1>
Index: head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
+++ head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
@@ -1969,17 +1969,33 @@
<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">

File Metadata

Mime Type
text/plain
Expires
Fri, Jul 3, 9:57 AM (16 h, 50 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
34619794
Default Alt Text
D24430.diff (15 KB)

Event Timeline