Improve Introduction to the buildsystem documentation

- Simplify history section on SCons.
- Add a section on `production` and `dev_mode` aliases.
- Add a section on `debug_symbols` and `separate_debug_symbols`.
- Add a section on `optimize`.

contributing/development/compiling/introduction_to_the_buildsystem.rst

@@ -8,12 +8,10 @@ Introduction to the buildsystem
 SCons
 -----
 
-Godot uses `SCons <https://www.scons.org/>`__ to build. We love it, we are
-not changing it for anything else. We are not even sure other build
-systems are up to the task of building Godot. We constantly get requests
-to move the build system to CMake, or Visual Studio, but this is not
-going to happen. There are many reasons why we have chosen SCons over
-other alternatives, for example:
+Godot uses `SCons <https://www.scons.org/>`__ to build. We love it, we are not
+changing it for anything else. We constantly get requests to move the build
+system to CMake, or Visual Studio, but this is not going to happen. There are
+many reasons why we have chosen SCons over other alternatives, for example:
 
 -  Godot can be compiled for a dozen different platforms: all PC
    platforms, all mobile platforms, many consoles, and WebAssembly.
@@ -22,9 +20,8 @@ other alternatives, for example:
    can't afford reconfiguring and rebuilding the project each time.
    SCons can do this with no sweat, without breaking the builds.
 -  SCons will *never* break a build no matter how many changes,
-   configurations, additions, removals etc. You have more chances to die
-   struck by lightning than needing to clean and rebuild in SCons.
--  Godot build process is not simple. Several files are generated by
+   configurations, additions, removals etc.
+-  Godot's build process is not simple. Several files are generated by
    code (binders), others are parsed (shaders), and others need to offer
    customization (plugins). This requires complex logic which is easier
    to write in an actual programming language (like Python) rather than
@@ -33,8 +30,8 @@ other alternatives, for example:
    platform has a specific detection process, and all these must be
    handled as specific cases with special code written for each.
 
-So, please try to keep an open mind and get at least a little familiar with it
-if you are planning to build Godot yourself.
+Please try to keep an open mind and get at least a little familiar with it if
+you are planning to build Godot yourself.
 
 Setup
 -----
@@ -141,15 +138,45 @@ All builds are optimized. Each mode means:
 
 The editor is enabled by default in all PC targets (Linux, Windows, macOS),
 disabled for everything else. Disabling the editor produces a binary that can
-run projects but that does not include the editor or the Project Manager.
+run projects but does not include the editor or the Project Manager.
 
 ::
 
     scons platform=<platform> target=editor/template_debug/template_release
 
+Development and production aliases
+----------------------------------
+
+When creating builds for development (running debugging/:ref:`profiling <doc_using_cpp_profilers>`
+tools), you often have different goals compared to production builds
+(making binaries as fast and small as possible).
+
+Godot provides two aliases for this purpose:
+
+- ``dev_mode=yes`` is an alias for ``verbose=yes warnings=extra werror=yes
+  tests=yes``. This enables warnings-as-errors behavior (similar to Godot's
+  continuous integration setup) and also builds :ref:`unit tests
+  <doc_unit_testing>` so you can run them locally.
+- ``production=yes`` is an alias for ``use_static_cpp=yes debug_symbols=no
+  lto=auto``. Statically linking libstdc++ allows for better binary portability
+  when compiling for Linux. This alias also enables link-time optimization when
+  compiling for Linux, Web and Windows with MinGW, but keeps LTO disabled when
+  compiling for macOS, iOS or Windows with MSVC. This is because LTO on those
+  platforms is very slow to link or has issues with the generated code.
+
+You can manually override options from those aliases by specifying them on the
+same command line with different values. For example, you can use ``scons
+production=yes debug_symbols=yes`` to create production-optimized binaries with
+debugging symbols included.
+
 Dev build
 ---------
 
+.. note::
+
+    ``dev_build`` should **not** be confused with ``dev_mode``, which is an
+    alias for several development-related options (see above).
+
 When doing engine development the ``dev_build`` option can be used together
 with ``target`` to enable dev-specific code. ``dev_build`` defines ``DEV_ENABLED``,
 disables optimization (``-O0``/``/0d``), enables generating debug symbols, and
@@ -162,6 +189,55 @@ does not define ``NDEBUG`` (so ``assert()`` works in thirdparty libraries).
 This flag appends the ``.dev`` suffix (for development) to the generated
 binary name.
 
+Debugging symbols
+-----------------
+
+By default, ``debug_symbols=no`` is used, which means **no** debugging symbols
+are included in compiled binaries. Use ``debug_symbols=yes`` to include debug
+symbols within compiled binaries, which allows debuggers and profilers to work
+correctly. Debugging symbols are also required for Godot's crash stacktraces to
+display with references to source code files and lines.
+
+The downside is that debugging symbols are large files (significantly larger
+than the binaries themselves). As a result, official binaries currently do not
+include debugging symbols. This means you need to compile Godot yourself to have
+access to debugging symbols.
+
+When using ``debug_symbols=yes``, you can also use
+``separate_debug_symbols=yes`` to put debug information in a separate file with
+a ``.debug`` suffix. This allows distributing both files independently. Note
+that on Windows, when compiling with MSVC, debugging information is *always*
+written to a separate ``.pdb`` file regardless of ``separate_debug_symbols``.
+
+.. tip::
+
+    Use the ``strip <path/to/binary>`` command to remove debugging symbols from
+    a binary you've already compiled.
+
+Optimization level
+------------------
+
+Several compiler optimization levels can be chosen from:
+
+- ``optimize=speed_trace`` *(default when targeting non-Web platforms)*: Favors
+  execution speed at the cost of larger binary size. Optimizations may sometimes
+  negatively impact debugger usage (stack traces may be less accurate. If this
+  occurs to you, use ``optimize=debug`` instead.
+- ``optimize=speed``: Favors even more execution speed, at the cost of even
+  larger binary size compared to ``optimize=speed_trace``. Even less friendly to
+  debugging compared to ``optimize=debug``, as this uses the most aggressive
+  optimizations available.
+- ``optimize=size`` *(default when targeting the Web platform)*: Favors small
+  binaries at the cost of slower execution speed.
+- ``optimize=debug``: Only enables optimizations that do not impact debugging in
+  any way. This results in faster binaries than ``optimize=none``, but slower
+  binaries than ``optimize=speed_trace``.
+- ``optimize=none``: Do not perform any optimization. This provides the fastest
+  build times, but the slowest execution times.
+- ``optimize=custom`` *(advanced users only)*: Do not pass optimization
+  arguments to the C/C++ compilers. You will have to pass arguments manually
+  using the ``CFLAGS``, ``CCFLAGS`` and ``CXXFLAGS`` SCons options.
+
 Architecture
 ------------