crystal
— Compiler
for the Crystal language.
crystal |
command [switches] programfile -- [arguments] |
Crystal is a statically type-checked programming language. It was
created with the beauty of Ruby and the performance of C in mind.
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.
The crystal command accepts the following options
init
TYPE
[DIR | NAME DIR]
Generates a new Crystal project.
TYPE is one of:
- lib
- Creates a library skeleton
- app
- Creates an application skeleton
This initializes the lib/app project folder as a git
repository, with a license file, a README file, a shard.yml for use with
shards (the Crystal dependency manager), a .gitignore file, and src and
spec folders.
DIR - directory where project will be generated
NAME - name of project to be generated (default: basename of DIR)
Options:
-f,
--force
- Force overwrite existing files.
-s,
--skip-existing
- Skip existing files.
build
[options] [programfile] [--] [arguments]
Compile program.
Options:
--cross-compile
- Generate an object file for cross compilation and prints the command
to build the executable. The object file should be copied to the
target system and the printed command should be executed there. This
flag mainly exists for porting the compiler to new platforms, where
possible run the compiler on the target platform directly.
-d,
--debug
- Generate the output with symbolic debug symbols. These are read when
debugging the built program with tools like lldb, gdb, valgrind etc.
and provide mappings to the original source code for those tools.
--no-debug
- Generate the output without any symbolic debug symbols.
--lto
FLAG
- Use ThinLTO --lto=thin.
-D
FLAG, --define
FLAG
- Define a compile-time flag. This is useful to conditionally define
types, methods, or commands based on flags available at compile time.
The default flags are from the target triple given with
--target-triple or the hosts default, if none is given.
--emit
[asm|llvm-bc|llvm-ir|obj]
- Comma separated list of types of output for the compiler to emit. You
can use this to see the generated LLVM IR, LLVM bitcode, assembly, and
object files.
-f
text|json, --format
text|json
- Format of output. Defaults to text. The json format can be used to get
a more parser-friendly output.
--error-trace
- Show full error trace.
--ll
- Dump LLVM assembly file to output directory.
--link-flags
FLAGS
- Pass additional flags to the linker. Though you can specify those
flags on the source code, this is useful for passing environment
specific information directly to the linker, like non-standard library
paths or names. For more information on specifying linker flags on
source, you can read the "C bindings" section of the
documentation available on the official web site.
--mcpu
CPU
- Specify a specific CPU to generate code for. This will pass a -mcpu
flag to LLVM, and is only intended to be used for cross-compilation.
For a list of available CPUs, invoke "llvm-as < /dev/null |
llc -march=xyz -mcpu=help". Passing --mcpu native will pass the
host CPU name to tune performance for the host.
--mattr
CPU
- Override or control specific attributes of the target, such as whether
SIMD operations are enabled or not. The default set of attributes is
set by the current CPU. This will pass a -mattr flag to LLVM, and is
only intended to be used for cross-compilation. For a list of
available attributes, invoke "llvm-as < /dev/null | llc
-march=xyz -mattr=help".
--mcmodel
-default|kernel|small|medium|large
- Specifies a specific code model to generate code for. This will pass a
--code-model flag to LLVM.
--no-color
- Disable colored output.
--no-codegen
- Don't do code generation, just parse the file.
-o
- Specify filename of output.
--prelude
- Specify prelude to use. The default one initializes the garbage
collector. You can also use --prelude=empty to use no preludes. This
can be useful for checking code generation for a specific source code
file.
--release
- Turn on optimizations for the generated code, which are disabled by
default.
--error-trace
- Show full stack trace. Disabled by default, as the full trace usually
makes error messages less readable and not always deliver relevant
information.
-s,
--stats
- Print statistics about the different compiler stages for the current
build. Output time and used memory for each compiler process.
-p,
--progress
- Print statistics about the progress for the current build.
-t,
--time
- Print statistics about the execution time.
--single-module
- Generate a single LLVM module.
--threads
NUM
- Maximum number of threads to use for code generation. The default is 8
threads.
--target
TRIPLE
- Enable target triple; intended to use for cross-compilation. See llvm
documentation for more information about target triple.
--verbose
- Display the commands executed by the system.
--static
- Create a statically linked executable.
--stdin-filename
FILENAME
- Source file name to be read from STDIN.
docs
Generate documentation from comments using a subset of
markdown. The output is saved in html format on the created docs/
folder. More information about documentation conventions can be found at
https://crystal-lang.org/docs/conventions/documenting_code.html.
Options:
--project-name
NAME
- Set the project name. The default value is extracted from shard.yml if
available.
In case no default can be found, this option is
mandatory.
--project-version
VERSION
- Set the project version. The default value is extracted from current
git commit or shard.yml if available.
In case no default can be found, this option is
mandatory.
--json-config-url
URL
- Set the URL pointing to a config file (used for discovering
versions).
--source-refname
REFNAME
- Set source refname (e.g. git tag, commit hash). The default value is
extracted from current git commit if available.
If this option is missing and can't be automatically
determined, the generator can't produce source code links.
--source-url-pattern
URL
- Set URL pattern for source code links. The default value is extracted
from git remotes ("origin" or first one) if available and
the provider's URL pattern is recognized.
Supported replacement tags:
- %{refname}
- commit reference
- %{path}
- path to source file inside the repository
- %{filename}
- basename of the source file
- %{line}
- line number
If this option is missing and can't be automatically
determined, the generator can't produce source code links.
-o
DIR, --output
DIR
- Set the output directory (default: ./docs).
-b
URL, --canonical-base-url
URL
- Indicate the preferred URL with rel="canonical" link
element.
-b
URL, --sitemap-base-url
URL
- Set the sitemap base URL. Sitemap will only be generated when this
option is set.
--sitemap-priority
PRIO
- Set the priority assigned to sitemap entries (default: 1.0).
--sitemap-changefreq
FREQ
- Set the changefreq assigned to sitemap entries (default: never).
env
[variables]
Print Crystal-specific environment variables in a format
compatible with shell scripts. If one or more variable names are given
as arguments, it prints only the value of each named variable on its own
line.
Variables:
-
- CRYSTAL_CACHE_DIR
- Please see ENVIRONMENT VARIABLES.
-
- CRYSTAL_LIBRARY_PATH
- Please see ENVIRONMENT VARIABLES.
-
- CRYSTAL_PATH
- Please see ENVIRONMENT VARIABLES.
-
- CRYSTAL_VERSION
- Contains Crystal version.
eval
[options][source]
Evaluate code from arguments or, if no arguments are passed,
from the standard input. Useful for experiments.
Options:
-d,
--debug
- Generate the output with symbolic debug symbols.These are read when
debugging the built program with tools like lldb, gdb, valgrind etc.
and provide mappings to the original source code for those tools.
--no-debug
- Generate the output without any symbolic debug symbols.
-D
FLAG,--define
FLAG
- Define a compile-time flag. This is useful to conditionally define
types, methods, or commands based on flags available at compile time.
The default flags are from the target triple given with
--target-triple or the hosts default, if none is given.
--error-trace
- Show full error trace.
--release
- Turn on optimizations for the generated code, which are disabled by
default.
-s,
--stats
- Print statistics about the different compiler stages for the current
build. Output time and used memory for each compiler process.
-p,
--progress
- Print statistics about the progress for the current build.
-t,
--time
- Print statistics about the execution time.
--no-color
- Disable colored output.
play
[options][file]
Starts the crystal playground server on port 8080, by
default.
Options:
-p
PORT,--port
PORT
- Run the playground on the specified port. Default is 8080.
-b
HOST,--binding
HOST
- Bind the playground to the specified IP.
-v,
--verbose
- Display detailed information of the executed code.
run
[options][programfile][--][arguments]
The default command. Compile and run program.
Options:Same as the build options.
spec
[options][files]
Compile and run specs (in spec directory).
Options:
-d,
--debug
- Generate the output with symbolic debug symbols.These are read when
debugging the built program with tools like lldb, gdb, valgrind etc.
and provide mappings to the original source code for those tools.
--no-debug
- Generate the output without any symbolic debug symbols.
-D
FLAG,--define
FLAG
- Define a compile-time flag. This is useful to conditionally define
types, methods, or commands based on flags available at compile time.
The default flags are from the target triple given with
--target-triple or the hosts default, if none is given.
--error-trace
- Show full error trace.
--release
- Turn on optimizations for the generated code, which are disabled by
default.
-s,
--stats
- Print statistics about the different compiler stages for the current
build. Output time and used memory for each compiler process.
-p,
--progress
- Print statistics about the progress for the current build.
-t,
--time
- Print statistics about the execution time.
--no-color
- Disable colored output.
tool
[tool][switches][programfile][--][arguments]
Run a tool. The available tools are: context, format,
hierarchy, implementations, and types.
Tools:
context
- Show context for given location.
expand
- Show macro expansion for given location.
format
- Format project, directories and/or files with the coding style used in
the standard library. You can use
the
--check
flag to check whether the formatter
would make any changes.
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.
implementations
- Show implementations for a given call.
Use
--cursor
to specify the cursor position. The
format for the cursor position is file:line:column.
types
- Show type of main variables of file.
help,
--help,
-h
-
Show help. Option --help or -h can also be added to each
command for command-specific help.
version,
--version,
-v
-
Show version.
-
- 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_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'.
shards
(1)
- https://crystal-lang.org/
- The official web site.
- https://github.com/crystal-lang/crystal
- Official Repository.