Использование компилятора

Компиляция и запуск одной командой

Чтобы скомпилировать и запустить программу за один раз, вызовите crystal run, указав единственное имя файла:

$ echo 'puts "Hello World!"' > hello_world.cr
$ crystal run hello_world.cr
Hello World!

Команда run компилирует исходный файл hello_world.cr в исполняемый файл во временном расположении и сразу же запускает его.

Создание исполняемого файла

Команда crystal build собирает исполняемый файл. Выходной файл имеет то же имя, что и исходный файл, но без расширения .cr.

$ crystal build hello_world.cr
$ ./hello_world
Hello World!

Сборки для выпуска

По умолчанию сгенерированные исполняемые файлы не оптимизированы в полной мере. Для включения оптимизаций можно использовать флаг --release.

$ crystal build hello_world.cr --release

Компиляция без режима выпуска происходит намного быстрее, а полученные двоичные файлы при этом обеспечивают достаточно высокую производительность.

Сборку в режиме выпуска следует использовать для готовых к эксплуатации исполняемых файлов и при проведении тестов производительности. Для обычных сборок в процессе разработки это, как правило, не требуется.

Чтобы уменьшить размер распространяемых двоичных файлов, можно использовать флаг --no-debug. Он удаляет отладочные символы, уменьшая размер файла, но, очевидно, усложняя отладку.

Создание статически связанного исполняемого файла

Для создания статически связанного исполняемого файла можно использовать флаг --static:

$ crystal build hello_world.cr --release --static

Дополнительные сведения о статической компоновке приведены в руководстве по статической компоновке.

Компилятор использует переменную окружения CRYSTAL_LIBRARY_PATH как первое место поиска статических и динамических библиотек для компоновки. Это можно использовать, чтобы предоставить статические версии библиотек, также доступных в виде динамических.

Создание проекта Crystal

Команда crystal init помогает инициализировать папку проекта Crystal, создавая базовую структуру проекта. crystal init app <name> используется для приложения, а crystal init lib <name> — для библиотеки.

$ crystal init app myapp
    create  myapp/.gitignore
    create  myapp/.editorconfig
    create  myapp/LICENSE
    create  myapp/README.md
    create  myapp/shard.yml
    create  myapp/src/myapp.cr
    create  myapp/spec/spec_helper.cr
    create  myapp/spec/myapp_spec.cr
Initialized empty Git repository in /home/crystal/myapp/.git/

Не все эти файлы нужны для каждого проекта, а некоторые из них могут потребовать дополнительной настройки, однако crystal init создает подходящую среду по умолчанию для разработки приложений и библиотек на Crystal.

Команды компилятора

• crystal init: создать новый проект
• crystal build: собрать исполняемый файл
• crystal docs: сгенерировать документацию
• crystal env: вывести сведения об окружении Crystal
• crystal eval: выполнить код из аргументов или стандартного ввода
• crystal play: запустить сервер интерактивной среды Crystal
• crystal run: собрать и запустить программу
• crystal spec: собрать и запустить тесты
• crystal tool: запустить инструмент компилятора
• crystal help: показать справку по командам и параметрам
• crystal version: показать версию

Чтобы просмотреть доступные параметры конкретной команды, укажите --help после команды:

crystal run

Команда run компилирует исходный файл в исполняемый файл и сразу же запускает его.

crystal [run] [<options>] <programfile> [-- <argument>...]

Аргументы для скомпилированного двоичного файла можно отделить от аргументов компилятора двойным дефисом --. Между компиляцией и запуском исполняемый файл хранится во временном расположении.

Пример:

$ echo 'puts "Hello #{ARGV[0]?}!"' > hello_world.cr
$ crystal run hello_world.cr -- Crystal
Hello Crystal!

Распространенные параметры:

• --release: компилировать в режиме выпуска, выполняя дополнительную работу для оптимизации сгенерированного кода.
• --progress: показывать ход компиляции.
• --static: выполнять статическую компоновку.

Другие параметры описаны во встроенной справке: crystal run --help или на странице руководства man crystal.

crystal build

Команда crystal build собирает динамически связанный исполняемый файл.

crystal build [<options>] <programfile>

Если не указано иное, результирующий двоичный файл будет иметь то же имя, что и исходный файл, но без расширения .cr.

Пример:

$ echo 'puts "Hello #{ARGV[0]?}!"' > hello_world.cr
$ crystal build hello_world.cr
$ ./hello_world Crystal
Hello Crystal!

Распространенные параметры:

• --cross-compile: создать файл .o и вывести в stdout команду для создания исполняемого файла.
• -D FLAG, --define FLAG: определить флаг времени компиляции.
• -o <output_file>: задать имя исполняемого файла.
• --release: компилировать в режиме выпуска, выполняя дополнительную работу для оптимизации сгенерированного кода.
• --link-flags FLAGS: дополнительные флаги для передачи компоновщику.
• --lto=thin: использовать ThinLTO для повышения производительности сборок выпуска.
• --no-debug: пропустить отладочную символьную информацию, уменьшив размер выходного файла.
• --progress: показывать ход компиляции.
• --static: выполнять статическую компоновку.
• --verbose: отображать выполняемые команды.

Другие параметры описаны во встроенной справке: crystal build --help или на странице руководства man crystal.

crystal eval

Команда crystal eval считывает исходный код Crystal из командной строки или stdin, компилирует его в исполняемый файл и сразу же запускает его.

crystal eval [<options>] [<source>]

Если аргумент source не указан, исходный код Crystal считывается из стандартного ввода. Между компиляцией и запуском исполняемый файл хранится во временном расположении.

Пример:

$ crystal eval 'puts "Hello World"'
Hello World!
$ echo 'puts "Hello World"' | crystal eval
Hello World!

Распространенные параметры:

• -o <output_file>: задать имя исполняемого файла.
• --release: компилировать в режиме выпуска, выполняя дополнительную работу для оптимизации сгенерированного кода.
• --lto=thin: использовать ThinLTO для повышения производительности.
• --no-debug: пропустить отладочную символьную информацию, уменьшив размер выходного файла.
• --progress: показывать ход компиляции.
• --static: выполнять статическую компоновку.

Другие параметры описаны во встроенной справке: crystal eval --help или на странице руководства man crystal.

crystal version

Команда crystal version выводит версию Crystal, версию LLVM и тройку целевой платформы по умолчанию.

crystal version

Пример:

$ crystal version
Crystal 1.2.2 [6529d725a] (2021-11-10)

LLVM: 10.0.0
Default target: x86_64-unknown-linux-gnu

crystal init

Команда crystal init инициализирует папку проекта Crystal.

crystal init (lib|app) <name> [<dir>]

Первый аргумент — это либо lib, либо app. lib — это повторно используемая библиотека, тогда как app описывает приложение, не предназначенное для использования в качестве зависимости. В репозитории библиотеки нет файла shard.lock и цели сборки в shard.yml, но есть инструкции по ее использованию в качестве зависимости.

Пример:

$ crystal init lib my_cool_lib
    create  my_cool_lib/.gitignore
    create  my_cool_lib/.editorconfig
    create  my_cool_lib/LICENSE
    create  my_cool_lib/README.md
    create  my_cool_lib/shard.yml
    create  my_cool_lib/src/my_cool_lib.cr
    create  my_cool_lib/spec/spec_helper.cr
    create  my_cool_lib/spec/my_cool_lib_spec.cr
Initialized empty Git repository in ~/my_cool_lib/.git/

crystal docs

Команда crystal docs генерирует документацию API из встроенных строк документации в файлах Crystal (см. Документирование кода).

crystal docs [--output=<output_dir>] [--canonical-base-url=<url>] [<source_file>...]

Команда создает статический веб-сайт в output_dir (по умолчанию ./docs), состоящий из HTML-файлов для каждого типа Crystal и имеющий структуру папок, отражающую пространства имен Crystal. Стартовую страницу docs/index.html можно открыть в любом веб-браузере. Вся документация API также сохраняется в виде JSON-документа в $output_dir/index.json.

По умолчанию добавляются все файлы Crystal в ./src (то есть src/**/*.cr). Чтобы учесть зависимости порядка загрузки, можно использовать source_file для указания одной или нескольких начальных точек генератору документации.

crystal docs src/my_app.cr

Распространенные параметры:

• --project-name=NAME: задать имя проекта. Значение по умолчанию извлекается из shard.yml, если он доступен. Если значение по умолчанию не найдено, этот параметр обязателен.
• --project-version=VERSION: задать версию проекта. Значение по умолчанию извлекается из текущего коммита git или shard.yml, если он доступен. Если значение по умолчанию не найдено, этот параметр обязателен.
• --output=DIR, -o DIR: задать выходную папку (по умолчанию: ./docs)
• --canonical-base-url=URL, -b URL: задать канонический базовый URL

Чтобы приведенный выше пример создал документацию в public с пользовательским каноническим базовым URL и начальной точкой src/my_app.cr, можно использовать следующие аргументы:

crystal docs --output public --canonical-base-url http://example.com/ src/my_app.cr

crystal env

Команда crystal env выводит переменные окружения, используемые Crystal.

crystal env [<var>...]

По умолчанию информация выводится в виде скрипта оболочки. Если указаны один или несколько аргументов var, значение каждой указанной переменной выводится на отдельной строке.

Пример:

$ crystal env
CRYSTAL_CACHE_DIR="/home/crystal/.cache/crystal"
CRYSTAL_PATH="/usr/bin/../share/crystal/src:lib"
CRYSTAL_VERSION="0.28.0"
CRYSTAL_LIBRARY_PATH="/usr/bin/../lib/crystal/lib"
$ crystal env CRYSTAL_VERSION
0.28.0

crystal spec

Команда crystal spec компилирует и запускает набор тестов Crystal.

crystal spec [<options>] [<file>...] [-- [<runner_options>]]

Все аргументы files объединяются в один исходный файл Crystal. Если аргумент указывает на папку, добавляются все файлы тестов из этой папки. Если аргумент files не указан, используется значение по умолчанию ./spec. К имени файла можно добавить : и номер строки, чтобы передать это расположение параметру запуска --location (см. ниже).

Запустите crystal spec --options, чтобы просмотреть доступные параметры.

Параметры запуска:

runner_options передаются скомпилированному исполняемому файлу, который запускает тесты. Их следует отделять от остальных аргументов двойным дефисом (--).

• --verbose: выводить подробную информацию, включая имена всех примеров.
• --profile: выводить 10 самых медленных тестов.
• --fail-fast: прервать запуск тестов при первой ошибке.
• --junit_output <output_dir>: генерировать выходные данные в формате JUnit XML.

Следующие параметры можно комбинировать, чтобы отфильтровать список запускаемых тестов.

• --example <name>: запускать примеры, полные вложенные имена которых содержат name.
• --line <line>: запускать примеры, номера строк которых соответствуют line.
• --location <file>:<line>: запускать примеры в line в file (можно использовать несколько параметров).
• --tag <tag>: запускать примеры с указанным тегом или исключать примеры, добавив ~ перед тегом (можно использовать несколько параметров).
  • --tag a --tag b включит тесты с тегом a ИЛИ b.
  • --tag ~a --tag ~b включит тесты без тега a И без тега b.
  • --tag a --tag ~b включит тесты с тегом a, но без тега b

Пример:

$ crystal spec
F

Failures:

  1) Myapp works
     Failure/Error: false.should eq(true)

       Expected: true
            got: false

     # spec/myapp_spec.cr:7

Finished in 880 microseconds
1 examples, 1 failures, 0 errors, 0 pending

Failed examples:

crystal spec spec/myapp_spec.cr:6 # Myapp works

crystal play

Команда crystal play запускает веб-сервер, предоставляющий интерактивную среду Crystal.

crystal play [--port <port>] [--binding <host>] [--verbose] [file]

crystal tool

• crystal tool context: показать контекст для указанного расположения
• crystal tool expand: показать раскрытие макроса для указанного расположения
• crystal tool format: форматировать файлы Crystal
• crystal tool hierarchy: показать иерархию типов
• crystal tool implementations: показать реализации для указанного вызова в указанном расположении
• crystal tool types: показать типы основных переменных

crystal tool format

Команда crystal tool format применяет форматирование по умолчанию к исходным файлам Crystal.

crystal tool format [--check] [<path>...]

path может быть именем файла или папки; в этом случае форматируются все файлы Crystal в дереве папок. Если path не указан, используется текущая рабочая папка.

Форматтер также форматирует блоки кода Crystal в комментариях (см. Документирование кода).

Переменные окружения

Компилятор Crystal использует следующие переменные окружения, если они заданы в окружении. В противном случае компилятор присваивает им значения по умолчанию. Их значения можно просмотреть с помощью crystal env.

• CRYSTAL_CACHE_DIR: задает путь, по которому Crystal кэширует результаты частичной компиляции для ускорения последующих сборок. Этот путь также используется для временного хранения исполняемых файлов при запуске программ Crystal с помощью crystal run, а не crystal build. По умолчанию используется первый каталог из ${XDG_CACHE_HOME}/crystal (если задан XDG_CACHE_HOME), ${HOME}/.cache/crystal, ${HOME}/.crystal, ./.crystal, который существует или может быть создан. Если CRYSTAL_CACHE_DIR задана, но указывает на путь, недоступный для записи, вместо нее используются значения по умолчанию.
• CRYSTAL_PATH: задает пути, по которым Crystal ищет необходимые файлы.
• CRYSTAL_VERSION доступна только в выводе crystal env. Компилятор не устанавливает и не считывает ее.
• CRYSTAL_LIBRARY_PATH: компилятор использует пути из этой переменной как первое место поиска статических и динамических библиотек для компоновки. Например, если статические библиотеки помещены в build/libs, установка этой переменной окружения укажет компилятору искать библиотеки там.