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.
Checking the stable version of the documentation...
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 (defineTOOLS_ENABLEDeDEBUG_ENABLED)target=template_debug: Compila um modelo de exportação de depuração (defineDEBUG_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 paraverbose=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 parause_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ê, useoptimize=debugno lugar.optimize=speed: Favorece ainda mais a velocidade de execução, à custa de um tamanho de binário ainda maior em comparação comoptimize=speed_trace. Ainda menos amigável para a depuração em comparação comoptimize=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 comoptimize=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 queoptimize=none, mas mais lentos do queoptimize=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 SConscflags,ccflagsecxxflags.
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.
Ver também
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:
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:
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"
set SCONSFLAGS=-j4
$env: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.