godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity

Migrate contributing contents to a separate documentation site.

Browse Source
This commit is contained in:
Lukas Tenbrink
2025-08-08 15:30:02 +02:00
parent ab1ec59eec
commit 0855668721
309 changed files with 918 additions and 6055 deletions
Download Patch File Download Diff File Expand all files Collapse all files

309
engine_details/development/compiling/compiling_for_android.rst Normal file
View File

@@ -0,0 +1,309 @@
.. _doc_compiling_for_android:
Compiling for Android
=====================
.. highlight:: shell
.. seealso::
This page describes how to compile Android export template binaries from source.
If you're looking to export your project to Android instead, read :ref:`doc_exporting_for_android`.
Note
----
In most cases, using the built-in deployer and export templates is good
enough. Compiling the Android APK manually is mostly useful for custom
builds or custom packages for the deployer.
Also, you still need to follow the steps mentioned in the
:ref:`doc_exporting_for_android` tutorial before attempting to build
a custom export template.
Requirements
------------
For compiling under Windows, Linux or macOS, the following is required:
- `Python 3.8+ <https://www.python.org/downloads/>`_.
- `SCons 4.0+ <https://scons.org/pages/download.html>`_ build system.
- `Android SDK <https://developer.android.com/studio/#command-tools>`_
(command-line tools are sufficient).
- Required SDK components will be automatically installed.
- On Linux, **do not use an Android SDK provided by your distribution's repositories** as it will often be outdated.
- On macOS, **do not use an Android SDK provided by Homebrew** as it will not be installed in a unified location.
- Gradle (will be downloaded and installed automatically if missing).
- JDK 17 (either OpenJDK or Oracle JDK).
- You can download a build from `Adoptium <https://adoptium.net/temurin/releases/?variant=openjdk17>`_.
.. seealso:: To get the Godot source code for compiling, see
:ref:`doc_getting_source`.
For a general overview of SCons usage for Godot, see
:ref:`doc_introduction_to_the_buildsystem`.
.. _doc_android_setting_up_the_buildsystem:
Setting up the buildsystem
--------------------------
- Set the environment variable ``ANDROID_HOME`` to point to the Android
SDK. If you downloaded the Android command-line tools, this would be
the folder where you extracted the contents of the ZIP archive.
- Windows: Press :kbd:`Windows + R`, type "control system",
then click on **Advanced system settings** in the left pane,
then click on **Environment variables** on the window that appears.
- Linux or macOS: Add the text ``export ANDROID_HOME="/path/to/android-sdk"``
to your ``.bashrc`` or ``.zshrc`` where ``/path/to/android-sdk`` points to
the root of the SDK directories.
- Install the necessary SDK components in this folder:
- Accept the SDK component licenses by running the following command
where ``android_sdk_path`` is the path to the Android SDK, then answering all the prompts with ``y``:
::
cmdline-tools/latest/bin/sdkmanager --sdk_root=<android_sdk_path> --licenses
- Complete setup by running the following command where ``android_sdk_path`` is the path to the Android SDK.
::
cmdline-tools/latest/bin/sdkmanager --sdk_root=<android_sdk_path> "platform-tools" "build-tools;35.0.0" "platforms;android-35" "cmdline-tools;latest" "cmake;3.10.2.4988404" "ndk;28.1.13356709"
- After setting up the SDK and environment variables, be sure to
**restart your terminal** to apply the changes. If you are using
an IDE with an integrated terminal, you need to restart the IDE.
- Run ``scons platform=android``. If this fails, go back and check the steps.
If you completed the setup correctly, the NDK will begin downloading.
If you are trying to compile GDExtension, you need to first compile
the engine to download the NDK, then you can compile GDExtension.
Building the export templates
-----------------------------
Godot needs three export templates for Android: the optimized "release"
template (``android_release.apk``), the debug template (``android_debug.apk``),
and the Gradle build template (``android_source.zip``).
As Google requires all APKs to include ARMv8 (64-bit) libraries since August 2019,
the commands below build templates containing both ARMv7 and ARMv8 libraries.
Compiling the standard export templates is done by calling SCons from the Godot
root directory with the following arguments:
- Release template (used when exporting with **Debugging Enabled** unchecked)
::
scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64 generate_android_binaries=yes
- Debug template (used when exporting with **Debugging Enabled** checked)
::
scons platform=android target=template_debug arch=arm32
scons platform=android target=template_debug arch=arm64 generate_android_binaries=yes
- (**Optional**) Dev template (used when troubleshooting)
::
scons platform=android target=template_debug arch=arm32 dev_build=yes
scons platform=android target=template_debug arch=arm64 dev_build=yes generate_android_binaries=yes
The resulting templates will be located under the ``bin`` directory:
- ``bin/android_release.apk`` for the release template
- ``bin/android_debug.apk`` for the debug template
- ``bin/android_dev.apk`` for the dev template
- ``bin/android_source.zip`` for the Gradle build template
.. note::
- If you are changing the list of architectures you're building, remember to add ``generate_android_binaries=yes`` to the *last* architecture you're building, so that the template files are generated after the build.
- To include debug symbols in the generated templates, add the ``debug_symbols=yes`` parameters to the SCons command.
- Note that you can include ``separate_debug_symbols=yes`` to generate the debug symbols in a separate ``*-native-debug-symbols.zip`` file.
.. seealso::
If you want to enable Vulkan validation layers, see
:ref:`Vulkan validation layers on Android <doc_vulkan_validation_layers_android>`.
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 ``arch=x86_32``, and
``arch=x86_64`` arguments before building the APK with Gradle. For
example, for the release template:
::
scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64
scons platform=android target=template_release arch=x86_32
scons platform=android target=template_release arch=x86_64 generate_android_binaries=yes
This will create template binaries that works on all platforms.
The final binary size of exported projects will depend on the platforms you choose
to support when exporting; in other words, unused platforms will be removed from
the binary.
Cleaning the generated export templates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use the following commands to remove the generated export templates:
::
cd platform/android/java
# On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean
Using the export templates
--------------------------
Godot needs release and debug binaries that were compiled against the same
version/commit as the editor. If you are using official binaries
for the editor, make sure to install the matching export templates,
or build your own from the same version.
When exporting your game, Godot uses the templates as a base, and updates their content as needed.
Installing the templates
~~~~~~~~~~~~~~~~~~~~~~~~
The newly-compiled templates (``android_debug.apk``
, ``android_release.apk``, and ``android_source.zip``) must be copied to Godot's templates folder
with their respective names. The templates folder can be located in:
- Windows: ``%APPDATA%\Godot\export_templates\<version>\``
- Linux: ``$HOME/.local/share/godot/export_templates/<version>/``
- macOS: ``$HOME/Library/Application Support/Godot/export_templates/<version>/``
``<version>`` is of the form ``major.minor[.patch].status`` using values from
``version.py`` in your Godot source repository (e.g. ``4.1.3.stable`` or ``4.2.dev``).
You also need to write this same version string to a ``version.txt`` file located
next to your export templates.
.. TODO: Move these paths to a common reference page
However, if you are writing your custom modules or custom C++ code, you
might instead want to configure your template binaries as custom export templates
in the project export menu. You must have **Advanced Options** enabled to set this.
.. image:: img/andtemplates.webp
You don't even need to copy them, you can just reference the resulting
file in the ``bin\`` directory of your Godot source folder, so that the
next time you build you will automatically have the custom templates
referenced.
Building the Godot editor
-------------------------
Compiling the editor is done by calling SCons from the Godot
root directory with the following arguments:
::
scons platform=android arch=arm32 production=yes target=editor
scons platform=android arch=arm64 production=yes target=editor
scons platform=android arch=x86_32 production=yes target=editor
scons platform=android arch=x86_64 production=yes target=editor generate_android_binaries=yes
- You can add the ``dev_build=yes`` parameter to generate a dev build of the Godot editor.
- You can add the ``debug_symbols=yes`` parameters to include the debug symbols in the generated build.
- Note that you can include ``separate_debug_symbols=yes`` to generate the debug symbols in a separate ``*-native-debug-symbols.zip`` file.
- You can skip certain architectures depending on your target device to speed up compilation.
Remember to add ``generate_android_binaries=yes`` to the *last* architecture you're building, so that binaries are generated after the build.
The resulting binaries will be located under ``bin/android_editor_builds/``.
Removing the Editor binaries
----------------------------
You can use the following commands to remove the generated editor binaries:
::
cd platform/android/java
# On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean
Installing the Godot editor APK
-------------------------------
With an Android device with Developer Options enabled, connect the Android device to your computer via its charging cable to a USB/USB-C port.
Open up a Terminal/Command Prompt and run the following commands from the root directory with the following arguments:
::
adb install ./bin/android_editor_builds/android_editor-release.apk
Troubleshooting
---------------
Platform doesn't appear in SCons
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Double-check that you've set the ``ANDROID_HOME``
environment variable. This is required for the platform to appear in SCons'
list of detected platforms.
See :ref:`Setting up the buildsystem <doc_android_setting_up_the_buildsystem>`
for more information.
Application not installed
~~~~~~~~~~~~~~~~~~~~~~~~~
Android might complain the application is not correctly installed.
If so:
- Check that the debug keystore is properly generated.
- Check that the jarsigner executable is from JDK 8.
If it still fails, open a command line and run `logcat <https://developer.android.com/studio/command-line/logcat>`_:
::
adb logcat
Then check the output while the application is installed;
the error message should be presented there.
Seek assistance if you can't figure it out.
Application exits immediately
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the application runs but exits immediately, this might be due to
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/<arch>/``
where ``<arch>`` 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.
In any case, ``adb logcat`` should also show the cause of the error.

111
engine_details/development/compiling/compiling_for_ios.rst Normal file
View File

@@ -0,0 +1,111 @@
.. _doc_compiling_for_ios:
Compiling for iOS
=================
.. highlight:: shell
.. seealso::
This page describes how to compile iOS export template binaries from source.
If you're looking to export your project to iOS instead, read :ref:`doc_exporting_for_ios`.
Requirements
------------
- `Python 3.8+ <https://www.python.org/downloads/macos/>`_.
- `SCons 4.0+ <https://scons.org/pages/download.html>`_ build system.
- `Xcode <https://apps.apple.com/us/app/xcode/id497799835>`_.
- Launch Xcode once and install iOS support. If you have already launched
Xcode and need to install iOS support, go to *Xcode -> Settings... -> Platforms*.
- Go to *Xcode -> Settings... -> Locations -> Command Line Tools* and select
an installed version. Even if one is already selected, re-select it.
- Download and follow README instructions to build a static ``.xcframework``
from the `MoltenVK SDK <https://github.com/KhronosGroup/MoltenVK#fetching-moltenvk-source-code>`__.
.. note:: If you have `Homebrew <https://brew.sh/>`_ installed, you can easily
install SCons using the following command:
::
brew install scons
Installing Homebrew will also fetch the Command Line Tools
for Xcode automatically if you don't have them already.
Similarly, if you have `MacPorts <https://www.macports.org/>`_
installed, you can easily install SCons using the
following command:
::
sudo port install scons
.. seealso:: To get the Godot source code for compiling, see
:ref:`doc_getting_source`.
For a general overview of SCons usage for Godot, see
:ref:`doc_introduction_to_the_buildsystem`.
Compiling
---------
Open a Terminal, go to the root folder of the engine source code and type
the following to compile a debug build:
::
scons platform=ios target=template_debug generate_bundle=yes
To compile a release build:
::
scons platform=ios target=template_release generate_bundle=yes
To create an Xcode project like in the official builds, you need to use the
template located in ``misc/dist/ios_xcode``. The release and debug libraries
should be placed in ``libgodot.ios.debug.xcframework`` and
``libgodot.ios.release.xcframework`` respectively. This process can be automated
by using the ``generate_bundle=yes`` option on the *last* SCons command used to
build export templates (so that all binaries can be included).
The MoltenVK static ``.xcframework`` folder must also be placed in the
``ios_xcode`` folder once it has been created. MoltenVK is always statically
linked on iOS; there is no dynamic linking option available, unlike macOS.
Run
---
To run on a device, follow these instructions:
:ref:`doc_exporting_for_ios`.
iOS exports can run directly on an Apple Silicon Mac. To run exported iOS project
on Mac, open exported project in Xcode and select ``My Mac`` in the ``Run Destinations``
dropdown.
Troubleshooting
---------------
Fatal error: 'cstdint' file not found
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you get a compilation error of this form early on, it's likely because
the Xcode command line tools installation needs to be repaired after
a macOS or Xcode update:
::
./core/typedefs.h:45:10: fatal error: 'cstdint' file not found
45 | #include <cstdint>
| ^~~~~~~~~
Run these two commands to reinstall Xcode command line tools
(enter your administrator password as needed):
::
sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install
If it still does not work, try updating Xcode from the Mac App Store and try again.

619
engine_details/development/compiling/compiling_for_linuxbsd.rst Normal file
View File

@@ -0,0 +1,619 @@
.. _doc_compiling_for_linuxbsd:
Compiling for Linux, \*BSD
==========================
.. highlight:: shell
.. seealso::
This page describes how to compile Linux editor and export template binaries from source.
If you're looking to export your project to Linux instead, read :ref:`doc_exporting_for_linux`.
Requirements
------------
For compiling under Linux or other Unix variants, the following is
required:
- GCC 9+ or Clang 6+.
- `Python 3.8+ <https://www.python.org/downloads/>`_.
- `SCons 4.0+ <https://scons.org/pages/download.html>`_ build system.
- pkg-config (used to detect the development libraries listed below).
- Development libraries:
- X11, Xcursor, Xinerama, Xi and XRandR.
- Wayland and wayland-scanner.
- Mesa.
- ALSA.
- PulseAudio.
- *Optional* - libudev (build with ``udev=yes``).
.. seealso::
To get the Godot source code for compiling, see :ref:`doc_getting_source`.
For a general overview of SCons usage for Godot, see :ref:`doc_introduction_to_the_buildsystem`.
.. _doc_compiling_for_linuxbsd_oneliners:
Distro-specific one-liners
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tabs::
.. tab:: Alpine Linux
::
apk add \
scons \
pkgconf \
gcc \
g++ \
libx11-dev \
libxcursor-dev \
libxinerama-dev \
libxi-dev \
libxrandr-dev \
mesa-dev \
eudev-dev \
alsa-lib-dev \
pulseaudio-dev
.. tab:: Arch Linux
::
pacman -Sy --noconfirm --needed \
scons \
pkgconf \
gcc \
libxcursor \
libxinerama \
libxi \
libxrandr \
wayland-utils \
mesa \
glu \
libglvnd \
alsa-lib \
pulseaudio
.. tab:: Debian/Ubuntu
::
sudo apt-get update
sudo apt-get install -y \
build-essential \
scons \
pkg-config \
libx11-dev \
libxcursor-dev \
libxinerama-dev \
libgl1-mesa-dev \
libglu1-mesa-dev \
libasound2-dev \
libpulse-dev \
libudev-dev \
libxi-dev \
libxrandr-dev \
libwayland-dev
.. tab:: Fedora
::
sudo dnf install -y \
scons \
pkgconfig \
gcc-c++ \
libstdc++-static \
wayland-devel
.. tab:: FreeBSD
::
pkg install \
py37-scons \
pkgconf \
xorg-libraries \
libXcursor \
libXrandr \
libXi \
xorgproto \
libGLU \
alsa-lib \
pulseaudio
.. tab:: Gentoo
::
emerge --sync
emerge -an \
dev-build/scons \
x11-libs/libX11 \
x11-libs/libXcursor \
x11-libs/libXinerama \
x11-libs/libXi \
dev-util/wayland-scanner \
media-libs/mesa \
media-libs/glu \
media-libs/alsa-lib \
media-sound/pulseaudio
.. tab:: Mageia
::
sudo urpmi --auto \
scons \
task-c++-devel \
wayland-devel \
"pkgconfig(alsa)" \
"pkgconfig(glu)" \
"pkgconfig(libpulse)" \
"pkgconfig(udev)" \
"pkgconfig(x11)" \
"pkgconfig(xcursor)" \
"pkgconfig(xinerama)" \
"pkgconfig(xi)" \
"pkgconfig(xrandr)"
.. tab:: NetBSD
::
pkg_add \
pkg-config \
py37-scons
.. hint::
For audio support, you can optionally install ``pulseaudio``.
.. tab:: OpenBSD
::
pkg_add \
python \
scons \
llvm
.. tab:: openKylin
::
sudo apt update
sudo apt install -y \
python3-pip \
build-essential \
pkg-config \
libx11-dev \
libxcursor-dev \
libxinerama-dev \
libgl1-mesa-dev \
libglu1-mesa-dev \
libasound2-dev \
libpulse-dev \
libudev-dev \
libxi-dev \
libxrandr-dev \
libwayland-dev
sudo pip install scons
.. tab:: openSUSE
::
sudo zypper install -y \
scons \
pkgconfig \
libX11-devel \
libXcursor-devel \
libXrandr-devel \
libXinerama-devel \
libXi-devel \
wayland-devel \
Mesa-libGL-devel \
alsa-devel \
libpulse-devel \
libudev-devel \
gcc-c++ \
libGLU1
.. tab:: Solus
::
eopkg install -y \
-c system.devel \
scons \
libxcursor-devel \
libxinerama-devel \
libxi-devel \
libxrandr-devel \
wayland-devel \
mesalib-devel \
libglu \
alsa-lib-devel \
pulseaudio-devel
Compiling
---------
Start a terminal, go to the root dir of the engine source code and type:
::
scons platform=linuxbsd
.. note::
Prior to Godot 4.0, the Linux/\*BSD target was called ``x11`` instead of
``linuxbsd``. If you are looking to compile Godot 3.x, make sure to use the
`3.x branch of this documentation <https://docs.godotengine.org/en/3.6/development/compiling/compiling_for_x11.html>`__.
.. tip::
If you are compiling Godot to make changes or contribute to the engine,
you may want to use the SCons options ``dev_build=yes`` or ``dev_mode=yes``.
See :ref:`doc_introduction_to_the_buildsystem_development_and_production_aliases`
for more info.
If all goes well, the resulting binary executable will be placed in the
"bin" subdirectory. This executable file contains the whole engine and
runs without any dependencies. Executing it will bring up the Project
Manager.
.. note::
If you wish to compile using Clang rather than GCC, use this command:
::
scons platform=linuxbsd use_llvm=yes
Using Clang appears to be a requirement for OpenBSD, otherwise fonts
would not build.
For RISC-V architecture devices, use the Clang compiler instead of the GCC compiler.
.. tip:: If you are compiling Godot for production use, you can
make the final executable smaller and faster by adding the
SCons option ``production=yes``. This enables additional compiler
optimizations and link-time optimization.
LTO takes some time to run and requires about 7 GB of available RAM
while compiling. If you're running out of memory with the above option,
use ``production=yes lto=none`` or ``production=yes lto=thin`` for a
lightweight but less effective form of LTO.
.. note:: If you want to use separate editor settings for your own Godot builds
and official releases, you can enable
:ref:`doc_data_paths_self_contained_mode` by creating a file called
``._sc_`` or ``_sc_`` in the ``bin/`` folder.
Running a headless/server build
-------------------------------
To run in *headless* mode which provides editor functionality to export
projects in an automated manner, use the normal build:
::
scons 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 <doc_command_line_tutorial>`, use:
::
scons platform=linuxbsd target=template_debug
To compile a *server* build which is optimized to run dedicated game servers, use:
::
scons platform=linuxbsd target=template_release production=yes
Building export templates
-------------------------
.. warning:: Linux binaries usually won't run on distributions that are
older than the distribution they were built on. If you wish to
distribute binaries that work on most distributions,
you should build them on an old distribution such as Ubuntu 20.04.
You can use a virtual machine or a container to set up a suitable
build environment.
To build Linux or \*BSD export templates, run the build system with the
following parameters:
- (32 bits)
::
scons platform=linuxbsd target=template_release arch=x86_32
scons platform=linuxbsd target=template_debug arch=x86_32
- (64 bits)
::
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.
To create standard export templates, the resulting files in the ``bin/`` folder
must be copied to:
::
$HOME/.local/share/godot/export_templates/<version>/
and named like this (even for \*BSD which is seen as "Linux/X11" by Godot):
.. code:: text
linux_debug.arm32
linux_debug.arm64
linux_debug.x86_32
linux_debug.x86_64
linux_release.arm32
linux_release.arm64
linux_release.x86_32
linux_release.x86_64
However, if you are writing your custom modules or custom C++ code, you
might instead want to configure your binaries as custom export templates
in the project export menu. You must have **Advanced Options** enabled
to set this.
.. image:: img/lintemplates.webp
You don't even need to copy them, you can just reference the resulting
files in the ``bin/`` directory of your Godot source folder, so the next
time you build, you automatically have the custom templates referenced.
Cross-compiling for RISC-V devices
----------------------------------
To cross-compile Godot for RISC-V devices, we need to setup the following items:
- `riscv-gnu-toolchain <https://github.com/riscv-collab/riscv-gnu-toolchain/releases>`__.
While we are not going to use this directly, it provides us with a sysroot, as well
as header and libraries files that we will need. There are many versions to choose
from, however, the older the toolchain, the more compatible our final binaries will be.
If in doubt, `use this version <https://github.com/riscv-collab/riscv-gnu-toolchain/releases/tag/2023.07.07>`__,
and download ``riscv64-glibc-ubuntu-20.04-gcc-nightly-2023.07.07-nightly.tar.gz``. Extract
it somewhere and remember its path.
- `mold <https://github.com/rui314/mold/releases>`__. This fast linker,
is the only one that correctly links the resulting binary. Download it, extract it,
and make sure to add its ``bin`` folder to your PATH. Run
``mold --help | grep support`` to check if your version of Mold supports RISC-V.
If you don't see RISC-V, your Mold may need to be updated.
To make referencing our toolchain easier, we can set an environment
variable like this:
::
export RISCV_TOOLCHAIN_PATH="path to toolchain here"
This way, we won't have to manually set the directory location
each time we want to reference it.
With all the above setup, we are now ready to build Godot.
Go to the root of the source code, and execute the following build command:
::
PATH="$RISCV_TOOLCHAIN_PATH/bin:$PATH" \
scons arch=rv64 use_llvm=yes linker=mold lto=none target=editor \
ccflags="--sysroot=$RISCV_TOOLCHAIN_PATH/sysroot --gcc-toolchain=$RISCV_TOOLCHAIN_PATH -target riscv64-unknown-linux-gnu" \
linkflags="--sysroot=$RISCV_TOOLCHAIN_PATH/sysroot --gcc-toolchain=$RISCV_TOOLCHAIN_PATH -target riscv64-unknown-linux-gnu"
.. note::
RISC-V GCC has `bugs with its atomic operations <https://github.com/riscv-collab/riscv-gcc/issues/15>`__
which prevent it from compiling Godot correctly. That's why Clang is used instead. Make sure that
it *can* compile to RISC-V. You can verify by executing this command ``clang -print-targets``,
make sure you see ``riscv64`` on the list of targets.
.. warning:: The code above includes adding ``$RISCV_TOOLCHAIN_PATH/bin`` to the PATH,
but only for the following ``scons`` command. Since riscv-gnu-toolchain uses
its own Clang located in the ``bin`` folder, adding ``$RISCV_TOOLCHAIN_PATH/bin``
to your user's PATH environment variable may block you from accessing another
version of Clang if one is installed. For this reason it's not recommended to make
adding the bin folder permanent. You can also omit the ``PATH="$RISCV_TOOLCHAIN_PATH/bin:$PATH"`` line
if you want to use scons with self-installed version of Clang, but it may have
compatibility issues with riscv-gnu-toolchain.
The command is similar in nature, but with some key changes. ``ccflags`` and
``linkflags`` append additional flags to the build. ``--sysroot`` points to
a folder simulating a Linux system, it contains all the headers, libraries,
and ``.so`` files Clang will use. ``--gcc-toolchain`` tells Clang where
the complete toolchain is, and ``-target riscv64-unknown-linux-gnu``
indicates to Clang the target architecture, and OS we want to build for.
If all went well, you should now see a ``bin`` directory, and within it,
a binary similar to the following:
.. code:: text
godot.linuxbsd.editor.rv64.llvm
You can now copy this executable to your favorite RISC-V device,
then launch it there by double-clicking, which should bring up
the project manager.
If you later decide to compile the export templates, copy the above
build command but change the value of ``target`` to ``template_debug`` for
a debug build, or ``template_release`` for a release build.
Using Clang and LLD for faster development
------------------------------------------
You can also use Clang and LLD to build Godot. This has two upsides compared to
the default GCC + GNU ld setup:
- LLD links Godot significantly faster compared to GNU ld or gold. This leads to
faster iteration times.
- Clang tends to give more useful error messages compared to GCC.
To do so, install Clang and the ``lld`` package from your distribution's package manager
then use the following SCons command:
::
scons platform=linuxbsd use_llvm=yes linker=lld
After the build is completed, a new binary with a ``.llvm`` suffix will be
created in the ``bin/`` folder.
It's still recommended to use GCC for production builds as they can be compiled using
link-time optimization, making the resulting binaries smaller and faster.
If this error occurs:
.. code:: text
/usr/bin/ld: cannot find -l:libatomic.a: No such file or directory
There are two solutions:
- In your SCons command, add the parameter ``use_static_cpp=no``.
- Follow `these instructions <https://github.com/ivmai/libatomic_ops#installation-and-usage>`__ to configure, build, and
install ``libatomic_ops``. Then, copy ``/usr/lib/libatomic_ops.a`` to ``/usr/lib/libatomic.a``, or create a soft link
to ``libatomic_ops`` by command ``ln -s /usr/lib/libatomic_ops.a /usr/lib/libatomic.a``. The soft link can ensure the
latest ``libatomic_ops`` will be used without the need to copy it every time when it is updated.
Using mold for faster development
---------------------------------
For even faster linking compared to LLD, you can use `mold <https://github.com/rui314/mold>`__.
mold can be used with either GCC or Clang.
As of January 2023, mold is not readily available in Linux distribution
repositories, so you will have to install its binaries manually.
- Download mold binaries from its `releases page <https://github.com/rui314/mold/releases/latest>`__.
- Extract the ``.tar.gz`` file, then move the extracted folder to a location such as ``.local/share/mold``.
- Add ``$HOME/.local/share/mold/bin`` to your user's ``PATH`` environment variable.
For example, you can add the following line at the end of your ``$HOME/.bash_profile`` file:
::
PATH="$HOME/.local/share/mold/bin:$PATH"
- Open a new terminal (or run ``source "$HOME/.bash_profile"``),
then use the following SCons command when compiling Godot:
::
scons platform=linuxbsd linker=mold
Using system libraries for faster development
---------------------------------------------
`Godot bundles the source code of various third-party libraries. <https://github.com/godotengine/godot/tree/master/thirdparty>`__
You can choose to use system versions of third-party libraries instead.
This makes the Godot binary faster to link, as third-party libraries are
dynamically linked. Therefore, they don't need to be statically linked
every time you build the engine (even on small incremental changes).
However, not all Linux distributions have packages for third-party libraries
available (or they may not be up-to-date).
Moving to system libraries can reduce linking times by several seconds on slow
CPUs, but it requires manual testing depending on your Linux distribution. Also,
you may not be able to use system libraries for everything due to bugs in the
system library packages (or in the build system, as this feature is less
tested).
To compile Godot with system libraries, install these dependencies **on top** of the ones
listed in the :ref:`doc_compiling_for_linuxbsd_oneliners`:
.. tabs::
.. tab:: Debian/Ubuntu
::
sudo apt-get update
sudo apt-get install -y \
libembree-dev \
libenet-dev \
libfreetype-dev \
libpng-dev \
zlib1g-dev \
libgraphite2-dev \
libharfbuzz-dev \
libogg-dev \
libtheora-dev \
libvorbis-dev \
libwebp-dev \
libmbedtls-dev \
libminiupnpc-dev \
libpcre2-dev \
libsdl3-dev \
libzstd-dev \
libsquish-dev \
libicu-dev
.. tab:: Fedora
::
sudo dnf install -y \
embree-devel \
enet-devel \
glslang-devel \
graphite2-devel \
harfbuzz-devel \
libicu-devel \
libsquish-devel \
libtheora-devel \
libvorbis-devel \
libwebp-devel \
libzstd-devel \
mbedtls-devel \
miniupnpc-devel \
SDL3-devel
After installing all required packages, use the following command to build Godot:
.. NOTE: Some `builtin_` options aren't used here because they break the build as of January 2023
(tested on Fedora 37).
::
scons platform=linuxbsd builtin_embree=no builtin_enet=no builtin_freetype=no builtin_graphite=no builtin_harfbuzz=no builtin_libogg=no builtin_libpng=no builtin_libtheora=no builtin_libvorbis=no builtin_libwebp=no builtin_mbedtls=no builtin_miniupnpc=no builtin_pcre2=no builtin_sdl=no builtin_zlib=no builtin_zstd=no
On Debian stable, you will need to remove `builtin_embree=no` as the system-provided
Embree version is too old to work with Godot's latest `master` branch
(which requires Embree 4).
You can view a list of all built-in libraries that have system alternatives by
running ``scons -h``, then looking for options starting with ``builtin_``.
.. warning::
When using system libraries, the resulting binary is **not** portable
across Linux distributions anymore. Do not use this approach for creating
binaries you intend to distribute to others, unless you're creating a
package for a Linux distribution.

281
engine_details/development/compiling/compiling_for_macos.rst Normal file
View File

@@ -0,0 +1,281 @@
.. _doc_compiling_for_macos:
Compiling for macOS
===================
.. highlight:: shell
.. note::
This page describes how to compile macOS editor and export template binaries from source.
If you're looking to export your project to macOS instead, read :ref:`doc_exporting_for_macos`.
Requirements
------------
For compiling under macOS, the following is required:
- `Python 3.8+ <https://www.python.org/downloads/macos/>`_.
- `SCons 4.0+ <https://scons.org/pages/download.html>`_ build system.
- `Xcode <https://apps.apple.com/us/app/xcode/id497799835>`_
(or the more lightweight Command Line Tools for Xcode).
- `Vulkan SDK <https://sdk.lunarg.com/sdk/download/latest/mac/vulkan-sdk.dmg>`_
for MoltenVK (macOS doesn't support Vulkan out of the box).
The latest Vulkan SDK version can be installed quickly by running
``misc/scripts/install_vulkan_sdk_macos.sh`` within the Godot source repository.
.. note:: If you have `Homebrew <https://brew.sh/>`_ installed, you can easily
install SCons using the following command:
::
brew install scons
Installing Homebrew will also fetch the Command Line Tools
for Xcode automatically if you don't have them already.
Similarly, if you have `MacPorts <https://www.macports.org/>`_
installed, you can easily install SCons using the
following command:
::
sudo port install scons
.. seealso:: To get the Godot source code for compiling, see
:ref:`doc_getting_source`.
For a general overview of SCons usage for Godot, see
:ref:`doc_introduction_to_the_buildsystem`.
Compiling
---------
Start a terminal, go to the root directory of the engine source code.
To compile for Intel (x86-64) powered Macs, use:
::
scons platform=macos arch=x86_64
To compile for Apple Silicon (ARM64) powered Macs, use:
::
scons platform=macos arch=arm64
.. tip::
If you are compiling Godot to make changes or contribute to the engine,
you may want to use the SCons options ``dev_build=yes`` or ``dev_mode=yes``.
See :ref:`doc_introduction_to_the_buildsystem_development_and_production_aliases`
for more info.
If all goes well, the resulting binary executable will be placed in the
``bin/`` subdirectory. This executable file contains the whole engine and
runs without any dependencies. Executing it will bring up the Project
Manager.
.. note:: Using a standalone editor executable is not recommended, it should be always packaged into a
``.app`` bundle to avoid UI activation issues.
.. note:: If you want to use separate editor settings for your own Godot builds
and official releases, you can enable
:ref:`doc_data_paths_self_contained_mode` by creating a file called
``._sc_`` or ``_sc_`` in the ``bin/`` folder.
Automatic ``.app`` bundle creation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To automatically create a ``.app`` bundle like in the official builds, use the ``generate_bundle=yes`` option on the *last*
SCons command used to build editor:
::
scons platform=macos arch=x86_64
scons platform=macos arch=arm64 generate_bundle=yes
Manual ``.app`` bundle creation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To support both architectures in a single "Universal 2" binary,
run the above two commands and then use ``lipo`` to bundle them together:
::
lipo -create bin/godot.macos.editor.x86_64 bin/godot.macos.editor.arm64 -output bin/godot.macos.editor.universal
To create a ``.app`` bundle, you need to use the template located in ``misc/dist/macos_tools.app``. Typically, for an optimized
editor binary built with ``dev_build=yes``:
::
cp -r misc/dist/macos_tools.app ./bin/Godot.app
mkdir -p bin/Godot.app/Contents/MacOS
cp bin/godot.macos.editor.universal bin/Godot.app/Contents/MacOS/Godot
chmod +x bin/Godot.app/Contents/MacOS/Godot
codesign --force --timestamp --options=runtime --entitlements misc/dist/macos/editor.entitlements -s - bin/Godot.app
.. note::
If you are building the ``master`` branch, you also need to include support
for the MoltenVK Vulkan portability library. By default, it will be linked
statically from your installation of the Vulkan SDK for macOS.
You can also choose to link it dynamically by passing ``use_volk=yes`` and
including the dynamic library in your ``.app`` bundle:
::
mkdir -p <Godot bundle name>.app/Contents/Frameworks
cp <Vulkan SDK path>/macOS/lib/libMoltenVK.dylib <Godot bundle name>.app/Contents/Frameworks/libMoltenVK.dylib
Running a headless/server build
-------------------------------
To run in *headless* mode which provides editor functionality to export
projects in an automated manner, use the normal build:
::
scons platform=macos target=editor
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 <doc_command_line_tutorial>`, use:
::
scons platform=macos target=template_debug
To compile a release *server* build which is optimized to run dedicated game servers, use:
::
scons platform=macos target=template_release production=yes
Building export templates
-------------------------
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 2* binaries which support both ARM64 and Intel
x86_64 architectures.
- To support ARM64 (Apple Silicon) + Intel x86_64:
::
scons platform=macos target=template_debug arch=arm64
scons platform=macos target=template_release arch=arm64
scons platform=macos target=template_debug arch=x86_64
scons platform=macos target=template_release arch=x86_64 generate_bundle=yes
- To support ARM64 (Apple Silicon) only (smaller file size, but less compatible with older hardware):
::
scons platform=macos target=template_debug arch=arm64
scons platform=macos target=template_release arch=arm64 generate_bundle=yes
To create a ``.app`` bundle like in the official builds, you need to use the
template located in ``misc/dist/macos_template.app``. This process can be automated by using
the ``generate_bundle=yes`` option on the *last* SCons command used to build export templates
(so that all binaries can be included). This option also takes care of calling ``lipo`` to create
a *Universal 2* binary from two separate ARM64 and x86_64 binaries (if both were compiled beforehand).
.. note::
You also need to include support for the MoltenVK Vulkan portability
library. By default, it will be linked statically from your installation of
the Vulkan SDK for macOS. You can also choose to link it dynamically by
passing ``use_volk=yes`` and including the dynamic library in your ``.app``
bundle:
::
mkdir -p macos_template.app/Contents/Frameworks
cp <Vulkan SDK path>/macOS/libs/libMoltenVK.dylib macos_template.app/Contents/Frameworks/libMoltenVK.dylib
In most cases, static linking should be preferred as it makes distribution
easier. The main upside of dynamic linking is that it allows updating
MoltenVK without having to recompile export templates.
You can then zip the ``macos_template.app`` folder to reproduce the ``macos.zip``
template from the official Godot distribution:
::
zip -r9 macos.zip macos_template.app
Cross-compiling for macOS from Linux
------------------------------------
It is possible to compile for macOS in a Linux environment (and maybe also in
Windows using the Windows Subsystem for Linux). For that, you'll need to install
`OSXCross <https://github.com/tpoechtrager/osxcross>`__ to be able to use macOS
as a target. First, follow the instructions to install it:
Clone the `OSXCross repository <https://github.com/tpoechtrager/osxcross>`__
somewhere on your machine (or download a ZIP file and extract it somewhere), e.g.:
::
git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross"
1. Follow the instructions to package the SDK:
https://github.com/tpoechtrager/osxcross#packaging-the-sdk
2. Follow the instructions to install OSXCross:
https://github.com/tpoechtrager/osxcross#installation
After that, you will need to define the ``OSXCROSS_ROOT`` as the path to
the OSXCross installation (the same place where you cloned the
repository/extracted the zip), e.g.:
::
export OSXCROSS_ROOT="$HOME/osxcross"
Now you can compile with SCons like you normally would:
::
scons platform=macos
If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument:
::
scons platform=macos osxcross_sdk=darwin15
Troubleshooting
---------------
Fatal error: 'cstdint' file not found
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you get a compilation error of this form early on, it's likely because
the Xcode command line tools installation needs to be repaired after
a macOS or Xcode update:
.. code:: text
./core/typedefs.h:45:10: fatal error: 'cstdint' file not found
45 | #include <cstdint>
| ^~~~~~~~~
Run these two commands to reinstall Xcode command line tools
(enter your administrator password as needed):
::
sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install
If it still does not work, try updating Xcode from the Mac App Store and try again.

14
engine_details/development/compiling/compiling_for_visionos.rst Normal file
View File

@@ -0,0 +1,14 @@
.. _doc_compiling_for_visionos:
Compiling for visionOS
======================
.. seealso::
This page describes how to compile visionOS export template binaries from source.
If you're looking to export your project to visionOS instead, see :ref:`doc_exporting_for_visionos`.
Compiling instructions for visionOS are currently identical to
:ref:`doc_compiling_for_ios`, except you should replace instances of
``platform=ios`` with ``platform=visionos`` in the SCons options.
See the linked page for details.

145
engine_details/development/compiling/compiling_for_web.rst Normal file
View File

@@ -0,0 +1,145 @@
.. _doc_compiling_for_web:
Compiling for the Web
=====================
.. seealso::
This page describes how to compile HTML5 editor and export template binaries from source.
If you're looking to export your project to HTML5 instead, read :ref:`doc_exporting_for_web`.
.. highlight:: shell
Requirements
------------
To compile export templates for the Web, the following is required:
- `Emscripten 3.1.62+ <https://emscripten.org>`__.
- `Python 3.8+ <https://www.python.org/>`__.
- `SCons 4.0+ <https://scons.org/pages/download.html>`__ build system.
.. seealso:: To get the Godot source code for compiling, see
:ref:`doc_getting_source`.
For a general overview of SCons usage for Godot, see
:ref:`doc_introduction_to_the_buildsystem`.
Building export templates
-------------------------
Before starting, confirm that ``emcc`` is available in your PATH. This is
usually configured by the Emscripten SDK, e.g. when invoking ``emsdk activate``
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 ``template_release`` for a release build or ``template_debug`` for a debug build:
::
scons platform=web target=template_release
scons platform=web target=template_debug
By default, the :ref:`JavaScriptBridge singleton <doc_web_javascript_bridge>` 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 target=template_release javascript_eval=no
scons platform=web target=template_debug javascript_eval=no
By default, WebWorker threads support is enabled. To disable it and only use a single thread,
the ``threads`` option can be used to build the web template without threads support:
::
scons platform=web target=template_release threads=no
scons platform=web target=template_debug threads=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
``godot.web.template_release.wasm32.zip`` for release or ``godot.web.template_debug.wasm32.zip``
for debug.
Finally, rename the zip archive to ``web_release.zip`` for the
release template:
::
mv bin/godot.web.template_release.wasm32.zip bin/web_release.zip
And ``web_debug.zip`` for the debug template:
::
mv bin/godot.web.template_debug.wasm32.zip bin/web_debug.zip
GDExtension
-----------
The default export templates do not include GDExtension support for
performance and compatibility reasons. See the
:ref:`export page <doc_javascript_export_options>` for more info.
You can build the export templates using the option ``dlink_enabled=yes``
to enable GDExtension support:
::
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.
Finally, rename the zip archives to ``web_dlink_release.zip`` and
``web_dlink_release.zip`` for the release template:
::
mv bin/godot.web.template_release.wasm32.dlink.zip bin/web_dlink_release.zip
mv bin/godot.web.template_debug.wasm32.dlink.zip bin/web_dlink_debug.zip
Building the editor
-------------------
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 target=editor
Once finished, the resulting file will be placed in the ``bin`` subdirectory.
Its name will be ``godot.web.editor.wasm32.zip``. You can upload the
zip content to your web server and visit it with your browser to use the editor.
Refer to the :ref:`export page <doc_javascript_export_options>` for the web
server requirements.
.. tip::
The Godot repository includes a
`Python script to host a local web server <https://raw.githubusercontent.com/godotengine/godot/master/platform/web/serve.py>`__.
This can be used to test the web editor locally.
After compiling the editor, extract the ZIP archive that was created in the
``bin/`` folder, then run the following command in the Godot repository
root:
::
# You may need to replace `python` with `python3` on some platforms.
python platform/web/serve.py
This will serve the contents of the ``bin/`` folder and open the default web
browser automatically. In the page that opens, access ``godot.editor.html``
and you should be able to test the web editor this way.
Note that for production use cases, this Python-based web server should not
be used. Instead, you should use an established web server such as Apache or
nginx.

505
engine_details/development/compiling/compiling_for_windows.rst Normal file
View File

@@ -0,0 +1,505 @@
.. _doc_compiling_for_windows:
Compiling for Windows
=====================
.. highlight:: shell
.. seealso::
This page describes how to compile Windows editor and export template binaries from source.
If you're looking to export your project to Windows instead, read :ref:`doc_exporting_for_windows`.
Requirements
------------
For compiling under Windows, the following is required:
- A C++ compiler. Use one of the following:
- `Visual Studio Community <https://www.visualstudio.com/vs/community/>`_,
version 2019 or later. Visual Studio 2022 is recommended.
**Make sure to enable C++ in the list of workflows to install.**
If you've already installed Visual Studio without C++ support, run the installer
again; it should present you a **Modify** button.
Supports ``x86_64``, ``x86_32``, and ``arm64``.
- `MinGW-w64 <https://mingw-w64.org/>`_ with GCC can be used as an alternative to
Visual Studio. Be sure to install/configure it to use the ``posix`` thread model.
**Important:** When using MinGW to compile the ``master`` branch, you need GCC 9 or later.
Supports ``x86_64`` and ``x86_32`` only.
- `MinGW-LLVM <https://github.com/mstorsjo/llvm-mingw/releases>`_ with clang can be used as
an alternative to Visual Studio and MinGW-w64.
Supports ``x86_64``, ``x86_32``, and ``arm64``.
- `Python 3.8+ <https://www.python.org/downloads/windows/>`_.
**Make sure to enable the option to add Python to the** ``PATH`` **in the installer.**
- `SCons 4.0+ <https://scons.org/pages/download.html>`_ build system. Using the
latest release is recommended, especially for proper support of recent Visual
Studio releases.
.. note:: If you have `Scoop <https://scoop.sh/>`_ installed, you can easily
install MinGW and other dependencies using the following command:
::
scoop install python mingw
Scons will still need to be installed via pip
.. note:: If you have `MSYS2 <https://www.msys2.org/>`_ installed, you can easily
install MinGW and other dependencies using the following command:
::
pacman -S mingw-w64-x86_64-gcc mingw-w64-i686-gcc make python-pip
For each MSYS2 MinGW subsystem, you should then run
`pip3 install scons` in its shell.
.. seealso:: To get the Godot source code for compiling, see
:ref:`doc_getting_source`.
For a general overview of SCons usage for Godot, see
:ref:`doc_introduction_to_the_buildsystem`.
Setting up SCons
----------------
To install SCons, open the command prompt and run the following command:
::
python -m pip install scons
If you are prompted with the message
``Defaulting to user installation because normal site-packages is not
writeable``, you may have to run that command again using elevated
permissions. Open a new command prompt as an Administrator then run the command
again to ensure that SCons is available from the ``PATH``.
To check whether you have installed Python and SCons correctly, you can
type ``python --version`` and ``scons --version`` into a command prompt
(``cmd.exe``).
If the commands above don't work, make sure to add Python to your ``PATH``
environment variable after installing it, then check again.
You can do so by running the Python installer again and enabling the option
to add Python to the ``PATH``.
If SCons cannot detect your Visual Studio installation, it might be that your
SCons version is too old. Update it to the latest version with
``python -m pip install --upgrade scons``.
.. _doc_compiling_for_windows_install_vs:
Downloading Godot's source
--------------------------
Refer to :ref:`doc_getting_source` for detailed instructions.
The tutorial will assume from now on that you placed the source code in
``C:\godot``.
.. warning::
To prevent slowdowns caused by continuous virus scanning during compilation,
add the Godot source folder to the list of exceptions in your antivirus
software.
For Windows Defender, hit the :kbd:`Windows` key, type "Windows Security"
then hit :kbd:`Enter`. Click on **Virus & threat protection** on the left
panel. Under **Virus & threat protection settings** click on **Manage Settings**
and scroll down to **Exclusions**. Click **Add or remove exclusions** then
add the Godot source folder.
Compiling
---------
Selecting a compiler
~~~~~~~~~~~~~~~~~~~~
SCons will automatically find and use an existing Visual Studio installation.
If you do not have Visual Studio installed, it will attempt to use
MinGW instead. If you already have Visual Studio installed and want to
use MinGW-w64, pass ``use_mingw=yes`` to the SCons command line. Note that MSVC
builds cannot be performed from the MSYS2 or MinGW shells. Use either
``cmd.exe`` or PowerShell instead. If you are using MinGW-LLVM, pass both
``use_mingw=yes`` and ``use_llvm=yes`` to the SCons command line.
.. tip::
During development, using the Visual Studio compiler is usually a better
idea, as it links the Godot binary much faster than MinGW. However, MinGW
can produce more optimized binaries using link-time optimization (see
below), making it a better choice for production use. This is particularly
the case for the GDScript VM which performs much better with MinGW compared
to MSVC. Therefore, it's recommended to use MinGW to produce builds that you
distribute to players.
All official Godot binaries are built in
`custom containers <https://github.com/godotengine/build-containers>`__
using MinGW.
Running SCons
~~~~~~~~~~~~~
After opening a command prompt, change to the root directory of
the engine source code (using ``cd``) and type:
.. code-block:: doscon
C:\godot> scons platform=windows
.. note:: When compiling with multiple CPU threads, SCons may warn about
pywin32 being missing. You can safely ignore this warning.
.. tip::
If you are compiling Godot to make changes or contribute to the engine,
you may want to use the SCons options ``dev_build=yes`` or ``dev_mode=yes``.
See :ref:`doc_introduction_to_the_buildsystem_development_and_production_aliases`
for more info.
If all goes well, the resulting binary executable will be placed in
``C:\godot\bin\`` with the name ``godot.windows.editor.x86_32.exe`` or
``godot.windows.editor.x86_64.exe``. By default, SCons will build a binary matching
your CPU architecture, but this can be overridden using ``arch=x86_64``,
``arch=x86_32``, or ``arch=arm64``.
This executable file contains the whole engine and runs without any
dependencies. Running it will bring up the Project Manager.
.. tip:: If you are compiling Godot for production use, you can
make the final executable smaller and faster by adding the
SCons option ``production=yes``. This enables additional compiler
optimizations and link-time optimization.
LTO takes some time to run and requires up to 30 GB of available RAM
while compiling (depending on toolchain). If you're running out of memory
with the above option, use ``production=yes lto=none`` or ``production=yes lto=thin``
(LLVM only) for a lightweight but less effective form of LTO.
.. note:: If you want to use separate editor settings for your own Godot builds
and official releases, you can enable
:ref:`doc_data_paths_self_contained_mode` by creating a file called
``._sc_`` or ``_sc_`` in the ``bin/`` folder.
Compiling with support for Direct3D 12
--------------------------------------
By default, builds of Godot do not contain support for the Direct3D 12 graphics
API.
You can install the required dependencies by running
``python misc/scripts/install_d3d12_sdk_windows.py``
in the Godot source repository. After running this script, add the ``d3d12=yes``
SCons option to enable Direct3D 12 support. This will use the default paths for
the various dependencies, which match the ones used in the script.
You can find the detailed steps below if you wish to set up dependencies
manually, but the above script handles everything for you (including the
optional PIX and Agility SDK components).
- `godot-nir-static library <https://github.com/godotengine/godot-nir-static/releases/>`_.
We compile the Mesa libraries you will need into a static library. Download it
anywhere, unzip it and remember the path to the unzipped folder, you will
need it below.
.. note:: You can optionally build the godot-nir-static libraries yourself with
the following steps:
1. Install the Python package `mako <https://www.makotemplates.org>`_
which is needed to generate some files.
2. Clone the `godot-nir-static <https://github.com/godotengine/godot-nir-static>`_
directory and navigate to it.
3. Run the following:
::
git submodule update --init
./update_mesa.sh
scons
If you are building with MinGW-w64, add ``use_mingw=yes`` to the ``scons``
command, you can also specify build architecture using ``arch={architecture}``.
If you are building with MinGW-LLVM, add both ``use_mingw=yes`` and
``use_llvm=yes`` to the ``scons`` command.
If you are building with MinGW and the binaries are not located in
the ``PATH``, add ``mingw_prefix="/path/to/mingw"`` to the ``scons``
command.
Mesa static library should be built using the same compiler and the
same CRT (if you are building with MinGW) you are using for building
Godot.
Optionally, you can compile with the following for additional features:
- `PIX <https://devblogs.microsoft.com/pix/download>`_ is a performance tuning
and debugging application for Direct3D12 applications. If you compile-in
support for it, you can get much more detailed information through PIX that
will help you optimize your game and troubleshoot graphics bugs. To use it,
download the WinPixEventRuntime package. You will be taken to a NuGet package
page where you can click "Download package" to get it. Once downloaded, change
the file extension to .zip and unzip the file to some path.
- `Agility SDK <https://devblogs.microsoft.com/directx/directx12agility>`_ can
be used to provide access to the latest Direct3D 12 features without relying
on driver updates. To use it, download the latest Agility SDK package. You
will be taken to a NuGet package page where you can click "Download package"
to get it. Once downloaded, change the file extension to .zip and unzip the
file to some path.
.. note:: If you use a preview version of the Agility SDK, remember to enable
developer mode in Windows; otherwise it won't be used.
.. note:: If you want to use a PIX with MinGW build, navigate to PIX runtime
directory and use the following commands to generate import library:
::
# For x86-64:
gendef ./bin/x64/WinPixEventRuntime.dll
dlltool --machine i386:x86-64 --no-leading-underscore -d WinPixEventRuntime.def -D WinPixEventRuntime.dll -l ./bin/x64/libWinPixEventRuntime.a
# For ARM64:
gendef ./bin/ARM64/WinPixEventRuntime.dll
dlltool --machine arm64 --no-leading-underscore -d WinPixEventRuntime.def -D WinPixEventRuntime.dll -l ./bin/ARM64/libWinPixEventRuntime.a
When building Godot, you will need to tell SCons to use Direct3D 12 and where to
look for the additional libraries:
.. code-block:: doscon
C:\godot> scons platform=windows d3d12=yes mesa_libs=<...>
Or, with all options enabled:
.. code-block:: doscon
C:\godot> scons platform=windows d3d12=yes mesa_libs=<...> agility_sdk_path=<...> pix_path=<...>
.. note:: For the Agility SDK's DLLs you have to explicitly choose the kind of
workflow. Single-arch is the default (DLLs copied to ``bin/``). If you
pass ``agility_sdk_multi_arch=yes`` to SCons, you'll opt-in for
multi-arch. DLLs will be copied to the appropriate ``bin/<arch>/``
subdirectories and at runtime the right one will be loaded.
Compiling with ANGLE support
----------------------------
ANGLE provides a translation layer from OpenGL ES 3.x to Direct3D 11 and can be used
to improve support for the Compatibility renderer on some older GPUs with outdated
OpenGL drivers and on Windows for ARM.
By default, Godot is built with dynamically linked ANGLE, you can use it by placing
``libEGL.dll`` and ``libGLESv2.dll`` alongside the executable.
.. note:: You can use dynamically linked ANGLE with export templates as well, rename
aforementioned DLLs to ``libEGL.{architecture}.dll`` and ``libGLESv2.{architecture}.dll``
and place them alongside export template executables, and libraries will
be automatically copied during the export process.
To compile Godot with statically linked ANGLE:
- Download pre-built static libraries from `godot-angle-static library <https://github.com/godotengine/godot-angle-static/releases>`_, and unzip them.
- When building Godot, add ``angle_libs={path}`` to tell SCons where to look for the ANGLE libraries:
::
scons platform=windows angle_libs=<...>
.. note:: You can optionally build the godot-angle-static libraries yourself with
the following steps:
1. Clone the `godot-angle-static <https://github.com/godotengine/godot-angle-static>`_
directory and navigate to it.
2. Run the following command:
::
git submodule update --init
./update_angle.sh
scons
If you are buildng with MinGW, add ``use_mingw=yes`` to the command,
you can also specify build architecture using ``arch={architecture}``.
If you are building with MinGW-LLVM, add both ``use_mingw=yes`` and
``use_llvm=yes`` to the ``scons`` command.
If you are building with MinGW and the binaries are not located in
the ``PATH``, add ``mingw_prefix="/path/to/mingw"`` to the ``scons``
command.
ANGLE static library should be built using the same compiler and the
same CRT (if you are building with MinGW) you are using for building
Godot.
Development in Visual Studio
----------------------------
Using an IDE is not required to compile Godot, as SCons takes care of everything.
But if you intend to do engine development or debugging of the engine's C++ code,
you may be interested in configuring a code editor or an IDE.
Folder-based editors don't require any particular setup to start working with Godot's
codebase. To edit projects with Visual Studio they need to be set up as a solution.
You can create a Visual Studio solution via SCons by running SCons with
the ``vsproj=yes`` parameter, like this:
::
scons platform=windows vsproj=yes
You will be able to open Godot's source in a Visual Studio solution now,
and able to build Godot using Visual Studio's **Build** button.
.. seealso:: See :ref:`doc_configuring_an_ide_vs` for further details.
Cross-compiling for Windows from other operating systems
--------------------------------------------------------
If you are a Linux or macOS user, you need to install
`MinGW-w64 <https://www.mingw-w64.org/>`__, which typically comes in 32-bit
and 64-bit variants, or `MinGW-LLVM <https://github.com/mstorsjo/llvm-mingw/releases>`_,
which comes as a single archive for all target architectures.
The package names may differ based on your distribution, here are some known ones:
+----------------+--------------------------------------------------------------+
| **Arch Linux** | :: |
| | |
| | pacman -S mingw-w64 |
+----------------+--------------------------------------------------------------+
| **Debian** / | :: |
| **Ubuntu** | |
| | apt install mingw-w64 |
+----------------+--------------------------------------------------------------+
| **Fedora** | :: |
| | |
| | dnf install mingw64-gcc-c++ mingw64-winpthreads-static \ |
| | mingw32-gcc-c++ mingw32-winpthreads-static |
+----------------+--------------------------------------------------------------+
| **macOS** | :: |
| | |
| | brew install mingw-w64 |
+----------------+--------------------------------------------------------------+
| **Mageia** | :: |
| | |
| | urpmi mingw64-gcc-c++ mingw64-winpthreads-static \ |
| | mingw32-gcc-c++ mingw32-winpthreads-static |
+----------------+--------------------------------------------------------------+
Before attempting the compilation, SCons will check for
the following binaries in your ``PATH`` environment variable:
::
# for MinGW-w64
i686-w64-mingw32-gcc
x86_64-w64-mingw32-gcc
# for MinGW-LLVM
aarch64-w64-mingw32-clang
i686-w64-mingw32-clang
x86_64-w64-mingw32-clang
If the binaries are not located in the ``PATH`` (e.g. ``/usr/bin``),
you can define the following environment variable to give a hint to
the build system:
::
export MINGW_PREFIX="/path/to/mingw"
Where ``/path/to/mingw`` is the path containing the ``bin`` directory where
``i686-w64-mingw32-gcc`` and ``x86_64-w64-mingw32-gcc`` are located (e.g.
``/opt/mingw-w64`` if the binaries are located in ``/opt/mingw-w64/bin``).
To make sure you are doing things correctly, executing the following in
the shell should result in a working compiler (the version output may
differ based on your system):
::
${MINGW_PREFIX}/bin/x86_64-w64-mingw32-gcc --version
# x86_64-w64-mingw32-gcc (GCC) 13.2.0
.. note:: If you are building with MinGW-LLVM, add ``use_llvm=yes`` to the ``scons`` command.
.. note:: When cross-compiling for Windows using MinGW-w64, keep in mind only
``x86_64`` and ``x86_32`` architectures are supported. MinGW-LLVM supports
``arm64`` as well. Be sure to specify the right ``arch=`` option when
invoking SCons if building from a different architecture.
Troubleshooting
~~~~~~~~~~~~~~~
Cross-compiling from some Ubuntu versions may lead to
`this bug <https://github.com/godotengine/godot/issues/9258>`_,
due to a default configuration lacking support for POSIX threading.
You can change that configuration following those instructions, for 64-bit:
::
sudo update-alternatives --config x86_64-w64-mingw32-gcc
<choose x86_64-w64-mingw32-gcc-posix from the list>
sudo update-alternatives --config x86_64-w64-mingw32-g++
<choose x86_64-w64-mingw32-g++-posix from the list>
And for 32-bit:
::
sudo update-alternatives --config i686-w64-mingw32-gcc
<choose i686-w64-mingw32-gcc-posix from the list>
sudo update-alternatives --config i686-w64-mingw32-g++
<choose i686-w64-mingw32-g++-posix from the list>
Creating Windows export templates
---------------------------------
Windows export templates are created by compiling Godot without the editor,
with the following flags:
.. code-block:: doscon
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
C:\godot> scons platform=windows target=template_debug arch=arm64
C:\godot> scons platform=windows target=template_release arch=arm64
If you plan on replacing the standard export templates, copy these to the
following location, replacing ``<version>`` with the version identifier
(such as ``4.2.1.stable`` or ``4.3.dev``):
.. code-block:: none
%APPDATA%\Godot\export_templates\<version>\
With the following names:
::
windows_debug_x86_32_console.exe
windows_debug_x86_32.exe
windows_debug_x86_64_console.exe
windows_debug_x86_64.exe
windows_debug_arm64_console.exe
windows_debug_arm64.exe
windows_release_x86_32_console.exe
windows_release_x86_32.exe
windows_release_x86_64_console.exe
windows_release_x86_64.exe
windows_release_arm64_console.exe
windows_release_arm64.exe
However, if you are using custom modules or custom engine code, you
may instead want to configure your binaries as custom export templates
in the project export menu. You must have **Advanced Options** enabled
to set this.
.. image:: img/wintemplates.webp
You don't need to copy them in this case, just reference the resulting
files in the ``bin\`` directory of your Godot source folder, so the next
time you build, you will automatically have the custom templates referenced.

234
engine_details/development/compiling/compiling_with_dotnet.rst Normal file
View File

@@ -0,0 +1,234 @@
.. _doc_compiling_with_dotnet:
Compiling with .NET
===================
.. highlight:: shell
Requirements
------------
- `.NET SDK 8.0+ <https://dotnet.microsoft.com/download>`_
You can use ``dotnet --info`` to check which .NET SDK versions are installed.
Enable the .NET module
----------------------
.. note:: C# support for Godot has historically used the
`Mono <https://www.mono-project.com/>`_ runtime instead of the
`.NET Runtime <https://github.com/dotnet/runtime>`_ and internally
many things are still named ``mono`` instead of ``dotnet`` or
otherwise referred to as ``mono``.
By default, the .NET module is disabled when building. To enable it, add the
option ``module_mono_enabled=yes`` to the SCons command line, while otherwise
following the instructions for building the desired Godot binaries.
Generate the glue
-----------------
Parts of the sources of the managed libraries are generated from the ClassDB.
These source files must be generated before building the managed libraries.
They can be generated by any .NET-enabled Godot editor binary by running it with
the parameters ``--headless --generate-mono-glue`` followed by the path to an
output directory.
This path must be ``modules/mono/glue`` in the Godot directory:
::
<godot_binary> --headless --generate-mono-glue modules/mono/glue
This command will tell Godot to generate the C# bindings for the Godot API at
``modules/mono/glue/GodotSharp/GodotSharp/Generated``, and the C# bindings for
the editor tools at ``modules/mono/glue/GodotSharp/GodotSharpEditor/Generated``.
Once these files are generated, you can build Godot's managed libraries for all
the desired targets without having to repeat this process.
``<godot_binary>`` refers to the editor binary you compiled with the .NET module
enabled. Its exact name will differ based on your system and configuration, but
should be of the form ``bin/godot.<platform>.editor.<arch>.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 .NET support, you
might have similarly named binaries without this suffix. These binaries can't be
used to generate the .NET glue.
.. note:: 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.
Godot will print an error at startup if there is an API mismatch
between ClassDB and the glue sources.
Building the managed libraries
------------------------------
Once you have generated the .NET glue, you can build the managed libraries with
the ``build_assemblies.py`` script:
::
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin
If everything went well, the ``GodotSharp`` directory, containing the managed
libraries, should have been created in the ``bin`` directory.
.. note:: By default, all development builds share a version number, which can
cause some issues with caching of the NuGet packages. To solve this
issue either use ``GODOT_VERSION_STATUS`` to give every build a unique
version or delete ``GodotNuGetFallbackFolder`` after every build to
clear the package cache.
Unlike "classical" Godot builds, when building with the .NET module enabled
(and depending on the target platform), a data directory may be created both
for the editor and for exported projects. This directory is important for
proper functioning and must be distributed together with Godot.
More details about this directory in
:ref:`Data directory<compiling_with_dotnet_data_directory>`.
Build Platform
~~~~~~~~~~~~~~
Provide the ``--godot-platform=<platform>`` argument to control for which
platform specific the libraries are built. Omit this argument to build for the
current system.
This currently only controls the inclusion of the support for Visual Studio as
an external editor, the libraries are otherwise identical.
NuGet packages
~~~~~~~~~~~~~~
The API assemblies, source generators, and custom MSBuild project SDK are
distributed as NuGet packages. This is all transparent to the user, but it can
make things complicated during development.
In order to use Godot with a development version of those packages, a local
NuGet source must be created where MSBuild can find them.
First, pick a location for the local NuGet source. If you don't have a
preference, create an empty directory at one of these recommended locations:
- On Windows, ``C:\Users\<username>\MyLocalNugetSource``
- On Linux, \*BSD, etc., ``~/MyLocalNugetSource``
This path is referred to later as ``<my_local_source>``.
After picking a directory, run this .NET CLI command to configure NuGet to use
your local source:
::
dotnet nuget add source <my_local_source> --name MyLocalNugetSource
When you run the ``build_assemblies.py`` script, pass ``<my_local_source>`` to
the ``--push-nupkgs-local`` option:
::
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source>
This option ensures the packages will be added to the specified local NuGet
source and that conflicting versions of the package are removed from the NuGet
cache. It's recommended to always use this option when building the C# solutions
during development to avoid mistakes.
Building without depending on deprecated features (NO_DEPRECATED)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When building Godot without deprecated classes and functions, i.e. the ``deprecated=no``
argument for scons, the managed libraries must also be built without dependencies to deprecated code.
This is done by passing the ``--no-deprecated`` argument:
::
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --no-deprecated
Double Precision Support (REAL_T_IS_DOUBLE)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When building Godot with double precision support, i.e. the ``precision=double``
argument for scons, the managed libraries must be adjusted to match by passing
the ``--precision=double`` argument:
::
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --precision=double
Examples
--------
Example (Windows)
~~~~~~~~~~~~~~~~~
::
# Build editor binary
scons platform=windows target=editor module_mono_enabled=yes
# Build export templates
scons platform=windows target=template_debug module_mono_enabled=yes
scons platform=windows target=template_release module_mono_enabled=yes
# Generate glue sources
bin/godot.windows.editor.x86_64.mono --headless --generate-mono-glue modules/mono/glue
# Build .NET assemblies
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --godot-platform=windows
Example (Linux, \*BSD)
~~~~~~~~~~~~~~~~~~~~~~
::
# Build editor binary
scons platform=linuxbsd target=editor module_mono_enabled=yes
# Build export templates
scons platform=linuxbsd target=template_debug module_mono_enabled=yes
scons platform=linuxbsd target=template_release module_mono_enabled=yes
# Generate glue sources
bin/godot.linuxbsd.editor.x86_64.mono --headless --generate-mono-glue modules/mono/glue
# Generate binaries
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --godot-platform=linuxbsd
.. _compiling_with_dotnet_data_directory:
Data directory
--------------
The data directory is a dependency for Godot binaries built with the .NET module
enabled. It contains important files for the correct functioning of Godot. It
must be distributed together with the Godot executable.
Editor
~~~~~~
The name of the data directory for the Godot editor will always be
``GodotSharp``. This directory contains an ``Api`` subdirectory with the Godot
API assemblies and a ``Tools`` subdirectory with the tools required by the
editor, like the ``GodotTools`` assemblies and its dependencies.
On macOS, if the Godot editor is distributed as a bundle, the ``GodotSharp``
directory may be placed in the ``<bundle_name>.app/Contents/Resources/``
directory inside the bundle.
Export templates
~~~~~~~~~~~~~~~~
The data directory for exported projects is generated by the editor during the
export. It is named ``data_<APPNAME>_<ARCH>``, where ``<APPNAME>`` is the
application name as specified in the project setting ``application/config/name``
and ``<ARCH>`` is the current architecture of the export.
In the case of multi-architecture exports multiple such data directories will be
generated.
Command-line options
--------------------
The following is the list of command-line options available when building with
the .NET module:
- **module_mono_enabled**\ =yes | **no**
- Build Godot with the .NET module enabled.

86
engine_details/development/compiling/compiling_with_script_encryption_key.rst Normal file
View File

@@ -0,0 +1,86 @@
.. _doc_compiling_with_script_encryption_key:
Compiling with PCK encryption key
=================================
.. highlight:: shell
The export dialog gives you the option to encrypt your PCK file with a 256-bit
AES key when releasing your project. This will make sure your scenes, scripts
and other resources are not stored in plain text and can not easily be ripped
by some script kiddie.
Of course, the key needs to be stored in the binary, but if it's compiled,
optimized and without symbols, it would take some effort to find it.
For this to work, you need to build the export templates from source,
with that same key.
.. warning::
This will **not** work if you use official, precompiled export templates.
It is absolutely **required** to compile your own export templates to use
PCK encryption.
Step by step
------------
1. Generate a 256-bit AES key in hexadecimal format. You can use the aes-256-cbc variant from
`this service <https://asecuritysite.com/encryption/keygen>`_.
Alternatively, you can generate it yourself using
`OpenSSL <https://www.openssl.org/>`__ command-line tools:
::
openssl rand -hex 32 > godot.gdkey
The output in ``godot.gdkey`` should be similar to:
::
# NOTE: Do not use the key below! Generate your own key instead.
aeb1bc56aaf580cc31784e9c41551e9ed976ecba10d315db591e749f3f64890f
You can generate the key without redirecting the output to a file, but
that way you can minimize the risk of exposing the key.
2. Set this key as environment variable in the console that you will use to
compile Godot, like this:
.. tabs::
.. code-tab:: bash Linux/macOS
export SCRIPT_AES256_ENCRYPTION_KEY="your_generated_key"
.. code-tab:: bat Windows (cmd)
set SCRIPT_AES256_ENCRYPTION_KEY=your_generated_key
.. code-tab:: bat Windows (PowerShell)
$env:SCRIPT_AES256_ENCRYPTION_KEY="your_generated_key"
3. Compile Godot export templates and set them as custom export templates
in the export preset options.
4. Set the encryption key in the **Encryption** tab of the export preset:
.. image:: img/encryption_key.png
5. Add filters for the files/folders to encrypt. **By default**, include filters
are empty and **nothing will be encrypted**.
6. Export the project. The project should run with the files encrypted now.
Troubleshooting
---------------
If you get an error like below, it means the key wasn't properly included in
your Godot build. Godot is encrypting PCK file during export, but can't read
it at runtime.
::
ERROR: open_and_parse: Condition "String::md5(md5.digest) != String::md5(md5d)" is true. Returning: ERR_FILE_CORRUPT
At: core/io/file_access_encrypted.cpp:103

127
engine_details/development/compiling/cross-compiling_for_ios_on_linux.rst Normal file
View File

@@ -0,0 +1,127 @@
.. _doc_cross-compiling_for_ios_on_linux:
Cross-compiling for iOS on Linux
================================
.. highlight:: shell
The procedure for this is somewhat complex and requires a lot of steps,
but once you have the environment properly configured you can
compile Godot for iOS anytime you want.
Disclaimer
----------
While it is possible to compile for iOS on a Linux environment, Apple is
very restrictive about the tools to be used (especially hardware-wise),
allowing pretty much only their products to be used for development. So
this is **not official**. However, in 2010 Apple said they relaxed some of the
`App Store review guidelines <https://developer.apple.com/app-store/review/guidelines/>`__
to allow any tool to be used, as long as the resulting binary does not
download any code, which means it should be OK to use the procedure
described here and cross-compiling the binary.
Requirements
------------
- `XCode with the iOS SDK <https://developer.apple.com/download/all/?q=Xcode>`__
(you must be logged into an Apple ID to download Xcode).
- `Clang >= 3.5 <https://clang.llvm.org>`__ for your development
machine installed and in the ``PATH``. It has to be version >= 3.5
to target ``arm64`` architecture.
- `xar <https://mackyle.github.io/xar/>`__ and `pbzx <https://github.com/NiklasRosenstein/pbzx>`__
(required to extract the ``.xip`` archive Xcode comes in).
- For building xar and pbzx, you may want to follow
`this guide <https://gist.github.com/phracker/1944ce190e01963c550566b749bd2b54>`__.
- `cctools-port <https://github.com/tpoechtrager/cctools-port>`__
for the needed build tools. The procedure for building is quite
peculiar and is described below.
- This also has some extra dependencies: automake, autogen, libtool.
Configuring the environment
---------------------------
Preparing the SDK
~~~~~~~~~~~~~~~~~
Extract the Xcode ``.xip`` file you downloaded from Apple's developer website:
::
mkdir xcode
xar -xf /path/to/Xcode_X.x.xip -C xcode
pbzx -n Content | cpio -i
[...]
######### Blocks
Note that for the commands below, you will need to replace the version (``x.x``)
with whatever iOS SDK version you're using. If you don't know your iPhone SDK
version, you can see the JSON file inside of
``Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs``.
Extract the iOS SDK:
::
export IOS_SDK_VERSION="x.x"
mkdir -p iPhoneSDK/iPhoneOS${IOS_SDK_VERSION}.sdk
cp -r xcode/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/* iPhoneSDK/iPhoneOS${IOS_SDK_VERSION}.sdk
cp -r xcode/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/include/c++/* iPhoneSDK/iPhoneOS${IOS_SDK_VERSION}.sdk/usr/include/c++
fusermount -u xcode
Pack the SDK so that cctools can use it:
::
cd iPhoneSDK
tar -cf - * | xz -9 -c - > iPhoneOS${IOS_SDK_VERSION}.sdk.tar.xz
Toolchain
~~~~~~~~~
Build cctools:
::
git clone https://github.com/tpoechtrager/cctools-port.git
cd cctools-port/usage_examples/ios_toolchain
./build.sh /path/iPhoneOS${IOS_SDK_VERSION}.sdk.tar.xz arm64
Copy the tools to a nicer place. Note that the SCons scripts for
building will look under ``usr/bin`` inside the directory you provide
for the toolchain binaries, so you must copy to such subdirectory, akin
to the following commands:
::
mkdir -p "$HOME/iostoolchain/usr"
cp -r target/bin "$HOME/iostoolchain/usr/"
Now you should have the iOS toolchain binaries in
``$HOME/iostoolchain/usr/bin``.
Compiling Godot for iPhone
--------------------------
Once you've done the above steps, you should keep two things in your
environment: the built toolchain and the iPhoneOS SDK directory. Those
can stay anywhere you want since you have to provide their paths to the
SCons build command.
For the iPhone platform to be detected, you need the ``OSXCROSS_IOS``
environment variable defined to anything.
::
export OSXCROSS_IOS="anything"
Now you can compile for iPhone using SCons like the standard Godot
way, with some additional arguments to provide the correct paths:
::
scons platform=ios arch=arm64 target=template_release IOS_SDK_PATH="/path/to/iPhoneSDK" IOS_TOOLCHAIN_PATH="/path/to/iostoolchain" ios_triple="arm-apple-darwin11-"

67
engine_details/development/compiling/getting_source.rst Normal file
View File

@@ -0,0 +1,67 @@
.. _doc_getting_source:
Getting the source
==================
.. highlight:: shell
Downloading the Godot source code
---------------------------------
Before :ref:`getting into the SCons build system <doc_introduction_to_the_buildsystem>`
and compiling Godot, you need to actually download the Godot source code.
The source code is available on `GitHub <https://github.com/godotengine/godot>`__
and while you can manually download it via the website, in general you want to
do it via the ``git`` version control system.
If you are compiling in order to make contributions or pull requests, you should
follow the instructions from the `Pull Request workflow <https://contributing.godotengine.org/en/latest/organization/pull_requests/creating_pull_requests.html>`__.
If you don't know much about ``git`` yet, there are a great number of
`tutorials <https://git-scm.com/book>`__ available on various websites.
In general, you need to install ``git`` and/or one of the various GUI clients.
Afterwards, to get the latest development version of the Godot source code
(the unstable ``master`` branch), you can use ``git clone``.
If you are using the ``git`` command line client, this is done by entering
the following in a terminal:
::
git clone https://github.com/godotengine/godot.git
# You can add the --depth 1 argument to omit the commit history (shallow clone).
# A shallow clone is faster, but not all Git operations (like blame) will work.
For any stable release, visit the `release page <https://github.com/godotengine/godot/releases>`__
and click on the link for the release you want.
You can then download and extract the source from the download link on the page.
With ``git``, you can also clone a stable release by specifying its branch or tag
after the ``--branch`` (or just ``-b``) argument:
::
# Clone the continuously maintained stable branch (`4.4` as of writing).
git clone https://github.com/godotengine/godot.git -b 4.4
# Clone the `4.4-stable` tag. This is a fixed revision that will never change.
git clone https://github.com/godotengine/godot.git -b 4.4-stable
# After cloning, optionally go to a specific commit.
# This can be used to access the source code at a specific point in time,
# e.g. for development snapshots, betas and release candidates.
cd godot
git checkout f4af8201bac157b9d47e336203d3e8a8ef729de2
The `maintenance branches <https://github.com/godotengine/godot/branches/all>`__
are used to release further patches on each minor version.
You can get the source code for each release and pre-release in ``.tar.xz`` format from
`godotengine/godot-builds on GitHub <https://github.com/godotengine/godot-builds/releases>`__.
This lacks version control information but has a slightly smaller download size.
After downloading the Godot source code,
you can :ref:`continue to compiling Godot <doc_introduction_to_the_buildsystem>`.

BIN
engine_details/development/compiling/img/andtemplates.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
engine_details/development/compiling/img/encryption_key.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

BIN
engine_details/development/compiling/img/lintemplates.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
engine_details/development/compiling/img/wintemplates.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

75
engine_details/development/compiling/index.rst Normal file
View File

@@ -0,0 +1,75 @@
:allow_comments: False
.. _doc_compiling_index:
Building from source
====================
.. highlight:: shell
Godot prides itself on being very easy to build, by C++ project 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 targeting 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.
.. rubric:: Basics of building Godot
:heading-level: 2
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
.. rubric:: Building for target platforms
:heading-level: 2
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
compiling_for_android
compiling_for_ios
compiling_for_visionos
compiling_for_web
cross-compiling_for_ios_on_linux
.. rubric:: Other compilation targets and options
:heading-level: 2
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
compiling_with_script_encryption_key
optimizing_for_size

496
engine_details/development/compiling/introduction_to_the_buildsystem.rst Normal file
View File

@@ -0,0 +1,496 @@
.. _doc_introduction_to_the_buildsystem:
Introduction to the buildsystem
===============================
.. highlight:: shell
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:
::
scons
This produces an editor build for your current platform, operating system, and architecture.
You can change what gets built by specifying a target, a platform, and/or an architecture.
For example, to build an export template used for running exported games, you can run:
::
scons target=template_release
If you plan to debug or develop the engine, then you might want to enable the ``dev_build``
option to enable dev-only debugging code:
::
scons 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`
- :ref:`doc_compiling_for_linuxbsd`
- :ref:`doc_compiling_for_macos`
- :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 the system has 4 CPU threads or fewer, it will use all threads by default.
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 12 threads:
::
scons -j12
Platform selection
------------------
Godot's build system will begin by detecting the platforms it can build
for. If not detected, the platform will simply not appear on the list of
available platforms. The build requirements for each platform are
described in the rest of this tutorial section.
SCons is invoked by just calling ``scons``. If no platform is specified,
SCons will detect the target platform automatically based on the host platform.
It will then start building for the target platform right away.
To list the available target platforms, use ``scons platform=list``:
.. code:: text
scons platform=list
scons: Reading SConscript files ...
The following platforms are available:
android
ios
linuxbsd
macos
web
windows
Please run SCons again and select a valid platform: platform=<string>
To build for a platform (for example, ``linuxbsd``), run with the ``platform=``
(or ``p=`` to make it short) argument:
::
scons platform=linuxbsd
.. _doc_introduction_to_the_buildsystem_resulting_binary:
Resulting binary
----------------
The resulting binaries will be placed in the ``bin/`` subdirectory,
generally with this naming convention:
::
godot.<platform>.<target>[.dev][.double].<arch>[.<extra_suffix>][.<ext>]
For the previous build attempt, the result would look like this:
.. code-block:: console
ls bin
bin/godot.linuxbsd.editor.x86_64
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:: doscon
C:\godot> dir bin/
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
it to the different platforms. For that the export templates are needed (which
can be either downloaded from `godotengine.org <https://godotengine.org/>`__, or
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_target:
Target
------
The ``target`` option controls if the editor is compiled and debug flags are used.
Optimization levels (``optimize``) and whether each build contains debug symbols
(``debug_symbols``) is controlled separately from the target. Each mode means:
- ``target=editor``: Build an editor binary (defines ``TOOLS_ENABLED`` and ``DEBUG_ENABLED``)
- ``target=template_debug``: Build a debug export template (defines ``DEBUG_ENABLED``)
- ``target=template_release``: Build a release export template
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 does not include the editor or the Project Manager.
The list of :ref:`command line arguments <doc_command_line_tutorial>`
available varies depending on the build type.
::
scons platform=<platform> target=editor|template_debug|template_release
.. _doc_introduction_to_the_buildsystem_development_and_production_aliases:
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
does not define ``NDEBUG`` (so ``assert()`` works in thirdparty libraries).
::
scons platform=<platform> dev_build=yes
This flag appends the ``.dev`` suffix (for development) to the generated
binary name.
.. seealso::
There are additional SCons options to enable *sanitizers*, which are tools
you can enable at compile-time to better debug certain engine issues.
See :ref:`doc_using_sanitizers` for more information.
.. _doc_introduction_to_the_buildsystem_debugging_symbols:
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=size_extra``: Favors even smaller binaries, at the cost of even
slower execution speed compared to ``optimize=size``.
- ``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
------------
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.
Supported values for the ``arch`` option are **auto**, **x86_32**, **x86_64**,
**arm32**, **arm64**, **rv64**, **ppc32**, **ppc64** and **wasm32**.
::
scons platform=<platform> arch={auto|x86_32|x86_64|arm32|arm64|rv64|ppc32|ppc64|wasm32}
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:
Custom modules
--------------
It's possible to compile modules residing outside of Godot's directory
tree, along with the built-in modules.
A ``custom_modules`` build option can be passed to the command line before
compiling. The option represents a comma-separated list of directory paths
containing a collection of independent C++ modules that can be seen as C++
packages, just like the built-in ``modules/`` directory.
For instance, it's possible to provide both relative, absolute, and user
directory paths containing such modules:
::
scons custom_modules="../modules,/abs/path/to/modules,~/src/godot_modules"
.. note::
If there's any custom module with the exact directory name as a built-in
module, the engine will only compile the custom one. This logic can be used
to override built-in module implementations.
.. seealso::
:ref:`doc_custom_modules_in_cpp`
Cleaning generated files
------------------------
Sometimes, you may encounter an error due to generated files being present. You
can remove them by using ``scons --clean <options>``, where ``<options>`` is the
list of build options you've used to build Godot previously.
Alternatively, you can use ``git clean -fixd`` which will clean build artifacts
for all platforms and configurations. Beware, as this will remove all untracked
and ignored files in the repository. Don't run this command if you have
uncommitted work!
Other build options
-------------------
There are several other build options that you can use to configure the
way Godot should be built (compiler, debug options, etc.) as well as the
features to include/disable.
Check the output of ``scons --help`` for details about each option for
the version you are willing to compile.
.. _doc_overriding_build_options:
Overriding the build options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using a file
^^^^^^^^^^^^
The default ``custom.py`` file can be created at the root of the Godot Engine
source to initialize any SCons build options passed via the command line:
.. code-block:: python
:caption: custom.py
optimize = "size"
module_mono_enabled = "yes"
use_llvm = "yes"
extra_suffix = "game_title"
You can also disable some of the built-in modules before compiling, saving some
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 <https://godot-build-options-generator.github.io/>`__
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:
.. code-block:: shell
scons profile=path/to/custom.py
.. note:: Build options set from the file can be overridden by the command line
options.
It's also possible to override the options conditionally:
.. code-block:: python
:caption: custom.py
import version
# Override options specific for Godot 3.x and 4.x versions.
if version.major == 3:
pass
elif version.major == 4:
pass
Using the SCONSFLAGS
^^^^^^^^^^^^^^^^^^^^
``SCONSFLAGS`` is an environment variable which is used by the SCons to set the
options automatically without having to supply them via the command line.
For instance, you may want to force a number of CPU threads with the
aforementioned ``-j`` option for all future builds:
.. tabs::
.. code-tab:: bash Linux/macOS
export SCONSFLAGS="-j4"
.. code-tab:: bat Windows (cmd)
set SCONSFLAGS=-j4
.. code-tab:: powershell Windows (PowerShell)
$env:SCONSFLAGS="-j4"
SCU (single compilation unit) build
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Regular builds tend to be bottlenecked by including large numbers of headers
in each compilation translation unit. Primarily to speed up development (rather
than for production builds), Godot offers a "single compilation unit" build
(aka "Unity / Jumbo" build).
For the folders accelerated by this option, multiple ``.cpp`` files are
compiled in each translation unit, so headers can be shared between multiple
files, which can dramatically decrease build times.
To perform an SCU build, use the ``scu_build=yes`` SCons option.
.. note:: When developing a Pull Request using SCU builds, be sure to make a
regular build prior to submitting the PR. This is because SCU builds
by nature include headers from earlier ``.cpp`` files in the
translation unit, therefore won't catch all the includes you will
need in a regular build. The CI will catch these errors, but it will
usually be faster to catch them on a local build on your machine.
Export templates
----------------
Official export templates are downloaded from the Godot Engine site:
`godotengine.org <https://godotengine.org/>`__. However, you might want
to build them yourself (in case you want newer ones, you are using custom
modules, or simply don't trust your own shadow).
If you download the official export templates package and unzip it, you
will notice that most files are optimized binaries or packages for each
platform:
.. code-block:: none
android_debug.apk
android_release.apk
android_source.zip
ios.zip
linux_debug.arm32
linux_debug.arm64
linux_debug.x86_32
linux_debug.x86_64
linux_release.arm32
linux_release.arm64
linux_release.x86_32
linux_release.x86_64
macos.zip
version.txt
web_debug.zip
web_dlink_debug.zip
web_dlink_nothreads_debug.zip
web_dlink_nothreads_release.zip
web_dlink_release.zip
web_nothreads_debug.zip
web_nothreads_release.zip
web_release.zip
windows_debug_x86_32_console.exe
windows_debug_x86_32.exe
windows_debug_x86_64_console.exe
windows_debug_x86_64.exe
windows_debug_arm64_console.exe
windows_debug_arm64.exe
windows_release_x86_32_console.exe
windows_release_x86_32.exe
windows_release_x86_64_console.exe
windows_release_x86_64.exe
windows_release_arm64_console.exe
windows_release_arm64.exe
To create those yourself, follow the instructions detailed for each
platform in this same tutorial section. Each platform explains how to
create its own template.
The ``version.txt`` file should contain the corresponding Godot version
identifier. This file is used to install export templates in a version-specific
directory to avoid conflicts. For instance, if you are building export templates
for Godot 3.1.1, ``version.txt`` should contain ``3.1.1.stable`` on the first
line (and nothing else). This version identifier is based on the ``major``,
``minor``, ``patch`` (if present) and ``status`` lines of the
`version.py file in the Godot Git repository <https://github.com/godotengine/godot/blob/master/version.py>`__.
If you are developing for multiple platforms, macOS is definitely the most
convenient host platform for cross-compilation, since you can cross-compile for
every target. Linux and Windows come in second place,
but Linux has the advantage of being the easier platform to set this up.

356
engine_details/development/compiling/optimizing_for_size.rst Normal file
View File

@@ -0,0 +1,356 @@
.. _doc_optimizing_for_size:
Optimizing a build for size
===========================
.. highlight:: shell
Rationale
---------
Sometimes, it is desired to optimize a build for size rather than speed.
This means not compiling unused functions from the engine, as well as using
specific compiler flags to aid on decreasing build size.
Common situations include creating builds for mobile and Web platforms.
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.
The options below are listed from the most important (greatest size savings)
to the least important (lowest size savings).
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 <doc_using_cpp_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 Web. Instead, pass ``debug_symbols=no``
on the SCons command line when compiling.
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 target=template_release lto=full
Linking becomes much slower and more RAM-consuming with this option,
so it should be used only for release builds. You need to have at least
8 GB of RAM available for successful linking with LTO enabled. Since the operating
system and programs will take up some RAM, in practice, you need 12 GB of RAM
installed in your system (preferably 16 GB) to compile Godot with LTO enabled.
Optimizing for size instead of speed
------------------------------------
- **Space savings:** High
- **Difficulty:** Easy
- **Performed in official builds:** Yes, but only for web builds
Godot 3.1 onwards allows compiling using size optimizations (instead of speed).
To enable this, set the ``optimize`` flag to ``size``:
::
scons target=template_release optimize=size
Some platforms such as WebAssembly already use this mode by default.
Godot 4.5 introduced the ``size_extra`` option, which can further reduce size.
::
scons target=template_release optimize=size_extra
Disabling advanced text server
------------------------------
- **Space savings:** High
- **Difficulty:** Easy
- **Performed in official builds:** No
By default, Godot uses an advanced text server with the support for the
following features:
- Right-to-left typesetting and complex scripts, required to write languages
such as Arabic and Hebrew.
- Font ligatures and OpenType features (such as small capitals, fractions and
slashed zero).
Godot provides a fallback text server that isn't compiled by default. This text
server can be used as a lightweight alternative to the default advanced text
server:
::
scons target=template_release module_text_server_adv_enabled=no module_text_server_fb_enabled=yes
If you only intend on supporting Latin, Greek and Cyrillic-based languages in
your project, the fallback text server should suffice.
This fallback text server can also process large amounts of text more quickly
than the advanced text server. This makes the fallback text server a good fit
for mobile/web projects.
.. note::
Remember to always pass ``module_text_server_fb_enabled=yes`` when using
``module_text_server_adv_enabled=no``. Otherwise, the compiled binary won't
contain any text server, which means no text will be displayed at all when
running the project.
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:
::
scons 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
by about 15%.
Disabling advanced GUI objects
------------------------------
- **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:
::
scons target=template_release disable_advanced_gui=yes
This is everything that will be disabled:
- :ref:`class_AcceptDialog`
- :ref:`class_CharFXTransform`
- :ref:`class_CodeEdit`
- :ref:`class_CodeHighlighter`
- :ref:`class_ColorPicker`
- :ref:`class_ColorPickerButton`
- :ref:`class_ConfirmationDialog`
- :ref:`class_FileDialog`
- :ref:`class_FoldableContainer`
- :ref:`class_FoldableGroup`
- :ref:`class_GraphEdit`
- :ref:`class_GraphElement`
- :ref:`class_GraphFrame`
- :ref:`class_GraphNode`
- :ref:`class_HSplitContainer`
- :ref:`class_MenuBar`
- :ref:`class_MenuButton`
- :ref:`class_OptionButton`
- :ref:`class_PopupMenu` (will make all popup menus unavailable in code for classes that use them,
like :ref:`class_LineEdit`, even though those classes are still available)
- :ref:`class_RichTextEffect`
- :ref:`class_RichTextLabel`
- :ref:`class_SpinBox`
- :ref:`class_SplitContainer`
- :ref:`class_SubViewportContainer`
- :ref:`class_SyntaxHighlighter`
- :ref:`class_TextEdit`
- :ref:`class_Tree`
- :ref:`class_TreeItem`
- :ref:`class_VSplitContainer`
Disabling physics engines
-------------------------
- **Space savings:** Low to moderate
- **Difficulty:** Easy
- **Performed in official builds:** No
If your 3D project uses Jolt Physics, you can disable GodotPhysics3D at compile-time as
it will never be used:
::
scons target=template_release module_godot_physics_3d_enabled=no
Inversely, if your 3D project uses GodotPhysics3D, you can disable Jolt Physics at compile-time:
::
scons target=template_release module_jolt_enabled=no
If your project uses 3D rendering but not physics (or 2D rendering but not physics),
you can also disable 2D or 3D physics entirely. Most 3D projects can take advantage
of this, as they don't make use of 2D physics:
::
scons target=template_release disable_physics_2d=yes
::
scons target=template_release disable_physics_3d=yes
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:
::
scons --help
The list of modules that can be disabled will appear, together with all
build options. If you are working on a simple 2D game, you could disable
a lot of them:
::
scons target=template_release module_astcenc_enabled=no module_basis_universal_enabled=no module_bcdec_enabled=no module_bmp_enabled=no module_camera_enabled=no module_csg_enabled=no module_dds_enabled=no module_enet_enabled=no module_etcpak_enabled=no module_fbx_enabled=no module_gltf_enabled=no module_gridmap_enabled=no module_hdr_enabled=no module_interactive_music_enabled=no module_jsonrpc_enabled=no module_ktx_enabled=no module_mbedtls_enabled=no module_meshoptimizer_enabled=no module_minimp3_enabled=no module_mobile_vr_enabled=no module_msdfgen_enabled=no module_multiplayer_enabled=no module_noise_enabled=no module_navigation_2d_enabled=no module_navigation_3d_enabled=no module_ogg_enabled=no module_openxr_enabled=no module_raycast_enabled=no module_regex_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_webxr_enabled=no module_zip_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 might
want to keep networking-related modules, regex support,
``minimp3``/``ogg``/``vorbis`` to play music, or ``theora`` to play videos).
Alternatively, you can supply a list of disabled modules by creating
``custom.py`` at the root of the source, with the contents similar to the
following:
.. code-block:: python
:caption: custom.py
module_astcenc_enabled = "no"
module_basis_universal_enabled = "no"
module_bcdec_enabled = "no"
module_bmp_enabled = "no"
module_camera_enabled = "no"
module_csg_enabled = "no"
module_dds_enabled = "no"
module_enet_enabled = "no"
module_etcpak_enabled = "no"
module_fbx_enabled = "no"
module_gltf_enabled = "no"
module_gridmap_enabled = "no"
module_hdr_enabled = "no"
module_interactive_music_enabled = "no"
module_jsonrpc_enabled = "no"
module_ktx_enabled = "no"
module_mbedtls_enabled = "no"
module_meshoptimizer_enabled = "no"
module_minimp3_enabled = "no"
module_mobile_vr_enabled = "no"
module_msdfgen_enabled = "no"
module_multiplayer_enabled = "no"
module_noise_enabled = "no"
module_navigation_2d_enabled = "no"
module_navigation_3d_enabled = "no"
module_ogg_enabled = "no"
module_openxr_enabled = "no"
module_raycast_enabled = "no"
module_regex_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_webxr_enabled = "no"
module_zip_enabled = "no"
.. seealso::
:ref:`doc_overriding_build_options`.
Optimizing the distribution of your project
-------------------------------------------
Desktop
~~~~~~~
.. note::
This section is only relevant when distributing the files on a desktop
platform that doesn't perform its own compression or packing. As such, this
advice is relevant when you distribute ZIP archives on itch.io or GitHub
Releases.
Platforms like Steam already apply their own compression scheme, so you
don't need to create a ZIP archive to distribute files in the first place.
As an aside, you can look into optimizing the distribution of your project itself.
This can be done even without recompiling the export template.
`7-Zip <https://7-zip.org/>`__ can be used to create ZIP archives that are more
efficient than usual, while remaining compatible with every ZIP extractor
(including Windows' own built-in extractor). ZIP size reduction in a large
project can reach dozens of megabytes compared to a typical ZIP compressor,
although average savings are in the 1-5 MB range. Creating this ZIP archive will
take longer than usual, but it will extract just as fast as any other ZIP
archive.
When using the 7-Zip GUI, this is done by creating a ZIP archive with the Ultra
compression mode. When using the command line, this is done using the following
command:
::
7z a -mx9 my_project.zip folder_containing_executable_and_pck
Web
~~~
Enabling gzip or Brotli compression for all file types from the web export
(especially the ``.wasm`` and ``.pck``) can reduce the download size
significantly, leading to faster loading times, especially on slow connections.
Creating precompressed gzip or Brotli files with a high compression level can be
even more efficient, as long as the web server is configured to serve those
files when they exist. When supported, Brotli should be preferred over gzip as
it has a greater potential for file size reduction.
See :ref:`doc_exporting_for_web_serving_the_files` for instructions.

111
engine_details/development/configuring_an_ide/android_studio.rst Normal file
View File

@@ -0,0 +1,111 @@
.. _doc_configuring_an_ide_android_studio:
Android Studio
==============
`Android Studio <https://developer.android.com/studio>`_ is a free
IDE for Android development made by `Google <https://about.google/>`_ and `JetBrains <https://www.jetbrains.com/>`_.
It's based on `IntelliJ IDEA <https://www.jetbrains.com/idea/>`_ and has a
feature-rich editor which supports Java and C/C++. It can be used to
work on Godot's core engine as well as the Android platform codebase.
Importing the project
---------------------
- From the Android Studio's welcome window select **Open**.
.. figure:: img/android_studio_setup_project_1.png
:figclass: figure-w480
:align: center
Android Studio's welcome window.
- Navigate to ``<Godot root directory>/platform/android/java`` and select the ``settings.gradle`` file.
- Android Studio will import and index the project.
Android Studio project layout
-----------------------------
The project is organized using `Android Studio's modules <https://developer.android.com/studio/projects#ApplicationModules>`_:
- ``lib`` module:
- Located under ``<Godot root directory>/platform/android/java/lib``, this is a **library module** that organizes
the Godot java and native code and make it available as a reusable dependency / artifact.
- The artifact generated by this module is made available for other Android modules / projects to use as a dependency, via `MavenCentral <https://repo1.maven.org/maven2/org/godotengine/godot/>`_.
- ``editor`` module:
- Located under ``<Godot root directory>/platform/android/java/editor``, this is an **application module** that holds
the source code for the Android port of the Godot Editor.
- This module has a dependency on the ``lib`` module.
- ``app`` module:
- Located under ``<Godot root directory>/platform/android/java/app``, this is an **application module** that holds
the source code for the Android build templates.
- This module has a dependency on the ``lib`` module.
Building & debugging the editor module
--------------------------------------
- To build the ``editor`` module:
- Select the `Run/Debug Configurations drop down <https://developer.android.com/studio/run/rundebugconfig#running>`_ and select ``editor``.
.. figure:: img/android_studio_editor_configurations_drop_down.webp
:figclass: figure-w480
:align: center
- Select **Run > Run 'editor'** from the top menu or `click the Run icon <https://developer.android.com/studio/run/rundebugconfig#running>`_.
- To debug the ``editor`` module:
- Open the **Build Variants** window using **View > Tools Windows > Build Variants** from the top menu.
- In the **Build Variants** window, make sure that in the **Active Build Variant** column, the ``:editor`` entry is set to one of the **Dev** variants.
.. figure:: img/android_studio_editor_build_variant.webp
:figclass: figure-w480
:align: center
- Open the **Run/Debug Configurations** window by clicking on **Run > Edit Configurations...** on the top menu.
- In the **Run/Debug Configurations** window, select the ``editor`` entry, and under **Debugger** make sure the **Debug Type** is set to ``Dual (Java + Native)``
- Click the ``+`` sign under the **Symbol Directories** section, and add the ``lib`` module directory: ``platform/android/java/lib``
.. figure:: img/android_studio_editor_debug_type_setup.webp
:figclass: figure-w480
:align: center
- Select **Run > Debug 'editor'** from the top menu or `click the Debug icon <https://developer.android.com/studio/run/rundebugconfig#running>`_.
Building & debugging the app module
-----------------------------------
The ``app`` module requires the presence of a Godot project in its ``assets`` directory (``<Godot root directory>/platform/android/java/app/assets``) to run.
This is usually handled by the Godot Editor during the export process.
While developing in Android Studio, it's necessary to manually add a Godot project under that directory to replicate the export process.
Once that's done, you can follow the instructions below to run/debug the ``app`` module:
- To build the ``app`` module:
- Select the `Run/Debug Configurations drop down <https://developer.android.com/studio/run/rundebugconfig#running>`_ and select ``app``.
.. figure:: img/android_studio_app_configurations_drop_down.webp
:figclass: figure-w480
:align: center
- Select **Run > Run 'app'** from the top menu or `click the Run icon <https://developer.android.com/studio/run/rundebugconfig#running>`_.
- To debug the ``app`` module:
- Open the **Build Variants** window using **View > Tools Windows > Build Variants** from the top menu.
- In the **Build Variants** window, make sure that in the **Active Build Variant** column, the ``:app`` entry is set to one of the **Dev** variants.
.. figure:: img/android_studio_app_build_variant.webp
:figclass: figure-w480
:align: center
- Open the **Run/Debug Configurations** window by clicking on **Run > Edit Configurations...** on the top menu.
- In the **Run/Debug Configurations** window, select the ``app`` entry, and under **Debugger** make sure the **Debug Type** is set to ``Dual (Java + Native)``
- Click the ``+`` sign under the **Symbol Directories** section, and add the ``lib`` module directory: ``platform/android/java/lib``
.. figure:: img/android_studio_app_debug_type_setup.webp
:figclass: figure-w480
:align: center
- Select **Run > Debug 'app'** from the top menu or `click the Debug icon <https://developer.android.com/studio/run/rundebugconfig#running>`_.
If you run into any issues, ask for help in
`Godot's Android dev channel <https://chat.godotengine.org/channel/android>`__.

120
engine_details/development/configuring_an_ide/clion.rst Normal file
View File

@@ -0,0 +1,120 @@
.. _doc_configuring_an_ide_clion:
CLion
=====
`CLion <https://www.jetbrains.com/clion/>`_ is a
`JetBrains <https://www.jetbrains.com/>`_ IDE for C++ that's free for individual, non-commercial development.
Importing the project
---------------------
CLion can import a project's `compilation database file <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`_, commonly named ``compile_commands.json``. To generate the compilation database file, open the terminal, change to the Godot root directory, and run:
::
scons compiledb=yes
Then, open the Godot root directory with CLion and wait for the project to be fully
indexed. If code completion, parameter information, or refactoring are not enabled,
you will need to load the project with CMake. To do this, find the ``CMakeLists.txt``
file in the ``platform\android\java\nativeSrcsConfigs`` directory, right click and
select :button:`Load CMake Project`. Once the project reloads, a ``godot`` build configuration
will be added. This configuration can be safely deleted as the CMake file will not
build the project and only exists for loading the project in JetBrains IDEs.
.. note:: Windows Users:
For ``compile_commands.json`` to load correctly in CLion, you must first have the Visual Studio toolchain configured for CLion.
- Navigate to **Preferences > Build, Execution, Deployment > Toolchains**
- Click the **+** button and select ``Visual Studio``
- CLion will attempt to detect your Visual Studio installation. If it is unsuccessful, use the file icon to the right of ``Toolset:`` to select the directory with your Visual Studio installation.
You may exit and reload CLion and it will reload ``compile_commands.json``
.. figure:: img/clion_visual_studio_toolchain.webp
:align: center
Compiling and debugging the project
-----------------------------------
CLion does not support compiling and debugging Godot via SCons out of the box. This can be achieved by creating a custom build target and run configuration in CLion. Before creating a custom build target, you must :ref:`compile Godot <toc-devel-compiling>` once on the command line, to generate the Godot executable. Open the terminal, change into the Godot root directory, and execute:
::
scons dev_build=yes
To add a custom build target that invokes SCons for compilation:
- Open CLion and navigate to **Preferences > Build, Execution, Deployment > Custom Build Targets**
.. figure:: img/clion-preferences.png
:align: center
- Click **Add target** and give the target a name, e.g. ``Godot debug``.
.. figure:: img/clion-target.png
:align: center
- Click **...** next to the **Build:** selectbox, then click the **+** button in the **External Tools** dialog to add a new external tool.
.. figure:: img/clion-external-tools.png
:align: center
- Give the tool a name, e.g. ``Build Godot debug``, set **Program** to ``scons``, set **Arguments** to the compilation settings you want (see :ref:`compiling Godot <toc-devel-compiling>`), and set the **Working directory** to ``$ProjectFileDir$``, which equals the Godot root directory. Click **OK** to create the tool.
.. note:: CLion does not expand shell commands like ``scons -j$(nproc)``. Use concrete values instead, e.g. ``scons -j8``.
.. figure:: img/clion-create-build-tool.webp
:align: center
- Back in the **External Tools** dialog, click the **+** again to add a second external tool for cleaning the Godot build via SCons. Give the tool a name, e.g. ``Clean Godot debug``, set **Program** to ``scons``, set **Arguments** to ``-c`` (which will clean the build), and set the **Working directory** to ``$ProjectFileDir$``. Click **OK** to create the tool.
.. figure:: img/clion-create-clean-tool.png
:align: center
- Close the **External Tools** dialog. In the **Custom Build Target** dialog for the custom ``Godot debug`` build target, select the **Build Godot debug** tool from the **Build** select box, and select the **Clean Godot debug** tool from the **Clean** select box. Click **OK** to create the custom build target.
.. figure:: img/clion-select-tools.png
:align: center
- In the main IDE window, click **Add Configuration**.
.. figure:: img/clion-add-configuration.png
:align: center
- In the **Run/Debug Configuration** dialog, click **Add new...**, then select **Custom Build Application** to create a new custom run/debug configuration.
.. figure:: img/clion-add-custom-build-application.png
:align: center
- Give the run/debug configuration a name, e.g. ``Godot debug``, select the ``Godot debug`` custom build target as the **Target**. Select the Godot executable in the ``bin/`` folder as the **Executable**, and set the **Program arguments** to ``--editor --path path-to-your-project/``, where ``path-to-your-project/`` should be a path pointing to an existing Godot project. If you omit the ``--path`` argument, you will only be able to debug the Godot Project Manager window. Click **OK** to create the run/debug configuration.
.. figure:: img/clion-run-configuration.png
:align: center
You can now build, run, debug, profile, and Valgrind check the Godot editor via the run configuration.
.. figure:: img/clion-build-run.png
:align: center
When playing a scene, the Godot editor will spawn a separate process. You can debug this process in CLion by going to **Run > Attach to process...**, typing ``godot``, and selecting the Godot process with the highest **pid** (process ID), which will usually be the running project.
Ignoring object and library files
-----------------------------------
After building Godot in CLion, you may see the object and library files showing up in the **Project** view.
.. figure:: img/clion-object-library-files-in-project-view.webp
:align: center
You can configure CLion to ignore those files:
- Open CLion and navigate to **Preferences > Editor > File Types > Ignored Files and Folders**
- Click the **+** button to add ``*.o`` and ``*.a`` to the list. In Windows, you would add ``*.obj`` and ``*.dll``.
.. figure:: img/clion-ignore-object-library-files.webp
:align: center
Now, the files should be ignored in the Project view.

129
engine_details/development/configuring_an_ide/code_blocks.rst Normal file
View File

@@ -0,0 +1,129 @@
.. _doc_configuring_an_ide_code_blocks:
Code::Blocks
============
`Code::Blocks <https://codeblocks.org/>`_ is a free, open-source, cross-platform IDE.
Creating a new project
----------------------
From Code::Blocks' main screen, click **Create a new project** or select **File > New > Project...**.
.. figure:: img/code_blocks_file_new_project.png
:figclass: figure-w480
:align: center
In the **New from template** window, from **Projects**, select **Empty project**, and click **Go**.
.. figure:: img/code_blocks_new_empty_project.png
:figclass: figure-w480
:align: center
Click Next, to pass the welcome to the new empty project wizard.
.. figure:: img/code_blocks_wizard_welcome.png
:figclass: figure-w480
:align: center
The project file should be created in the root of the cloned project folder. To achieve this, first, ensure that the **Project title** is the same as the folder name that Godot was cloned into. Unless you cloned the project into a folder with a different name, this will be ``godot``.
Second, ensure that the **Folder to create project in** is the folder you ran the Git clone command from, not the ``godot`` project folder. Confirm that the **Resulting filename** field will create the project file in the root of the cloned project folder.
.. figure:: img/code_blocks_project_title_and_location.png
:figclass: figure-w480
:align: center
The compiler and configuration settings are managed through **SCons** and will be configured later. However, it's worth deselecting the **Create "Release" configuration** option; so only a single build target is created before clicking **Finish**.
.. figure:: img/code_blocks_compiler_and_configuration.png
:figclass: figure-w480
:align: center
Configuring the build
---------------------
The first step is to change the project properties. Right-click on the new project and select **Properties...**.
.. figure:: img/code_blocks_open_properties.png
:figclass: figure-w480
:align: center
Check the **This is a custom Makefile** property. Click OK to save the changes.
.. figure:: img/code_blocks_project_properties.png
:figclass: figure-w480
:align: center
The next step is to change the build options. Right-click on the new project and select **Build Options...**.
.. figure:: img/code_blocks_open_build_options.png
:figclass: figure-w480
:align: center
Select the **"Make" commands** tab and remove all the existing commands for all the build targets. For each build target enter the **SCons** command for creating the desired build in the **Build project/target** field. The minimum is ``scons``. For details on the **SCons** build options, see :ref:`doc_introduction_to_the_buildsystem`. It's also useful to add the ``scons --clean`` command in the **Clean project/target** field to the project's default commands.
If you're using Windows, all the commands need to be preceded with ``cmd /c`` to initialize the command interpreter.
.. figure:: img/code_blocks_scons_minimum.png
:figclass: figure-w480
:align: center
.. figure:: img/code_blocks_scons_clean.png
:figclass: figure-w480
:align: center
Windows example:
.. figure:: img/code_blocks_scons_windows.png
:figclass: figure-w480
:align: center
Code::Blocks should now be configured to build Godot; so either select **Build > Build**, click the gear button, or press :kbd:`Ctrl + F9`.
Configuring the run
-------------------
Once **SCons** has successfully built the desired target, reopen the project **Properties...** and select the **Build targets** tab. In the **Output filename** field, browse to the ``bin`` folder and select the compiled file.
Deselect the **Auto-generate filename prefix** and **Auto-generate filename extension** options.
.. figure:: img/code_blocks_build_targets.png
:figclass: figure-w480
:align: center
Code::Blocks should now be configured to run your compiled Godot executable; so either select **Build > Run**, click the green arrow button, or press :kbd:`Ctrl + F10`.
There are two additional points worth noting. First, if required, the **Execution working dir** field can be used to test specific projects, by setting it to the folder containing the ``project.godot`` file. Second, the **Build targets** tab can be used to add and remove build targets for working with and creating different builds.
Adding files to the project
---------------------------
To add all the Godot code files to the project, right-click on the new project and select **Add files recursively...**.
.. figure:: img/code_blocks_add_files_recursively.png
:figclass: figure-w480
:align: center
It should automatically select the project folder; so simply click **Open**. By default, all code files are included, so simply click **OK**.
.. figure:: img/code_blocks_select_files.png
:figclass: figure-w480
:align: center
Code style configuration
------------------------
Before editing any files, remember that all code needs to comply with the `code style guidelines <https://contributing.godotengine.org/en/latest/engine/guidelines/code_style.html>`__. One important difference with Godot is the use of tabs for indents. Therefore, the key default editor setting that needs to be changed in Code::Blocks is to enable tabs for indents. This setting can be found by selecting **Settings > Editor**.
.. figure:: img/code_blocks_update_editor_settings.png
:figclass: figure-w480
:align: center
Under **General Settings**, on the **Editor Settings** tab, under **Tab Options** check **Use TAB character**.
.. figure:: img/code_block_use_tab_character.png
:figclass: figure-w480
:align: center
That's it. You're ready to start contributing to Godot using the Code::Blocks IDE. Remember to save the project file and the **Workspace**. If you run into any issues, ask for help in one of `Godot's community channels <https://godotengine.org/community>`__.

BIN
engine_details/development/configuring_an_ide/img/android_studio_app_build_variant.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.2 KiB

BIN
engine_details/development/configuring_an_ide/img/android_studio_app_configurations_drop_down.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

BIN
engine_details/development/configuring_an_ide/img/android_studio_app_debug_type_setup.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
engine_details/development/configuring_an_ide/img/android_studio_editor_build_variant.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.3 KiB

BIN
engine_details/development/configuring_an_ide/img/android_studio_editor_configurations_drop_down.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 63 KiB

BIN
engine_details/development/configuring_an_ide/img/android_studio_editor_debug_type_setup.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
engine_details/development/configuring_an_ide/img/android_studio_setup_project_1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.0 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-add-configuration.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-add-custom-build-application.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 340 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-build-run.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-create-build-tool.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-create-clean-tool.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 274 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-external-tools.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 301 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-ignore-object-library-files.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 126 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-object-library-files-in-project-view.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-preferences.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 582 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-run-configuration.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 588 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-select-tools.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 611 KiB

BIN
engine_details/development/configuring_an_ide/img/clion-target.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 605 KiB

BIN
engine_details/development/configuring_an_ide/img/clion_visual_studio_toolchain.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
engine_details/development/configuring_an_ide/img/code_block_use_tab_character.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 108 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_add_files_recursively.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_build_targets.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 59 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_compiler_and_configuration.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_file_new_project.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 160 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_new_empty_project.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 52 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_open_build_options.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_open_properties.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_project_properties.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 69 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_project_title_and_location.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 38 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_scons_clean.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_scons_minimum.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_scons_windows.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.7 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_select_files.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_update_editor_settings.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
engine_details/development/configuring_an_ide/img/code_blocks_wizard_welcome.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

0
engine_details/development/configuring_an_ide/img/kdevelop_addincludes.png Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_addincludes.webp Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_buildconfig.png Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_buildconfig.webp Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_configlaunches.png Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_configlaunches.webp Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_configlaunches2.png Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_configlaunches2.webp Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_custombuild.png Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_custombuild.webp Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_newproject.png Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_newproject.webp Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_openconfig.png Normal file
View File

0
engine_details/development/configuring_an_ide/img/kdevelop_openconfig.webp Normal file
View File

BIN
engine_details/development/configuring_an_ide/img/qtcreator-apply-import-filter.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

BIN
engine_details/development/configuring_an_ide/img/qtcreator-edit-codestyle.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

BIN
engine_details/development/configuring_an_ide/img/qtcreator-edit-files-menu.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
engine_details/development/configuring_an_ide/img/qtcreator-new-project.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

BIN
engine_details/development/configuring_an_ide/img/qtcreator-options-cpp.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
engine_details/development/configuring_an_ide/img/qtcreator-project-name-includes.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.0 KiB

BIN
engine_details/development/configuring_an_ide/img/qtcreator-projects-build.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

BIN
engine_details/development/configuring_an_ide/img/qtcreator-run-command.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
engine_details/development/configuring_an_ide/img/qtcreator-set-project-path.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
engine_details/development/configuring_an_ide/img/qtcreator-set-scons-command.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
engine_details/development/configuring_an_ide/img/rider_attach_to_process.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 165 KiB

BIN
engine_details/development/configuring_an_ide/img/rider_attach_to_process_dialog.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 136 KiB

BIN
engine_details/development/configuring_an_ide/img/rider_configurations.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
engine_details/development/configuring_an_ide/img/rider_configurations_changed.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 190 KiB

BIN
engine_details/development/configuring_an_ide/img/rider_run_debug.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
engine_details/development/configuring_an_ide/img/vs_1_install_cpp_package.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.4 KiB

BIN
engine_details/development/configuring_an_ide/img/vs_2_project_properties.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.7 KiB

BIN
engine_details/development/configuring_an_ide/img/vs_3_debug_command_line.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.2 KiB

BIN
engine_details/development/configuring_an_ide/img/vs_4_debugging_main.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.8 KiB

BIN
engine_details/development/configuring_an_ide/img/vscode_1_create_launch.json.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.7 KiB

BIN
engine_details/development/configuring_an_ide/img/vscode_2_launch.json.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 77 KiB

BIN
engine_details/development/configuring_an_ide/img/vscode_3_tasks.json.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

BIN
engine_details/development/configuring_an_ide/img/vscode_configure_task.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.0 KiB

BIN
engine_details/development/configuring_an_ide/img/vscode_create_tasksjson.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.8 KiB

BIN
engine_details/development/configuring_an_ide/img/vscode_create_tasksjson_others.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.3 KiB

BIN
engine_details/development/configuring_an_ide/img/vscode_edit_configurations.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.5 KiB

BIN
engine_details/development/configuring_an_ide/img/xcode_1_create_external_build_project.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
engine_details/development/configuring_an_ide/img/xcode_2_set_external_build_project_parameters.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
engine_details/development/configuring_an_ide/img/xcode_3_configure_scons.webp Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

Some files were not shown because too many files have changed in this diff Show More