Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Introducción al sistema de compilación

Godot is a primarily C++ project and it uses the SCons build system. 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 export template for your current platform, operating system, and architecture. An export template is a build of the engine that is used for running exported projects. To build the editor instead you can run the following command:

scons target=editor

If you plan to debug or develop the engine, then you might want to add another option to the command:

scons dev_build=yes
scons target=editor dev_build=yes

Following sections in the article will explain these and other universal options in more detail. But before you can compile Godot, you need to install a few prerequisites. Please refer to the platform documentation to learn more:

• Compilando para Android

• Compilando para IOS

• Compiling for Linux, *BSD

• Compilando para macOS

• Compilando para la Web

• Compilando para Windows

These articles cover in great detail both how to setup your environment to compile Godot on a specific platform, and how to compile for that platform. Please feel free to go back and forth between them and this article to reference platform-specific and universal configuration options.

Using multi-threading

The build process may take a while, depending on how powerful your system is. By default, Godot's SCons setup is configured to use all CPU threads but one (to keep the system responsive during compilation). If you want to adjust how many CPU threads SCons will use, use the -j <threads> parameter to specify how many threads will be used for the build.

Example for using 4 threads:

scons -j4

Seleccion de plataforma

El sistema de compilación de Godot comenzará detectando las plataformas para las que se puede compilar. Si no se detecta una plataforma, simplemente no aparecerá en la lista de plataformas disponibles. Los requisitos de compilación para cada plataforma se describen en el resto de esta sección del tutorial.

SCons se invoca simplemente llamando a scons. Si no se especifica una plataforma, SCons detectará automáticamente la plataforma de destino basándose en la plataforma del host. Luego, comenzará a compilar para la plataforma de destino de inmediato.

Para listar las plataformas de destino disponibles, utiliza el comando "scons platform=list":

scons platform=list
scons: Reading SConscript files ...
The following platforms are available:

    android
    javascript
    linuxbsd
    server
    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

Binario resultante

Los archivos binarios resultantes se ubicarán en el subdirectorio bin/, generalmente con esta convención de nombres:

godot.<platform>.<target>[.dev][.double].<arch>[.<extra_suffix>][.<ext>]

Para el intento anterior de compilación, el resultado se verá así:

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.

Un binario de Windows con la misma configuración se verá así:

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, or you can build them yourself).

Además de eso, hay algunas opciones estándar que se pueden configurar en todos los objetivos de compilación, las cuales se explicarán a continuación.

Objetivo

Target controls if the editor is contained and debug flags are used. All builds are optimized. Each mode means:

• target=editor: Build with editor, optimized, with debugging code (defines: TOOLS_ENABLED, DEBUG_ENABLED, -O2//O2)

• target=template_debug: Build with C++ debugging symbols (defines: DEBUG_ENABLED, -O2//O2)

• target=template_release: Build without symbols (defines: -O3//O2)

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.

scons platform=<platform> target=editor/template_debug/template_release

Development and production aliases

When creating builds for development (running debugging/profiling 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 unit tests 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

Nota

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.

Ver también

There are additional SCons options to enable sanitizers, which are tools you can enable at compile-time to better debug certain engine issues. See Using sanitizers for more information.

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.

Truco

Use the strip <path/to/binary> command to remove debugging symbols from a binary you've already compiled.

Optimization level

Several compiler optimization levels can be chosen from:

• optimize=speed_trace (default when targeting non-Web platforms): Favors execution speed at the cost of larger binary size. Optimizations may sometimes negatively impact debugger usage (stack traces may be less accurate. If this occurs to you, use optimize=debug instead.

• optimize=speed: Favors even more execution speed, at the cost of even larger binary size compared to optimize=speed_trace. Even less friendly to debugging compared to optimize=debug, as this uses the most aggressive optimizations available.

• optimize=size (default when targeting the Web platform): Favors small binaries at the cost of slower execution speed.

• optimize=debug: Only enables optimizations that do not impact debugging in any way. This results in faster binaries than optimize=none, but slower binaries than optimize=speed_trace.

• optimize=none: Do not perform any optimization. This provides the fastest build times, but the slowest execution times.

• optimize=custom (advanced users only): Do not pass optimization arguments to the C/C++ compilers. You will have to pass arguments manually using the CFLAGS, CCFLAGS and CXXFLAGS SCons options.

Architecture

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.

Módulos personalizados

Es posible compilar módulos que se encuentren fuera del árbol de directorios de Godot, junto con los módulos integrados.

Se puede pasar una opción de compilación llamada custom_modules en la línea de comandos antes de compilar. Esta opción representa una lista separada por comas de rutas de directorio que contienen una colección de módulos C++ independientes que pueden considerarse como paquetes de C++, al igual que el directorio incorporado modules/.

Por ejemplo, es posible proporcionar rutas de directorio tanto relativas, absolutas como del directorio del usuario que contienen dichos módulos:

scons custom_modules="../modules,/abs/path/to/modules,~/src/godot_modules"

Nota

Si hay algún módulo personalizado con el mismo nombre de directorio que un módulo integrado, el motor solo compilará el personalizado. Esta lógica se puede usar para anular las implementaciones de módulos integrados.

Ver también

Módulos personalizados en C++

Limpiando archivos generados

A veces, es posible que encuentres un error debido a que los archivos generados están presentes. Puedes eliminarlos usando scons --clean <opciones>, donde <opciones> es la lista de opciones de compilación que utilizaste previamente para compilar Godot.

Como alternativa, puedes usar git clean -fixd, lo cual limpiará los artefactos de compilación para todas las plataformas y configuraciones. Ten cuidado, ya que esto eliminará todos los archivos no rastreados e ignorados en el repositorio. ¡No ejecutes este comando si tienes trabajo sin confirmar!

Otras opciones de compilación

Hay varias otras opciones de compilación que puedes usar para configurar la forma en que se debe compilar Godot (compilador, opciones de depuración, etc.), así como las funciones para incluir o deshabilitar.

Verifica la salida de scons --help para obtener detalles sobre cada opción para la versión que deseas compilar.

Sobreescribendo las opciones de configuración

Usando un archivo

El archivo predeterminado custom.py se puede crear en la raíz del código fuente de Godot Engine para inicializar cualquier opción de compilación de SCons que se pase a través de la línea de comandos:

# custom.py

optimize = "size"
module_mono_enabled = "yes"
use_llvm = "yes"
extra_suffix = "game_title"

También puedes deshabilitar algunos de los módulos integrados antes de compilar, lo que ahorrará tiempo en el proceso de construcción del motor. Consulta la página Optimizando una compilación para reducir el tamaño para obtener más detalles al respecto.

Ver también

Puedes utilizar el generador en línea de opciones de compilación de Godot en Godot build options generator para generar un archivo custom.py que contenga las opciones de SCons. Luego, puedes guardar este archivo y colocarlo en la raíz del directorio de código fuente de Godot.

Otro archivo personalizado se puede especificar explícitamente con la opción de línea de comandos profile, lo que permite anular la configuración de compilación predeterminada:

scons profile=path/to/custom.py

Nota

Las opciones de compilación establecidas desde el archivo pueden ser anuladas por las opciones de la línea de comandos.

También es posible anular las opciones condicionalmente:

# 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

Usando las SCONSFLAGS

SCONSFLAGS es una variable de entorno que se utiliza en SCons para establecer opciones automáticamente sin tener que proporcionarlas a través de la línea de comandos.

For instance, you may want to force a number of CPU threads with the aforementioned -j option for all future builds:

Linux/macOSWindows (cmd)Windows (PowerShell)

export 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 make a SCU build, use the scu_build=yes SCons option.

Nota

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.

Plantillas de exportación

Las plantillas de exportación oficiales se descargan desde el sitio de Godot Engine: godotengine.org. Sin embargo, es posible que desees compilarlas tú mismo (en caso de que desees versiones más nuevas, estés utilizando módulos personalizados o simplemente no confíes en tu propia sombra).

Si descargas el paquete oficial de plantillas de exportación y lo descomprimes, notarás que la mayoría de los archivos son binarios o paquetes optimizados para cada plataforma:

android_debug.apk
android_release.apk
web_debug.zip
web_release.zip
linux_server_32
linux_server_64
linux_x11_32_debug
linux_x11_32_release
linux_x11_64_debug
linux_x11_64_release
macos.zip
version.txt
windows_32_debug.exe
windows_32_release.exe
windows_64_debug.exe
windows_64_release.exe

Para crear esas plantillas por ti mismo, sigue las instrucciones detalladas para cada plataforma en esta misma sección del tutorial. Cada plataforma explica cómo crear su propia plantilla.

El archivo version.txt debe contener el identificador de versión correspondiente a Godot. Este archivo se utiliza para instalar las plantillas de exportación en un directorio específico de la versión para evitar conflictos. Por ejemplo, si estás creando plantillas de exportación para Godot 3.1.1, el archivo version.txt debe contener 3.1.1.stable en la primera línea (y nada más). Este identificador de versión se basa en las líneas major, minor, patch (si está presente) y status del archivo version.py en el repositorio Git de Godot.

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.