Merge pull request #1897 from dsnopek/select-api-version

Add `api_version` build option to select the API JSON file

.github/workflows/ci-scons.yml

@@ -5,8 +5,6 @@ on:
 env:
   # Only used for the cache key. Increment version to force clean build.
   GODOT_BASE_BRANCH: master
-  # Used to select the version of Godot to run the tests with.
-  GODOT_TEST_VERSION: master
   # Use UTF-8 on Linux.
   LANG: en_US.UTF-8
   LC_ALL: en_US.UTF-8
@@ -33,6 +31,16 @@ jobs:
             run-tests: true
             cache-name: linux-x86_64
 
+          - name: 🐧 Linux (GCC) for Godot 4.5
+            os: ubuntu-22.04
+            platform: linux
+            artifact-name: godot-cpp-linux-glibc2.27-x86_64-release-godot45
+            artifact-path: bin/libgodot-cpp.linux.template_release.x86_64.a
+            run-tests: true
+            api-version: 4.5
+            godot-test-versions: "4.5-stable"
+            cache-name: linux-x86_64-godot45
+
           - name: 🏁 Windows (x86_64, MSVC)
             os: windows-2022
             platform: windows
@@ -110,22 +118,23 @@ jobs:
 
       - name: Generate godot-cpp sources only
         run: |
-          scons platform=${{ matrix.platform }} verbose=yes build_library=no ${{ matrix.flags }}
+          scons platform=${{ matrix.platform }} verbose=yes build_library=no ${{ matrix.flags }} ${{ matrix.api-version && format('api_version={0}', matrix.api-version) || '' }}
           scons -c
 
       - name: Build godot-cpp (debug)
         run: |
-          scons platform=${{ matrix.platform }} verbose=yes target=template_debug ${{ matrix.flags }}
+          scons platform=${{ matrix.platform }} verbose=yes target=template_debug ${{ matrix.flags }} ${{ matrix.api-version && format('api_version={0}', matrix.api-version) || '' }}
+
 
       - name: Build test without rebuilding godot-cpp (debug)
         run: |
           cd test
-          scons platform=${{ matrix.platform }} verbose=yes target=template_debug ${{ matrix.flags }} build_library=no
+          scons platform=${{ matrix.platform }} verbose=yes build_library=no target=template_debug ${{ matrix.flags }} ${{ matrix.api-version && format('api_version={0}', matrix.api-version) || '' }}
 
       - name: Build test and godot-cpp (release)
         run: |
           cd test
-          scons platform=${{ matrix.platform }} verbose=yes target=template_release ${{ matrix.flags }}
+          scons platform=${{ matrix.platform }} verbose=yes target=template_release ${{ matrix.flags }} ${{ matrix.api-version && format('api_version={0}', matrix.api-version) || '' }}
 
       - name: Save Godot build cache
         uses: ./.github/actions/godot-cache-save
@@ -135,7 +144,7 @@ jobs:
 
       - name: Download latest Godot artifacts
         uses: dsnopek/action-download-artifact@1322f74e2dac9feed2ee76a32d9ae1ca3b4cf4e9
-        if: matrix.run-tests && env.GODOT_TEST_VERSION == 'master'
+        if: matrix.run-tests
         with:
           repo: godotengine/godot
           branch: master
@@ -149,27 +158,38 @@ jobs:
           path: godot-artifacts
 
       - name: Prepare Godot artifacts for testing
-        if: matrix.run-tests && env.GODOT_TEST_VERSION == 'master'
+        if: matrix.run-tests
         run: |
-          chmod +x ./godot-artifacts/godot.linuxbsd.editor.x86_64.mono
-          echo "GODOT=$(pwd)/godot-artifacts/godot.linuxbsd.editor.x86_64.mono" >> $GITHUB_ENV
+          mkdir ./godot-builds
+          mv ./godot-artifacts/godot.linuxbsd.editor.x86_64.mono ./godot-builds/godot-master
+          mv ./godot-artifacts/GodotSharp ./godot-builds/
+          chmod +x ./godot-builds/godot-master
 
-      - name: Download requested Godot version for testing
-        if: matrix.run-tests && env.GODOT_TEST_VERSION != 'master'
+      - name: Download supported Godot versions for testing
+        if: matrix.run-tests && matrix.godot-test-versions
         run: |
-          wget "https://github.com/godotengine/godot-builds/releases/download/${GODOT_TEST_VERSION}/Godot_v${GODOT_TEST_VERSION}_linux.x86_64.zip" -O Godot.zip
-          unzip -a Godot.zip
-          chmod +x "Godot_v${GODOT_TEST_VERSION}_linux.x86_64"
-          echo "GODOT=$(pwd)/Godot_v${GODOT_TEST_VERSION}_linux.x86_64" >> $GITHUB_ENV
+          for version in ${{ matrix.godot-test-versions }}; do
+            wget "https://github.com/godotengine/godot-builds/releases/download/${version}/Godot_v${version}_linux.x86_64.zip" -O Godot.zip
+            unzip -a Godot.zip
+            mv "Godot_v${version}_linux.x86_64" "./godot-builds/godot-${version}"
+            chmod +x "./godot-builds/godot-${version}"
+            rm Godot.zip
+          done
 
       - name: Run tests
         if: matrix.run-tests
         run: |
-          $GODOT --headless --version
+          GODOT_BUILDS="$(pwd)/godot-builds"
           cd test
-          # Need to run the editor so .godot is generated... but it crashes! Ignore that :-)
-          (cd project && (timeout 30 $GODOT --import --headless >/dev/null 2>&1 || true))
-          ./run-tests.sh
+          for version in ${{ matrix.godot-test-versions }} master; do
+            rm -rf ./project/.godot
+            export GODOT="${GODOT_BUILDS}/godot-${version}"
+            $GODOT --headless --version
+            # Need to run the editor so .godot is generated... but it crashes! Ignore that :-)
+            (cd project && (timeout 30 $GODOT --import --headless >/dev/null 2>&1 || true))
+            ./run-tests.sh
+          done
+          cd ..
 
       - name: Upload artifact
         uses: actions/upload-artifact@v4

cmake/godotcpp.cmake

@@ -114,6 +114,12 @@ function(godotcpp_options)
     set_property(CACHE GODOTCPP_TARGET PROPERTY STRINGS "template_debug;template_release;editor")
 
     # Input from user for GDExtension interface header and the API JSON file
+    set(GODOTCPP_API_VERSION
+        ""
+        CACHE STRING
+        "The Godot API version to target (ex \"4.5\") using one of the included API JSON files"
+    )
+    set_property(CACHE GODOTCPP_API_VERSION PROPERTY STRINGS ";4.5;4.6")
     set(GODOTCPP_GDEXTENSION_DIR
         "gdextension"
         CACHE PATH
@@ -122,7 +128,7 @@ function(godotcpp_options)
     set(GODOTCPP_CUSTOM_API_FILE
         ""
         CACHE FILEPATH
-        "Path to a custom GDExtension API JSON file (takes precedence over `GODOTCPP_GDEXTENSION_DIR`) ( /path/to/custom_api_file )"
+        "Path to a custom GDExtension API JSON file (takes precedence over `GODOTCPP_GDEXTENSION_DIR` and `GODOTCPP_API_VERSION`) ( /path/to/custom_api_file )"
     )
 
     #TODO generate_bindings
@@ -244,7 +250,15 @@ function(godotcpp_generate)
     math(EXPR BITS "${CMAKE_SIZEOF_VOID_P} * 8") # CMAKE_SIZEOF_VOID_P refers to target architecture.
 
     # API json File
-    set(GODOTCPP_GDEXTENSION_API_FILE "${GODOTCPP_GDEXTENSION_DIR}/extension_api.json")
+    set(GODOTCPP_LATEST_API_VERSION "4.6")
+    if(GODOTCPP_API_VERSION STREQUAL "" OR GODOTCPP_API_VERSION STREQUAL GODOTCPP_LATEST_API_VERSION)
+        set(GODOTCPP_GDEXTENSION_API_FILE "${GODOTCPP_GDEXTENSION_DIR}/extension_api.json")
+    else()
+        string(REPLACE "." "-" GODOTCPP_API_VERSION_DASHED "${GODOTCPP_API_VERSION}")
+        set(GODOTCPP_GDEXTENSION_API_FILE
+            "${GODOTCPP_GDEXTENSION_DIR}/extension_api-${GODOTCPP_API_VERSION_DASHED}.json"
+        )
+    endif()
     if(GODOTCPP_CUSTOM_API_FILE) # User-defined override.
         set(GODOTCPP_GDEXTENSION_API_FILE "${GODOTCPP_CUSTOM_API_FILE}")
     endif()

tools/godotcpp.py

@@ -176,6 +176,8 @@ def scons_generate_bindings(target, source, env):
     return None
 
 
+supported_api_versions = ["4.5", "4.6"]
+
 platforms = ["linux", "macos", "windows", "android", "ios", "web"]
 
 # CPU architecture options.
@@ -259,6 +261,14 @@ def options(opts, env):
             allowed_values=("editor", "template_release", "template_debug"),
         )
     )
+    opts.Add(
+        EnumVariable(
+            key="api_version",
+            help='The Godot API version to target (ex "4.5") using one of the included API JSON files',
+            default=env.get("api_version", None),
+            allowed_values=supported_api_versions,
+        )
+    )
     opts.Add(
         PathVariable(
             key="gdextension_dir",
@@ -270,7 +280,7 @@ def options(opts, env):
     opts.Add(
         PathVariable(
             key="custom_api_file",
-            help="Path to a custom GDExtension API JSON file (takes precedence over `gdextension_dir`)",
+            help="Path to a custom GDExtension API JSON file (takes precedence over `gdextension_dir` and `api_version`)",
             default=env.get("custom_api_file", None),
             validator=validate_file,
         )
@@ -538,11 +548,22 @@ def generate(env):
     env.AddMethod(_godot_cpp, "GodotCPP")
 
 
+def _get_api_file(extension_dir, api_version):
+    if api_version is None or api_version == supported_api_versions[-1]:
+        return os.path.join(extension_dir, "extension_api.json")
+
+    filename = "extension_api-%s.json" % api_version.replace(".", "-")
+    path = os.path.join(extension_dir, filename)
+    if not os.path.exists(path):
+        raise UserError("Cannot find `%s` file for api_version %s" % (filename, api_version))
+
+    return path
+
+
 def _godot_cpp(env):
     extension_dir = normalize_path(env.get("gdextension_dir", default=env.Dir("gdextension").srcnode().abspath), env)
-    api_file = normalize_path(
-        env.get("custom_api_file", default=os.path.join(extension_dir, "extension_api.json")), env
-    )
+    default_api_file = _get_api_file(extension_dir, env.get("api_version", None))
+    api_file = normalize_path(env.get("custom_api_file", default=default_api_file), env)
 
     bindings = env.GodotCPPBindings(
         env.Dir("."),