編譯時期標誌¶

編譯時期標誌是透過編譯器，經由巨集方法提供的布林值。它們允許根據編譯時期的條件，有條件地包含或排除程式碼。

編譯器會提供數個預設標誌，其中包含關於編譯器選項和目標平台的資訊。使用者提供的標誌會傳遞給編譯器，使其能作為功能標誌使用。

查詢標誌¶

標誌僅是一個已命名的識別符號，其狀態為已設定或未設定。可以透過巨集方法 flag? 從程式碼查詢狀態。它接收一個標誌名稱，作為字串或符號字面值，並回傳一個布林字面值，指出標誌的狀態。

以下程式碼顯示如何使用編譯時期標誌來印出目標作業系統家族。

{% if flag?(:unix) %}
  puts "This program is compiled for a UNIX-like operating system"
{% elsif flag?(:windows) %}
  puts "This program is compiled for Windows"
{% else %}
  # Currently, all supported targets are either UNIX or Windows platforms, so
  # this branch is practically unreachable.
  puts "Compiling for some other operating system"
{% end %}

還有巨集方法 host_flag?，它可以回傳某個標誌是否針對「主機」平台設定。在交叉編譯期間，主機平台可能與目標平台（由 flag? 查詢）不同。

編譯器提供的標誌¶

編譯器定義了一些隱含標誌。它們描述了目標平台或編譯器選項。

目標平台標誌¶

特定於平台的標誌衍生自目標三元組。有關支援的目標平台清單，請參閱平台支援。

crystal --version 會顯示編譯器的預設目標三元組。可以使用 --target 選項來變更。

下表中每個表格的標誌都是互斥的，除非標示為（衍生）。

架構¶

目標架構是目標三元組的第一個組成部分。

標誌名稱	描述
`aarch64`	AArch64 架構
`avr`	AVR 架構
`arm`	ARM 架構
`i386`	x86 架構 (32 位元)
`wasm32`	WebAssembly
`x86_64`	x86-64 架構
`bits32` (衍生)	32 位元架構
`bits64` (衍生)	64 位元架構

供應商¶

供應商是目標三元組的第二個組成部分。它通常未使用，因此最常見的供應商是 unknown。

標誌名稱	描述
`macosx`	Apple
`portbld`	FreeBSD 變體
`unknown`	不明供應商

作業系統¶

作業系統衍生自目標三元組的第三個組成部分。

標誌名稱	描述
`bsd` (衍生)	BSD 系列 (DragonFlyBSD、FreeBSD、NetBSD、OpenBSD)
`darwin`	Darwin (MacOS)
`dragonfly`	DragonFlyBSD
`freebsd`	FreeBSD
`linux`	Linux
`netbsd`	NetBSD
`openbsd`	OpenBSD
`solaris`	Solaris/illumos
`unix` (衍生)	類 UNIX (BSD、Darwin、Linux、Solaris)
`windows`	Windows

ABI¶

ABI 衍生自目標三元組的最後一個組成部分。

標誌名稱	描述
`android`	Android (Bionic C 執行時期)
`armhf` (衍生)	具有硬浮點的 ARM EABI
`gnu`	GNU
`gnueabihf`	具有硬浮點的 GNU EABI
`msvc`	Microsoft Visual C++
`musl`	musl
`wasi`	Web Assembly 系統介面
`win32` (衍生)	Windows API

編譯器選項¶

編譯器會根據編譯器設定來設定這些標誌。

標誌名稱	描述
`release`	編譯器以發佈模式運作 (`--release` 或 `-O3 --single-module` CLI 選項)
`debug`	編譯器產生除錯符號 (沒有 `--no-debug` CLI 選項)
`static`	編譯器建立靜態連結的可執行檔 (`--static` CLI 選項)
`docs`	處理程式碼以產生 API 文件 (`crystal docs` 命令)
`interpreted`	在直譯器中執行 (`crystal i`)

使用者提供的標誌¶

使用者提供的標誌不會自動定義。它們可以透過 --define 或 -D 命令列選項傳遞給編譯器。

這些標誌通常會啟用某些功能，這些功能會啟用破壞性的新功能或舊功能、新功能的預覽或完全替代的行為 (例如，用於除錯目的)。

$ crystal eval -Dfoo 'puts {{ flag?(:foo) }}'
true

Stdlib 功能¶

這些標誌 (flags) 可以在建置 Crystal 程式時啟用或停用標準函式庫中的功能。

標誌名稱	描述
`gc_none`	停用垃圾回收機制 (#5314)
`debug_raise`	用於 `raise` 邏輯的除錯標誌。會在拋出例外之前印出回溯 (backtrace)。
`preview_mt`	啟用多執行緒預覽。在 0.28.0 版本中引入 (#7546)
`skip_crystal_compiler_rt`	排除 Crystal 原生的 `compiler-rt` 實作。
`tracing`	建置時支援執行時期追蹤。
`use_libiconv`	使用 `libiconv` 而非系統的 `iconv` 函式庫。
`use_pcre2`	使用 PCRE2 作為正規表示式引擎（而非舊版的 PCRE）。在 1.7.0 版本中引入。
`use_pcre`	使用 PCRE 作為正規表示式引擎（而非 PCRE2）。在 1.8.0 版本中引入。
`win7`	針對 Windows 7 使用 Win32 WinNT API。
`without_iconv`	不連結 `iconv`/`libiconv`。
`without_openssl`	建置時不支援 OpenSSL。
`without_zlib`	建置時不支援 Zlib。

編譯器功能¶

這些標誌 (flags) 可以在建置 Crystal 程式時啟用或停用編譯器功能。

標誌名稱	描述
`no_number_autocast`	不會自動轉換數值運算式，僅會自動轉換字面值。
`no_restrictions_augmenter`	停用增強的限制擴充器。在 1.5 版本中引入 (#12103)。
`preview_dll`	在 Windows 上啟用動態連結；實驗性功能。
`preview_overload_order`	啟用 def 多載之間更穩健的排序。在 1.6 版本中引入 (#10711)。
`preview_win32_delay_load`	在 Windows 上延遲載入所有 DLL；實驗性功能。
`strict_multi_assign`	啟用一對多賦值的嚴格語意。在 1.3.0 版本中引入 (#11145, #11545)

編譯器建置功能¶

這些標誌 (flags) 可以在建置 Crystal 編譯器時啟用或停用功能。

標誌名稱	描述
`without_ffi`	建置編譯器時不包含 `libffi`。
`without_interpreter`	建置編譯器時不包含直譯器支援。
`without_playground`	建置編譯器時不包含 playground (`crystal play`)。
`i_know_what_im_doing`	針對非自願建置編譯器的安全防護措施。

使用者程式碼功能¶

只要不與編譯器提供的標誌或其他使用者自訂的標誌衝突，使用者程式碼可以自由使用自訂標誌。當使用特定於 shard 的標誌時，建議使用 shard 名稱作為前綴。