-
-
Notifications
You must be signed in to change notification settings - Fork 3.4k
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
base: master
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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. | ||||||
|
||||||
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. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is not correct, I would avoid making statements like this. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. TLDR: What you mean is Continuous deployment (CD) which is also integrated in the template. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 There was a problem hiding this comment. Choose a reason for hiding this commentThe 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? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What do you think of this?