Index: Mk/Uses/lua.mk
===================================================================
--- Mk/Uses/lua.mk
+++ Mk/Uses/lua.mk
@@ -5,16 +5,106 @@
 # MAINTAINER: ports@FreeBSD.org
 # Usage:
 #
-# USES+=	lua:[version]
+# USES+=	lua:[options,...]
 #
+# Options:
+#
+#   NN    (e.g. 52)  - specify an allowed Lua version (can use multiple times)
+#   NN+   (e.g. 52+) - specify a minimum Lua version (discouraged)
+#   -NN   (e.g. -53) - specify a maximum allowed version
+#   NN-NN (e.g. 51-53) - specify a range of allowed versions
+#
+#   flavors	define FLAVOR / FLAVORS as luaNN from the allowed versions
+#
+#   noflavors	don't use flavors
+#
+#   module	(implies flavors) specifies that the port is a Lua module
+#		(i.e. that it installes files in MODLIBDIR etc.)
+#
+#   build	add dependency to BUILD_DEPENDS
+#   run		add dependency to RUN_DEPENDS
+#
+#   env		define only the LUA_* vars and add them to PLIST_SUB and
+#		MAKE_ENV, do not add dependencies or other global state
+#
+#   envcore	as "env" but assume that we're building Lua itself
+#
+# Because of how Lua changes between versions, it's not usually considered
+# safe to specify NN+ version numbers for programs that embed Lua or provide
+# loadable Lua modules written in languages other than Lua, because API
+# changes will usually break things if you try and use a newer version than
+# the one you wrote the code for. In general do USES=lua:52,53 or
+# USES=lua:52-54 for such cases.
+#
+# If more than one version is allowed, then the LUA_DEFAULT version
+# (as set in DEFAULT_VERSIONS) is chosen if it is allowed, otherwise
+# the highest allowed version is chosen. But if "flavors" was requested,
+# and FLAVOR is set, we use that version.
+#
+# LUA_FLAVOR is defined to the desired flavor whether or not "flavors" was
+# selected; ports should use this to specify the flavor of dependencies
+# which are Lua modules or otherwise Lua-flavored.
+#
+# It's not generally expected that applications that embed Lua, or apps
+# written in Lua, would use USES=lua:flavors. Given that Lua is lightweight
+# and does not carry around a whole lot of module ecosystem with it, it is
+# best that application ports simply specify the Lua version or range of
+# versions that they support, and let the default one or the latest one be
+# used. However, they should still use LUA_FLAVOR as needed when specifying
+# dependencies.
+#
 .if !defined(_INCLUDE_USES_LUA_MK)
 _INCLUDE_USES_LUA_MK=	yes
 
 # When adding a version, please keep the comment in
 # Mk/bsd.default-versions.mk in sync.
-_LUA_VALID_VERSIONS=	53 52 51
+_LUA_VALID_VERSIONS:=	54 53 52 51
+.if defined(_LUA_EXTRA_VER)
+_LUA_VALID_VERSIONS+= ${_LUA_EXTRA_VER}
+.endif
 
-_LUA_DEFAULT_VERSION=	${LUA_DEFAULT:S/.//}
+_LUA_DEFAULT_VERSION:=	${LUA_DEFAULT:S/.//}
+
+# args
+_LUA_ARG_FLAVORS:=
+_LUA_ARG_MODULE:=
+_LUA_ARG_ENV:=
+_LUA_ARG_ENVCORE:=
+.if ${lua_ARGS:Mmodule}
+_LUA_ARG_FLAVORS:=yes
+_LUA_ARG_MODULE:=yes
+.endif
+.if ${lua_ARGS:Mflavors}
+_LUA_ARG_FLAVORS:=yes
+.endif
+.if ${lua_ARGS:Mnoflavors}
+_LUA_ARG_FLAVORS:=
+.endif
+.if ${lua_ARGS:Menv*}
+_LUA_ARG_ENV:=yes
+.endif
+.if ${lua_ARGS:Menvcore}
+_LUA_ARG_ENVCORE:=yes
+_LUA_ARG_FLAVORS:=
+.endif
+
+# envcore is for building Lua itself, so it overrides all version checks
+.if ${_LUA_ARG_ENVCORE}
+
+_LUA_WANTED_VERSION:=${lua_ARGS:M[1-9][0-9]:[1]}
+
+.  if ${lua_ARGS:M[1-9][0-9]:[#]} != 1
+IGNORE= USES=lua:envcore must also specify exactly one version number
+# set to avoid spurious errors below
+_LUA_WANTED_VERSION:=${_LUA_DEFAULT_VERSION}
+.  endif
+
+_LUA_VALID_VERSIONS:=${_LUA_WANTED_VERSION}
+_LUA_WANTED_VERSIONS:=${_LUA_WANTED_VERSION}
+_LUA_DEFAULT_VERSION:=${_LUA_WANTED_VERSION}
+
+.endif # _LUA_ARG_ENVCORE
+
 .if ! ${_LUA_VALID_VERSIONS:M${_LUA_DEFAULT_VERSION}}
 IGNORE=	Invalid lua version ${LUA_DEFAULT}
 .endif
@@ -22,89 +112,144 @@
 #
 # Parse a ver+ argument
 #
-.if ${lua_ARGS:M*+}
-_LUA_MIN_VERSION:=	${lua_ARGS:M*+:S/+//}
+.if ${lua_ARGS:M??+}
+_LUA_MIN_VERSION:=	${lua_ARGS:M??+:S/+//}
+_LUA_MAX_VERSION:=	99
+.endif
+
 #
-# Resolve minimum versions (ver+). Append anything greater or equal than the
-# specified minimum version to the list of wanted versions.
+# Parse a -ver argument
 #
-.  for _v in ${_LUA_VALID_VERSIONS}
-.    if ${_LUA_MIN_VERSION} <= ${_v}
+.if ${lua_ARGS:M-??}
+_LUA_MAX_VERSION:=	${lua_ARGS:M-??:S/-//}
+_LUA_MIN_VERSION:=	0
+.endif
+
+#
+# Parse a ver-ver argument
+#
+.if ${lua_ARGS:M??-??}
+_LUA_MIN_VERSION:=	${lua_ARGS:M??-??:S/-*//}
+_LUA_MAX_VERSION:=	${lua_ARGS:M??-??:S/*-//}
+.endif
+
+#
+# Parse one or more ver arguments
+#
+.if ${lua_ARGS:M[1-9][0-9]}
+.  for _v in ${lua_ARGS:M[1-9][0-9]}
+.    if ${_LUA_VALID_VERSIONS:M${_v}}
 _LUA_WANTED_VERSIONS+=${_v}
 .    endif
 .  endfor
+.  if empty(_LUA_WANTED_VERSIONS)
+IGNORE= USES=lua:nn did not find any valid version number
+.  endif
 .endif
 
 #
-# Parse one or more ver arguments
+# Resolve version ranges. Append anything within the range to the list of
+# wanted versions.
 #
-.if ${lua_ARGS:M5[1-3]}
-_LUA_WANTED_VERSIONS:=	${lua_ARGS:M5[1-3]}
+.if defined(_LUA_MIN_VERSION) && defined(_LUA_MAX_VERSION)
+.  for _v in ${_LUA_VALID_VERSIONS}
+.    if ${_LUA_MIN_VERSION} <= ${_v} && ${_LUA_MAX_VERSION} >= ${_v}
+_LUA_WANTED_VERSIONS+=${_v}
+.    endif
+.  endfor
+.  if empty(_LUA_WANTED_VERSIONS)
+IGNORE= USES=lua:xx-yy did not find any valid version
+.  endif
 .endif
 
 #
-# If no version was specified with any of the ver or ver+ arguments, set the
-# default version.
+# If no version was specified with any of the ver or ver+ arguments, allow
+# all versions.
 #
-.if !defined(_LUA_WANTED_VERSIONS)
-_LUA_WANTED_VERSIONS=	${_LUA_DEFAULT_VERSION}
+.if empty(_LUA_WANTED_VERSIONS)
+_LUA_WANTED_VERSIONS:=	${_LUA_VALID_VERSIONS}
 .endif
 
 #
-# Right now we have built a list of potential versions that we may depend on.
-# Let's sort them and remove any duplicates. We then locate the highest one
-# already installed, if any.
+# By now, _LUA_WANTED_VERSIONS is the list of valid version numbers that the
+# caller has allowed through. We want to put the default version, if it's in
+# the list, first, followed by all other versions in desc order; then the
+# first element is the one we want (or the default flavor in the flavor case)
 #
-.for _v in ${_LUA_WANTED_VERSIONS:O:u}
-_LUA_HIGHEST_VERSION:=${_v}
-.  if exists(${LOCALBASE}/bin/lua${_v})
-_LUA_HIGHEST_INSTALLED_VERSION:=	${_v}
+_LUA_WANTED_VERSIONS:= \
+	${_LUA_WANTED_VERSIONS:M${_LUA_DEFAULT_VERSION}} \
+	${_LUA_WANTED_VERSIONS:N${_LUA_DEFAULT_VERSION}:O:u:[-1..1]}
+
+.if ${_LUA_ARG_FLAVORS}
+.  if empty(FLAVORS)
+FLAVORS= ${_LUA_WANTED_VERSIONS:S/^/lua/}
 .  endif
-.endfor
-
-#
-# Depend on the default version if it fits, or the highest installed version,
-# or the highest version.
-#
-.if ${_LUA_WANTED_VERSIONS:M${_LUA_DEFAULT_VERSION}}
-_LUA_WANTED_VERSION:=	${_LUA_DEFAULT_VERSION}
-.elif defined(_LUA_HIGHEST_INSTALLED_VERSION)
-_LUA_WANTED_VERSION:=	${_LUA_HIGHEST_INSTALLED_VERSION}
+.  if empty(FLAVOR)
+FLAVOR= ${FLAVORS:[1]}
+.  endif
+.  if !empty(FLAVOR)
+_LUA_WANTED_VERSION:= ${FLAVOR:S/^lua//}
+.  endif
 .else
-_LUA_WANTED_VERSION:=	${_LUA_HIGHEST_VERSION}
+_LUA_WANTED_VERSION:= ${_LUA_WANTED_VERSIONS:[1]}
 .endif
 
+LUA_FLAVOR= ${_LUA_WANTED_VERSION:S/^/lua/}
+
+LUA_BASE=${LOCALBASE}
+
 #
 # Exported variables
 #
 LUA_VER_STR=		${_LUA_WANTED_VERSION}
-LUA_VER=		${_LUA_WANTED_VERSION:S/5/5./}
+LUA_VER=		${_LUA_WANTED_VERSION:S/^5/5./}
 LUA_CMD=		lua${_LUA_WANTED_VERSION}
 LUAC_CMD=		luac${_LUA_WANTED_VERSION}
-LUA_INCDIR=		${LOCALBASE}/include/lua${_LUA_WANTED_VERSION}
-LUA_MODLIBDIR=		${LOCALBASE}/lib/lua/${LUA_VER}
-LUA_MODSHAREDIR=	${LOCALBASE}/share/lua/${LUA_VER}
-LUA_LIBDIR=		${LOCALBASE}/lib
+LUA_INCDIR=		${LUA_BASE}/include/lua${_LUA_WANTED_VERSION}
+LUA_MODLIBDIR=		${LUA_BASE}/lib/lua/${LUA_VER}
+LUA_MODSHAREDIR=	${LUA_BASE}/share/lua/${LUA_VER}
+LUA_MODDOCSDIR=		${LUA_BASE}/share/doc/lua${_LUA_WANTED_VERSION}
+LUA_LIBDIR=		${LUA_BASE}/lib
 LUA_PKGNAMEPREFIX=	lua${LUA_VER_STR}-
 
-PLIST_SUB+=	LUA_MODLIBDIR=${LUA_MODLIBDIR:S,^${LOCALBASE}/,,} \
-		LUA_MODSHAREDIR=${LUA_MODSHAREDIR:S,^${LOCALBASE}/,,} \
+PLIST_SUB+=	LUA_MODLIBDIR=${LUA_MODLIBDIR:S,^${PREFIX}/,,} \
+		LUA_MODSHAREDIR=${LUA_MODSHAREDIR:S,^${PREFIX}/,,} \
+		LUA_MODDOCSDIR=${LUA_MODDOCSDIR:S,^${PREFIX}/,,} \
+		LUA_INCDIR=${LUA_INCDIR:S,^${PREFIX}/,,} \
+		LUA_LIBDIR=${LUA_LIBDIR:S,^${PREFIX}/,,} \
 		LUA_VER=${LUA_VER} \
-		LUA_INCDIR=${LUA_INCDIR:S,^${LOCALBASE}/,,} \
-		LUA_LIBDIR=${LUA_LIBDIR:S,^${LOCALBASE}/,,} \
 		LUA_VER_STR=${LUA_VER_STR}
 MAKE_ENV+=	LUA_MODLIBDIR=${LUA_MODLIBDIR} \
 		LUA_MODSHAREDIR=${LUA_MODSHAREDIR} \
+		LUA_MODDOCSDIR=${LUA_MODDOCSDIR} \
+		LUA_INCDIR=${LUA_INCDIR} \
+		LUA_LIBDIR=${LUA_LIBDIR} \
 		LUA_VER=${LUA_VER} \
-		LUA_INCDIR=${LUA_INCDIR} \
-		LUA_LIBDIR=${LUA_LIBDIR}
+		LUA_VER_STR=${LUA_VER_STR}
 
-.if ${lua_ARGS:Mbuild}
+# if building a module or Lua itself, or if the port defined LUA_DOCSUBDIR,
+# then define LUA_DOCSDIR too
+.if !empty(_LUA_ARG_ENVCORE) || !empty(_LUA_ARG_MODULE)
+.  if ${_LUA_ARG_ENVCORE}
+LUA_DOCSUBDIR=lua
+.  else
+LUA_DOCSUBDIR=${PORTNAME}
+.  endif
+.endif
+.if !empty(LUA_DOCSUBDIR)
+LUA_DOCSDIR=	${LUA_MODDOCSDIR}/${LUA_DOCSUBDIR}
+PLIST_SUB+=	LUA_DOCSDIR=${LUA_DOCSDIR:S,^${PREFIX}/,,}
+MAKE_ENV+=	LUA_DOCSDIR=${LUA_DOCSDIR}
+.endif
+
+.if empty(_LUA_ARG_ENV)
+.  if ${lua_ARGS:Mbuild}
 BUILD_DEPENDS+=	${LUA_CMD}:lang/lua${LUA_VER_STR}
-.elif ${lua_ARGS:Mrun}
+.  elif ${lua_ARGS:Mrun}
 RUN_DEPENDS+=	${LUA_CMD}:lang/lua${LUA_VER_STR}
-.else
+.  else
 LIB_DEPENDS+=	liblua-${LUA_VER}.so:lang/lua${LUA_VER_STR}
+.  endif
 .endif
 
 .endif