File: README.md
Crystal
Crystal is a programming language with the following goals:
- Have a syntax similar to Ruby (but compatibility with it is not a goal)
- Statically type-checked but without having to specify the type of variables or method arguments.
- Be able to call C code by writing bindings to it in Crystal.
- Have compile-time evaluation and generation of code, to avoid boilerplate code.
- Compile to efficient native code.
Why?
We love Ruby's efficiency for writing code.
We love C's efficiency for running code.
We want the best of both worlds.
We want the compiler to understand what we mean without having to specify types everywhere.
We want full OOP.
Oh, and we don't want to write C code to make the code run faster.
Project Status
Within a major version, language features won't be removed or changed in any way that could prevent a Crystal program written with that version from compiling and working. The built-in standard library might be enriched, but it will always be done with backwards compatibility in mind.
Development of the Crystal language is possible thanks to the community's effort and the continued support of 84codes and every other sponsor.
Installing
Follow these installation instructions
Try it online
Documentation
Community
Have any questions or suggestions? Ask on the Crystal Forum, on our Gitter channel or IRC channel #crystal-lang at irc.libera.chat, or on Stack Overflow under the crystal-lang tag. There is also an archived Google Group.
Contributing
The Crystal repository is hosted at crystal-lang/crystal on GitHub.
Read the general Contributing guide, and then:
- Fork it (https://github.com/crystal-lang/crystal/fork)
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
File: doc/man/crystal.adoc
= crystal(1)
:doctype: manpage
:date: {localdate}
:crystal_version: {crystal_version}
:man manual: Crystal Compiler Command Line Reference Guide
:man source: crystal {crystal_version}
== 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:
[source, shell]
crystal some_program.cr
Crystal files usually end with the .cr extension, though this is not mandatory.
Alternatively you can use the run command:
[source, shell]
crystal run some_program.cr
To create an executable use the build command:
[source, shell]
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:
[source, shell]
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
crystal-init(1):: Create a a new Crystal project
crystal-build(1):: Compile a Crystal program
crystal-docs(1):: Generate API docs for Crystal code
crystal-env(1):: Print environment variables for the Crystal compiler
crystal-eval(1):: Evaluate a crystal program
crystal-play(1):: Run the Crystal playground
crystal-run(1):: Compile and run a Crystal program
crystal-spec(1):: 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
crystal-tool-dependencies(1):: Show tree of required source files
crystal-tool-expand:: Show macro expansion for given location
crystal-tool-flags:: Print all macro 'flag?' values
crystal-tool-format(1):: 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.
crystal-tool-unreachable(1):: 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
shards(1)
https://crystal-lang.org/ The official web site.
https://github.com/crystal-lang/crystal Official Repository.
File: doc/man/crystal-build.adoc
= 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-modelflag 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.
File: doc/man/crystal-docs.adoc
= crystal-docs(1)
:doctype: manpage
:date: {localdate}
:crystal_version: {crystal_version}
:man manual: Crystal Compiler Command Line Reference Guide
:man source: crystal {crystal_version}
== Name
crystal-doc - Generate API docs for Crystal code
== Synopsis
crystal build [options] [programfile] [--] [arguments]
== Description
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).
File: doc/man/crystal-env.adoc
= crystal-env(1)
:doctype: manpage
:date: {localdate}
:crystal_version: {crystal_version}
:man manual: Crystal Compiler Command Line Reference Guide
:man source: crystal {crystal_version}
== Name
crystal-env - Print environment variables for the Crystal compiler
== Synopsis
crystal env [variables]
== Description
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_EXEC_PATH::
Please see ENVIRONMENT VARIABLES.
CRYSTAL_LIBRARY_PATH::
Please see ENVIRONMENT VARIABLES.
CRYSTAL_PATH::
Please see ENVIRONMENT VARIABLES.
CRYSTAL_VERSION::
Contains Crystal version.
== Informative Variables
These variables expose information about the Crystal compiler and cannot be configured externally.
=== CRYSTAL_VERSION
Contains Crystal version.
File: doc/man/crystal-eval.adoc
= crystal-eval(1)
:doctype: manpage
:date: {localdate}
:crystal_version: {crystal_version}
:man manual: Crystal Compiler Command Line Reference Guide
:man source: crystal {crystal_version}
== Name
crystal-eval - Evaluate a crystal program
== Synopsis
crystal eval [options] [source]
== Description
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.
-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.
--no-color::
Disable colored output.
File: doc/man/crystal-init.adoc
= crystal-init(1)
:doctype: manpage
:date: {localdate}
:crystal_version: {crystal_version}
:man manual: Crystal Compiler Command Line Reference Guide
:man source: crystal {crystal_version}
== Name
crystal-init - Create a a new Crystal project
== Synopsis
crystal init TYPE [DIR | NAME DIR]
== Description
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.
File: doc/man/crystal-play.adoc
= crystal-play(1)
:doctype: manpage
:date: {localdate}
:crystal_version: {crystal_version}
:man manual: Crystal Compiler Command Line Reference Guide
:man source: crystal {crystal_version}
== Name
crystal-play - Run the Crystal playground
== Synopsis
crystal play [options] [file]
== Description
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.
File: doc/man/crystal-run.adoc
= crystal-run(1)
:doctype: manpage
:date: {localdate}
:crystal_version: {crystal_version}
:man manual: Crystal Compiler Command Line Reference Guide
:man source: crystal {crystal_version}
== Name
crystal-run - Compile and run a Crystal program
== Synopsis
crystal run [options] [programfile] [--] [arguments]
== Description
The default command. Compile and run program.
== Options
Same as the build options.
File: doc/man/crystal-spec.adoc
= crystal-spec(1)
:doctype: manpage
:date: {localdate}
:crystal_version: {crystal_version}
:man manual: Crystal Compiler Command Line Reference Guide
:man source: crystal {crystal_version}
== Name
crystal-spec - Compile and run Crystal spec files
== Synopsis
crystal spec [options] [files]
== 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.
-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.
--no-color::
Disable colored output.