Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
3 changes: 2 additions & 1 deletion tutorials/scripting/cpp/about_godot_cpp.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <doc_godot_cpp_build_system>`.
34 changes: 34 additions & 0 deletions tutorials/scripting/cpp/build_system/scons.rst
Original file line number Diff line number Diff line change
Expand Up @@ -73,3 +73,37 @@ There are two popular ways by which cross platform builds can be achieved:
`godot-cpp-template <https://github.com/godotengine/godot-cpp-template>`__ contains an
`example setup <https://github.com/godotengine/godot-cpp-template/tree/main/.github/workflows>`__
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 <doc_compiling_index>` 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=<platform> custom_api_file=<PATH_TO_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"
38 changes: 0 additions & 38 deletions tutorials/scripting/cpp/gdextension_cpp_example.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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=<PATH_TO_FILE>``
to the scons command below.

To generate and compile the bindings, use this command (replacing ``<platform>``
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=<platform> custom_api_file=<PATH_TO_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
------------------------

Expand Down
Loading