CRYSTAL(1)

Crystal Compiler Command Line Reference Guide

CRYSTAL(1)

NAME

crystal - compiler for the Crystal language

SYNOPSIS

crystal command [switches] programfile — [arguments]

DESCRIPTION

Crystal is a statically type-checked programming language. It was created with the beauty of Ruby and the performance of C in mind.

USAGE

You can compile and run a program by invoking the compiler with a single filename:

crystal some_program.cr

Crystal files usually end with the .cr extension, though this is not mandatory.

Alternatively you can use the run command:

crystal run some_program.cr

To create an executable use the build command:

crystal build some_program.cr

This will create an executable named "some_program".

Note that by default the generated executables are not fully optimized. To turn optimizations on, use the --release flag:

crystal build --release some_program.cr

Make sure to always use --release for production-ready executables and when performing benchmarks.

The optimizations are not turned on by default because the compile times are much faster without them and the performance of the program is still pretty good without them, so it allows to use the crystal command almost to be used as if it was an interpreter.

CRYSTAL COMMANDS

Main commands

crystal-init(1)

Create a a new Crystal project

crystal-build(1)

Compile a Crystal program

crystal-docs(1)

Generate API docs for Crystal code

crystal-env(1)

Print environment variables for the Crystal compiler

crystal-eval(1)

Evaluate a crystal program

crystal-play(1)

Run the Crystal playground

crystal-run(1)

Compile and run a Crystal program

crystal-spec(1)

Compile and run Crystal spec files

crystal-clear_cache

Clear the compiler cache (located at 'CRYSTAL_CACHE_DIR').

crystal-help

Show help. Option --help or -h can also be added to each command for command-specific help.

crystal-version

Show version.

Tools

crystal-tool-context

Show context for given location

crystal-tool-dependencies(1)

Show tree of required source files

crystal-tool-expand

Show macro expansion for given location

crystal-tool-flags

Print all macro 'flag?' values

crystal-tool-format(1)

Format Crystal source files

crystal-tool-hierarchy

Show hierarchy of types from file. Also show class and struct members, with type and size. Types can be filtered with a regex by using the -e flag.

crystal-tool-implementations

Show implementations for a given call. Use --cursor to specify the cursor position. The format for the cursor position is file:line:column.

crystal-tool-macro_code_coverage

Generate a macro code coverage report.

crystal-tool-types

Show type of main variables of file.

crystal-tool-unreachable(1)

Identify methods that are never called

OPTIMIZATIONS

The optimization level specifies the codegen effort for producing optimal code. It’s a trade-off between compilation performance (decreasing per optimization level) and runtime performance (increasing per optimization level).

Production builds should usually have the highest optimization level. Best results are achieved with --release which also implies --single-module

-O0

No optimization (default)

-O1

Low optimization

-O2

Middle optimization

-O3

High optimization

-Os

Middle optimization with focus on file size

-Oz

Middle optimization aggressively focused on file size

ENVIRONMENT VARIABLES

CRYSTAL_CACHE_DIR

Defines path where Crystal caches partial compilation results for faster subsequent builds. This path is also used to temporarily store executables when Crystal programs are run with 'crystal run' rather than 'crystal build'.

CRYSTAL_EXEC_PATH

Determines the path where crystal looks for external sub-commands.

CRYSTAL_LIBRARY_PATH

Defines paths where Crystal searches for (binary) libraries. Multiple paths can be separated by ":". These paths are passed to the linker as -L flags.

The pattern '$ORIGIN' at the start of the path expands to the directory where the compiler binary is located. For example, '$ORIGIN/../lib/crystal' resolves the standard library path relative to the compiler location in a generic way, independent of the absolute paths (assuming the relative location is correct).

CRYSTAL_PATH

Defines paths where Crystal searches for required source files. Multiple paths can be separated by ":".

The pattern '$ORIGIN' at the start of the path expands to the directory where the compiler binary is located. For example, '$ORIGIN/../share/crystal/src' resolves the standard library path relative to the compiler location in a generic way, independent of the absolute paths (assuming the relative location is correct).

CRYSTAL_OPTS

Defines options for the Crystal compiler to be used besides the command line arguments. The syntax is identical to the command line arguments. This is handy when using Crystal in build setups, for example 'CRYSTAL_OPTS=--debug make build'.