= crystal-build(1)
:doctype: manpage
:date: {localdate}
:crystal_version: {crystal_version}
:man manual: Crystal Compiler Command Line Reference Guide
:man source: crystal {crystal_version}

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