Add content for 'C++ and Lua' article

.gitignore

@@ -4,4 +4,6 @@
 /lua
 /*.rock
 /*.sublime-workspace
+
+build
 profile.json

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "src/cpp/cmake_git_submodule/lua"]
+	path = src/cpp/cmake_git_submodule/lua
+	url = https://github.com/lua/lua.git

src/cpp/README.md

@@ -0,0 +1,30 @@
+# Lua with C++
+
+This folder contains a set of examples from my article [C++ and Lua](https://martin-fieber.de/blog/cpp-and-lua) as part of the [Lua series](https://martin-fieber.de/series/lua).
+
+## Examples
+
+| Folder                     | Contents                                            |
+| -------------------------- | --------------------------------------------------- |
+| `cmake_find_package/`      | Include Lua in a project via CMake `find_package`   |
+| `cmake_external_project/`  | Include Lua in a project via CMake external project |
+| `cmake_git_submodule/`     | Include Lua in a project via Git submodule          |
+| `example-read-config/`     | All about reading data from Lua                     |
+| `example-functions/`       | Calling Lua functions from C++                      |
+| `example-cpp-to-lua/`      | Calling a C++ from Lua                              |
+| `example-custom-module`    | Define a custom Lua module from C++                 |
+| `example-override-builtin` | Override built-in Lua functions                     |
+
+## Setup
+
+Every example is set up the same, using CMake to build. Setting any example folder as current working directory, run the following command to create the CMake build configuration.
+
+```shell
+cmake -B build
+```
+
+The next command will build the executable into the folder `build`.
+
+```shell
+cmake --build build
+```

src/cpp/cmake_external_project/CMakeLists.txt

@@ -0,0 +1,34 @@
+cmake_minimum_required(VERSION 3.18)
+
+# Setup a CMake project for C++
+project(
+  LuaWithCMakeExternalProject
+  VERSION 1.0
+  LANGUAGES CXX)
+
+# Add an executable based on one source file
+add_executable(ProgramName main.cpp)
+
+# Include the fetch content module
+include(FetchContent)
+
+# Fetch Lua from git mirror
+FetchContent_Declare(
+  lua
+  GIT_REPOSITORY "https://github.com/lua/lua.git"
+  GIT_TAG v5.5.0
+)
+
+# Make content available
+FetchContent_MakeAvailable(lua)
+
+# Setup Lua library target with include directories
+add_library(Lua::Lua INTERFACE IMPORTED)
+target_include_directories(
+  Lua::Lua
+  INTERFACE "${lua_SOURCE_DIR}")
+
+# Link Lua library to the executable
+target_link_libraries(
+  ProgramName
+  PRIVATE Lua::Lua)

src/cpp/cmake_external_project/README.md

@@ -0,0 +1,17 @@
+# Lua, CMake, FetchContent
+
+Using Lua with CMake and the `FetchContent` module. Lua will be fetched from source.
+
+## Setup
+
+With the folder containing this file as current working directory, run the following command to create the CMake build configuration.
+
+```shell
+cmake -B build
+```
+
+The next command will build the executable into the folder `build`.
+
+```shell
+cmake --build build
+```

src/cpp/cmake_external_project/main.cpp

@@ -0,0 +1,7 @@
+#include <lua.hpp>
+
+int main() {
+  // More to come ...
+
+  return 0;
+}

src/cpp/cmake_find_package/CMakeLists.txt

@@ -0,0 +1,29 @@
+cmake_minimum_required(VERSION 3.18)
+
+# Setup a CMake project for C++
+project(
+  LuaWithCMakeFindPackage
+  VERSION 1.0
+  LANGUAGES CXX)
+
+# Add an executable based on one source file
+add_executable(ProgramName main.cpp)
+
+# Try to find the Lua package on the system
+find_package(Lua)
+
+# If Lua was found and target is not set up
+if(Lua_FOUND AND NOT TARGET Lua::Lua)
+  # Setup Lua library target
+  add_library(Lua::Lua INTERFACE IMPORTED)
+
+  # Set include directories
+  target_include_directories(
+    Lua::Lua
+    INTERFACE "${LUA_INCLUDE_DIR}")
+endif()
+
+# Link Lua library to the executable
+target_link_libraries(
+  ProgramName
+  PRIVATE Lua::Lua)

src/cpp/cmake_find_package/README.md

@@ -0,0 +1,17 @@
+# Lua, CMake, find_package
+
+Using Lua with CMake and find_package. This requires Lua to already be installed/available on the system.
+
+## Setup
+
+With the folder containing this file as current working directory, run the following command to create the CMake build configuration.
+
+```shell
+cmake -B build
+```
+
+The next command will build the executable into the folder `build`.
+
+```shell
+cmake --build build
+```

src/cpp/cmake_find_package/main.cpp

@@ -0,0 +1,7 @@
+#include <lua.hpp>
+
+int main() {
+  // More to come ...
+
+  return 0;
+}

src/cpp/cmake_git_submodule/CMakeLists.txt

@@ -0,0 +1,21 @@
+cmake_minimum_required(VERSION 3.18)
+
+# Setup a CMake project for C++
+project(
+  LuaWithGitSubmodules
+  VERSION 1.0
+  LANGUAGES CXX)
+
+# Add an executable based on one source file
+add_executable(ProgramName main.cpp)
+
+# Setup Lua library target with include directories
+add_library(Lua::Lua INTERFACE IMPORTED)
+target_include_directories(
+  Lua::Lua
+  INTERFACE "lua")
+
+# Link Lua library to the executable
+target_link_libraries(
+  ProgramName
+  PRIVATE Lua::Lua)

src/cpp/cmake_git_submodule/README.md

@@ -0,0 +1,17 @@
+# Lua, CMake, Git Submodules
+
+Using Lua with CMake and the Git submodules.
+
+## Setup
+
+With the folder containing this file as current working directory, run the following command to create the CMake build configuration.
+
+```shell
+cmake -B build
+```
+
+The next command will build the executable into the folder `build`.
+
+```shell
+cmake --build build
+```

src/cpp/cmake_git_submodule/main.cpp

@@ -0,0 +1,7 @@
+#include <lua.hpp>
+
+int main() {
+  // More to come ...
+
+  return 0;
+}

src/cpp/example-cpp-to-lua/CMakeLists.txt

@@ -0,0 +1,32 @@
+cmake_minimum_required(VERSION 3.18)
+
+# Setup a CMake project for C++
+project(
+  LuaExampleCppToLua
+  VERSION 1.0
+  LANGUAGES CXX)
+
+# Add an executable based on one source file
+add_executable(ProgramName main.cpp)
+
+# Let's use C++23
+target_compile_features(ProgramName PRIVATE cxx_std_23)
+
+# Try to find the Lua package on the system
+find_package(Lua REQUIRED)
+
+# If Lua was found and target is not set up
+if(Lua_FOUND AND NOT TARGET Lua::Lua)
+  add_library(Lua::Lua INTERFACE IMPORTED)
+  set_target_properties(
+    Lua::Lua
+    PROPERTIES
+      INTERFACE_INCLUDE_DIRECTORIES "${LUA_INCLUDE_DIR}"
+      INTERFACE_LINK_LIBRARIES "${LUA_LIBRARIES}"
+  )
+endif()
+
+# Link Lua library to the executable
+target_link_libraries(
+  ProgramName
+  PRIVATE Lua::Lua)

src/cpp/example-cpp-to-lua/README.md

@@ -0,0 +1,17 @@
+# Functions example
+
+Different examples on how to create functions in C++ to be called from Lua.
+
+## Setup
+
+With the folder containing this file as current working directory, run the following command to create the CMake build configuration.
+
+```shell
+cmake -B build
+```
+
+The next command will build the executable into the folder `build`.
+
+```shell
+cmake --build build
+```

src/cpp/example-cpp-to-lua/main.cpp

@@ -0,0 +1,46 @@
+#include <print>
+
+#include <lua.hpp>
+
+int compute(lua_State *L) {
+  // Function arguments are on the stack in reverse order
+  lua_Number arg_2 = lua_tonumber(L, -1);
+  lua_Number arg_1 = lua_tonumber(L, -2);
+
+  // First return value pushed to the stack
+  lua_pushnumber(L, arg_2 + arg_1);
+
+  // A second return value
+  lua_pushnumber(L, arg_2 * arg_1);
+
+  // Return number of Lua function return values
+  return 2;
+}
+
+int main() {
+
+  // Open Lua state
+  lua_State *L = luaL_newstate();
+  luaL_openlibs(L);
+
+  // Setup function before running the script
+  lua_pushcfunction(L, compute);
+  lua_setglobal(L, "compute");
+
+  // Load and run file
+  if (luaL_dofile(L, "./script.lua") == LUA_OK) {
+
+    // This will be printed after the Lua is done
+    std::print("Done\n");
+
+  } else {
+    // On error reading the file, an error message
+    // will be on top of the stack.
+    std::print("Error reading configuration file:\n");
+    luaL_error(L, "Error: %s\n", lua_tostring(L, -1));
+  }
+
+  lua_close(L);
+
+  return 0;
+}

src/cpp/example-cpp-to-lua/script.lua

@@ -0,0 +1,5 @@
+-- Example script file
+
+local first, second = compute(2, 10)
+print("Result 1 = " .. first)
+print("Result 2 = " .. second)

src/cpp/example-custom-module/CMakeLists.txt

@@ -0,0 +1,32 @@
+cmake_minimum_required(VERSION 3.18)
+
+# Setup a CMake project for C++
+project(
+  LuaExampleCppDataToLua
+  VERSION 1.0
+  LANGUAGES CXX)
+
+# Add an executable based on one source file
+add_executable(ProgramName main.cpp)
+
+# Let's use C++23
+target_compile_features(ProgramName PRIVATE cxx_std_23)
+
+# Try to find the Lua package on the system
+find_package(Lua REQUIRED)
+
+# If Lua was found and target is not set up
+if(Lua_FOUND AND NOT TARGET Lua::Lua)
+  add_library(Lua::Lua INTERFACE IMPORTED)
+  set_target_properties(
+    Lua::Lua
+    PROPERTIES
+      INTERFACE_INCLUDE_DIRECTORIES "${LUA_INCLUDE_DIR}"
+      INTERFACE_LINK_LIBRARIES "${LUA_LIBRARIES}"
+  )
+endif()
+
+# Link Lua library to the executable
+target_link_libraries(
+  ProgramName
+  PRIVATE Lua::Lua)

src/cpp/example-custom-module/README.md

@@ -0,0 +1,17 @@
+# Userdata
+
+Example on how to get data from C++ to Lua.
+
+## Setup
+
+With the folder containing this file as current working directory, run the following command to create the CMake build configuration.
+
+```shell
+cmake -B build
+```
+
+The next command will build the executable into the folder `build`.
+
+```shell
+cmake --build build
+```