mirror of
https://github.com/godotengine/godot-docs.git
synced 2025-12-31 17:49:03 +03:00
110 lines
4.3 KiB
ReStructuredText
110 lines
4.3 KiB
ReStructuredText
.. _doc_godot_cpp_build_system:
|
|
|
|
Main build system: Working with SCons
|
|
=====================================
|
|
|
|
.. seealso:: This page documents how to compile godot-cpp. If you're looking to compile Godot instead, see
|
|
:ref:`doc_introduction_to_the_buildsystem`.
|
|
|
|
`godot-cpp <https://github.com/godotengine/godot-cpp>`__ uses `SCons <https://scons.org>`__ as its main build system.
|
|
It is modeled after :ref:`Godot's build system <doc_compiling_index>`, and some commands available there are also
|
|
available in godot-cpp projects.
|
|
|
|
Getting started
|
|
---------------
|
|
|
|
To build a godot-cpp project, it is generally sufficient to install `SCons <https://scons.org>`__, and simply run it
|
|
in the project directory:
|
|
|
|
scons
|
|
|
|
You may want to learn about available options:
|
|
|
|
scons --help
|
|
|
|
To cleanly re-build your project, add ``--clean`` to your build command:
|
|
|
|
scons --clean
|
|
|
|
You can find more information about common SCons arguments and build patterns in the
|
|
`SCons User Guide <https://scons.org/doc/latest/HTML/scons-user/index.html>`__. Additional commands may be added by
|
|
individual godot-cpp projects, so consult their specific documentation for more information on those.
|
|
|
|
Configuring an IDE
|
|
------------------
|
|
|
|
Most IDEs can use a ``compile_commands.json`` file to understand a C++ project. You can generate it with godot-cpp using
|
|
the following command:
|
|
|
|
.. code-block:: shell
|
|
|
|
# Generate compile_commands.json while compiling.
|
|
scons compiledb=yes
|
|
|
|
# Generate compile_commands.json without compiling.
|
|
scons compiledb=yes compile_commands.json
|
|
|
|
For more information, please check out the :ref:`IDE configuration guides <doc_configuring_an_ide>`.
|
|
Although written for Godot engine contributors, they are largely applicable to godot-cpp projects as well.
|
|
|
|
Loading your GDExtension in Godot
|
|
---------------------------------
|
|
|
|
Godot loads GDExtensions by finding :ref:`.gdextension <doc_gdextension_file>` files in the project directory.
|
|
``.gdextension`` files are used to select and load a binary compatible with the current computer / operating system.
|
|
|
|
The `godot-cpp-template <https://github.com/godotengine/godot-cpp-template>`__, as well as the
|
|
:ref:`Getting Started section <doc_godot_cpp_getting_started>`, provide example ``.gdextension`` files for GDExtensions
|
|
that are widely compatible to many different systems.
|
|
|
|
Building for multiple platforms
|
|
-------------------------------
|
|
|
|
GDExtensions are expected to run on many different systems, each with separate binaries and build configurations.
|
|
If you are planning to publish your GDExtension, we recommend you provide binaries for all configurations that are
|
|
mentioned in the `godot-cpp-template <https://github.com/godotengine/godot-cpp-template>`__
|
|
`.gdextension file <https://github.com/godotengine/godot-cpp-template/blob/main/demo/bin/example.gdextension>`__.
|
|
|
|
There are two popular ways by which cross platform builds can be achieved:
|
|
|
|
- Cross-platform build tools
|
|
- Continuous Integration (CI)
|
|
|
|
`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"
|