CRYSTAL-BUILD(1)                 Crystal Compiler Command Line Reference Guide

NAME
       crystal-build - Compile a Crystal program

SYNOPSIS
       crystal build [options] [programfile] [--] [arguments]

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.

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

       --x86-asm-syntax [att|intel]
           Select the assembly dialect for --emit=asm. The default is att,
           which stands for the AT&T syntax supported by tools like the GNU
           Assembler. intel selects the Intel syntax which is preferred for
           Windows tools.

       --frame-pointers [auto|always|non-leaf]
           Control the preservation of frame pointers. The default value,
           --frame-pointers=auto, will preserve frame pointers on debug builds
           and try to omit them on release builds (certain platforms require
           them to stay enabled). --frame-pointers=always will always preserve
           them, and non-leaf will only force their preservation on non-leaf
           functions.

       -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. Disabled by default, as the full trace
           usually makes error messages less readable and may not always
           deliver relevant information.

       --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, pass --mcpu help when
           building any Crystal source code.  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|tiny|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 FILE, --output FILE
           Specify output path. If a directory, the filename is derived from
           the first source file (default:   current directory)

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

       -O LEVEL
           Optimization mode: 0 (default), 1, 2, 3. See OPTIMIZATIONS for
           details.

       --release
           Compile in release mode. Equivalent to -O3 --single-module

       -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.  By default, one LLVM module is
           created for each type in a program.  --release implies this option.

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

crystal 1.21.0                    2026-07-23                  CRYSTAL-BUILD(1)