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+ + + + <literal>USES=lua</literal> 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: 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. + + 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 should + have a line of this form: 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 (which may be used multiple times), + 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 closest requested + version to the default 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. + + + Configuration and Compiler flags + + Software that uses Lua may have + been written to auto-detect the Lua + version in use. In general ports should override this + assumption, and force the use of the specific + Lua version selected as described + above. Depending on the sortware being ported, this might + require any or all of: + + + + + Using LUA_VER as part of a parameter + to the software's configuration script via + CONFIGURE_ARGS or + CONFIGURE_ENV (or equivalent for other + build systems); + + + + + Adding -I${LUA_INCDIR}, + -L${LUA_LIBDIR}, and + -llua-${LUA_VER} to CFLAGS, + LDFLAGS, LIBS respectively + as appropriate; + + + + + Patch the software's configuration or build files to select + the correct version. + + + + + + + + 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). However, the port may choose to define + LUA_DOCSUBDIR as a suitable subdirectory name + (usually the port's PORTNAME as long as this + does not conflict with the PORTNAME of any + module), in which case the framework will define both + LUA_DOCSDIR and + LUA_EXAMPLESDIR. + + + As with module ports, a flavored port should avoid installing + files that would conflict between versions. Typically this is done + by adding LUA_VER_STR as a suffix to program + names (e.g. using + USES=uniquefiles), and + otherwise using either LUA_VER or + LUA_VER_STR as part of any other files or + subdirectories used outside of LUA_MODLIBDIR + and LUA_MODSHAREDIR. + + + Defined Variables @@ -6439,48 +6574,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 port + + + LUA_INCDIR The directory where - Lua and - tolua header files are + Lua header files are installed LUA_LIBDIR The 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_MODLIBDIR The directory where Lua module libraries - (.so) are installed + (.so) are to be installed + by this port LUA_MODSHAREDIR The directory where Lua modules - (.lua) are installed + (.lua) are to be installed + by this port @@ -6491,18 +6647,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 <application>Lua</application> + 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 + <application>Lua</application> + + 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 <application>Lua</application> + 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: 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 @@ <literal>lua</literal> Possible arguments: (none), - XY+, XY, - build, run + XY+, + -XY, + XY-ZA, + module, flavors, + build, run, + env Adds 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 .