Browse Source

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.

Lukas Tenbrink 1 month ago
parent
commit
88604e597b

+ 2 - 1
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 <doc_godot_cpp_build_system>`.

+ 34 - 0
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 <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"

+ 0 - 38
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=<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
 ------------------------