Up to date

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

建置系統簡介

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:

• 為 Android 進行編譯

• 最佳化建置檔案大小

• 通過 Mono 進行編譯

• 最佳化建置檔案大小

• 最佳化建置檔案大小

• 最佳化建置檔案大小

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

選擇平台

Godot 的建置系統會通過偵測能建置的平台來開始。如果為偵測到，則該平台不會顯示在可用平台的列表中。建置對各個平台的需求寫在本教學接下來的段落中。

只需要呼叫 scons 就可以開啟 SCons。若未指定平台，SCons 會自動依據宿主機的平台來偵測目標平台。接著，SCons 會直接開始為目標平台進行建置。

若要列出所有可用的目標平台，請使用 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>

若要為某個平台建置 (如 x11)，請使用 platform= (或簡寫為 p= ) 印數來執行：

scons platform=linuxbsd

產生的二進位檔

產生的二進位檔會放在 bin/ 子資料夾中。通常來說會依照下列命名慣例：

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

依照前面這個建置例子，產生的結果會長這樣：

ls bin
bin/godot.linuxbsd.editor.x86_64

這表示，這個二進位檔是給 X11 用的，並未經過最佳化，有編譯進工具 (整個編輯器)，且是用於 64 位元的。

使用相同設定的 Window 二進位執行檔會長這樣：

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

由於該二進位執行檔包含了專案管理員、編輯器與所有用於執行遊戲的東西，可以將該執行檔複製到任何地方。但是，這個二進位執行檔缺少了可以匯出至其他平台的資料。要匯出至其他平台，則需要匯出樣板 (匯出樣板可以從 godotengine.org 下載，或是可自行建置)。

除此之外，還有其他能用於所有建置目標的標準選項，下方將進行說明。

目標

建置目標是用來控制最佳化旗標與偵錯旗標的。各個模式分別代表：

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

工具預設會在所有 PC 目標上啟用 (Linux, Window, macOS)，其他平台則預設關閉。如果將工具禁用，產生的二進位檔則只能執行專案，而不會包含編輯器與專案管理員。

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

開發

建立開發建置（執行偵錯/分析 工具）時，與生產建置相比，您通常有不同的目標（使二進位檔案盡可能快且小）。

Godot 提供了一系列常見的容器：

• dev_mode=yes 是``verbose=yes warnings=extra werror=yes tests=yes`` 的別名。這將啟用警告即錯誤行為（類似於 Godot 的持續整合設定），並且還建置:ref:單元測試 <doc_unit_testing>，以便您可以在本地運作它們。

• product=yes 是``use_static_cpp=yes debug_symbols=no lto=auto`` 的別名。靜態連結 libstdc++ 可以在針對 Linux 進行編譯時實作更好的二進位可攜性。當使用 MinGW 編譯 Linux、Web 和 Windows 時，此別名還可以啟用連結時最佳化，但在使用 MSVC 編譯 macOS、iOS 或 Windows 時保持停用 LTO。這是因為這些平台上的 LTO 連結速度非常慢或產生的程式碼有問題。

您可以透過在同一命令列上使用不同的值指定這些別名來手動覆寫這些選項。例如，您可以使用 scons production=yes debug_symbols=yes 建立包含偵錯符號的生產最佳化二進位檔案。

開發建構

備註

dev_build 不應與 dev_mode 混淆，後者是幾個與開發相關的選項的別名（見上文）。

在進行引擎開發時，「dev_build」選項可以與「target」一起使用來啟用特定於開發的程式碼。 dev_build 定義``DEV_ENABLED``，停用最佳化（-O0//0d），啟用產生偵錯符號，且不定義``NDEBUG``（因此``assert( ) `` 適用於第三方函式庫）。

scons platform=<platform> dev_build=yes

此旗標將“.dev”後綴（用於開發）附加到產生的二進位名稱。

也參考

還有其他 SCons 選項可以啟用 sanitizers，這些工具可以在編譯時啟用，以更好地偵錯某些引擎問題。請參閱 doc_using_sanitizers 以了解更多資訊。

偵錯

預設情況下，使用“debug_symbols=no”，這表示編譯的二進位檔案中不包含偵錯符號。使用“debug_symbols=yes”在編譯的二進位檔案中包含偵錯符號，這允許偵錯器和分析器正常工作。 Godot 的當機堆疊追蹤還需要偵錯符號來顯示對原始程式碼檔案和行的參考。

缺點是除錯符號是大檔案（比二進位檔案本身大得多）。因此，官方二進位檔案目前不包含偵錯符號。這意味著您需要自己編譯 Godot 才能存取偵錯符號。

當使用“debug_symbols=yes”時，您也可以使用“separate_debug_symbols=yes”將偵錯資訊放在帶有“.debug”後綴的單獨檔案中。這允許獨立分發兩個檔案。請注意，在 Windows 上，當使用 MSVC 進行編譯時，偵錯資訊*總是*寫入到單獨的 .pdb 檔案中，無論 ``separate_debug_symbols ``如何。

小訣竅

使用“strip <path/to/binary>”命令從已編譯的二進位檔案中刪除偵錯符號。

最佳化

可以選擇以下幾種編譯器最佳化等級：

• optimize=speed_trace （針對非 Web 平台時的預設設定）：以較大的二進位大小為代價提高執行速度。最佳化有時可能會對偵錯器的使用產生負面影響（堆疊追蹤可能不太準確。如果您遇到這種情況，請改用「optimize=debug」。

• 「optimize=speed」：與「optimize=speed_trace」相比，有利於更高的執行速度，但代價是二進位大小更大。與“optimize=debug”相比，除錯更加不友好，因為它使用了最積極的優化。

• optimize=size （針對 Web 平台時的預設值）：支援小型二進位檔案，但代價是執行速度較慢。

• optimize=debug：僅啟用不會以任何方式影響偵錯的最佳化。這會導致二進位檔案比“optimize=none”更快，但比“optimize=speed_trace”慢。

• optimize=none：不執行任何最佳化。這提供了最快的建置時間，但執行時間最慢。

• optimize=custom （僅限進階使用者）：不要將最佳化參數傳遞給 C/C++ 編譯器。您必須使用“CFLAGS”、“CCFLAGS”和“CXXFLAGS” SCons 選項手動傳遞參數。

架構

位元是用來控制要執行二進位檔的 CPU 或作業系統版本。主要是用於桌面環境，而其他平台通常會忽略此一旗標。

「arch」 選項支援的值為 auto、x86_32、x86_64、arm32、arm64、rv64、ppc32 **、 **ppc64 和**wasm32**。

scons platform=<platform> arch={auto|x86_32|x86_64|arm32|arm64|rv64|ppc32|ppc64|wasm32}

該旗標會加在最終產生的二進位檔檔名後方加上對應的 .32 或 .64 後置詞。若使用 bits=default ，則會使用偵測到的架構。

自定義模組

除了內建模組之外，還可以編譯在 Godot 資料夾外部的模組。

可以在編譯前將 custom_modules 建置選項傳給命令行。該選項為以半形逗號分隔的列表，內含資料夾路徑。各個資料夾則需放置與內建 modules/ 資料夾內一樣，可被視為 C++ 套件的獨立的 C++ 模組。

舉例來說，可以同時提供包含這種模組的相對路徑、絕對路徑、以及使用者資料夾路徑：

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

備註

若有自定模組的資料夾名稱與內建模組的名稱相同，則 Godot 只會編譯自定模組。可以利用這個功能來複寫掉內建的模組。

也參考

doc_custom_modules_in_c++

清理產生的檔案

有時候可能會因為已有產生出來的檔案而發聲錯誤。可以使用 scons --clean <選項> 來移除產生的檔案。<選項> 是之前用來建置 Godot 的建置選項列表。

另外，也可以使用 git clean --fixd ，該指令會清除所有平台有設定的建置結果。請小心，因為這個指令同時也會移除儲存庫中所有尚未被 Git 追蹤的檔案以及 Git 忽略的檔案。若有還未 Commit 的更改，請不要執行這個指令！

其他建置選項

還有其他一些可以用來設定如何建置 Godot 的建置選項 (調整編譯器、除錯選項…等)，還有一些可以調整要包含或禁用特定功能的選項。

請檢視 scons --help 的輸出，以瞭解各個選項在要編譯的版本上之詳細說明。

複寫建置選項

使用檔案

預設可以在 Godot Engine 的原始碼根目錄建立一個 custom.py 檔案來初始化任何通過命令行傳給 SCons 的建置選項：

# custom.py

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

也可以在編譯前禁用一些內建模組，來節省建置引擎的時間。請參考 最佳化建置檔案大小 一頁以瞭解詳情。

也參考

可以通過 Godot 建置選項產生器 線上工具來產生包含 SCons 選項的 custom.py 檔案。然後將該檔案保存並放置於 Godot 原始碼資料夾的根目錄。

另外也可以通過 profile 命令行選項來明確指定要用哪個自定檔案。兩種方法都會複寫預設的建置組態：

scons profile=path/to/custom.py

備註

通過檔案設定的建置選項可以通過命令行選項來複寫。

也可以有條件地複寫選項：

# 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

使用 SCONSFLAGS

SCONSFLAGS 是 SCons 用來自動設定選項的環境變數，使用 SCONSFLAGS 就不需要通過命令行來給定選項。

舉例來說，我們可能會想使用剛才提到的 -j 選項來同時為所有功能進行建置：

Linux/macOSWindows (cmd)Windows (PowerShell)

export SCONSFLAGS="-j4"

SCU（單一編譯單元）建構

常規建置往往會因每個編譯翻譯單元中包含大量標頭而遇到瓶頸。主要是為了加快開發速度（而不是生產建置），Godot 提供了「單一編譯單元」建置（又稱「Unity / Jumbo」建置）。

對於透過此選項加速的資料夾，每個翻譯單元中都會編譯多個“.cpp”檔案，因此可以在多個檔案之間共用標頭，這可以顯著減少建置時間。

若要建置 SCU，請使用 scu_build=yes SCons 選項。

備註

使用 SCU 建置開發 Pull 請求時，請務必在提交 PR 之前進行常規建置。這是因為 SCU 建置本質上包含翻譯單元中早期 .cpp 檔案的標頭，因此不會捕獲常規建置中所需的所有包含內容。 CI 會捕獲這些錯誤，但在電腦上的本機建置上捕獲它們通常會更快。

匯出樣板

官方匯出樣板可以從 Godot Engine 網站進行下載: godotengine.org 。但你也可以自行進行建置 (例如當需要新版本、使用自定模組、或是不信任其他人建置的版本時)。

若下載官方匯出模板套件並解壓縮後，可以注意到大多數檔案都是為各個平台最佳化過的二進位檔或套件：

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

若要自己進行建置，請依照個別平台教學中的詳細說明來進行。各個平台的說明文件中都解釋了如何建置樣板。

version.txt 檔案中應該要包含有對應的 Godot 版本識別項。這個檔案是用來將匯出樣板安裝到版本特定的資料夾中，以避免衝突。舉例來說，如果為 Godot 3.1.1 建置匯出樣板，則 version.txt 的第一行應包含 3.1.1.stable (且不得含有其他內容)。這個版本識別項是基於 主板號 Major 、 次版號 Minor 、 修訂號 Patch (若有的話)、以及 Godot Git 儲存庫中的 version.py 檔案 狀態 Status 。

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.