使用編譯器¶

一次編譯並執行¶

要一次編譯並執行程式，請使用 crystal run 並帶入單一檔案名稱

$ echo 'puts "Hello World!"' > hello_world.cr
$ crystal run hello_world.cr
Hello World!

run 指令會將原始碼檔案 hello_world.cr 編譯為暫時位置中的二進位可執行檔，並立即執行。

建立可執行檔¶

crystal build 指令會建立二進位可執行檔。輸出檔案的名稱與原始碼檔案相同，但移除 .cr 副檔名。

$ crystal build hello_world.cr
$ ./hello_world
Hello World!

發佈組建¶

預設情況下，產生的可執行檔並未完全最佳化。可以使用 --release 旗標啟用最佳化。

$ crystal build hello_world.cr --release

在不使用發佈模式編譯的情況下速度會快得多，並且產生的二進位檔仍然能提供相當不錯的效能。

發佈模式組建應該用於準備生產的可執行檔和執行基準測試時。對於簡單的開發組建，通常沒有這樣做的理由。

若要減少可散佈檔案的二進位大小，可以使用 --no-debug 旗標。這會移除除錯符號以減少檔案大小，但顯然會使除錯更加困難。

建立靜態連結的可執行檔¶

可以使用 --static 旗標建立靜態連結的可執行檔

$ crystal build hello_world.cr --release --static

注意

目前僅在 Alpine Linux 上支援完全靜態連結的可執行檔組建。

有關靜態連結的更多資訊可以在靜態連結指南中找到。

編譯器會將 CRYSTAL_LIBRARY_PATH 環境變數作為要連結的靜態和動態函式庫的第一個查詢目的地。這可以用來提供同時以動態函式庫形式提供的靜態版本的函式庫。

建立 Crystal 專案¶

crystal init 指令可協助初始化 Crystal 專案資料夾，設定基本專案結構。 crystal init app <name> 用於應用程式，crystal init lib <name> 用於函式庫。

$ crystal init app myapp
    create  myapp/.gitignore
    create  myapp/.editorconfig
    create  myapp/LICENSE
    create  myapp/README.md
    create  myapp/shard.yml
    create  myapp/src/myapp.cr
    create  myapp/spec/spec_helper.cr
    create  myapp/spec/myapp_spec.cr
Initialized empty Git repository in /home/crystal/myapp/.git/

並非每個專案都需要所有這些檔案，有些可能需要更多自訂，但 crystal init 為開發 Crystal 應用程式和函式庫建立良好的預設環境。

編譯器指令¶

crystal init：產生新的專案
crystal build：建立可執行檔
crystal docs：產生文件
crystal env：列印 Crystal 環境資訊
crystal eval：從引數或標準輸入評估程式碼
crystal play：啟動 crystal playground 伺服器
crystal run：建立並執行程式
crystal spec：建立並執行規格
crystal tool：執行編譯器工具
crystal clear_cache：清除編譯器快取
crystal help：顯示關於指令和選項的說明
crystal version：顯示版本

若要查看特定指令的可用選項，請在指令後使用 --help

`crystal run`¶

run 指令會將原始碼檔案編譯為二進位可執行檔，並立即執行。

crystal [run] [<options>] <programfile> [-- <argument>...]

要編譯的二進位檔的引數可以使用雙破折號 -- 與編譯器引數分隔。二進位可執行檔會儲存在編譯和執行之間的暫時位置中。

範例

$ echo 'puts "Hello #{ARGV[0]?}!"' > hello_world.cr
$ crystal run hello_world.cr -- Crystal
Hello Crystal!

常見選項

-O LEVEL：定義最佳化層級：0（預設）、1、2、3。請參閱最佳化以瞭解詳細資訊。
--release：以發佈模式編譯。相當於 -O3 --single-module。
--progress：在編譯期間顯示進度。
--static：靜態連結。

更多選項在整合式說明中說明：crystal run --help 或 man page man crystal。

`crystal build`¶

crystal build 指令會建立動態連結的二進位可執行檔。

crystal build [<options>] <programfile>

除非指定，否則產生的二進位檔會與原始碼檔案同名，但移除 .cr 副檔名。

範例

$ echo 'puts "Hello #{ARGV[0]?}!"' > hello_world.cr
$ crystal build hello_world.cr
$ ./hello_world Crystal
Hello Crystal!

常見選項

--cross-compile：產生 .o 檔案，並將產生可執行檔的指令列印到 stdout。
-D FLAG, --define FLAG：定義編譯時旗標。
-o <output_file>：定義二進位可執行檔的名稱。
-O LEVEL：定義最佳化層級：0（預設）、1、2、3。請參閱最佳化以瞭解詳細資訊。
--release：以發佈模式編譯。相當於 -O3 --single-module。
--link-flags FLAGS：要傳遞給連結器的其他旗標。
--no-debug：跳過任何符號除錯資訊，以減少輸出檔案大小。
--progress：在編譯期間顯示進度。
--static：靜態連結。
--verbose：顯示已執行的指令。

更多選項在整合式說明中說明：crystal build --help 或 man page man crystal。

`crystal eval`¶

crystal eval 指令會從命令列或 stdin 讀取 Crystal 原始碼，將其編譯為二進位可執行檔，並立即執行。

crystal eval [<options>] [<source>]

如果未提供 source 引數，則會從標準輸入讀取 Crystal 原始碼。二進位可執行檔會儲存在編譯和執行之間的暫時位置中。

範例

$ crystal eval 'puts "Hello World"'
Hello World!
$ echo 'puts "Hello World"' | crystal eval
Hello World!

注意

以互動方式執行時，通常可以輸入傳輸結束字元 (Ctrl+D) 來關閉 stdin。

常見選項

-o <output_file>：定義二進位可執行檔的名稱。
-O LEVEL：定義最佳化層級：0（預設）、1、2、3。請參閱最佳化以瞭解詳細資訊。
--release：以發佈模式編譯。相當於 -O3 --single-module。
--no-debug：跳過任何符號除錯資訊，以減少輸出檔案大小。
--progress：在編譯期間顯示進度。
--static：靜態連結。

更多選項在整合式說明中說明：crystal eval --help 或 man page man crystal。

`crystal version`¶

crystal version 指令會列印 Crystal 版本、LLVM 版本和預設目標三元組。

crystal version

範例

$ crystal version
Crystal 1.14.0 [dacd97bcc] (2024-10-09)

LLVM: 18.1.6
Default target: x86_64-unknown-linux-gnu

`crystal init`¶

crystal init 指令會初始化 Crystal 專案資料夾。

crystal init (lib|app) <name> [<dir>]

第一個引數是 lib 或 app。 lib 是可重複使用的函式庫，而 app 描述不打算作為相依性的應用程式。函式庫在其存放庫中沒有 shard.lock 檔案，並且在 shard.yml 中沒有建置目標，而是有關於將其用作相依性的指示。

範例

$ crystal init lib my_cool_lib
    create  my_cool_lib/.gitignore
    create  my_cool_lib/.editorconfig
    create  my_cool_lib/LICENSE
    create  my_cool_lib/README.md
    create  my_cool_lib/shard.yml
    create  my_cool_lib/src/my_cool_lib.cr
    create  my_cool_lib/spec/spec_helper.cr
    create  my_cool_lib/spec/my_cool_lib_spec.cr
Initialized empty Git repository in ~/my_cool_lib/.git/

`crystal docs`¶

crystal docs 指令會從 Crystal 檔案中的內嵌文件字串產生 API 文件（請參閱程式碼文件化）。

crystal docs [--output=<output_dir>] [--canonical-base-url=<url>] [<source_file>...]

此命令會在 output_dir (預設為 ./docs) 中建立靜態網站，其中包含每個 Crystal 類型的 HTML 檔案，並以反映 Crystal 命名空間的資料夾結構呈現。任何網頁瀏覽器都可以開啟入口點 docs/index.html。整個 API 文件也會以 JSON 文件形式儲存在 $output_dir/index.json 中。

預設情況下，./src 中的所有 Crystal 檔案都會附加 (即 src/**/*.cr)。為了考慮載入順序的相依性，可以使用 source_file 來指定文件產生器的一個 (或多個) 入口點。

crystal docs src/my_app.cr

常見選項

--project-name=NAME: 設定專案名稱。如果有的話，預設值會從 shard.yml 中提取。如果找不到預設值，則此選項為必要選項。
--project-version=VERSION: 設定專案版本。如果有的話，預設值會從目前的 git commit 或 shard.yml 中提取。如果找不到預設值，則此選項為必要選項。
--output=DIR, -o DIR: 設定輸出目錄 (預設值: ./docs)
--canonical-base-url=URL, -b URL: 設定正規基礎網址

為了讓上述範例將文件輸出到 public，並使用自訂正規基礎網址和入口點 src/my_app.cr，可以使用以下引數

crystal docs --output public --canonical-base-url http://example.com/ src/my_app.cr

`crystal env`¶

crystal env 命令會印出 Crystal 使用的環境變數。

crystal env [<var>...]

預設情況下，它會以 shell script 的形式印出資訊。如果提供一個或多個 var 引數，則每個具名變數的值會印在自己的行上。

範例

$ crystal env
CRYSTAL_CACHE_DIR=/home/crystal/.cache/crystal
CRYSTAL_PATH=lib:/usr/bin/../share/crystal/src
CRYSTAL_VERSION=1.9.0
CRYSTAL_LIBRARY_PATH=/usr/bin/../lib/crystal
CRYSTAL_LIBRARY_RPATH=''
CRYSTAL_OPTS=''
$ crystal env CRYSTAL_VERSION
1.9.0

`crystal spec`¶

crystal spec 命令會編譯並執行 Crystal spec 套件。

crystal spec [<options>] [<file>[:line] | <folder>]... [-- [<runner_options>]]

所有 files 引數都會串連成單一個 Crystal 來源。如果引數指向資料夾，則會附加該資料夾 (及其遞迴子資料夾) 中名為 *_spec.cr 的所有 spec 檔案。如果沒有提供 files 引數，則預設為 ./spec 資料夾。檔名可以附加 : 和行號，將此位置提供給 --location 執行器選項 (請參閱下方)。

執行 crystal spec --options 以取得可用的前置選項。

執行器選項

runner_options 提供給編譯後的二進位可執行檔，以執行 spec。它們應該與其他引數以雙破折號 (--) 分隔。

--verbose, -v: 印出詳細輸出，包括所有範例名稱。
--profile, -p: 印出 10 個最慢的 spec。
--fail-fast: 在第一次失敗時中止 spec 執行。
--junit_output <output_dir>: 產生 JUnit XML 輸出。
--tap: 為測試任何協定 (TAP)產生輸出。
--(no-)color: 啟用 ANSI 彩色輸出。如果 STDOUT 是 TTY，預設模式會自動啟用色彩。
--order <mode>: 以指定的順序執行範例。<mode> 可以是 default (定義順序)、random 或數值種子值。預設值為 default。
--list-tags: 列出所有已定義的標籤並結束。
--dry-run: 傳遞所有測試，而不實際執行它們。
--help, -h: 印出說明並結束。

可以組合下列執行器選項來篩選要執行的 spec 清單。

--example <name>, -e <name>: 執行其完整巢狀名稱包含 <name> 的範例。
--line <line>, -l <line>: 執行其行號符合 <line> 的範例。
--location <file>:<line>: 執行 <file> 中 <line> 的範例 (允許多個選項)。
--tag <tag>: 執行具有指定標籤的範例，或在標籤前加上 ~ 來排除範例 (允許多個選項)。
- --tag a --tag b 將包含標記為 a 或 b 的 spec。
- --tag ~a --tag ~b 將包含未標記為 a 且未標記為 b 的 spec。
- --tag a --tag ~b 將包含標記為 a，但未標記為 b 的 spec。

範例

$ crystal spec
F

Failures:

  1) Myapp works
     Failure/Error: false.should eq(true)

       Expected: true
            got: false

     # spec/myapp_spec.cr:7

Finished in 880 microseconds
1 examples, 1 failures, 0 errors, 0 pending

Failed examples:

crystal spec spec/myapp_spec.cr:6 # Myapp works

`crystal play`¶

crystal play 命令會啟動一個網頁伺服器，以提供互動式 Crystal 遊樂場。

crystal play [--port <port>] [--binding <host>] [--verbose] [file]

Screenshot of Crystal playground

`crystal tool`¶

crystal tool context: 顯示指定位置的上下文
crystal tool dependencies: 顯示所需來源檔案的樹狀結構
crystal tool expand: 顯示指定位置的巨集展開
crystal tool flags: 印出所有巨集 flag? 值
crystal tool format: 格式化 Crystal 檔案
crystal tool hierarchy: 顯示類型階層
crystal tool implementations: 顯示位置中給定呼叫的實作
crystal tool types: 顯示主要變數的類型
crystal tool unreachable: 顯示永不呼叫的方法。

`crystal tool dependencies`¶

顯示所需來源檔案的樹狀結構。

crystal tool dependencies [options] [programfile]

選項

-D FLAG, --define FLAG: 定義編譯時旗標。這對於根據編譯時可用的旗標有條件地定義類型、方法或命令很有用。預設旗標來自使用 --target-triple 給定的目標三元組，如果未給定則來自主機預設值。
-f FORMAT, --format FORMAT: 輸出格式 tree (預設)、flat、dot 或 mermaid。
-i PATH, --include PATH: 在輸出中包含路徑。
-e PATH, --exclude PATH: 在輸出中排除路徑。
--verbose: 顯示已跳過和已篩選路徑的開頭
--error-trace: 顯示完整錯誤追蹤。
-h, --help: 顯示此訊息
--prelude PATH: 指定要使用的前奏。預設的前奏會初始化垃圾收集器。您也可以使用 --prelude=empty 來使用沒有前奏。這對於檢查特定原始碼檔案的程式碼產生非常有用。
-s, --stats: 啟用統計資料輸出
-p, --progress: 啟用進度輸出
-t, --time: 啟用執行時間輸出
--stdin-filename: 要從 STDIN 讀取的來源檔案名稱

`crystal tool format`¶

crystal tool format 命令會將預設格式套用至 Crystal 原始碼檔案。

crystal tool format [--check] [<path>...]

path 可以是檔案或資料夾名稱，並包含該資料夾樹狀結構中的所有 Crystal 檔案。省略 path 等同於指定目前的工作目錄。

格式化程式也適用於註解中的 Crystal 程式碼區塊 (請參閱文件化程式碼)。

`crystal tool unreachable`¶

顯示永不呼叫的方法。

crystal tool unreachable [options] [programfile]

文字輸出是一個由 Tab 分隔欄位的行清單。

輸出欄位

count: 此方法的所有呼叫總和 (僅適用於 --tallies 選項；否則會跳過)
location: 路徑名稱、行和列，全部以冒號分隔
名稱
lines: def 的行長度
註釋

選項

-D FLAG, --define FLAG: 定義編譯時旗標
-f FORMAT, --format FORMAT: 輸出格式 text (預設)、json 或 csv
--tallies: 也會印出可達方法及其呼叫次數。
--check: 如果有任何無法到達的程式碼，則以錯誤結束。
--error-trace: 顯示完整錯誤追蹤
-h, --help: 顯示此訊息
-i PATH, --include PATH: 包含路徑
-e PATH, --exclude PATH: 排除路徑 (預設值: lib)
--no-color: 停用彩色輸出
--prelude PATH: 使用給定的檔案作為前奏
-s, --stats: 啟用統計資料輸出
-p, --progress: 啟用進度輸出
-t, --time: 啟用執行時間輸出
--stdin-filename: 要從 STDIN 讀取的來源檔案名稱

`crystal clear_cache`¶

清除位於 CRYSTAL_CACHE_DIR 的編譯器快取。

最佳化¶

最佳化層級指定產生最佳程式碼的程式碼產生工作。這是編譯效能 (每個最佳化層級都會降低) 和執行階段效能 (每個最佳化層級都會提高) 之間的取捨。

生產版本通常應該具有最高最佳化層級。使用 --release 可獲得最佳結果，這也表示 --single-module。

-O0: 無最佳化 (預設)
-O1: 低最佳化
-O2: 中等最佳化
-O3: 高最佳化

環境變數¶

如果環境中設定了以下環境變數，Crystal 編譯器會使用它們。否則，編譯器會使用預設值填入它們。它們的值可以使用 crystal env 來檢查。

CRYSTAL_CACHE_DIR: 定義 Crystal 快取部分編譯結果的路徑，以加速後續組建。當 Crystal 程式使用 crystal run 而不是 crystal build 執行時，此路徑也用於暫時儲存可執行檔。預設值是 ${XDG_CACHE_HOME}/crystal (如果已定義 XDG_CACHE_HOME)、${HOME}/.cache/crystal、${HOME}/.crystal、./.crystal 中存在或可以建立的第一個目錄。如果設定了 CRYSTAL_CACHE_DIR 但指向不可寫入的路徑，則會改用預設值。
CRYSTAL_PATH: 定義 Crystal 搜尋所需檔案的路徑。
CRYSTAL_VERSION 僅可作為 crystal env 的輸出。編譯器不會設定也不會讀取它。
CRYSTAL_LIBRARY_PATH: 編譯器使用此變數中的路徑作為要連結的靜態和動態程式庫的第一個查詢目的地。例如，如果靜態程式庫放在 build/libs 中，則適當地設定環境變數會告訴編譯器在那裡尋找程式庫。

當環境變數 NO_COLOR 存在 (具有非空字串的值) 時，編譯器會符合 NO_COLOR 並關閉終端機中的 ANSI 色彩跳脫符號。

使用編譯器¶

一次編譯並執行¶

建立可執行檔¶

發佈組建¶

建立靜態連結的可執行檔¶

建立 Crystal 專案¶

編譯器指令¶

crystal run¶

crystal build¶

crystal eval¶

crystal version¶

crystal init¶

crystal docs¶

crystal env¶

crystal spec¶

crystal play¶

crystal tool¶

crystal tool dependencies¶

crystal tool format¶

crystal tool unreachable¶

crystal clear_cache¶

最佳化¶

環境變數¶

`crystal run`¶

`crystal build`¶

`crystal eval`¶

`crystal version`¶

`crystal init`¶

`crystal docs`¶

`crystal env`¶

`crystal spec`¶

`crystal play`¶

`crystal tool`¶

`crystal tool dependencies`¶

`crystal tool format`¶

`crystal tool unreachable`¶

`crystal clear_cache`¶