Add a Lua build-system (#28854)

Reworking lua to allow easier substitution of the base lua implementation.

Also adding in a maintained version of luajit and re-factoring the entire stack 
to use a custom build-system to centralize functionality like environment 
variable management and luarocks installation.

The `lua-lang` virtual is now versioned so that a package that requires 
Lua 5.1 semantics can get any lua, but one that requires 5.2 will only 
get upstream lua.

The luaposix package requires lua-bit32, but only when built with a 
lua conforming to version 5.1.  This adds the package, and the 
dependencies, but exposed a problem with luarocks dependency 
detection.  Since we're  installing each package in its own "tree" and 
there's no environment  variable to list extra trees, spack now 
generates a luarocks config  file that lists all the trees of all the 
dependencies, and references  it by setting `LUAROCKS_CONFIG` 
in the build environment of every LuaPackage.  This allows luarocks 
to find the spack installed  dependencies correctly rather than 
trying (and failing) to download them.

Co-authored-by: Adam J. Stewart <ajstewart426@gmail.com>
Co-authored-by: Tom Scogland <tscogland@llnl.gov>
Co-authored-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>

1 files changed, 105 insertions, 0 deletions

diff --git a/lib/spack/docs/build_systems/luapackage.rst b/lib/spack/docs/build_systems/luapackage.rst
new file mode 100644
index 0000000000..6332edfc20
--- /dev/null
+++ b/lib/spack/docs/build_systems/luapackage.rst
@@ -0,0 +1,105 @@
+.. Copyright 2013-2022 Lawrence Livermore National Security, LLC and other
+   Spack Project Developers. See the top-level COPYRIGHT file for details.
+
+   SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+.. _luapackage:
+
+------------
+LuaPackage
+------------
+
+LuaPackage is a helper for the common case of Lua packages that provide
+a rockspec file.  This is not meant to take a rock archive, but to build
+a source archive or repository that provides a rockspec, which should cover
+most lua packages. In the case a Lua package builds by Make rather than
+luarocks, prefer MakefilePackage.
+
+^^^^^^
+Phases
+^^^^^^
+
+The ``LuaPackage`` base class comes with the following phases:
+
+#. ``unpack`` - if using a rock, unpacks the rock and moves into the source directory
+#. ``preprocess`` - adjust sources or rockspec to fix build
+#. ``install`` - install the project
+
+By default, these phases run:
+
+.. code-block:: console
+
+   # If the archive is a source rock
+   $ luarocks unpack <archive>.src.rock
+   $ # preprocess is a noop by default
+   $ luarocks make <name>.rockspec
+
+
+Any of these phases can be overridden in your package as necessary.
+
+^^^^^^^^^^^^^^^
+Important files
+^^^^^^^^^^^^^^^
+
+Packages that use the Lua/LuaRocks build system can be identified by the
+presence of a ``*.rockspec`` file in their sourcetree, or can be fetched as
+a source rock archive (``.src.rock``). This file declares things like build
+instructions and dependencies, the ``.src.rock`` also contains all code.
+
+It is common for the rockspec file to list the lua version required in
+a dependency. The LuaPackage class adds appropriate dependencies on a Lua
+implementation, but it is a good idea to specify the version required with
+a ``depends_on`` statement.  The block normally will be a table definition like
+this:
+
+.. code-block:: lua
+
+   dependencies = {
+      "lua >= 5.1",
+   }
+
+The LuaPackage class supports source repositories and archives containing
+a rockspec and directly downloading source rock files.  It *does not* support
+downloading dependencies listed inside a rockspec, and thus does not support
+directly downloading a rockspec as an archive.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Build system dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+All base dependencies are added by the build system, but LuaRocks is run to
+avoid downloading extra Lua dependencies during build.  If the package needs
+Lua libraries outside the standard set, they should be added as dependencies.
+
+To specify a Lua version constraint but allow all lua implementations, prefer
+to use ``depends_on("lua-lang@5.1:5.1.99")`` to express any 5.1 compatible
+version. If the package requires LuaJit rather than Lua,
+a ``depends_on("luajit")`` should be used to ensure a LuaJit distribution is
+used instead of the Lua interpreter. Alternately, if only interpreted Lua will
+work ``depends_on("lua")`` will express that.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Passing arguments to luarocks make
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you need to pass any arguments to the ``luarocks make`` call, you can
+override the ``luarocks_args`` method like so:
+
+.. code-block:: python
+
+    def luarocks_args(self):
+        return ['flag1', 'flag2']
+
+One common use of this is to override warnings or flags for newer compilers, as in:
+
+.. code-block:: python
+
+    def luarocks_args(self):
+        return ["CFLAGS='-Wno-error=implicit-function-declaration'"]
+
+^^^^^^^^^^^^^^^^^^^^^^
+External documentation
+^^^^^^^^^^^^^^^^^^^^^^
+
+For more information on the LuaRocks build system, see:
+https://luarocks.org/