refactor(lib): lua is external dependency

Author: alandefreitas

.clang-format

@@ -200,7 +200,7 @@ IncludeCategories:
     Priority: 0
   - Regex: '^".*"'                               # quoted includes come next
     Priority: 1
-  - Regex: '^<lib/.*>'                        # internal project headers
+  - Regex: '^<lib/.*>'                           # internal project headers
     Priority: 2
   - Regex: '^<mrdocs/.*>'                        # internal project headers
     Priority: 3
@@ -214,12 +214,15 @@ IncludeCategories:
     Priority: 7
   - Regex: '^<duktape/.*>'                       # duktape headers
     Priority: 8
-  - Regex: '^<(?!mrdocs/|clang/|llvm/|test_suite/|fmt/|duktape/)[^/]+/.*>' # other angle-bracket includes
+    # Lua headers
+  - Regex: '^<lua.*>'                           # Lua headers
     Priority: 9
-  - Regex: '^<[^/]+>'                            # C++ standard headers like <vector>
+  - Regex: '^<(?!mrdocs/|clang/|llvm/|test_suite/|fmt/|duktape/)[^/]+/.*>' # other angle-bracket includes
     Priority: 10
-  - Regex: '.*'                                  # fallback
+  - Regex: '^<[^/]+>'                            # C++ standard headers like <vector>
     Priority: 11
+  - Regex: '.*'                                  # fallback
+    Priority: 12
 
 # Comments
 FixNamespaceComments: true

.github/workflows/ci.yml

@@ -402,6 +402,26 @@ jobs:
           run-tests: false
           trace-commands: true
 
+      - name: Install Lua
+        uses: alandefreitas/cpp-actions/cmake-workflow@v1.8.12
+        with:
+          source-dir: ../third-party/lua
+          url: https://github.com/lua/lua/archive/refs/tags/v5.4.8.tar.gz
+          patches: |
+            ./third-party/lua/CMakeLists.txt
+            ./third-party/lua/LuaConfig.cmake.in
+          build-dir: ${sourceDir}/build
+          cc: ${{ steps.setup-cpp.outputs.cc }}
+          cxx: ${{ steps.setup-cpp.outputs.cxx }}
+          ccflags: ${{ matrix.common-ccflags }}
+          cxxflags: ${{ steps.rmatrix.outputs.common-cxxflags }}
+          build-type: ${{ matrix.build-type }}
+          shared: false
+          install: true
+          install-prefix: ${sourceDir}/install
+          run-tests: false
+          trace-commands: true
+
       - name: Install Libxml2
         uses: alandefreitas/cpp-actions/cmake-workflow@v1.8.12
         if: matrix.compiler == 'msvc'
@@ -479,6 +499,9 @@ jobs:
             -D CMAKE_EXE_LINKER_FLAGS="${{ steps.rmatrix.outputs.common-ldflags }}"
             -D LLVM_ROOT="${{ steps.rmatrix.outputs.llvm-path }}"
             -D duktape_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/duktape/install"
+            -D LUA_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"
+            -D Lua_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"
+            -D lua_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"
             ${{ runner.os == 'Windows' && '-D LibXml2_ROOT=../third-party/libxml2/install' || '' }}
           export-compile-commands: true
           run-tests: true

CMakeLists.txt

@@ -284,6 +284,9 @@ if (NOT DUKTAPE_FOUND)
     find_package(Duktape REQUIRED CONFIG)
 endif()
 
+# Lua
+find_package(Lua CONFIG REQUIRED)
+
 unset(CMAKE_FOLDER)
 
 #-------------------------------------------------
@@ -322,7 +325,6 @@ target_include_directories(mrdocs-core
     PRIVATE
     "${PROJECT_SOURCE_DIR}/src"
     "${PROJECT_BINARY_DIR}/src"
-    "${PROJECT_SOURCE_DIR}/third-party/lua/src"
 )
 target_compile_definitions(
     mrdocs-core
@@ -345,6 +347,7 @@ target_include_directories(mrdocs-core
         "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
 )
 target_link_libraries(mrdocs-core PRIVATE ${DUKTAPE_LIBRARY})
+target_link_libraries(mrdocs-core PRIVATE Lua::lua)
 
 # Clang
 if (CLANG_SIMPLE_LIBS)

bootstrap.py

@@ -91,6 +91,13 @@ class InstallOptions:
     duktape_build_dir: str = "<duktape-src-dir>/build/<duktape-build-type:lower><\"-\":if(cc)><cc:basename><\"-\":if(sanitizer)><sanitizer:lower>"
     duktape_install_dir: str = "<duktape-src-dir>/install/<duktape-build-type:lower><\"-\":if(cc)><cc:basename><\"-\":if(sanitizer)><sanitizer:lower>"
 
+    # Lua
+    lua_src_dir: str = "<third-party-src-dir>/lua"
+    lua_url: str = "https://github.com/lua/lua/archive/refs/tags/v5.4.8.tar.gz"
+    lua_build_type: str = "<mrdocs-build-type>"
+    lua_build_dir: str = "<lua-src-dir>/build/<lua-build-type:lower><\"-\":if(cc)><cc:basename><\"-\":if(sanitizer)><sanitizer:lower>"
+    lua_install_dir: str = "<lua-src-dir>/install/<lua-build-type:lower><\"-\":if(cc)><cc:basename><\"-\":if(sanitizer)><sanitizer:lower>"
+
     # LLVM
     llvm_src_dir: str = "<third-party-src-dir>/llvm-project"
     llvm_build_type: str = "<mrdocs-build-type>"
@@ -152,6 +159,11 @@ class InstallOptions:
     "duktape_build_type": "CMake build type for Duktape. (Release, Debug, RelWithDebInfo, MilRelSize)",
     "duktape_build_dir": "Directory where Duktape will be built.",
     "duktape_install_dir": "Directory where Duktape will be installed.",
+    "lua_src_dir": "Directory for the Lua source code.",
+    "lua_url": "Download URL for the Lua source archive.",
+    "lua_build_type": "Build type for Lua. (Release, Debug)",
+    "lua_build_dir": "Directory where Lua will be built.",
+    "lua_install_dir": "Directory where Lua will be installed.",
     "libxml2_src_dir": "Directory for the libxml2 source code.",
     "libxml2_build_type": "CMake build type for libxml2: Release always recommended. (Release, Debug, RelWithDebInfo, MilRelSize)",
     "libxml2_build_dir": "Directory where libxml2 will be built.",
@@ -1162,6 +1174,63 @@ def install_duktape(self):
             self.options.duktape_install_dir,
             extra_args)
 
+    def install_lua(self):
+        # Resolve paths/values
+        self.prompt_dependency_path_option("lua_src_dir")
+        if not os.path.exists(self.options.lua_src_dir):
+            self.prompt_option("lua_url")
+            os.makedirs(self.options.lua_src_dir, exist_ok=True)
+            archive_filename = os.path.basename(self.options.lua_url)
+            archive_path = os.path.join(self.options.third_party_src_dir, archive_filename)
+            self.download_file(self.options.lua_url, archive_path)
+
+            # Extract lua-5.4.8.tar.gz, flatten top-level dir into lua_src_dir
+            mode = "r:gz" if archive_filename.endswith(".gz") else "r:*"
+            with tarfile.open(archive_path, mode) as tar:
+                top_level = tar.getmembers()[0].name.split('/')[0]
+                for member in tar.getmembers():
+                    rel = os.path.relpath(member.name, top_level)
+                    if rel == '.' or rel.startswith('..'):
+                        continue
+                    member.name = rel
+                    tar.extract(member, path=self.options.lua_src_dir)
+            os.remove(archive_path)
+
+        # Copy our tiny CMake patch files (like we do for Duktape)
+        lua_patches = os.path.join(self.options.mrdocs_src_dir, 'third-party', 'lua')
+        if os.path.exists(lua_patches):
+            for fname in os.listdir(lua_patches):
+                src = os.path.join(lua_patches, fname)
+                dst = os.path.join(self.options.lua_src_dir, fname)
+                shutil.copy(src, dst)
+
+        # Lua’s own tree puts sources under src/; our CMakeLists handles that.
+        self.prompt_build_type_option("lua_build_type")
+        # align ABI expectations like we do for Duktape:
+        if not self.is_abi_compatible(self.options.mrdocs_build_type, self.options.lua_build_type):
+            if self.options.mrdocs_build_type.lower() == "debug":
+                self.options.lua_build_type = "OptimizedDebug"
+            else:
+                self.options.lua_build_type = self.options.mrdocs_build_type
+
+        self.prompt_dependency_path_option("lua_build_dir")
+        self.prompt_dependency_path_option("lua_install_dir")
+
+        extra_args = []
+        if self.options.sanitizer:
+            flag = self.sanitizer_flag_name(self.options.sanitizer)
+            for arg in ("CMAKE_C_FLAGS", "CMAKE_CXX_FLAGS"):
+                extra_args.append(f"-D{arg}=-fsanitize={flag} -fno-sanitize-recover={flag} -fno-omit-frame-pointer")
+
+        # Standard cmake_workflow like Duktape
+        self.cmake_workflow(
+            self.options.lua_src_dir,
+            self.options.lua_build_type,
+            self.options.lua_build_dir,
+            self.options.lua_install_dir,
+            extra_args
+        )
+
     def install_libxml2(self):
         self.prompt_dependency_path_option("libxml2_src_dir")
         if not os.path.exists(self.options.libxml2_src_dir):
@@ -1338,7 +1407,9 @@ def create_cmake_presets(self):
                 "Duktape_ROOT": self.options.duktape_install_dir,
                 "libxml2_ROOT": self.options.libxml2_install_dir,
                 "LibXml2_ROOT": self.options.libxml2_install_dir,
-                "MRDOCS_BUILD_TESTS": self.options.mrdocs_build_tests,
+                "LUA_ROOT": self.options.lua_install_dir,
+                "Lua_ROOT": self.options.lua_install_dir,
+                "lua_ROOT": self.options.lua_install_dir,
                 "MRDOCS_BUILD_DOCS": False,
                 "MRDOCS_GENERATE_REFERENCE": False,
                 "MRDOCS_GENERATE_ANTORA_REFERENCE": False
@@ -2580,6 +2651,7 @@ def install_all(self):
         self.probe_compilers()
         self.install_ninja()
         self.install_duktape()
+        self.install_lua()
         self.install_llvm()
         if self.prompt_option("mrdocs_build_tests"):
             self.install_libxml2()

src/lib/Support/Lua.cpp

@@ -13,11 +13,12 @@
 #include <mrdocs/Support/Path.hpp>
 #include <mrdocs/Support/Report.hpp>
 #include <llvm/Support/raw_ostream.h>
+#include <lua.h>
+#include <lualib.h>
 #include <format>
-#include <lua.hpp>
+#include <lauxlib.h>
 #include <print>
 
-namespace clang {
 namespace mrdocs {
 namespace lua {
 
@@ -1205,4 +1206,3 @@ lua_main()
 
 } // lua
 } // mrdocs
-} // clang

src/lib/Support/LuaHandlebars.cpp

@@ -11,7 +11,6 @@
 #include "LuaHandlebars.hpp"
 #include <mrdocs/Support/Lua.hpp>
 
-namespace clang {
 namespace mrdocs {
 
 // VFALCO:
@@ -67,4 +66,3 @@ tryLoadHandlebars(
 }
 
 } // mrdocs
-} // clang

src/lib/Support/LuaHandlebars.hpp

@@ -14,7 +14,6 @@
 #include <mrdocs/Platform.hpp>
 #include <mrdocs/Support/Lua.hpp>
 
-namespace clang {
 namespace mrdocs {
 
 /** Add the Handlebars Lua instance as a global
@@ -25,6 +24,5 @@ tryLoadHandlebars(
     lua::Context const& ctx);
 
 } // mrdocs
-} // clang
 
 #endif // MRDOCS_LIB_SUPPORT_LUAHANDLEBARS_HPP

src/lib/lua.cpp

@@ -0,0 +1,89 @@
+#
+# Licensed under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+# Copyright (c) 2025 Alan de Freitas (alandefreitas@gmail.com)
+#
+# Official repository: https://github.com/cppalliance/mrdocs
+#
+#
+
+cmake_minimum_required(VERSION 3.13)
+
+set(lua_MAJOR_VERSION 5)
+set(lua_MINOR_VERSION 4)
+set(lua_PATCH_VERSION 8)
+set(lua_VERSION ${lua_MAJOR_VERSION}.${lua_MINOR_VERSION}.${lua_PATCH_VERSION})
+
+option(CMAKE_VERBOSE_MAKEFILE "Create verbose makefile" OFF)
+option(BUILD_SHARED_LIBS "Create lua as a shared library" OFF)
+
+project(lua VERSION ${lua_VERSION} LANGUAGES C)
+
+# Check if ./src exists
+if (EXISTS "${CMAKE_CURRENT_LIST_DIR}/src")
+    # Lua sources live under ./src
+    file(GLOB LUA_SOURCES "${CMAKE_CURRENT_LIST_DIR}/src/*.c")
+    list(REMOVE_ITEM LUA_SOURCES
+            "${CMAKE_CURRENT_LIST_DIR}/src/lua.c"
+            "${CMAKE_CURRENT_LIST_DIR}/src/luac.c"
+    )
+    file(GLOB LUA_HEADERS "${CMAKE_CURRENT_LIST_DIR}/src/*.h")
+else()
+    # Lua sources live under ./ (github release)
+    file(GLOB LUA_SOURCES "${CMAKE_CURRENT_LIST_DIR}/*.c")
+    list(REMOVE_ITEM LUA_SOURCES
+            "${CMAKE_CURRENT_LIST_DIR}/lua.c"
+            "${CMAKE_CURRENT_LIST_DIR}/luac.c"
+    )
+    file(GLOB LUA_HEADERS "${CMAKE_CURRENT_LIST_DIR}/*.h")
+endif()
+
+add_library(lua ${LUA_SOURCES} ${LUA_HEADERS})
+target_include_directories(lua
+        PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_LIST_DIR}/src>
+        $<INSTALL_INTERFACE:include>
+)
+
+set_target_properties(lua PROPERTIES
+        PUBLIC_HEADER "${LUA_HEADERS}"
+        VERSION ${lua_VERSION}
+        SOVERSION ${lua_MAJOR_VERSION}
+)
+
+# Optional compatibility defines (uncomment if you need them)
+# target_compile_definitions(lua PRIVATE LUA_COMPAT_5_3)
+
+install(TARGETS lua
+        EXPORT LuaTargets
+        ARCHIVE DESTINATION "lib"
+        LIBRARY DESTINATION "lib"
+        RUNTIME DESTINATION "bin"
+        PUBLIC_HEADER DESTINATION "include"
+        COMPONENT dev
+)
+
+install(EXPORT LuaTargets
+        FILE LuaTargets.cmake
+        NAMESPACE Lua::
+        DESTINATION "share/Lua"
+)
+
+export(PACKAGE lua)
+
+include(CMakePackageConfigHelpers)
+write_basic_package_version_file(
+        "${PROJECT_BINARY_DIR}/LuaConfigVersion.cmake"
+        COMPATIBILITY SameMajorVersion
+)
+
+configure_file(LuaConfig.cmake.in
+        "${PROJECT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/LuaConfig.cmake" @ONLY)
+
+install(FILES
+        "${PROJECT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/LuaConfig.cmake"
+        "${PROJECT_BINARY_DIR}/LuaConfigVersion.cmake"
+        DESTINATION "share/Lua"
+)