Skip to content

Require 'api_version' and allow extensions to provide a default #2034

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dsnopek wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Require 'api_version' and allow extensions to provide a default #2034

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .github/workflows/ci-cmake.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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: >
Expand Down
13 changes: 7 additions & 6 deletions .github/workflows/ci-scons.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Comment thread
Ivorforce marked this conversation as resolved.
# Use UTF-8 on Linux.
LANG: en_US.UTF-8
LC_ALL: en_US.UTF-8
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/runner.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ jobs:
- '**/*.h'
- '**/*.inc'
- 'test/build_profile.json'
- 'gdextension/extension_api.json'
- 'gdextension/extension_api-*.json'
scons:
- '**/SConstruct'
- '**/SCsub'
Expand Down
2 changes: 1 addition & 1 deletion .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
)$

Expand Down
7 changes: 7 additions & 0 deletions CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,13 @@ project(
LANGUAGES CXX
)

# Set the default API version for the test project.
# We're only setting this here because the test project is built weird;
# in a normal project, it would be set before including this CMakeLists.txt.
if(GODOTCPP_ENABLE_TESTING)
set(GODOTCPP_DEFAULT_API_VERSION "4.7")
endif()

@enetheru enetheru Jul 30, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

whatever the godot-cpp is compiled with, so will the test. so this isn't necessary. setting it in the github yaml takes care of both.

@dsnopek dsnopek Jul 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, the idea is that the test project is an extension, and the imaginary author of that extension wants to set the default API version to "4.7". If you look in test/SConstruct we're setting the default to "4.7" there as well.

Similarly, I would love for the code referenced above to be in test/CMakeLists.txt, but I couldn't make that work because the test project is built weird, and I had to put it in the top-level CMakeLists.txt. If you know a way to put the default in test/CMakeLists.txt that would be awesome!

In a real project, I think the extension developer can set GODOTCPP_DEFAULT_API_VERSION before they include godot-cpp's CMakeLists.txt and it should work?

This doesn't really relate to what we're doing on CI (where we may test multiple different versions). This is attempting to set the default used for tests when the user doesn't explicitly set an API version, including when building locally

@dsnopek dsnopek Jul 30, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just added an additional comment by this code to explain that this only done this way because the test project is built weird :-)

@enetheru enetheru Aug 1, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For cmake the integration testing is just another target in the godot-cpp project.

compiler_detection()
godotcpp_generate()

Expand Down
5 changes: 3 additions & 2 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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:
Expand Down
11 changes: 9 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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("godot-cpp/SConstruct", {"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

Expand Down
6 changes: 6 additions & 0 deletions SConstruct
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,12 @@ except Exception:
# We apply platform specific toolchains via our custom tools.
env = Environment(tools=["default"], PLATFORM="")

try:
Import("api_version")
env["api_version"] = api_version
except Exception:
pass

env.PrependENVPath("PATH", os.getenv("PATH"))

# Custom options and profile flags.
Expand Down
14 changes: 8 additions & 6 deletions cmake/godotcpp.cmake
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
0 gdextension/extension_api.json → gdextension/extension_api-4-7.json
View file
Open in desktop
File renamed without changes.
2 changes: 1 addition & 1 deletion misc/scripts/check_get_file_list.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
from binding_generator import _generate_bindings, _get_file_list
from build_profile import generate_trimmed_api

api_filepath = "gdextension/extension_api.json"
api_filepath = "gdextension/extension_api-4-7.json"
interface_filepath = "gdextension/gdextension_interface.json"
bits = "64"
precision = "single"
Expand Down
2 changes: 1 addition & 1 deletion test/SConstruct
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
#!/usr/bin/env python

env = SConscript("../SConstruct")
env = SConscript("../SConstruct", {"api_version": "4.7"})

# For the reference:
# - CCFLAGS are compilation flags shared between C and C++
Expand Down
16 changes: 9 additions & 7 deletions tools/godotcpp.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,9 +176,6 @@ def scons_generate_bindings(target, source, env):

supported_api_versions = ["4.3", "4.4", "4.5", "4.6", "4.7"]

# We default to the latest stable Godot version.
default_api_version = "4.7"

platforms = ["linux", "macos", "windows", "android", "ios", "web"]

# CPU architecture options.
Expand Down Expand Up @@ -550,8 +547,10 @@ def generate(env):


def _get_api_file(extension_dir, api_version):
if api_version is None or api_version == default_api_version:
return os.path.join(extension_dir, "extension_api.json")
if api_version is None:
raise UserError("'api_version' must be provided")
if api_version not in supported_api_versions:
raise UserError("Unsupported 'api_version': %s" % api_version)

filename = "extension_api-%s.json" % api_version.replace(".", "-")
path = os.path.join(extension_dir, filename)
Expand All @@ -563,8 +562,11 @@ def _get_api_file(extension_dir, api_version):

def _godot_cpp(env):
extension_dir = normalize_path(env.get("gdextension_dir", default=env.Dir("gdextension").srcnode().abspath), 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)

api_file = env.get("custom_api_file", None)
if api_file is None:
api_file = _get_api_file(extension_dir, env.get("api_version", None))
api_file = normalize_path(api_file, env)

bindings = env.GodotCPPBindings(
env.Dir("."),
Expand Down
Loading