Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Introdução ao sistema de compilação

O Godot é um projeto prioritariamente em C++ e usa o sistema de compilação SCons. Nós amamos o SCons pela manutenção facilitada e simplicidade que ele traz para o nosso sistema de compilação. E graças a isso, compilar o Godot a partir do código-fonte pode ser tão simples quanto executar:

scons

Isso produz uma compilação do editor para a sua plataforma, sistema operacional e arquitetura atuais. Você pode alterar o que é compilado especificando um alvo (target), uma plataforma e/ou uma arquitetura. Por exemplo, para compilar um modelo de exportação usado para rodar jogos exportados, você pode executar:

scons target=template_release

Se você planeja depurar ou desenvolver a engine, pode querer ativar a opção dev_build para habilitar o código de depuração exclusivo para desenvolvedores:

scons dev_build=yes

As seções seguintes no artigo explicarão essas e outras opções universais em mais detalhes. Mas antes de compilar o Godot, você precisa instalar alguns pré-requisitos. Por favor, consulte a documentação da plataforma para saber mais:

Esses artigos cobrem em detalhes tanto como configurar o seu ambiente para compilar o Godot em uma plataforma específica quanto como compilar para essa plataforma. Sinta-se à vontade para alternar entre eles e este artigo para consultar opções de configuração universais e específicas da plataforma.

Usando paralelismo

O processo de build pode levar algum tempo, dependendo de quão poderoso é o seu sistema. Por padrão, a configuração SCons do Godot está definida para usar todas as threads da CPU, exceto uma (para manter o sistema responsivo durante a compilação). Se o sistema tiver 4 threads de CPU ou menos, ele usará todas as threads por padrão.

Se você quiser ajustar quantas threads de CPU o SCons usará, use o parâmetro -j<threads> para especificar a quantidade de threads para a compilação.

Exemplo para usar 12 threads:

scons -j12

Seleção de plataforma

O sistema de compilação do Godot começará detectando as plataformas para as quais pode compilar. Se não for detectada, a plataforma simplesmente não aparecerá na lista de plataformas disponíveis. Os requisitos de compilação para cada plataforma são descritos no resto desta seção de tutorial.

O SCons é invocado apenas chamando scons. Se nenhuma plataforma for especificada, o SCons detectará a plataforma de destino automaticamente com base na plataforma de host. Ele vai então começar a compilar para a plataforma-alvo imediatamente.

Para listar as plataformas de destino disponíveis, 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>

Para compilar para uma plataforma (por exemplo, linuxbsd), execute com o argumento platform= (ou p= para ficar mais curto):

scons platform=linuxbsd

Executável resultante

Os binários resultantes serão colocados no subdiretório bin/, geralmente seguindo esta convenção de nomenclatura:

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

Para a tentativa de build anterior, o resultado seria assim:

ls bin
bin/godot.linuxbsd.editor.x86_64

Isso significa que o executável é para Linux ou *BSD (não ambos), não é otimizado, tem o editor inteiro compilado e é destinado para 64 bits.

Um executável do Windows com a mesma configuração terá esta aparência:

C:\godot> dir bin/
godot.windows.editor.64.exe

Copie esse executável para o local que você preferir, pois contém o Gerenciador de Projetos, o editor e todos os meios para executar o jogo. No entanto, faltam os dados para exportá-lo para as diferentes plataformas. Para isso, os modelos de exportação são necessários (que podem ser baixados de godotengine.org, ou você pode compilá-los você mesmo).

Além disso, existem algumas opções padrão que podem ser definidas em todos os alvos de compilação, e que serão explicadas abaixo.

Alvo

A opção target controla se o editor será compilado e se as flags de depuração serão usadas. Os níveis de otimização (optimize) e se cada compilação conterá símbolos de depuração (debug_symbols) são controlados separadamente do target. Cada modo significa:

  • target=editor: Compila um binário do editor (define TOOLS_ENABLED e DEBUG_ENABLED)

  • target=template_debug: Compila um modelo de exportação de depuração (define DEBUG_ENABLED)

  • target=template_release: Compila um modelo de exportação de lançamento (release)

O editor está habilitado por padrão em todos os alvos de PC (Linux, Windows, macOS) e desativado para o resto. Desativar o editor produz um executável que pode executar projetos, mas não inclui o editor ou o Gerenciador de Projetos.

A lista de argumentos de linha de comando disponíveis varia dependendo do tipo de compilação.

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

Aliases de desenvolvimento e produção

Ao criar compilações para desenvolvimento (executando ferramentas de depuração/análise), você muitas vezes tem objetivos diferentes em comparação com as compilações de produção (tornando executáveis tanto rápidos quanto pequenos aonde for possível).

O Godot fornece dois aliases para este propósito:

  • dev_mode=yes é um alias para verbose=yes warnings=extra werror=yes testing=yes. Isso permite o comportamento de avisos como erros (semelhante à configuração contínua de integração do Godot) e também compila testes de unidade para que você possa executá-los localmente.

  • production=yes é um alias para use_static_cpp=yes debug_symbols=no lto=auto. Ligar o libstdc++ dinamicamente permite melhor portabilidade do executável ao compilar para Linux. Este alias também habilita a otimização de tempo de ligação ao compilar para Linux, Web e Windows com MinGW, mas mantém a LTO desabilitada ao compilar para macOS, iOS ou Windows com MSVC. Isso ocorre porque a LTO nessas plataformas é muito lenta ou tem problemas com o código gerado.

Você pode substituir manualmente as opções desses aliases especificando-os na mesma linha de comando com valores diferentes. Por exemplo, você pode usar scons production=yes debug_symbols=yes para criar executáveis otimizados para produção com símbolos de depuração incluídos.

Compilação dev

Nota

dev_build não deve ser confundido com dev_mode, que é um alias para várias opções relacionadas ao desenvolvimento (veja acima).

Ao realizar o desenvolvimento do motor, a opção dev_build pode ser usada junto com target para habilitar código específico para desenvolvimento. dev_build define DEV_ENABLED, desativa a otimização (-O0//0d), habilita a geração de símbolos de depuração e não define NDEBUG (portanto, assert() funciona em bibliotecas de terceiros).

scons platform=<platform> dev_build=yes

Esta flag anexa o sufixo .dev (para o desenvolvimento) ao nome gerado do executável.

Ver também

Existem opções do SCons adicionais para habilitar sanitizadores, que são ferramentas que você pode habilitar em tempo de compilação para melhor depurar certos problemas da engine. Veja Usando sanitizers para mais informações.

Símbolos de depuração

Por padrão, usa-se debug_symbols=no, o que significa que nenhum símbolo de depuração é incluído nos binários compilados. Use debug_symbols=yes para incluir símbolos de depuração nos binários compilados, o que permite que depuradores e analisadores de perfil funcionem corretamente. Os símbolos de depuração também são necessários para que os rastreamentos de travamento (stacktraces) do Godot sejam exibidos com referências aos arquivos e linhas do código-fonte.

A desvantagem é que os símbolos de depuração são arquivos grandes (significativamente maiores do que os próprios binários). Como resultado, os binários oficiais atualmente não incluem símbolos de depuração. Isso significa que você precisa compilar o Godot por conta própria para ter acesso aos símbolos de depuração.

Ao usar debug_symbols=yes, você também pode usar separate_debug_symbols=yes para colocar as informações de depuração em um arquivo separado com o sufixo .debug. Isso permite distribuir ambos os arquivos de forma independente. Note que no Windows, ao compilar com o MSVC, as informações de depuração são sempre gravadas em um arquivo .pdb separado, independentemente de separate_debug_symbols.

Dica

Use o comando strip <caminho/para/o/binario> para remover os símbolos de depuração de um binário que você já compilou.

Nível de otimização

Vários níveis de otimização do compilador podem ser escolhidos:

  • optimize=speed_trace (padrão ao visar plataformas que não sejam a Web): Favorece a velocidade de execução à custa de um tamanho de binário maior. As otimizações às vezes podem impactar negativamente o uso do depurador (os rastreamentos de pilha podem ser menos precisos). Se isso acontecer com você, use optimize=debug no lugar.

  • optimize=speed: Favorece ainda mais a velocidade de execução, à custa de um tamanho de binário ainda maior em comparação com optimize=speed_trace. Ainda menos amigável para a depuração em comparação com optimize=debug, pois usa as otimizações mais agressivas disponíveis.

  • optimize=size (padrão ao visar a plataforma Web): Favorece binários pequenos à custa de uma velocidade de execução mais lenta.

  • optimize=size_extra: Favorece binários ainda menores, à custa de uma velocidade de execução ainda mais lenta em comparação com optimize=size.

  • optimize=debug: Ativa apenas otimizações que não impactam a depuração de nenhuma forma. Isso resulta em binários mais rápidos do que optimize=none, mas mais lentos do que optimize=speed_trace.

  • optimize=none: Não realiza nenhuma otimização. Isso oferece os tempos de compilação mais rápidos, mas os tempos de execução mais lentos.

  • optimize=custom (apenas para usuários avançados): Não passa argumentos de otimização para os compiladores C/C++. Você terá que passar os argumentos manualmente usando as opções do SCons cflags, ccflags e cxxflags.

Arquitetura

A opção arch destina-se a controlar a versão da CPU ou do SO pretendida para executar os binários. Ela é focada principalmente em plataformas desktop e ignorada em todo o resto.

Os valores suportados para a opção arch são auto, x86_32, x86_64, arm32, arm64, rv64, ppc32, ppc64 e 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

É possível compilar módulos que residem fora da árvore de diretórios do Godot, juntamente com os módulos embutidos.

Uma opção de compilação custom_modules pode ser passada na linha de comando antes de compilar. A opção representa uma lista separada por vírgulas de caminhos de diretório contendo uma coleção de módulos C++ independentes que podem ser vistos como pacotes C++, exatamente como o diretório modules/ embutido.

Por exemplo, é possível fornecer caminhos de diretório relativos, absolutos e de usuário que contenham tais módulos:

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

Nota

Se houver algum módulo personalizado com o nome de diretório idêntico ao de um módulo embutido, a engine compilará apenas o personalizado. Essa lógica pode ser usada para sobrescrever as implementações de módulos embutidos.

Limpando arquivos gerados

Às vezes, você pode encontrar um erro devido à presença de arquivos gerados. Você pode removê-los usando scons --clean <opcoes>, onde <opcoes> é a lista de opções de compilação que você usou para compilar o Godot anteriormente.

Como alternativa, você pode usar git clean -fixd, que limpará os artefatos de compilação de todas as plataformas e configurações. Cuidado, pois isso removerá todos os arquivos não rastreados e ignorados no repositório. Não execute esse comando se tiver trabalhos não salvos (uncommitted)!

Outras opções de build

Existem várias outras opções de compilação que você pode usar para configurar a maneira como o Godot deve ser compilado (compilador, opções de depuração, etc.), bem como os recursos a serem incluídos/desativados.

Verifique a saída de scons --help para detalhes sobre cada opção para a versão que você deseja compilar.

Sobrescrevendo as opções de compilação

Usando um arquivo

O arquivo padrão custom.py pode ser criado na raiz do código-fonte do Godot Engine para inicializar quaisquer opções de compilação do SCons passadas por meio da linha de comando:

custom.py
optimize = "size"
module_mono_enabled = "yes"
use_llvm = "yes"
extra_suffix = "game_title"

Você também pode desativar alguns dos módulos integrados antes de compilar, economizando algum tempo que leva para construir o motor. Veja a página Otimizando uma compilação para o tamanho para mais detalhes.

Ver também

Você pode usar o Gerador de opções de compilação do Godot online para gerar um arquivo custom.py contendo as opções do SCons. Você pode então salvar esse arquivo e colocá-lo na raiz do diretório de origem do seu Godot.

Outro arquivo personalizado pode ser especificado explicitamente com a opção de linha de comando profile, ambos substituindo a configuração de compilação padrão:

scons profile=path/to/custom.py

Nota

As opções de compilação definidas a partir do arquivo podem ser substituídas pelas opções de linha de comando.

Também é possível substituir as opções 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 o SCONSFLAGS

SCONSFLAGS é uma variável de ambiente usada pelo SCons para definir as opções automaticamente sem ter que fornecê-las via linha de comando.

Por exemplo, você pode querer forçar uma série de threads de CPU com a opção -j mencionada acima para todas as compilações futuras:

export SCONSFLAGS="-j4"

Compilação SCU (single compilation unit)

As compilações regulares tendem a ser gargalos pela inclusão de um grande número de cabeçalhos (headers) em cada unidade de tradução de compilação. Principalmente para acelerar o desenvolvimento (em vez de compilações de produção), o Godot oferece uma compilação de unidade de compilação única (também conhecida como compilação "Unity / Jumbo").

Para as pastas aceleradas por esta opção, múltiplos arquivos .cpp são compilados em cada unidade de tradução, permitindo que os cabeçalhos sejam compartilhados entre vários arquivos, o que pode diminuir drasticamente os tempos de compilação.

Para realizar uma compilação SCU, use a opção do 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.

Modelos de exportação

Os modelos de exportação oficiais são baixados do site do Godot Engine: godotengine.org. No entanto, você pode querer compilá-los você mesmo (caso queira modelos mais novos, esteja usando módulos personalizados ou simplesmente não confie na própria sombra).

Se você baixar o pacote de modelos de exportação oficial e descompactá-lo, notará que a maioria dos arquivos são binários otimizados ou pacotes 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 criá-los você mesmo, siga as instruções detalhadas para cada plataforma nesta mesma seção do tutorial. Cada plataforma explica como criar seu próprio modelo.

O arquivo version.txt deve conter o identificador de versão correspondente do Godot. Este arquivo é usado para instalar os modelos de exportação em um diretório específico da versão para evitar conflitos. Por exemplo, se você estiver compilando modelos de exportação para o Godot 4.4.1, o version.txt deve conter 4.4.1.stable na primeira linha (e nada mais). Este identificador de versão é baseado nas linhas major, minor, patch (se presente) e status do arquivo version.py no repositório Git do Godot.

Se você está desenvolvendo para múltiplas plataformas, o macOS é definitivamente a plataforma de hospedagem mais conveniente para compilação cruzada, já que você pode compilar de forma cruzada para cada alvo. O Linux e o Windows vêm em segundo lugar, mas o Linux tem a vantagem de ser a plataforma mais fácil para configurar isso.