コンテンツへスキップ

コンパイラの利用

コンパイルと実行を一度に行う

プログラムを一度にコンパイルして実行するには、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: 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 ページ 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 <出力ファイル>: バイナリ実行可能ファイルの名前を定義します。
  • -O LEVEL: 最適化レベルを定義します: 0 (デフォルト)、1、2、3。詳細は、最適化を参照してください。
  • --release: リリースモードでコンパイルします。-O3 --single-module と同等です。
  • --link-flags FLAGS: リンカーに渡す追加のフラグ。
  • --no-debug: シンボリックデバッグ情報をスキップし、出力ファイルサイズを縮小します。
  • --progress: コンパイル中に進行状況を表示します。
  • --static: 静的にリンクします。
  • --verbose: 実行されたコマンドを表示します。

その他のオプションについては、統合ヘルプ crystal build --help または man ページ 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!

注記

インタラクティブに実行する場合、通常、stdin は送信終了文字（Ctrl+D）を入力することで閉じることができます。

一般的なオプション

  • -o <出力ファイル>: バイナリ実行可能ファイルの名前を定義します。
  • -O LEVEL: 最適化レベルを定義します: 0 (デフォルト)、1、2、3。詳細は、最適化を参照してください。
  • --release: リリースモードでコンパイルします。-O3 --single-module と同等です。
  • --no-debug: シンボリックデバッグ情報をスキップし、出力ファイルサイズを縮小します。
  • --progress: コンパイル中に進行状況を表示します。
  • --static: 静的にリンクします。

その他のオプションについては、統合ヘルプ（crystal eval --help）または man ページ（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 の名前空間を反映したフォルダ構造で、各 Crystal 型の HTML ファイルで構成されています。エントリポイント docs/index.html は、任意のウェブブラウザで開くことができます。API ドキュメント全体は、$output_dir/index.json に JSON ドキュメントとしても保存されます。

デフォルトでは、./src 内のすべての Crystal ファイルが追加されます（つまり、src/**/*.cr）。ロード順序の依存関係を考慮するために、source_file を使用して、ドキュメントジェネレータのエントリポイントを 1 つ（または複数）指定できます。

crystal docs src/my_app.cr

一般的なオプション

  • --project-name=NAME: プロジェクト名を設定します。デフォルト値は、利用可能な場合は shard.yml から抽出されます。デフォルトが見つからない場合は、このオプションは必須です。
  • --project-version=VERSION: プロジェクトのバージョンを設定します。デフォルト値は、現在の git コミットまたは利用可能な場合は shard.yml から抽出されます。デフォルトが見つからない場合は、このオプションは必須です。
  • --output=DIR, -o DIR: 出力ディレクトリを設定します（デフォルト: ./docs）
  • --canonical-base-url=URL, -b URL: 正規ベース URL を設定します。

上記の例で、カスタム正規ベース 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>...]

デフォルトでは、シェルスクリプトとして情報を出力します。1 つ以上の var 引数が指定された場合は、指定された各変数の値が 1 行ずつ出力されます。

例

$ 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 引数は、1 つの 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: Test Anything Protocol (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]

テキスト出力は、タブで区切られた列の行のリストです。

出力フィールド

  • count: このメソッドへのすべての呼び出しの合計（--tallies オプションを使用した場合のみ。それ以外の場合はスキップされます）
  • location: パス名、行、列（すべてコロンで区切られています）
  • 名前
  • lines: 行数での定義の長さ
  • 注釈

オプション

  • -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 build ではなく crystal run で実行される場合に、実行可能ファイルを一時的に保存するためにも使用されます。デフォルト値は、${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カラーエスケープをオフにします。