Update porters handbook for Lua changes

Submitted by:	 andrew_tao173.riddles.org.uk
Approved by:	mat@
Differential Revision:	https://reviews.freebsd.org/D24430

3 files changed, 306 insertions, 32 deletions

diff --git a/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
index dc720ce586..6c132b1199 100644
--- a/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
@@ -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>
diff --git a/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
index a9f2b88a88..5f9026c321 100644
--- a/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
@@ -6390,20 +6390,155 @@ 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">
@@ -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 &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>
 
diff --git a/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
index 43bda5fb53..f3cda9dc95 100644
--- a/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
@@ -1969,17 +1969,33 @@ GSSAPI_NONE_CONFIGURE_ON=	--without-gssapi</programlisting>
     <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">