Improve introduction into buildsystem

contributing/development/compiling/index.rst

@@ -1,12 +1,46 @@
 Building from source
 ====================
 
+.. highlight:: shell
+
+Godot prides itself on being very easy to build, by C++ projects' standards.
+:ref:`Godot uses the SCons build system <doc_faq_why_scons>`, and after the initial
+setup compiling the engine for your current platform should be as easy as running::
+
+    scons
+
+But you will probably need to use at least some of the available options to configure
+the build to match your specific needs, be it a custom engine fork, a lightweight build
+stripped of extra modules, or an executable targetting engine development.
+
+The articles below should help you navigate configuration options available, as well as
+prerequisites required to compile Godot exactly the way you need.
+
+Basics of building Godot
+------------------------
+
+Let's start with basics, and learn how to get Godot's source code, and then which options
+to use to compile it regardless of your target platform.
+
 .. toctree::
    :maxdepth: 1
    :name: toc-devel-compiling
 
    getting_source
    introduction_to_the_buildsystem
+
+Building for target platforms
+-----------------------------
+
+Below you can find instructions for compiling the engine for your specific target platform.
+Note that Godot supports cross-compilation, which means you can compile it for a target platform
+that doesn't match your current platform (say, target Linux while being on Windows). The guides
+will try their best to cover all possible situations.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-devel-compiling-platforms
+
    compiling_for_windows
    compiling_for_linuxbsd
    compiling_for_macos
@@ -15,6 +49,21 @@ Building from source
    cross-compiling_for_ios_on_linux
    compiling_for_uwp
    compiling_for_web
+
+Other compilation targets and options
+-------------------------------------
+
+Some additional universal compilation options require further setup. Namely, while Godot
+does have C#/.NET support as a part of its main codebase, it does not get compiled by
+default to reduce the executable size for users who don't need C# for their projects.
+
+Articles below explain how to configure the buildsystem for cases like this, and also
+cover some optimization techniques.
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-devel-compiling-options
+
    compiling_with_dotnet
-   optimizing_for_size
    compiling_with_script_encryption_key
+   optimizing_for_size

contributing/development/compiling/introduction_to_the_buildsystem.rst

@@ -6,11 +6,26 @@ Introduction to the buildsystem
 .. highlight:: shell
 
 
-Setup
------
+Godot is a primarily C++ project and it :ref:`uses the SCons build system. <doc_faq_why_scons>`
+We love SCons for how maintainable and easy to set up it makes our buildsystem. And thanks to
+that compiling Godot from source can be as simple as running::
 
-:ref:`Godot uses the SCons build system. <doc_faq_why_scons>`
-Please refer to the documentation for:
+    scons
+
+This produces an *export template* for your current platform, operating system, and architecture.
+An export template is a build of the engine that is used for running exported projects. To build
+the *editor* instead you can run the following command::
+
+    scons target=editor
+
+If you plan to debug or develop the engine, then you might want to add another option to the command::
+
+    scons dev_build=yes
+    scons target=editor dev_build=yes
+
+Following sections in the article will explain these and other universal options in more detail. But
+before you can compile Godot, you need to install a few prerequisites. Please refer to the platform
+documentation to learn more:
 
 - :ref:`doc_compiling_for_android`
 - :ref:`doc_compiling_for_ios`
@@ -20,6 +35,22 @@ Please refer to the documentation for:
 - :ref:`doc_compiling_for_web`
 - :ref:`doc_compiling_for_windows`
 
+These articles cover in great detail both how to setup your environment to compile Godot on a specific
+platform, and how to compile for that platform. Please feel free to go back and forth between them and
+this article to reference platform-specific and universal configuration options.
+
+Using multi-threading
+---------------------
+
+The build process may take a while, depending on how powerful your system is. By default, Godot's
+SCons setup is configured to use all CPU threads but one (to keep the system responsive during
+compilation). If you want to adjust how many CPU threads SCons will use, use the ``-j <threads>``
+parameter to specify how many threads will be used for the build.
+
+Example for using 4 threads::
+
+    scons -j4
+
 Platform selection
 ------------------
 
@@ -53,18 +84,6 @@ To build for a platform (for example, ``linuxbsd``), run with the ``platform=``
 
     scons platform=linuxbsd
 
-This will start the build process, which will take a while. By default, Godot's
-SCons setup is configured to use all CPU threads but one (to keep the system
-responsive during compilation). If you want to adjust how many CPU threads SCons
-will use, use the ``-j <threads>`` parameter to specify how many threads will be
-used for the build.
-
-Example for using 4 threads:
-
-::
-
-    scons platform=linuxbsd -j4
-
 .. _doc_introduction_to_the_buildsystem_resulting_binary:
 
 Resulting binary

contributing/development/index.rst

@@ -17,9 +17,25 @@ especially if you're new to using Git or GitHub.
    best_practices_for_engine_contributors
    code_style_guidelines
    cpp_usage_guidelines
+
+Buildsystem and work environment
+--------------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-contributing-to-the-engine-environment
+
+   configuring_an_ide/index
    compiling/index
    debugging/index
-   configuring_an_ide/index
+
+Engine architecture
+-------------------
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-contributing-to-the-engine-architecture
+
    core_and_modules/index
-   editor/index
    file_formats/index
+   editor/index