diff --git a/development/compiling/compiling_for_android.rst b/development/compiling/compiling_for_android.rst index 0ce72104806..97700e0341b 100644 --- a/development/compiling/compiling_for_android.rst +++ b/development/compiling/compiling_for_android.rst @@ -94,8 +94,8 @@ root directory with the following arguments: :: - scons platform=android target=release android_arch=armv7 - scons platform=android target=release android_arch=arm64v8 + scons platform=android target=template_release arch=armv7 + scons platform=android target=template_release arch=arm64v8 cd platform/android/java # On Windows .\gradlew generateGodotTemplates @@ -109,8 +109,8 @@ The resulting APK will be located at ``bin/android_release.apk``. :: - scons platform=android target=release_debug android_arch=armv7 - scons platform=android target=release_debug android_arch=arm64v8 + scons platform=android target=template_debug arch=armv7 + scons platform=android target=template_debug arch=arm64v8 cd platform/android/java # On Windows .\gradlew generateGodotTemplates @@ -130,16 +130,16 @@ Adding support for x86 devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you also want to include support for x86 and x86-64 devices, run the SCons -command a third and fourth time with the ``android_arch=x86``, and -``android_arch=x86_64`` arguments before building the APK with Gradle. For +command a third and fourth time with the ``arch=x86_32``, and +``arch=x86_64`` arguments before building the APK with Gradle. For example, for the release template: :: - scons platform=android target=release android_arch=armv7 - scons platform=android target=release android_arch=arm64v8 - scons platform=android target=release android_arch=x86 - scons platform=android target=release android_arch=x86_64 + scons platform=android target=template_release arch=armv7 + scons platform=android target=template_release arch=arm64v8 + scons platform=android target=template_release arch=x86 + scons platform=android target=template_release arch=x86_64 cd platform/android/java # On Windows .\gradlew generateGodotTemplates @@ -214,10 +214,10 @@ root directory with the following arguments: :: - scons platform=android android_arch=armv7 production=yes tools=yes target=release_debug - scons platform=android android_arch=arm64v8 production=yes tools=yes target=release_debug - scons platform=android android_arch=x86 production=yes tools=yes target=release_debug - scons platform=android android_arch=x86_64 production=yes tools=yes target=release_debug + scons platform=android arch=armv7 production=yes target=editor + scons platform=android arch=arm64v8 production=yes target=editor + scons platform=android arch=x86 production=yes target=editor + scons platform=android arch=x86_64 production=yes target=editor cd platform/android/java # On Windows .\gradlew generateGodotEditor @@ -289,8 +289,8 @@ one of the following reasons: - Make sure to use export templates that match your editor version; if you use a new Godot version, you *have* to update the templates too. -- ``libgodot_android.so`` is not in ``libs//`` - where ```` is the device's architecture. +- ``libgodot_android.so`` is not in ``libs//`` + where ```` is the device's architecture. - The device's architecture does not match the exported one(s). Make sure your templates were built for that device's architecture, and that the export settings included support for that architecture. diff --git a/development/compiling/compiling_for_linuxbsd.rst b/development/compiling/compiling_for_linuxbsd.rst index 95cbf5ba5dd..819a205919e 100644 --- a/development/compiling/compiling_for_linuxbsd.rst +++ b/development/compiling/compiling_for_linuxbsd.rst @@ -149,7 +149,7 @@ manager. .. note:: If you are compiling Godot for production use, then you can make the final executable smaller and faster by adding the - SCons option ``target=release_debug``. + SCons options ``target=template_release production=yes``. If you are compiling Godot with GCC, you can make the binary even smaller and faster by adding the SCons option ``use_lto=yes``. @@ -161,23 +161,27 @@ manager. :ref:`doc_data_paths_self_contained_mode` by creating a file called ``._sc_`` or ``_sc_`` in the ``bin/`` folder. -Compiling a headless/server build ---------------------------------- +Running a headless/server build +------------------------------- -To compile a *headless* build which provides editor functionality to export -projects in an automated manner, use:: +To run in *headless* mode which provides editor functionality to export +projects in an automated manner, use the normal build:: - scons -j8 platform=server tools=yes target=release_debug + scons -j8 platform=linuxbsd target=editor + +And then use the ``--headless`` command line argument:: + + ./bin/godot.linuxbsd.editor.x86_64 --headless To compile a debug *server* build which can be used with :ref:`remote debugging tools `, use:: - scons -j8 platform=server tools=no target=release_debug + scons -j8 platform=linuxbsd target=template_debug To compile a *server* build which is optimized to run dedicated game servers, use:: - scons -j8 platform=server tools=no target=release + scons -j8 platform=linuxbsd target=template_release production=yes Building export templates ------------------------- @@ -197,15 +201,15 @@ following parameters: :: - scons platform=linuxbsd tools=no target=release bits=32 - scons platform=linuxbsd tools=no target=release_debug bits=32 + scons platform=linuxbsd target=template_release arch=x86_32 + scons platform=linuxbsd target=template_debug arch=x86_32 - (64 bits) :: - scons platform=linuxbsd tools=no target=release bits=64 - scons platform=linuxbsd tools=no target=release_debug bits=64 + scons platform=linuxbsd target=template_release arch=x86_64 + scons platform=linuxbsd target=template_debug arch=x86_64 Note that cross-compiling for the opposite bits (64/32) as your host platform is not always straight-forward and might need a chroot environment. diff --git a/development/compiling/compiling_for_macos.rst b/development/compiling/compiling_for_macos.rst index f55c6fbd1af..3644cdb80c1 100644 --- a/development/compiling/compiling_for_macos.rst +++ b/development/compiling/compiling_for_macos.rst @@ -94,30 +94,34 @@ editor binary built with ``target=release_debug``:: mkdir -p Godot.app/Contents/Frameworks cp /macOS/lib/libMoltenVK.dylib Godot.app/Contents/Frameworks/libMoltenVK.dylib -Compiling a headless/server build ---------------------------------- +Running a headless/server build +------------------------------- -To compile a *headless* build which provides editor functionality to export -projects in an automated manner, use:: +To run in *headless* mode which provides editor functionality to export +projects in an automated manner, use the normal build:: - scons platform=server tools=yes target=release_debug --jobs=$(sysctl -n hw.logicalcpu) + scons platform=macos target=editor --jobs=$(sysctl -n hw.logicalcpu) + +And then use the ``--headless`` command line argument:: + + ./bin/godot.macos.editor.x86_64 --headless To compile a debug *server* build which can be used with :ref:`remote debugging tools `, use:: - scons platform=server tools=no target=release_debug --jobs=$(sysctl -n hw.logicalcpu) + scons platform=macos target=template_debug --jobs=$(sysctl -n hw.logicalcpu) To compile a release *server* build which is optimized to run dedicated game servers, use:: - scons platform=server tools=no target=release --jobs=$(sysctl -n hw.logicalcpu) + scons platform=macos target=template_release production=yes --jobs=$(sysctl -n hw.logicalcpu) Building export templates ------------------------- -To build macOS export templates, you have to compile with ``tools=no`` (no -editor) and respectively for ``target=release`` (release template) and -``target=release_debug``. +To build macOS export templates, you have to compile using the targets without +the editor: ``target=template_release`` (release template) and +``target=template_debug``. Official templates are universal binaries which support both Intel x86_64 and ARM64 architectures. You can also create export templates that support only one @@ -125,13 +129,13 @@ of those two architectures by leaving out the ``lipo`` step below. - For Intel x86_64:: - scons platform=macos tools=no target=release arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu) - scons platform=macos tools=no target=release_debug arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu) + scons platform=macos target=template_release arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu) + scons platform=macos target=template_debug arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu) - For ARM64 (Apple M1):: - scons platform=macos tools=no target=release arch=arm64 --jobs=$(sysctl -n hw.logicalcpu) - scons platform=macos tools=no target=release_debug arch=arm64 --jobs=$(sysctl -n hw.logicalcpu) + scons platform=macos target=template_release arch=arm64 --jobs=$(sysctl -n hw.logicalcpu) + scons platform=macos target=template_debug arch=arm64 --jobs=$(sysctl -n hw.logicalcpu) To support both architectures in a single "Universal 2" binary, run the above two commands blocks and then use ``lipo`` to bundle them together:: diff --git a/development/compiling/compiling_for_uwp.rst b/development/compiling/compiling_for_uwp.rst index 32e2e09e842..df091abcc27 100644 --- a/development/compiling/compiling_for_uwp.rst +++ b/development/compiling/compiling_for_uwp.rst @@ -66,8 +66,8 @@ be able to export. Open the command prompt for one architecture and run SCons twice (once for each target):: - C:\godot>scons platform=uwp target=release_debug - C:\godot>scons platform=uwp target=release + C:\godot>scons platform=uwp target=template_debug + C:\godot>scons platform=uwp target=template_release Repeat for the other architectures. diff --git a/development/compiling/compiling_for_web.rst b/development/compiling/compiling_for_web.rst index a206aeca9c0..ded57214776 100644 --- a/development/compiling/compiling_for_web.rst +++ b/development/compiling/compiling_for_web.rst @@ -34,18 +34,18 @@ and ``source ./emsdk_env.sh``/``emsdk_env.bat``. Open a terminal and navigate to the root directory of the engine source code. Then instruct SCons to build the Web platform. Specify ``target`` as -either ``release`` for a release build or ``release_debug`` for a debug build:: +either ``template_release`` for a release build or ``template_debug`` for a debug build:: - scons platform=web tools=no target=release - scons platform=web tools=no target=release_debug + scons platform=web target=template_release + scons platform=web target=template_debug By default, the :ref:`JavaScript singleton ` will be built into the engine. Official export templates also have the JavaScript singleton enabled. Since ``eval()`` calls can be a security concern, the ``javascript_eval`` option can be used to build without the singleton:: - scons platform=web tools=no target=release javascript_eval=no - scons platform=web tools=no target=release_debug javascript_eval=no + scons platform=web target=template_release javascript_eval=no + scons platform=web target=template_debug javascript_eval=no The engine will now be compiled to WebAssembly by Emscripten. Once finished, the resulting file will be placed in the ``bin`` subdirectory. Its name is @@ -71,8 +71,8 @@ performance and compatibility reasons. See the You can build the export templates using the option ``dlink_enabled=yes`` to enable GDExtension support:: - scons platform=web tools=no dlink_enabled=yes target=release - scons platform=web tools=no dlink_enabled=yes target=release_debug + scons platform=web dlink_enabled=yes target=template_release + scons platform=web dlink_enabled=yes target=template_debug Once finished, the resulting file will be placed in the ``bin`` subdirectory. Its name will have ``_dlink`` added. @@ -90,7 +90,7 @@ It is also possible to build a version of the Godot editor that can run in the browser. The editor version is not recommended over the native build. You can build the editor with:: - scons platform=web tools=yes target=release_debug + scons platform=web target=editor Once finished, the resulting file will be placed in the ``bin`` subdirectory. Its name will be ``godot.web.opt.tools.wasm32.zip``. You can upload the diff --git a/development/compiling/compiling_for_windows.rst b/development/compiling/compiling_for_windows.rst index c63b320b79b..2a909e8a73d 100644 --- a/development/compiling/compiling_for_windows.rst +++ b/development/compiling/compiling_for_windows.rst @@ -149,15 +149,15 @@ option to any SCons command you see below. If all goes well, the resulting binary executable will be placed in ``C:\godot\bin\`` with the name ``godot.windows.tools.32.exe`` or ``godot.windows.tools.64.exe``. By default, SCons will build a binary matching -your CPU architecture, but this can be overridden using ``bits=64`` or -``bits=32``. +your CPU architecture, but this can be overridden using ``arch=x86_64`` or +``arch=x86_32``. This executable file contains the whole engine and runs without any dependencies. Running it will bring up the Project Manager. .. note:: If you are compiling Godot for production use, then you can make the final executable smaller and faster by adding the - SCons option ``target=release_debug``. + SCons option ``target=template_release``. If you are compiling Godot with MinGW, you can make the binary even smaller and faster by adding the SCons option ``use_lto=yes``. @@ -269,10 +269,10 @@ Creating Windows export templates Windows export templates are created by compiling Godot without the editor, with the following flags:: - C:\godot> scons platform=windows tools=no target=release_debug bits=32 - C:\godot> scons platform=windows tools=no target=release bits=32 - C:\godot> scons platform=windows tools=no target=release_debug bits=64 - C:\godot> scons platform=windows tools=no target=release bits=64 + C:\godot> scons platform=windows target=template_debug arch=x86_32 + C:\godot> scons platform=windows target=template_release arch=x86_32 + C:\godot> scons platform=windows target=template_debug arch=x86_64 + C:\godot> scons platform=windows target=template_release arch=x86_64 If you plan on replacing the standard export templates, copy these to the following location, replacing ```` with the version identifier diff --git a/development/compiling/compiling_with_mono.rst b/development/compiling/compiling_with_mono.rst index 9db5ce01e0a..d01bc223646 100644 --- a/development/compiling/compiling_with_mono.rst +++ b/development/compiling/compiling_with_mono.rst @@ -58,15 +58,15 @@ Generate the glue Glue sources are the wrapper functions that will be called by managed methods. These source files must be generated before building your final binaries. In order to generate them, first, you must build a temporary Godot binary with the -options ``tools=yes`` and ``mono_glue=no``:: +options ``target=editor``:: - scons p= tools=yes module_mono_enabled=yes mono_glue=no + scons p= target=editor module_mono_enabled=yes After the build finishes, you need to run the compiled executable with the -parameter ``--generate-mono-glue`` followed by the path to an output directory. +parameters ``--headless --generate-mono-glue`` followed by the path to an output directory. This path must be ``modules/mono/glue`` in the Godot directory:: - --generate-mono-glue modules/mono/glue + --headless --generate-mono-glue modules/mono/glue This command will tell Godot to generate the file ``modules/mono/glue/mono_glue.gen.cpp``, the C# solution for the Godot API at ``modules/mono/glue/GodotSharp/GodotSharp/Generated``, @@ -74,11 +74,11 @@ and the C# solution for the editor tools at ``modules/mono/glue/GodotSharp/Godot Once these files are generated, you can build Godot for all the desired targets without having to repeat this process. -```` refers to the tools binary you compiled above with the Mono +```` refers to the editor binary you compiled above with the Mono module enabled. Its exact name will differ based on your system and configuration, but should be of the form -``bin/godot..tools..mono``, e.g. ``bin/godot.linuxbsd.tools.64.mono`` -or ``bin/godot.windows.tools.64.mono.exe``. Be especially aware of the **.mono** +``bin/godot..editor..mono``, e.g. ``bin/godot.linuxbsd.editor.x86_64.mono`` +or ``bin/godot.windows.editor.x86_32.mono.exe``. Be especially aware of the **.mono** suffix! If you've previously compiled Godot without Mono support, you might have similarly named binaries without this suffix. These binaries can't be used to generate the Mono glue. @@ -86,10 +86,6 @@ generate the Mono glue. Notes ^^^^^ -- **Do not build your final binaries with** ``mono_glue=no``. - This disables C# scripting. This option must be used only for the temporary - binary that will generate the glue. Godot will print a warning at startup if - it was built without the glue sources. - The glue sources must be regenerated every time the ClassDB-registered API changes. That is, for example, when a new method is registered to the scripting API or one of the parameters of such a method changes. @@ -100,15 +96,14 @@ Notes Rebuild with Mono glue ---------------------- -Once you have generated the Mono glue, you can build the final binary with -``mono_glue=yes``. This is the default value for ``mono_glue``, so you can also -omit it. To build a Mono-enabled editor:: +Once you have generated the Mono glue, you can generate the final binary with +the ``build_assemblies.py`` script.:: - scons p= tools=yes module_mono_enabled=yes mono_glue=yes + ./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin --godot-platform={PLATFORM_NAME} And Mono-enabled export templates:: - scons p= tools=no module_mono_enabled=yes mono_glue=yes + scons p= target=template_release module_mono_enabled=yes If everything went well, apart from the normal output, SCons should have created the following files in the ``bin`` directory: @@ -135,17 +130,19 @@ Example (Windows) :: - # Build temporary binary - scons p=windows tools=yes module_mono_enabled=yes mono_glue=no + # Build editor binary + scons p=windows target=editor module_mono_enabled=yes # Generate glue sources - bin\godot.windows.tools.64.mono --generate-mono-glue modules/mono/glue + bin\godot.windows.editor.x86_64.mono --generate-mono-glue modules/mono/glue + # Build .NET assemblies + ./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin --godot-platform=windows ### Build binaries normally # Editor - scons p=windows target=release_debug tools=yes module_mono_enabled=yes + scons p=windows target=editor module_mono_enabled=yes # Export templates - scons p=windows target=release_debug tools=no module_mono_enabled=yes - scons p=windows target=release tools=no module_mono_enabled=yes + scons p=windows target=template_debug module_mono_enabled=yes + scons p=windows target=template_release module_mono_enabled=yes Example (Linux, \*BSD) ^^^^^^^^^^^^^^^^^^^^^^ @@ -153,16 +150,18 @@ Example (Linux, \*BSD) :: # Build temporary binary - scons p=linuxbsd tools=yes module_mono_enabled=yes mono_glue=no + scons p=linuxbsd target=editor module_mono_enabled=yes # Generate glue sources - bin/godot.linuxbsd.tools.64.mono --generate-mono-glue modules/mono/glue + bin/godot.linuxbsd.editor.x86_64.mono --generate-mono-glue modules/mono/glue + # Generate binaries + ./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin --godot-platform=linuxbsd ### Build binaries normally # Editor - scons p=linuxbsd target=release_debug tools=yes module_mono_enabled=yes + scons p=linuxbsd target=editor module_mono_enabled=yes # Export templates - scons p=linuxbsd target=release_debug tools=no module_mono_enabled=yes - scons p=linuxbsd target=release tools=no module_mono_enabled=yes + scons p=linuxbsd target=template_debug module_mono_enabled=yes + scons p=linuxbsd target=template_release module_mono_enabled=yes .. _compiling_with_mono_data_directory: @@ -181,8 +180,8 @@ Export templates The name of the data directory for an export template differs based on the configuration it was built with. The format is -``data.mono...``, e.g. ``data.mono.linuxbsd.32.release_debug`` or -``data.mono.windows.64.release``. +``data.mono...``, e.g. ``data.mono.linuxbsd.x86_32.release_debug`` or +``data.mono.windows.x86_64.release``. This directory must be placed with its original name next to the Godot export templates. When exporting a project, Godot will also copy this directory with @@ -195,9 +194,9 @@ the contents of the data directory can be placed in the following locations inside the ZIP archive: +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Mono/lib`` | ``/osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib`` | +| ``bin/data.mono.../Mono/lib`` | ``/osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib`` | +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Mono/etc`` | ``/osx_template.app/Contents/Resources/GodotSharp/Mono/etc`` | +| ``bin/data.mono.../Mono/etc`` | ``/osx_template.app/Contents/Resources/GodotSharp/Mono/etc`` | +-------------------------------------------------------+---------------------------------------------------------------+ Editor @@ -215,13 +214,13 @@ Godot editor is distributed as a bundle, the contents of the data directory may be placed in the following locations: +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Api`` | ``.app/Contents/Frameworks/GodotSharp/Api`` | +| ``bin/data.mono.../Api`` | ``.app/Contents/Frameworks/GodotSharp/Api`` | +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Mono/lib`` | ``.app/Contents/Frameworks/GodotSharp/Mono/lib`` | +| ``bin/data.mono.../Mono/lib`` | ``.app/Contents/Frameworks/GodotSharp/Mono/lib`` | +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Mono/etc`` | ``.app/Contents/Resources/GodotSharp/Mono/etc`` | +| ``bin/data.mono.../Mono/etc`` | ``.app/Contents/Resources/GodotSharp/Mono/etc`` | +-------------------------------------------------------+---------------------------------------------------------------+ -| ``bin/data.mono.../Tools`` | ``.app/Contents/Frameworks/GodotSharp/Tools`` | +| ``bin/data.mono.../Tools`` | ``.app/Contents/Frameworks/GodotSharp/Tools`` | +-------------------------------------------------------+---------------------------------------------------------------+ The ``Mono`` subdirectory is optional. It will be needed when distributing the @@ -375,11 +374,6 @@ the Mono module: - Build Godot with the Mono module enabled. -- **mono_glue**\ =\ **yes** | no - - - Whether to include the glue source files in the build - and define ``MONO_GLUE_DISABLED`` as a preprocessor macro. - - **mono_prefix**\ =path - Path to the Mono installation directory for the target platform and architecture. diff --git a/development/compiling/cross-compiling_for_ios_on_linux.rst b/development/compiling/cross-compiling_for_ios_on_linux.rst index 72edb4fb9c7..08003e8fb61 100644 --- a/development/compiling/cross-compiling_for_ios_on_linux.rst +++ b/development/compiling/cross-compiling_for_ios_on_linux.rst @@ -141,4 +141,4 @@ way, with some additional arguments to provide the correct paths: :: - $ scons -j 4 platform=ios arch=arm64 target=release_debug IOS_SDK_PATH="/path/to/iPhoneSDK" IOS_TOOLCHAIN_PATH="/path/to/iostoolchain" ios_triple="arm-apple-darwin11-" + $ scons -j 4 platform=ios arch=arm64 target=template_release IOS_SDK_PATH="/path/to/iPhoneSDK" IOS_TOOLCHAIN_PATH="/path/to/iostoolchain" ios_triple="arm-apple-darwin11-" diff --git a/development/compiling/introduction_to_the_buildsystem.rst b/development/compiling/introduction_to_the_buildsystem.rst index fc1ec12a8e3..d727439f025 100644 --- a/development/compiling/introduction_to_the_buildsystem.rst +++ b/development/compiling/introduction_to_the_buildsystem.rst @@ -98,22 +98,22 @@ Resulting binary The resulting binaries will be placed in the ``bin/`` subdirectory, generally with this naming convention:: - godot..[opt].[tools/debug].[extension] + godot..[.dev][.double].[.][.] For the previous build attempt, the result would look like this:: ls bin - bin/godot.linuxbsd.tools.64 + bin/godot.linuxbsd.editor.x86_64 -This means that the binary is for Linux *or* \*BSD (*not* both), is not optimized, has tools (the -whole editor) compiled in, and is meant for 64 bits. +This means that the binary is for Linux *or* \*BSD (*not* both), is not optimized, has the +whole editor compiled in, and is meant for 64 bits. A Windows binary with the same configuration will look like this: .. code-block:: console C:\godot> dir bin/ - godot.windows.tools.64.exe + godot.windows.editor.64.exe Copy that binary to any location you like, as it contains the project manager, editor and all means to execute the game. However, it lacks the data to export @@ -124,63 +124,58 @@ you can build them yourself). Aside from that, there are a few standard options that can be set in all build targets, and which will be explained below. -.. _doc_introduction_to_the_buildsystem_tools: +.. _doc_introduction_to_the_buildsystem_target: -Tools ------ +Target +------ -Tools are enabled by default in all PC targets (Linux, Windows, macOS), -disabled for everything else. Disabling tools produces a binary that can -run projects but that does not include the editor or the project -manager. +Target controls if the editor is contained and debug flags are used. +All builds are optimized. Each mode means: -:: +- **editor**: Build with editor, optimized, with debugging code (defines: ``TOOLS_ENABLED``, ``DEBUG_ENABLED``, ``-O2``/``/O2``) +- **template_debug**: Build with C++ debugging symbols (defines: ``DEBUG_ENABLED``, ``-O2``/``/O2``) +- **template_release**: Build without symbols (defines: ``-O3``/``/O2``) - scons platform= tools=yes/no +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. -.. _doc_introduction_to_the_buildsystem_target: +:: -Target ------- + scons platform= target=editor/template_debug/template_release -Target controls optimization and debug flags. Each mode means: +Dev build +--------- -- **debug**: Build with C++ debugging symbols, runtime checks (performs - checks and reports error) and none to little optimization. -- **release_debug**: Build without C++ debugging symbols and - optimization, but keep the runtime checks (performs checks and - reports errors). Official editor binaries use this configuration. -- **release**: Build without symbols, with optimization and with little - to no runtime checks. This target can't be used together with - ``tools=yes``, as the editor requires some debug functionality and run-time - checks to run. +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 +does not define ``NDEBUG`` (so ``assert()`` works in thirdparty libraries). :: - scons platform= target=debug/release_debug/release + scons platform= dev_build=yes -This flag appends the ``.debug`` suffix (for debug), or ``.tools`` (for debug -with tools enabled). When optimization is enabled (release), it appends -the ``.opt`` suffix. +This flag appends the ``.dev`` suffix (for development) to the generated +binary name. -Bits ----- +Architecture +------------ -Bits is meant to control the CPU or OS version intended to run the +The ``arch`` option is meant to control the CPU or OS version intended to run the binaries. It is focused mostly on desktop platforms and ignored everywhere else. -- **32**: Build binaries for 32-bit platforms. -- **64**: Build binaries for 64-bit platforms. -- **default**: Build for the architecture that matches the host platform. +Supported values for the ``arch`` option are **auto**, **x86_32**, **x86_64**, +**arm32**, **arm64**, **rv64**, **ppc32**, **ppc64** and **wasm32**. :: - scons platform= bits=default/32/64 + scons platform= arch=auto/'auto/x86_32/x86_64/arm32/arm64/rv64/ppc32/ppc64/wasm32 -This flag appends ``.32`` or ``.64`` suffixes to resulting binaries when -relevant. If ``bits=default`` is used, the suffix will match the detected -architecture. +This flag appends the value of ``arch`` to resulting binaries when +relevant. The default value ``arch=auto`` detects the architecture +that matches the host platform. .. _doc_buildsystem_custom_modules: diff --git a/development/compiling/optimizing_for_size.rst b/development/compiling/optimizing_for_size.rst index bad59813441..23757113dd0 100644 --- a/development/compiling/optimizing_for_size.rst +++ b/development/compiling/optimizing_for_size.rst @@ -61,7 +61,7 @@ To enable this, set the ``optimize`` flag to ``size``: :: - scons p=windows target=release tools=no optimize=size + scons p=windows target=template_release optimize=size Some platforms such as WebAssembly already use this mode by default. @@ -79,7 +79,7 @@ and MSVC compilers: :: - scons p=windows target=release tools=no use_lto=yes + scons p=windows target=template_release use_lto=yes Linking becomes much slower and more RAM-consuming with this option, so it should be used only for release builds: @@ -100,7 +100,7 @@ For 2D games, having the whole 3D engine available usually makes no sense. Becau :: - scons p=windows target=release tools=no disable_3d=yes + scons p=windows target=template_release disable_3d=yes Tools must be disabled in order to use this flag, as the editor is not designed to operate without 3D support. Without it, the binary size can be reduced @@ -118,7 +118,7 @@ TextEdit or GraphEdit. They can be disabled using a build flag: :: - scons p=windows target=release tools=no disable_advanced_gui=yes + scons p=windows target=template_release disable_advanced_gui=yes This is everything that will be disabled: @@ -167,7 +167,7 @@ a lot of them: :: - scons p=windows target=release tools=no module_arkit_enabled=no module_assimp_enabled=no module_bmp_enabled=no module_bullet_enabled=no module_camera_enabled=no module_csg_enabled=no module_dds_enabled=no module_enet_enabled=no module_etc_enabled=no module_gridmap_enabled=no module_hdr_enabled=no module_jsonrpc_enabled=no module_mbedtls_enabled=no module_mobile_vr_enabled=no module_opensimplex_enabled=no module_pvr_enabled=no module_recast_enabled=no module_regex_enabled=no module_squish_enabled=no module_svg_enabled=no module_tga_enabled=no module_theora_enabled=no module_tinyexr_enabled=no module_upnp_enabled=no module_vhacd_enabled=no module_vorbis_enabled=no module_webrtc_enabled=no module_websocket_enabled=no module_xatlas_unwrap_enabled=no + scons p=windows target=template_release module_arkit_enabled=no module_assimp_enabled=no module_bmp_enabled=no module_bullet_enabled=no module_camera_enabled=no module_csg_enabled=no module_dds_enabled=no module_enet_enabled=no module_etc_enabled=no module_gdnative_enabled=no module_gridmap_enabled=no module_hdr_enabled=no module_jsonrpc_enabled=no module_mbedtls_enabled=no module_mobile_vr_enabled=no module_opensimplex_enabled=no module_pvr_enabled=no module_recast_enabled=no module_regex_enabled=no module_squish_enabled=no module_svg_enabled=no module_tga_enabled=no module_theora_enabled=no module_tinyexr_enabled=no module_upnp_enabled=no module_vhacd_enabled=no module_vorbis_enabled=no module_webrtc_enabled=no module_websocket_enabled=no module_xatlas_unwrap_enabled=no If this proves not to work for your use case, you should review the list of modules and see which ones you actually still need for your game (e.g. you diff --git a/development/cpp/configuring_an_ide/img/vscode_2_launch.json.png b/development/cpp/configuring_an_ide/img/vscode_2_launch.json.png index 968a8815f0c..516be2cadff 100644 Binary files a/development/cpp/configuring_an_ide/img/vscode_2_launch.json.png and b/development/cpp/configuring_an_ide/img/vscode_2_launch.json.png differ diff --git a/development/cpp/configuring_an_ide/img/vscode_3_tasks.json.png b/development/cpp/configuring_an_ide/img/vscode_3_tasks.json.png index 6c65c8e0968..1702642d3f9 100644 Binary files a/development/cpp/configuring_an_ide/img/vscode_3_tasks.json.png and b/development/cpp/configuring_an_ide/img/vscode_3_tasks.json.png differ diff --git a/development/cpp/configuring_an_ide/kdevelop.rst b/development/cpp/configuring_an_ide/kdevelop.rst index 7bf9a8c7df1..25fb39bd6de 100644 --- a/development/cpp/configuring_an_ide/kdevelop.rst +++ b/development/cpp/configuring_an_ide/kdevelop.rst @@ -77,7 +77,8 @@ Debugging the project - Click **Add** to create a new launch configuration. - Select **Executable** option and specify the path to your executable located in the ``/bin`` folder. The name depends on your build configuration, - e.g. ``godot.linuxbsd.tools.64`` for 64-bit LinuxBSD platform with ``tools`` enabled. + e.g. ``godot.linuxbsd.editor.dev.x86_64`` for 64-bit LinuxBSD platform with + ``platform=editor`` and ``dev_build=yes``. .. figure:: img/kdevelop_configlaunches2.png :figclass: figure-w480 diff --git a/development/cpp/configuring_an_ide/qt_creator.rst b/development/cpp/configuring_an_ide/qt_creator.rst index 5c97b33d804..9bc2d02f5bb 100644 --- a/development/cpp/configuring_an_ide/qt_creator.rst +++ b/development/cpp/configuring_an_ide/qt_creator.rst @@ -75,8 +75,9 @@ Debugging the project - From the left-side menu select **Projects** and open the **Run** tab. - Under **Executable** specify the path to your executable located in the ``/bin`` folder. The name depends on your build configuration, - e.g. ``godot.linuxbsd.tools.64`` for 64-bit LinuxBSD platform with ``tools`` enabled. - You can use ``%{buildDir}`` to reference the project root, e.g: ``%{buildDir}/bin/godot.linuxbsd.opt.tools.64``. + e.g. ``godot.linuxbsd.editor.dev.x86_64`` for 64-bit LinuxBSD platform with + ``platform=editor`` and ``dev_build=yes``. + You can use ``%{buildDir}`` to reference the project root, e.g: ``%{buildDir}/bin/godot.linuxbsd.editor.dev.x86_64``. - If you want to run a specific project, specify its root folder under **Working directory**. - If you want to run the editor, add ``-e`` to the **Command line arguments** field. diff --git a/development/cpp/configuring_an_ide/visual_studio_code.rst b/development/cpp/configuring_an_ide/visual_studio_code.rst index 9a693614007..0b1fb0f7a07 100644 --- a/development/cpp/configuring_an_ide/visual_studio_code.rst +++ b/development/cpp/configuring_an_ide/visual_studio_code.rst @@ -45,7 +45,9 @@ Importing the project "command": "scons", "args": [ "-j", - "$(nproc)" + "$(nproc)", + // enable for debugging with breakpoints + "dev_build=yes", ], "problemMatcher": "$msCompile" } @@ -61,7 +63,8 @@ Importing the project // Use this when your default shell is Command Prompt (cmd.exe). "-j %NUMBER_OF_PROCESSORS%", // Use this when your default shell is PowerShell. - "-j $env:NUMBER_OF_PROCESSORS" + "-j $env:NUMBER_OF_PROCESSORS", + "dev_build=yes", ], "problemMatcher": "$msCompile" } @@ -98,7 +101,7 @@ To run and debug the project you need to create a new configuration in the ``lau "type": "lldb", "request": "launch", // Change to godot.linuxbsd.tools.64.llvm for llvm-based builds. - "program": "${workspaceFolder}/bin/godot.linuxbsd.tools.64", + "program": "${workspaceFolder}/bin/godot.linuxbsd.editor.dev.x86_64", // Change the arguments below for the project you want to test with. // To run the project instead of editing it, remove the "--editor" argument. "args": [ "--editor", "--path", "path-to-your-godot-project-folder" ], @@ -115,7 +118,7 @@ To run and debug the project you need to create a new configuration in the ``lau "type": "cppdbg", "request": "launch", // Change to godot.linuxbsd.tools.64.llvm for llvm-based builds. - "program": "${workspaceFolder}/bin/godot.linuxbsd.tools.64", + "program": "${workspaceFolder}/bin/godot.linuxbsd.editor.dev.x86_64", // Change the arguments below for the project you want to test with. // To run the project instead of editing it, remove the "--editor" argument. "args": [ "--editor", "--path", "path-to-your-godot-project-folder" ], @@ -140,7 +143,7 @@ To run and debug the project you need to create a new configuration in the ``lau "name": "Launch Project", "type": "cppvsdbg", "request": "launch", - "program": "${workspaceFolder}/bin/godot.windows.tools.64.exe", + "program": "${workspaceFolder}/bin/godot.windows.editor.dev.x86_64.exe", // Change the arguments below for the project you want to test with. // To run the project instead of editing it, remove the "--editor" argument. "args": [ "--editor", "--path", "path-to-your-godot-project-folder" ], @@ -170,7 +173,8 @@ To run and debug the project you need to create a new configuration in the ``lau Do note that lldb may work better with LLVM-based builds. See :ref:`doc_compiling_for_linuxbsd` for further information. The name under ``program`` depends on your build configuration, -e.g. ``godot.linuxbsd.tools.64`` for 64-bit LinuxBSD platform with ``tools`` enabled. +e.g. ``godot.linuxbsd.editor.dev.x86_64`` for 64-bit LinuxBSD platform with +``platform=editor`` and ``dev_build=yes``. If you run into any issues, ask for help in one of `Godot's community channels `__. diff --git a/development/cpp/using_cpp_profilers.rst b/development/cpp/using_cpp_profilers.rst index 7145ea73056..718c29c6dfd 100644 --- a/development/cpp/using_cpp_profilers.rst +++ b/development/cpp/using_cpp_profilers.rst @@ -32,13 +32,13 @@ symbols, since these would make the download size significantly larger. To get profiling data that best matches the production environment, you should compile binaries with the following SCons options: -- For editor binaries: ``target=release_debug use_lto=yes`` -- For debug export templates: ``target=release_debug use_lto=yes`` -- For release export templates: ``tools=no target=release debug_symbols=yes`` +- For editor binaries: ``target=editor use_lto=yes`` +- For debug export templates: ``target=template_debug use_lto=yes`` +- For release export templates: ``target=template_release debug_symbols=yes`` - ``debug_symbols=yes`` is required as export templates are stripped from debugging symbols by default. -It is possible to run a profiler on less optimized builds (e.g. ``target=debug`` without LTO), +It is possible to run a profiler on less optimized builds (e.g. ``target=template_debug`` without LTO), but results will naturally be less representative of real world conditions. .. warning::