使用编译器

同时编译和运行

要同时编译和运行程序，请使用单个文件名调用 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 游乐场服务器
• 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 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 文件，并将生成可执行文件的命令打印到标准输出。
• -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 crystal。

crystal eval

crystal eval 命令从命令行或标准输入中读取 Crystal 源代码，将其编译成一个二进制可执行文件，然后立即运行该文件。

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

如果未提供 source 参数，则 Crystal 源代码将从标准输入中读取。二进制可执行文件存储在编译和运行之间的临时位置。

示例

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

注意

在交互式运行时，通常可以通过键入传输结束字符 (Ctrl+D) 来关闭标准输入。

常用选项

• -o <output_file>: 定义二进制可执行文件的名称。
• -O LEVEL: 定义优化级别：0（默认）、1、2、3。有关详细信息，请参阅 优化。
• --release: 在发布模式下编译。等效于 -O3 --single-module。
• --no-debug: 跳过任何符号调试信息，从而减小输出文件大小。
• --progress: 在编译期间显示进度。
• --static: 静态链接。

更多选项在集成帮助中描述：crystal eval --help 或手册页 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 可以通过任何 Web 浏览器打开。整个 API 文档也存储在 $output_dir/index.json 中的 JSON 文档中。

默认情况下，./src 中的所有 Crystal 文件将被附加（即 src/**/*.cr）。为了考虑加载顺序依赖关系，可以使用 source_file 指定一个（或多个）文档生成器的入口点。

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

对于上面的示例，要将文档输出到 public，并使用自定义的规范基址 URL，以及入口点 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 脚本的形式打印信息。如果提供了一个或多个 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 规格套件。

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

所有 files 参数都将连接成一个 Crystal 源代码。如果参数指向一个文件夹，则该文件夹（及其递归子文件夹）内所有名为 *_spec.cr 的规格文件将被附加。如果未提供 files 参数，则默认为 ./spec 文件夹。文件名可以后缀为 : 和行号，将此位置提供给 --location 运行器选项（见下文）。

运行 crystal spec --options 以查看可用的前缀选项。

运行器选项

runner_options 提供给编译后的二进制可执行文件，该文件运行规格。它们应该用双破折号 (--) 与其他参数隔开。

• --verbose, -v：打印详细输出，包括所有示例名称。
• --profile, -p：打印 10 个最慢的规格。
• --fail-fast：在第一个失败时中止规格运行。
• --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：打印帮助信息并退出。

以下运行器选项可以组合起来过滤要运行的规格列表。

• --example <name>, -e <name>：运行其完整嵌套名称包含 <name> 的示例。
• --line <line>, -l <line>：运行其行与 <line> 匹配的示例。
• --location <file>:<line>：运行 <file> 中 <line> 处的示例（允许使用多个选项）。
• --tag <tag>：运行具有指定标签的示例，或通过在标签前添加 ~ 来排除示例（允许使用多个选项）。
  • --tag a --tag b 将包含标记为 a 或 b 的规格。
  • --tag ~a --tag ~b 将包含未标记为 a 且未标记为 b 的规格。
  • --tag a --tag ~b 将包含标记为 a 但未标记为 b 的规格。

示例

$ 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 命令启动一个 Web 服务器，该服务器提供一个交互式 Crystal 游乐场。

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

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：路径名、行号和列号，全部用冒号分隔
• name
• lines：def 的长度（以行数计）
• annotations

选项

• -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 run 而不是 crystal build 运行 Crystal 程序时临时存储可执行文件。默认值为以下路径中第一个存在的或可以创建的目录：${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 彩色转义码。