Skip to content

Add "Build System" section to godot-cpp docs. #10919

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
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
77 changes: 77 additions & 0 deletions tutorials/scripting/cpp/build_system.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
.. _doc_godot_cpp_build_system:

Build System
============

`godot-cpp <https://github.com/godotengine/godot-cpp>`__ uses `SCons <https://scons.org>`__ as its 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
available in godot-cpp projects.
`godot-cpp <https://github.com/godotengine/godot-cpp>`__ uses `SCons <https://scons.org>`__ as its primary build system, modeled after :ref:`Godot's build system <doc_compiling_index>`. Alternatively CMake is supported as a secondary build system, but may lag behind in features.

What do you think of this?


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 individual documentations 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 in godot-cpp with
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. Generally, a single computer is only capable of building
for a few different platforms. For example, Windows users will be able to build for Windows, Android and Web,
but not for macOS or Linux.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not correct, I would avoid making statements like this.

Copy link
Member Author

@Ivorforce Ivorforce May 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is generally correct, at least if you ignore cross-compile tools. It's not the default to be able to cross compile to other platforms.
I think it's important to mention this, but I'm open to a different way of formulating this!

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I wanted to include this in a document I would predicate my statements on 'supported toolchains', which provides the easy path you want to mention, without being overly pessimistic on whats possible.


To make your GDExtension as widely compatible as possible, we recommend setting up Continuous Integration (CI) to build
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not really the point of CI though is it? the template project absolutely, but CI has a separate purpose unrelated to cross platform devlopment.

Suggested change
To make your GDExtension as widely compatible as possible, we recommend setting up Continuous Integration (CI) to build
To make your GDExtension as widely compatible as possible, we recommend using the godot-cpp-template project that uses CI to build for all platforms, or some such

Copy link
Member Author

@Ivorforce Ivorforce May 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose i'm biased since that's what I use it for: I don't use CI to verify correctness of my code, but it saves me a lot of headache trying to get builds for all the different platforms.

I don't know what else to recommend to users to get cross platform builds. I don't think recommending them cross-compile tools locally is a good idea since they won't be able to test them, and they can be inferior and more complicated than native tools.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The template is a good recommendation, it uses the github CI to achieve the result, but it's not the point of CI to perform cross platform development, so the recommendation is for the template, not for GIthub CI. I am pedantic with the meaning of words and the purpose of tools, as some users might be reading these things for the first time.

Copy link
Contributor

@paddy-exe paddy-exe May 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Continuous integration (CI in short) means that you are ensuring that newly integrated code doesn't break the project.
Continuous deployment (CD in short) means on the other hand to deliver software frequently through automated deployment (which is what @Ivorforce is meaning by this sentence). Both of these fall under the DevOps term.

TLDR: What you mean is Continuous deployment (CD) which is also integrated in the template.

Copy link
Member Author

@Ivorforce Ivorforce May 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I've seen it used, building the project is still CI, while CD is putting it into live production systems (or automatically offering it up for public download). Does this mismatch your understanding?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Ivorforce atlassian has an article describing the details, which fits my understanding: https://www.atlassian.com/continuous-delivery/principles/continuous-integration-vs-delivery-vs-deployment

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I'm seeing, building the project is part of CI?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can now see your interpretation of the words, so yes. I can see how you got there. it does work, from a certain point of view.

your GDExtension on many different platforms. The
`godot-cpp-template <https://github.com/godotengine/godot-cpp-template>`__ contains an example setup for a GitHub based
CI workflow.

CMake
-----

godot-cpp comes with a `CMakeLists.txt <https://github.com/godotengine/godot-cpp/blob/master/CMakeLists.txt>`__ file, to
support users that prefer using `CMake <https://cmake.org>`__ over `SCons <https://scons.org>`__ for their build system.

While actively supported, it is considered secondary to the SCons build system. This means it may lack some features
that are provided for users using SCons. It is documented in godot-cpp's
`cmake.rst <https://github.com/godotengine/godot-cpp/blob/master/doc/cmake.rst>`__ file.
1 change: 1 addition & 0 deletions tutorials/scripting/cpp/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,5 @@ the official C++ GDExtension bindings maintained as part of the Godot project.

about_godot_cpp
gdextension_cpp_example
build_system
gdextension_docs_system
Loading