From 73a22bf64b477153c4a6275fa4e8f25254ae9cd9 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Tue, 23 Nov 2021 19:45:55 +0100 Subject: [PATCH] Rework the Optimizing for size page - Order options from most important to least important. - Give estimates on space saved for each option. - Clarify the benefits of stripping binaries. - Link to the Godot build options generator in the Overriding build options link instead of linking it in the Optimizing for size page. (cherry picked from commit 8a956637680ebdd9cbaaced3a2d672e7e1e73c36) --- .../introduction_to_the_buildsystem.rst | 9 +- development/compiling/optimizing_for_size.rst | 123 ++++++++++++------ development/cpp/using_cpp_profilers.rst | 2 + 3 files changed, 92 insertions(+), 42 deletions(-) diff --git a/development/compiling/introduction_to_the_buildsystem.rst b/development/compiling/introduction_to_the_buildsystem.rst index c31764f73..082b20130 100644 --- a/development/compiling/introduction_to_the_buildsystem.rst +++ b/development/compiling/introduction_to_the_buildsystem.rst @@ -255,7 +255,14 @@ source to initialize any SCons build options passed via the command line: extra_suffix = "game_title" You can also disable some of the builtin modules before compiling, saving some -time it takes to build the engine, see :ref:`doc_optimizing_for_size` page for more details. +time it takes to build the engine. See :ref:`doc_optimizing_for_size` page for more details. + +.. seealso:: + + You can use the online + `Godot build options generator `__ + to generate a ``custom.py`` file containing SCons options. + You can then save this file and place it at the root of your Godot source directory. Another custom file can be specified explicitly with the ``profile`` command line option, both overriding the default build configuration: diff --git a/development/compiling/optimizing_for_size.rst b/development/compiling/optimizing_for_size.rst index f7667d68d..5e0833cff 100644 --- a/development/compiling/optimizing_for_size.rst +++ b/development/compiling/optimizing_for_size.rst @@ -17,16 +17,85 @@ This tutorial aims to give an overview on different methods to create a smaller binary. Before continuing, it is recommended to read the previous tutorials on compiling Godot for each platform. -.. seealso:: +The options below are listed from the most important (greatest size savings) +to the least important (lowest size savings). - You can use the online - `Godot build options generator `__ - to generate a ``custom.py`` file containing SCons options. - You can then save this file and place it at the root of your Godot source directory. +Stripping binaries +------------------ + +- **Space savings:** Very high +- **Difficulty:** Easy +- **Performed in official builds:** Yes + +If you build Windows (MinGW), Linux or macOS binaries from source, remember to +strip debug symbols from binaries by installing the ``strip`` package from your +distribution then running: + +:: + + strip path/to/godot.binary + +On Windows, ``strip.exe`` is included in most MinGW toolchain setups. + +This will reduce the size of compiled binaries by a factor between 5× and 10×. +The downside is that crash backtraces will no longer provide accurate information +(which is useful for troubleshooting the cause of a crash). +:ref:`C++ profilers ` will also no longer be able to display +function names (this does not affect the built-in GDScript profiler). + +.. note:: + + The above command will not work on Windows binaries compiled with MSVC + and platforms such as Android and HTML5. Instead, pass ``debug_symbols=no`` + on the SCons command line when compiling. + +Optimizing for size instead of speed +------------------------------------ + +- **Space savings:** High +- **Difficulty:** Easy +- **Performed in official builds:** Yes, but only for HTML5 + +Godot 3.1 onwards allows compiling using size optimizations (instead of speed). +To enable this, set the ``optimize`` flag to ``size``: + +:: + + scons p=windows target=release tools=no optimize=size + +Some platforms such as WebAssembly already use this mode by default. + +Compiling with link-time optimization +------------------------------------- + +- **Space savings:** High +- **Difficulty:** Easy +- **Performed in official builds:** Yes + +Enabling link-time optimization produces more efficient binaries, both in +terms of performance and file size. It works by eliminating duplicate +template functions and unused code. It can currently be used with the GCC +and MSVC compilers: + +:: + + scons p=windows target=release tools=no use_lto=yes + +Linking becomes much slower and more RAM-consuming with this option, +so it should be used only for release builds: + +- When compiling the ``master`` branch, you need to have at least 8 GB of RAM + available for successful linking with LTO enabled. +- When compiling the ``3.x`` branch, you need to have at least 6 GB of RAM + available for successful linking with LTO enabled. Disabling 3D ------------ +- **Space savings:** Moderate +- **Difficulty:** Easy +- **Performed in official builds:** No + For 2D games, having the whole 3D engine available usually makes no sense. Because of this, there is a build flag to disable it: :: @@ -40,6 +109,10 @@ by about 15%. Disabling advanced GUI nodes ---------------------------- +- **Space savings:** Moderate +- **Difficulty:** Easy +- **Performed in official builds:** No + Most small games don't require complex GUI controls such as Tree, ItemList, TextEdit or GraphEdit. They can be disabled using a build flag: @@ -50,6 +123,10 @@ TextEdit or GraphEdit. They can be disabled using a build flag: Disabling unwanted modules -------------------------- +- **Space savings:** Very low to moderate depending on modules +- **Difficulty:** Medium to hard depending on modules +- **Performed in official builds:** No + A lot of Godot's functions are offered as modules. You can see a list of modules with the following command: @@ -115,39 +192,3 @@ following: .. seealso:: :ref:`doc_overriding_build_options`. - -Optimizing for size instead of speed ------------------------------------- - -Godot 3.1 onwards allows compiling using size optimizations (instead of speed). -To enable this, set the ``optimize`` flag to ``size``: - -:: - - scons p=windows target=release tools=no optimize=size - -Some platforms such as WebAssembly already use this mode by default. - -Compiling with link-time optimization -------------------------------------- - -Enabling link-time optimization produces more efficient binaries, both in -terms of performance and file size. It works by eliminating duplicate -template functions and unused code. It can currently be used with the GCC -and MSVC compilers: - -:: - - scons p=windows target=release tools=no use_lto=yes - -Linking becomes much slower and more RAM consuming with this option, so it should be used only for -release builds. - -Stripping binaries ------------------- - -If you build from source, remember to strip debug symbols from binaries: - -:: - - strip godot.64 diff --git a/development/cpp/using_cpp_profilers.rst b/development/cpp/using_cpp_profilers.rst index 0a54833cd..e13c8b792 100644 --- a/development/cpp/using_cpp_profilers.rst +++ b/development/cpp/using_cpp_profilers.rst @@ -1,3 +1,5 @@ +.. _doc_using_cpp_profilers: + Using C++ profilers ===================