CRYSTAL(1)()

NAME
crystal - Compiler for the Crystal language.

SYNOPSYS
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.

OPTIONS
The crystal command accepts the following options

    init TYPE NAME [DIR]

    Generate a new 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 .travis.yml file for Travis CI integration, a shard.yml for use with shards (the Crystal dependency manager), a .gitignore file, and src and spec folders.

        NAME - name of project to be generated, e.g.: example

        DIR  - directory where project will be generated, default: NAME

    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".
    --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:

    -o DIR, --output DIR
        Set the output directory (default: ./docs).
    -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

    CRYSTAL_PATH
        Please see

    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.

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_PATH
    Defines paths where Crystal searches for required files.

SEE ALSO
shards(1)
https://crystal-lang.org/
    The official web site.
https://github.com/crystal-lang/crystal
    Official Repository.