Require 'api_version' and allow extensions to provide a 'default_api_version'

Author: dsnopek

.github/workflows/ci-cmake.yml

@@ -7,6 +7,8 @@ env:
   GODOT_BASE_BRANCH: master
   # Used to select the version of Godot to run the tests with.
   GODOT_TEST_VERSION: master
+  # The Godot API version to build against.
+  DEFAULT_API_VERSION: "4.7"
   # Use UTF-8 on Linux.
   LANG: en_US.UTF-8
   LC_ALL: en_US.UTF-8
@@ -121,16 +123,15 @@ jobs:
 
       - name: Configure godot-cpp-test with template_debug
         run: >
-          cmake --log-level=VERBOSE -S . -B cmake-build ${{ env.config-flags }} ${{ matrix.config-flags }}
+          cmake --log-level=VERBOSE -S . -B cmake-build '-DGODOTCPP_API_VERSION=${{ env.DEFAULT_API_VERSION }}' ${{ env.config-flags }} ${{ matrix.config-flags }}
 
       - name: Build godot-cpp-test (template_debug)
         run: >
           cmake --build cmake-build --verbose  --target godot-cpp-test ${{ matrix.build-flags }}
 
       - name: Configure godot-cpp-test with template_release
         run: >
-          cmake --fresh --log-level=VERBOSE -S . -B cmake-build
-          -DGODOTCPP_TARGET=template_release ${{ env.config-flags }} ${{ matrix.config-flags }}
+          cmake --fresh --log-level=VERBOSE -S . -B cmake-build -DGODOTCPP_TARGET=template_release '-DGODOTCPP_API_VERSION=${{ env.DEFAULT_API_VERSION }}' ${{ env.config-flags }} ${{ matrix.config-flags }}
 
       - name: Build godot-cpp-test (template_release)
         run: >

.github/workflows/ci-scons.yml

@@ -5,6 +5,8 @@ on:
 env:
   # Only used for the cache key. Increment version to force clean build.
   GODOT_BASE_BRANCH: master
+  # The Godot API version used by jobs that don't target a specific one.
+  DEFAULT_API_VERSION: "4.7"
   # Use UTF-8 on Linux.
   LANG: en_US.UTF-8
   LC_ALL: en_US.UTF-8
@@ -29,7 +31,6 @@ jobs:
             artifact-name: godot-cpp-linux-glibc2.27-x86_64-release
             artifact-path: bin/libgodot-cpp.linux.template_release.x86_64.a
             run-tests: true
-            api-version: 4.7
             cache-name: linux-x86_64
 
           - name: 🐧 Linux (GCC) for Godot 4.6
@@ -149,23 +150,23 @@ jobs:
 
       - name: Generate godot-cpp sources only
         run: |
-          scons platform=${{ matrix.platform }} verbose=yes build_library=no ${{ matrix.flags }} ${{ matrix.api-version && format('api_version={0}', matrix.api-version) || '' }}
-          scons -c
+          scons platform=${{ matrix.platform }} verbose=yes build_library=no ${{ matrix.flags }} api_version=${{ matrix.api-version || env.DEFAULT_API_VERSION }}
+          scons -c platform=${{ matrix.platform }} ${{ matrix.flags }} api_version=${{ matrix.api-version || env.DEFAULT_API_VERSION }}
 
       - name: Build godot-cpp (debug)
         run: |
-          scons platform=${{ matrix.platform }} verbose=yes target=template_debug ${{ matrix.flags }} ${{ matrix.api-version && format('api_version={0}', matrix.api-version) || '' }}
+          scons platform=${{ matrix.platform }} verbose=yes target=template_debug ${{ matrix.flags }} api_version=${{ matrix.api-version || env.DEFAULT_API_VERSION }}
 
 
       - name: Build test without rebuilding godot-cpp (debug)
         run: |
           cd test
-          scons platform=${{ matrix.platform }} verbose=yes build_library=no target=template_debug ${{ matrix.flags }} ${{ matrix.api-version && format('api_version={0}', matrix.api-version) || '' }}
+          scons platform=${{ matrix.platform }} verbose=yes build_library=no target=template_debug ${{ matrix.flags }} api_version=${{ matrix.api-version || env.DEFAULT_API_VERSION }}
 
       - name: Build test and godot-cpp (release)
         run: |
           cd test
-          scons platform=${{ matrix.platform }} verbose=yes target=template_release ${{ matrix.flags }} ${{ matrix.api-version && format('api_version={0}', matrix.api-version) || '' }}
+          scons platform=${{ matrix.platform }} verbose=yes target=template_release ${{ matrix.flags }} api_version=${{ matrix.api-version || env.DEFAULT_API_VERSION }}
 
       - name: Save Godot build cache
         uses: ./.github/actions/godot-cache-save

.github/workflows/runner.yml

@@ -38,7 +38,7 @@ jobs:
               - '**/*.h'
               - '**/*.inc'
               - 'test/build_profile.json'
-              - 'gdextension/extension_api.json'
+              - 'gdextension/extension_api-*.json'
             scons:
               - '**/SConstruct'
               - '**/SCsub'

.pre-commit-config.yaml

@@ -3,7 +3,7 @@ default_language_version:
 
 exclude: |
   (?x)^(
-    gdextension/extension_api\.json|
+    gdextension/extension_api-[0-9]+-[0-9]+\.json|
     gdextension/gdextension_interface\.json
   )$
 

CMakeLists.txt

@@ -61,6 +61,11 @@ project(
     LANGUAGES CXX
 )
 
+# Set the default API version for the test project.
+if(GODOTCPP_ENABLE_TESTING)
+    set(GODOTCPP_DEFAULT_API_VERSION "4.7")
+endif()
+
 compiler_detection()
 godotcpp_generate()
 

Makefile

@@ -1,6 +1,7 @@
 TARGET = template_debug
+API_VERSION = 4.7
 
-BASE = scons target=$(TARGET) $(EXTRA_ARGS)
+BASE = scons target=$(TARGET) api_version=$(API_VERSION) $(EXTRA_ARGS)
 LINUX = $(BASE) platform=linux
 WINDOWS = $(BASE) platform=windows
 MACOS = $(BASE) platform=macos
@@ -11,7 +12,7 @@ usage:
 	@echo -e "Specify one of the available targets:\n"
         # https://stackoverflow.com/a/26339924
 	@LC_ALL=C $(MAKE) -pRrq -f $(lastword $(MAKEFILE_LIST)) : 2>/dev/null | awk -v RS= -F: '/(^|\n)# Files(\n|$$)/,/(^|\n)# Finished Make data base/ {if ($$1 !~ "^[#.]") {print $$1}}' | sort | grep -E -v -e '^[^[:alnum:]]' -e '^$@$$'
-	@echo -e "\nDefine the SCons target with TARGET, and pass extra SCons arguments with EXTRA_ARGS."
+	@echo -e "\nDefine the SCons target with TARGET, the Godot API version to target with API_VERSION, and pass extra SCons arguments with EXTRA_ARGS."
 
 
 linux:

README.md

@@ -48,8 +48,15 @@ godot --dump-extension-api
 scons custom_api_file=extension_api.json
 ```
 
-If you don't provide `api_version` or `custom_api_file`, then, by default, godot-cpp will
-target the latest stable Godot version that it's aware of.
+Extension authors can provide a default target API version by passing it to godot-cpp's
+`SConstruct`, for example:
+
+```python
+env = SConscript("../SConstruct", {"default_api_version": "4.7"})
+```
+
+This is highly recommended! It allows the extension author to ensure that their extension
+is built with a version that provides all the necessary features by default.
 
 ## Contributing
 

SConstruct

@@ -17,6 +17,12 @@ except Exception:
     # We apply platform specific toolchains via our custom tools.
     env = Environment(tools=["default"], PLATFORM="")
 
+try:
+    Import("default_api_version")
+    env["default_api_version"] = default_api_version
+except Exception:
+    pass
+
 env.PrependENVPath("PATH", os.getenv("PATH"))
 
 # Custom options and profile flags.

cmake/godotcpp.cmake

@@ -264,18 +264,20 @@ function(godotcpp_generate)
     math(EXPR BITS "${CMAKE_SIZEOF_VOID_P} * 8") # CMAKE_SIZEOF_VOID_P refers to target architecture.
 
     # API json File
-    set(GODOTCPP_LATEST_API_VERSION "4.7")
-    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")
+    if(GODOTCPP_CUSTOM_API_FILE) # User-defined override.
+        set(GODOTCPP_GDEXTENSION_API_FILE "${GODOTCPP_CUSTOM_API_FILE}")
     else()
+        if(GODOTCPP_API_VERSION STREQUAL "")
+            set(GODOTCPP_API_VERSION "${GODOTCPP_DEFAULT_API_VERSION}")
+        endif()
+        if(GODOTCPP_API_VERSION STREQUAL "")
+            message(FATAL_ERROR "'GODOTCPP_API_VERSION' must be provided")
+        endif()
         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()
 
     # Interface json file.
     set(GODOTCPP_GDEXTENSION_INTERFACE_FILE "${GODOTCPP_GDEXTENSION_DIR}/gdextension_interface.json")