diff --git a/tutorials/scripting/cpp/about_godot_cpp.rst b/tutorials/scripting/cpp/about_godot_cpp.rst index 3a512c9e5c2..c8d0db17651 100644 --- a/tutorials/scripting/cpp/about_godot_cpp.rst +++ b/tutorials/scripting/cpp/about_godot_cpp.rst @@ -85,4 +85,5 @@ for details. Generally speaking, if you build a custom version of Godot, you should generate an ``extension_api.json`` from it for your GDExtensions, because it may have some differences -from official Godot builds. +from official Godot builds. You can learn more about the process of using custom +``extension_api.json`` files in the :ref:`build system section `. diff --git a/tutorials/scripting/cpp/build_system/scons.rst b/tutorials/scripting/cpp/build_system/scons.rst index b1e3d0d739d..cde436da27d 100644 --- a/tutorials/scripting/cpp/build_system/scons.rst +++ b/tutorials/scripting/cpp/build_system/scons.rst @@ -73,3 +73,37 @@ There are two popular ways by which cross platform builds can be achieved: `godot-cpp-template `__ contains an `example setup `__ for a GitHub based CI workflow. + +Using a custom API file +----------------------- + +Every branch of godot-cpp comes with an API file (``extension_api.json``) appropriate for +the respective Godot version (e.g. the ``4.3`` branch comes with the API file compatible +with Godot version ``4.3`` and later). + +However, you may want to use a custom ``extension_api.json``, for example: + +* If you want to use the latest APIs from Godot ``master``. +* If you :ref:`build Godot yourself ` with different options than the official builds (e.g. ``disable_3d=yes`` or ``precision=double``). +* If you want to use APIs exposed by custom modules. + +To use a custom API file, you first have to generate it from the appropriate Godot +executable: + +.. code-block:: shell + + godot --dump-extension-api + +The resulting ``extension_api.json`` file will be created in the executable's +directory. To use it, you can add ``custom_api_file`` to your build command: + +.. code-block:: shell + + scons platform= custom_api_file= + +Alternatively, you can add it as the default API file to your project by adding +the following line to your SConstruct file: + +.. code-block:: python + + localEnv["custom_api_file"] = "extension_api.json" diff --git a/tutorials/scripting/cpp/gdextension_cpp_example.rst b/tutorials/scripting/cpp/gdextension_cpp_example.rst index b5f9b2c9c8e..31bca9a1f3e 100644 --- a/tutorials/scripting/cpp/gdextension_cpp_example.rst +++ b/tutorials/scripting/cpp/gdextension_cpp_example.rst @@ -97,44 +97,6 @@ following commands: This will initialize the repository in your project folder. -Building the C++ bindings -------------------------- - -Now that we've downloaded our prerequisites, it is time to build the C++ -bindings. - -The repository contains a copy of the metadata for the current Godot release, -but if you need to build these bindings for a newer version of Godot, call -the Godot executable: - -.. code-block:: none - - godot --dump-extension-api - -The resulting ``extension_api.json`` file will be created in the executable's -directory. Copy it to the project folder and add ``custom_api_file=`` -to the scons command below. - -To generate and compile the bindings, use this command (replacing ```` -with ``windows``, ``linux`` or ``macos`` depending on your OS): - -The build process automatically detects the number of CPU threads to use for -parallel builds. To specify a number of CPU threads to use, add ``-jN`` at the -end of the SCons command line where ``N`` is the number of CPU threads to use. - -.. code-block:: none - - cd godot-cpp - scons platform= custom_api_file= - cd .. - -This step will take a while. When it is completed, you should have static -libraries that can be compiled into your project stored in ``godot-cpp/bin/``. - -.. note:: - - You may need to add ``bits=64`` to the command on Windows or Linux. - Creating a simple plugin ------------------------