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

Ivorforce · 2025-05-02T09:53:54Z

This article is meant as a jump-off point for new godot-cpp users to understand how to build their GDExtension, and how to work with the binaries.
Since much of the functionality is covered elsewhere, it is mainly some simple commands and explanations, and otherwise a hub of links for people to find the appropriate other spots.

Tagging @enetheru, I can't request review from you through GitHub but I'd like to hear your opinion as well :)

enetheru · 2025-05-02T13:21:45Z

you asked.. so..
I was confused as to the point of the document, it wasnt clear intially what the purpose of separating out the build system was to me and then the content of the document.
I spent a few minutes looking at the existing latest documents and it makes even less sense why buildsystem should be singled out.

Starting with what we have already:

about godot-cpp - details a little about the structure and differences of godot-cpp vs modules
getting started - short tutorial / quickstart
adding documentation. - more tutorial now specific to docs.

I would think that the buildsystem information belongs in the about section, and should not include any instruction, just links to the getting-started, or to a more detailed document.

and as a side note, the adding documentaion should be rolled into getting started, or at least have a chapter in there, and be stripped of any duplicate information like the bbcode tags, instead link to the appropriate section for that.

If there were going to be additional documents, they should be highly specific to a singular topic that can either be referenced from the about or quick start.

enetheru · 2025-05-02T13:24:00Z

Is there some planning issue or document I could review to get my bearings on requests for review?

Ivorforce · 2025-05-02T13:45:35Z

you asked.. so.. I was confused as to the point of the document, it wasnt clear intially what the purpose of separating out the build system was to me and then the content of the document. I spent a few minutes looking at the existing latest documents and it makes even less sense why buildsystem should be singled out.

Starting with what we have already:

about godot-cpp - details a little about the structure and differences of godot-cpp vs modules

getting started - short tutorial / quickstart

adding documentation. - more tutorial now specific to docs.

I would think that the buildsystem information belongs in the about section, and should not include any instruction, just links to the getting-started, or to a more detailed document.

and as a side note, the adding documentaion should be rolled into getting started, or at least have a chapter in there, and be stripped of any duplicate information like the bbcode tags, instead link to the appropriate section for that.

If there were going to be additional documents, they should be highly specific to a singular topic that can either be referenced from the about or quick start.

Thanks for offering your opinion, I was hoping for something opinionated so I'm glad I asked 😄

This is how I envision the godot-cpp section to look like once everything is done:

About godot-cpp: Explains what godot-cpp is, and how it connects to Godot. It does not contain any technical information.
Getting started: What users click on initially when they make their very first godot-cpp project. It gets you up to speed as fast as possible, and does not explain any detailed concepts.
Build system: Contains more detailed information about how to build godot-cpp. Since most of this is explained elsewhere, it ends up being mostly a link hub and collection of useful commands.
... other topics: More specialized articles on commonly needed features, e.g. how to bind methods, how to receive notifications, etc.

Perhaps you'd be interested in making a counter-proposal to this one? ^
This would definitely be interesting to discuss in the next GDExtension meeting as well!

paddy-exe · 2025-05-02T14:04:36Z

I would think that the buildsystem information belongs in the about section, and should not include any instruction, just links to the getting-started, or to a more detailed document.

That makes sense. I agree on that.

and as a side note, the adding documentaion should be rolled into getting started, or at least have a chapter in there, and be stripped of any duplicate information like the bbcode tags, instead link to the appropriate section for that.

Hard disagree on that. Getting started would mean getting some first result like the typical print("Hello World") in every programming language. It should not contain more detailed information. We have to be careful not to add to much information in there. Also, the BBCode tags are purposely integrated since not every BBCode tag from the original page is supported. I tried them out.

If there were going to be additional documents, they should be highly specific to a singular topic that can either be referenced from the about or quick start.

That would be a good topic to discuss at the next meeting.

enetheru · 2025-05-02T14:34:01Z

Hard disagree on that. Getting started would mean getting some first result like the typical print("Hello World") in every programming language. It should not contain more detailed information. We have to be careful not to add to much information in there. Also, the BBCode tags are purposely integrated since not every BBCode tag from the original page is supported. I tried them out.

Well perhaps I was overzealous on the topic, even if the documentation has its own page, it should have a mention in the getting started, even if its a link at the bottom section under next-steps.

tutorials/scripting/cpp/build_system.rst

enetheru · 2025-05-02T14:46:36Z

tutorials/scripting/cpp/build_system.rst

+
+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.


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

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!

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.

I changed the phrasing to also mention cross platform toolchains.

enetheru · 2025-05-02T14:50:55Z

tutorials/scripting/cpp/build_system.rst

+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.
+
+To make your GDExtension as widely compatible as possible, we recommend setting up Continuous Integration (CI) to build


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

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.

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.

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.

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?

@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

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

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.

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?

Yes this is how I would see it👍🏻

AThousandShips · 2025-05-27T09:36:25Z

Is there a reason this is only for 4.5 and that this does not apply to 4.4 and earlier?

Ivorforce · 2025-05-27T09:46:40Z

Is there a reason this is only for 4.5 and that this does not apply to 4.4 and earlier?

Yes, the restructuring (#10631) of these sections was only merged for 4.5, so it's somewhat difficult to merge back changes.
Contents wise, it is absolutely applicable to 4.4 backwards.

dsnopek · 2025-08-21T12:36:13Z

tutorials/scripting/cpp/build_system.rst

+
+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.


This doesn't need to be addressed here, but I personally think we should eventually move the contents of the cmake.rst into the documentation in this repo, now that the new CMake configuration has stabilized

Actually, that's a good point. We want to avoid restructuring after adding this information, so I've opted to just go for it and include the file. This means we'll need another round of reviews, but it should be worth it.

Ok, thanks! I've added some review on the content that was copied in

dsnopek

Thanks, this looks great to me! (...and sorry for taking so long to take a look at it)

tutorials/scripting/cpp/build_system.rst