Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

The Compiler and Toolchain

Tour the Crystal command-line tools (crystal init, build, run, tool format, spec, docs and shards). Learn project layout, flags and a daily development workflow.

Crystal ships with a small set of tools in a single command, crystal, plus a package manager called shards. Together they cover creating a project, formatting code, testing, generating documentation and installing libraries. Knowing them early saves you from reinventing things the language already gives you.

All commands in this lesson are shown read-only because the Crystal compiler is not available on this site. The Ruby stand-in at the end runs and imitates what a code formatter does.

The command overview

Run crystal with no arguments (or crystal help) to see the list. The ones you will use every day are these:

Command Purpose
crystal init app NAME Create a new application project
crystal init lib NAME Create a new library project
crystal run FILE Compile to a temporary executable and run
crystal build FILE Compile to an executable
crystal spec Run the tests in the spec folder
crystal tool format Format source files
crystal docs Generate HTML API documentation
crystal eval 'CODE' Compile and run a snippet
crystal tool ... Extra tools: context, hierarchy, expand and more

Creating a project

Terminal
crystal init app todo
cd todo

The generator creates this layout:

TEXT
todo/
  .gitignore
  .editorconfig
  LICENSE
  README.md
  shard.yml
  spec/
    spec_helper.cr
    todo_spec.cr
  src/
    todo.cr
  • src/todo.cr is your program's entry point.
  • spec/ holds tests (see the testing lesson).
  • shard.yml describes the project: name, version, authors, the Crystal version it needs, and its dependencies.

A fresh shard.yml looks like this:

YAML
name: todo
version: 0.1.0

authors:
  - Your Name <[email protected]>

targets:
  todo:
    main: src/todo.cr

crystal: ">= 1.0.0"

license: MIT

The targets section tells shards build which file to compile and what to call the executable.

Building with shards

For a project, build through shards, which also installs dependencies first:

Terminal
shards build            # development build into ./bin
shards build --release  # optimised build
./bin/todo

shards build writes the executable to the bin folder. For a single file crystal build is enough, for a project use shards build.

The formatter

Crystal has an official, non-configurable code formatter, so every Crystal project looks alike and style arguments disappear.

Terminal
crystal tool format            # reformat every .cr file under the current folder
crystal tool format src/       # a specific folder
crystal tool format --check    # only report files that need formatting (good for CI)

It fixes indentation to two spaces, removes extra blank lines, normalises spacing around operators and rewrites some syntax into its preferred form. Set your editor to run it on save.

Here is what it does to untidy code:

CRYSTAL
# Before
def add(a,b)
    a+b
end
puts   add(1,2)

# After
def add(a, b)
  a + b
end
puts add(1, 2)

The Ruby stand-in below is not the Crystal formatter. It is a tiny sketch of the idea: it re-indents a snippet using two spaces per nesting level, which is the first thing the real formatter does.

Ruby Stand-in: a tiny re-indenter in Ruby

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Documentation comments

crystal docs reads comments placed directly above a definition and builds a searchable website in a docs folder. Doc comments support Markdown.

CRYSTAL
# Adds two integers.
#
# ```
# add(2, 3) # => 5
# ```
def add(a : Int32, b : Int32) : Int32
  a + b
end

The code inside the fenced block can even be checked by tools, and a comment like # => 5 is the convention for showing a result. The standard library's own reference at the Crystal website is generated this way.

Looking inside the compiler

crystal tool has helpers that are great for learning:

  • crystal tool hierarchy FILE prints the class tree.
  • crystal tool context shows the types of variables at a position.
  • crystal tool expand shows what a macro expands to (see the macros chapter).
  • crystal tool unreachable reports code that is never called.

The first one that beginners should try is crystal tool format; the second is context, because seeing the inferred type of a variable teaches you how the compiler thinks.

Useful compile flags

Terminal
crystal build src/todo.cr --release --no-debug   # smaller binary, no debug info
crystal build src/todo.cr --static               # fully static binary (Linux, musl)
crystal build src/todo.cr --error-trace          # show the full path of a type error
crystal build src/todo.cr --stats                # show how long each phase took

--error-trace is worth remembering: a type error deep inside a library can hide the real cause, and the trace shows how the compiler got there.

A daily workflow

  1. crystal run src/todo.cr while experimenting.
  2. crystal tool format before you commit.
  3. crystal spec to run the tests.
  4. shards build --release for the executable you ship.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command creates a new application project skeleton?

    crystal init app NAME generates src, spec and shard.yml.
  2. 2. What is the purpose of crystal tool format --check?

    --check only reports; it is handy in continuous integration.
  3. 3. Where does a Crystal project's metadata and dependency list live?

    shard.yml describes the project and its dependencies for the shards tool.
  4. 4. Which flag shows how the compiler reached a type error inside library code?

    --error-trace prints the full chain of calls that led to the error.

Summary

  • One crystal command covers init, run, build, spec, docs, formatting and tools; shards manages dependencies and project builds.
  • crystal init app NAME makes src/, spec/ and shard.yml.
  • The formatter is official and not configurable, so all Crystal code looks alike.
  • Doc comments with Markdown become API documentation through crystal docs.
  • Use --release for shipping, --error-trace for hard type errors.

Next: How Crystal Compiles and Infers Types