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
Create a a new Crystal project
Compile a Crystal program
Generate API docs for Crystal code
Print environment variables for the Crystal compiler
Evaluate a crystal program
Run the Crystal playground
Compile and run a Crystal program
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
Show tree of required source files
crystal-tool-expand
Show macro expansion for given location
crystal-tool-flags
Print all macro 'flag?' values
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.
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'.
SEEALSO
<https://crystal-lang.org/> The official web site.
<https://github.com/crystal-lang/crystal> Official Repository.