Move godot-cpp custom bindings information to the 'build system' instructions from the intro doc, because most people won't need it for their first project.

This commit is contained in:
Lukas Tenbrink
2025-09-12 12:31:22 +02:00
parent 6ebd201367
commit 88604e597b
3 changed files with 36 additions and 39 deletions

View File

@@ -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>`.

View File

@@ -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"

View File

@@ -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
------------------------