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 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:

Estos artículos cubren en gran detalle tanto cómo configurar su entorno para compilar Godot en una plataforma específica como cómo compilar para esa plataforma. No dude en consultarlos y consultar este artículo para conocer las opciones de configuración universales y específicas de la plataforma.

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

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.

To list the available target platforms, use scons platform=list:

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

Binario resultante

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:

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

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 command line arguments available varies depending on the build type.

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

Development and production aliases

Al crear compilaciones de desarrollo (ejecutando herramientas de depuración/profiling), a menudo se tienen objetivos diferentes en comparación con las compilaciones de producción (hacer que los binarios sean lo más rápidos y pequeños posible).

Godot provides two aliases for this purpose:

  • dev_mode=yes es un alias para verbose=yes warnings=extra werror=yes tests=yes. Esto permite el comportamiento de advertencias como errores (similar a la configuración de integración continua de Godot) y también crea pruebas unitarias para que pueda ejecutarlas localmente.

  • production=yes es un alias para use_static_cpp=yes debug_symbols=no lto=auto. La vinculación estática de libstdc++ permite una mejor portabilidad binaria al compilar para Linux. Este alias también permite la optimización del tiempo de vinculación al compilar para Linux, Web y Windows con MinGW. Pero mantiene LTO deshabilitado al compilar para macOS, iOS o Windows con MSVC. Esto se debe a que LTO en esas plataformas es muy lento para vincularse o tiene problemas con el código generado.

Puedes anular manualmente las opciones de esos alias especificándolas en la misma línea de comandos con valores diferentes. Por ejemplo, puedes utilizar scons production=yes debug_symbols=yes para crear binarios optimizados para producción con símbolos de depuración incluidos.

Construcción de desarrollo

Nota

dev_build no debe confundirse con dev_mode, que es un alias para varias opciones relacionadas con el desarrollo (ver arriba).

Al desarrollar un motor, la opción dev_build se puede usar junto con target para habilitar código específico de desarrollo. dev_build define DEV_ENABLED, deshabilita la optimización (-O0//0d), habilita la generación de símbolos de depuración y no define NDEBUG (para que assert() funcione en bibliotecas de terceros).

scons platform=<platform> dev_build=yes

Esta bandera añade el sufijo .dev (para desarrollo) al nombre binario generado.

Ver también

Existen opciones adicionales de SCons para habilitar los sanitizers, que son herramientas que se pueden habilitar en tiempo de compilación para depurar mejor ciertos problemas del motor. Consulta Using sanitizers para obtener más información.

Debugging symbols

Por defecto, se utiliza debug_symbols=no, lo que significa que no se incluyen símbolos de depuración en los binarios compilados. Utiliza debug_symbols=yes para incluir símbolos de depuración dentro de los binarios compilados, lo que permite que los depuradores y los generadores de perfiles funcionen correctamente. Los símbolos de depuración también son necesarios para que los seguimientos de fallas de Godot se muestren con referencias a los archivos y líneas del código fuente.

La desventaja es que los símbolos de depuración son archivos grandes (significativamente más grandes que los propios binarios). Por lo tanto, los binarios oficiales actualmente no incluyen símbolos de depuración. Entonces debes compilar Godot para tener acceso a los símbolos de depuración.

Al utilizar debug_symbols=yes, también puede utilizar separate_debug_symbols=yes para colocar la información de depuración en un archivo separado con un sufijo .debug. Esto permite distribuir ambos archivos de forma independiente. Ten en cuenta que en Windows, al compilar con MSVC, la información de depuración siempre se escribe en un archivo .pdb separado independientemente de 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=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.

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.

Sobrescribendo 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"

You can also disable some of the built-in modules before compiling, saving some time it takes to build the engine. See Optimizando una compilación para reducir el tamaño page for more details.

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.

Por ejemplo, es posible que desees forzar una cantidad de subprocesos de CPU con la opción -j mencionada anteriormente para todas las compilaciones futuras:

export SCONSFLAGS="-j4"

Compilación por SCU («Unidad de Compilación Única» o «Single Compilation Unit»)

Las compilaciones regulares tienden a verse obstaculizadas por la inclusión de una gran cantidad de encabezados en cada unidad de traducción de compilación. Principalmente para acelerar el desarrollo (a diferencia de las compilaciones de producción), Godot ofrece una compilación de "unidad de compilación única" (también conocida como compilación "Unity/Jumbo").

Para las carpetas aceleradas por esta opción, se compilan múltiples archivos .cpp en cada unidad de traducción, por lo que los encabezados se pueden compartir entre varios archivos, lo que puede reducir drásticamente los tiempos de compilación.

Para realizar una compilación SCU, utiliza la opción SCons scu_build=yes.

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
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

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.