建置系統簡介

SCons

Godot 使用 SCons 來進行建置。我們很滿意 SCons,我們不會改用其他的建置系統。其實我們也不確定其他建置系統能否勝任建置 Godot 的任務。常常會有人問我們能不能改用其他建置系統,如 CMake 或 Visual Studio,但我們並不會改。會選擇 SCons 而不是其他系統有很多原因,如:

  • Godot 可以編譯到數十種不同的平台上:所有 PC 平台、所有行動平台、各種遊戲主機以及 WebAssembly。

  • 許多開發人員通常都需要 同時 為數個平台進行編譯,甚至需要為相同平台的不同架構進行編譯。這些開發人員可沒精力每次都為專案重新設定並重新建置。SCons 則可以輕鬆完成這項任務,且不會破壞建置的過程。

  • 不論做了多少的更改、設定、新增、移除…等,SCons 永遠都不會 把建置中斷。使用 SCons 是,需要清理並重新建置的機率比你被雷劈的機率還要低。

  • Godot 的建置過程可不簡單。有許多檔案是由程式產生的 (Binder),有些檔案是經過解析的 (Shader),還有一些檔案是用來提供客製化的 (外掛程式)。這個建置過程會需要複雜的邏輯,而使用真正的程式語言 (如 Python) 會簡單得多,因此不適合用那些用來建置、基於巨集的語言。

  • Godot 的建置過程會使用到大量交叉編譯的工具。各個平台都有特定的偵測過程,而這些過程都必須要通過撰寫特定的程式碼來作為各種特殊情況處理。

所以,如果你想自己建置 Godot 的話,請儘量保持開放的態度,並至少稍微熟悉一下 SCons。

Setup

如果要 為 Android 進行編譯, 為 iOS 進行編譯, 為 macOS 進行編譯, 為通用 Windows 平台進行編譯, 為網頁平台進行編譯, 為 Windows 進行編譯 and 為 X11 進行編譯 (Linux, *BSD) ,請參考上述的各個文件。

請注意,若使用 Windows/Visual Studio ,則依據安裝的環境,請不要使用一般的 Windows 命令提示資源來輸入下方的指令,必須要使用 適用於 VS 2017 x86_x64 Cross Tools 命令提示資源 (x86_x64 Cross Tools Command Prompt for VS 2017) 或類似工具。

選擇平台

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

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

若要列出所有可用的目標平台,請使用 scons platform=list

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

    android
    javascript
    server
    windows
    x11

Please run SCons again and select a valid platform: platform=<string>

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

scons platform=x11

這個指令會開始建置過程,會需要一段時間。若想要 SCons 建置快一點的話,可以使用 -j <核心數> 參數來指定建置過程要使用多少個核心。也可以保持使用單核心,這樣就可以同時用電腦做其他事 🙂

使用 4 核心的例子:

scons platform=x11 -j 4

產生的二進位檔

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

godot.<platform>.[opt].[tools/debug].<architecture>[extension]

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

ls bin
bin/godot.x11.tools.64

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

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

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

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

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

工具

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

scons platform=<platform> tools=yes/no

目標

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

  • debug: 以 C++ 除錯符號進行建置,包含執行階段檢查 (會進行檢查並回報錯誤) 以及最少量的最佳化。

  • release_debug: 以不含 C++ 除錯符號與最佳化的方式進行建置,僅保留執行階段檢查 (進行檢查並回報錯誤)。官方的編輯器二進位檔就是使用此設定。

  • release: 以不含符號的方式進行建置,包含最佳化與最少量的執行階段檢查。這個建置目標無法與 tools=yes 一起使用,因為要執行編輯器會需要一些除錯功能以及執行階段檢查。

scons platform=<platform> target=debug/release_debug/release

這個旗標會在檔名後加上 .debug (debug 版) 或 .tools (有啟用 tools 的 debug)。當有啟用最佳化時 (release),則會加上 .opt 後置詞。

位元

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

  • 32: 為 32 位元平台建置二進位檔。

  • 64: 為 64 位元平台建置二進位檔。

  • default: 為與宿主機平台相同的架構進行建置。

scons platform=<platform> bits=default/32/64

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

自定義模組

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

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

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

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

備註

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

清理產生的檔案

有時候可能會因為已有產生出來的檔案而發聲錯誤。可以使用 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"

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

另外也可以通過 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 選項來同時為所有功能進行建置:

export SCONSFLAGS="-j4"
set SCONSFLAGS=-j4
$env:SCONSFLAGS="-j4"

匯出樣板

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

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

android_debug.apk
android_release.apk
webassembly_debug.zip
webassembly_release.zip
linux_server_32
linux_server_64
linux_x11_32_debug
linux_x11_32_release
linux_x11_64_debug
linux_x11_64_release
osx.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

若要為多個平台進行開發,那麼 macOS 絕對是進行交叉編譯最方便的平台了,因為 (除了 UWP 外) 幾乎可以為所有平台進行交叉編譯。Linux 與 Windows 則為其次,但 Linux 的優點是比起其他平台更容易安裝開發環境。