Index: en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
+++ en_US.ISO8859-1/books/porters-handbook/flavors/chapter.xml
@@ -424,4 +424,28 @@
USES= python:3.5+
+
+
+ USES=lua and Flavors
+ When using USES=lua:module
+ or USES=lua:flavors,
+ the port will automatically have FLAVORS
+ filled in with the Lua versions it
+ supports. However, it is not expected that ordinary
+ applications (rather than Lua
+ modules) should use this feature; most applications that embed
+ or otherwise use Lua should simply
+ use USES=lua.
+
+ LUA_FLAVOR is available (and must be
+ used) to depend on the correct version of dependencies
+ regardless of whether the port used the
+ flavors or module
+ parameters.
+
+ See for further
+ information.
+
Index: en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
+++ en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
@@ -6279,20 +6279,107 @@
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.
+
+ Applications that use Lua
+ 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
+ @${LUA_FLAVOR} suffix on the port
+ origin.
+
Version Selection
- A port using Lua only needs to
- have this line:
+ A port using Lua normally only
+ needs to have this line:USES= lua
- If a specific version of Lua is needed, instructions on
- how to select it are given in the USES=lua part
- of .
+ If a specific version of Lua, or range of versions, is
+ needed, it can be specified as a parameter in the form
+ XY, XY+,
+ -XY, or XY-ZA. The
+ default version of Lua as set via
+ DEFAULT_VERSIONS will be used if it falls
+ in the requested range, otherwise the latest version in the
+ range will be used. For example:
+
+ USES= lua:52-53
+
+ Note that no attempt is made to adjust the version
+ selection based on the presence of any already-installed
+ Lua version.
+
+
+ The XY+ form of version specification
+ should not be used without careful consideration; the
+ Lua API changes to some extent in
+ every version, and configuration tools like
+ CMake or
+ Autoconf will often fail to work
+ on future versions of Lua until
+ updated to do so. Only use this form if you are very
+ confident that your port will build on future versions
+ without needing an update, or if you are using the
+ module or flavors
+ parameters explained below.
+
+ The reason this is a problem is that when the default
+ version of Lua is outside the
+ version range specified, e.g. when the default is 5.2 and
+ your port specifies 53+, then when version
+ 5.4 becomes available, your port will automatically switch to
+ building with 5.4.
+
+
+
+
+ Version Flavors
+
+ A port which installs a Lua
+ module (rather than an application that simply makes use of
+ Lua) should build a separate
+ flavor for each supported Lua
+ version. This is done by adding the module
+ parameter:
+
+ USES= lua:module
+
+ A version number or range of versions can be specified as
+ well; use a comma to separate parameters.
+
+ Since each flavor must have a different package name, the
+ variable LUA_PKGNAMEPREFIX is provided which
+ will be set to an appropriate value; the intended usage
+ is:
+
+ PKGNAMEPREFIX= ${LUA_PKGNAMEPREFIX}
+
+ Module ports should normally install files only to
+ LUA_MODLIBDIR,
+ LUA_MODSHAREDIR,
+ LUA_DOCSDIR, and
+ LUA_EXAMPLESDIR, 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.
+
+ A port (other than a Lua module)
+ which wishes to build a separate package for each
+ Lua version should use the
+ flavors parameter:
+
+ USES= lua:flavors
+
+ This operates the same way as the module
+ parameter described above, but without the assumption that the
+ package should be documented as a Lua
+ module (so LUA_DOCSDIR and
+ LUA_EXAMPLESDIR are not defined by
+ default).
@@ -6328,48 +6415,69 @@
- LUA_PREFIX
- The prefix where Lua
- (and components) is installed
+ LUA_FLAVOR
+ The flavor name corresponding to the selected
+ Lua version, to be used
+ for specifying dependencies
- LUA_SUBDIR
- The directory under
- ${PREFIX}/bin,
- ${PREFIX}/share and
- ${PREFIX}/lib where
- Lua is installed
+ LUA_BASE
+ The prefix that should be used to locate
+ Lua (and components) that
+ are already installed
+
+
+
+ LUA_PREFIX
+ The prefix where Lua
+ (and components) are to be installed by this portLUA_INCDIRThe directory where
- Lua and
- tolua header files are
+ Lua header files are
installedLUA_LIBDIRThe directory where
- Lua and
- tolua libraries are
+ Lua libraries are
installed
+
+ LUA_REFMODLIBDIR
+ The directory where
+ Lua module libraries
+ (.so) that are already
+ installed are to be found
+
+
+
+ LUA_REFMODSHAREDIR
+ The directory where
+ Lua modules
+ (.lua) that are already
+ installed are to be found
+
+
LUA_MODLIBDIRThe directory where
Lua module libraries
- (.so) are installed
+ (.so) are to be installed
+ by this port
LUA_MODSHAREDIRThe directory where
Lua modules
- (.lua) are installed
+ (.lua) are to be installed
+ by this port
@@ -6380,18 +6488,96 @@
LUA_CMD
- The path to the Lua
- interpreter
+ The name of the Lua
+ interpreter (e.g. lua53)LUAC_CMD
- The path to the Lua
- compiler
+ The name of the Lua
+ compiler (e.g. luac53)
+
+ These additional variables are available for ports that
+ specified the module parameter:
+
+
+ Variables Defined for Lua
+ Module Ports
+
+
+
+
+ Name
+ Description
+
+
+
+
+ LUA_DOCSDIR
+ the directory to which the module's
+ documentation should be installed.
+
+
+
+ LUA_EXAMPLESDIR
+ the directory to which the module's
+ example files should be installed.
+
+
+
+
+
+
+
+
+ Examples
+
+
+ Makefile for an application using
+ Lua
+
+ This example shows how to reference a
+ Lua module required at run
+ time. Notice that the reference must specify a
+ flavor.
+
+ 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>
+
+
+
+ Makefile for a simple Lua
+ module
+
+ 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>
+
+
Index: en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
+++ en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
@@ -1866,17 +1866,33 @@
luaPossible arguments: (none),
- XY+,
XY,
- build, run
+ XY+,
+ -XY,
+ XY-ZA,
+ module, flavors,
+ build, run,
+ envAdds a dependency on Lua. By
default this is a library dependency, unless overridden by the
- build or run option. The
- default version is 5.2, unless set by the
- XY parameter (for
- example, 51 or
- 52+).
+ build and/or run option.
+ The env option prevents the addition of any
+ dependency, while still defining all the usual variables.
+
+ The default version is set by the usual
+ DEFAULT_VERSIONS mechanism, unless a version or
+ range of versions is specified as an argument, for
+ example, 51 or 51-53.
+
+ Applications using Lua are
+ normally built for only a single Lua
+ version. However, library modules intended to be loaded by
+ Lua code should use the
+ module option to build with multiple
+ flavors.
+
+ For more information see .