Несмотря на то, что это касается пользовательского интерфейса, создание файла конфигурации и размещение сгенерированной документации по каждому пути — это не то, что он обрабатывает за вас. В зависимости от ваших требований, этого встроенного способа может быть достаточно. Но использование стороннего решения или чего-то, что вы создадите самостоятельно, также является вариантом, если вам требуются дополнительные функции.
Резюме
Вот и все, что вам нужно знать! Все, что вам нужно знать о том, как наилучшим образом документировать свой код. Типизированный характер Crystal помогает частично облегчить написание документации, поскольку он справляется с основами. Использование markdown для комментариев к коду также помогает приблизить документацию к коду, снижая вероятность его устаревания.
Теперь, когда мы знаем, как написать хорошо спроектированное, протестированное и документированное приложение, пришло время перейти к последнему шагу: его развертыванию! В следующей главе мы узнаем, как следует управлять версиями сегментов, как создать рабочий двоичный файл и как распространять его с помощью Docker.
16. Развертывание кода
Одним из основных преимуществ Crystal является то, что его двоичные файлы могут быть статически связаны. Это означает, что все зависимости программы от времени выполнения включены в сам двоичный файл. Если бы вместо этого двоичный файл был динамически связан, пользователю потребовалось бы установить эти зависимости для использования программы. Аналогично, поскольку он компилируется в один двоичный файл, его распространение значительно упрощается, поскольку не требуется включать исходный код.
В этой главе мы рассмотрим следующие темы:
• Управление версиями вашего сегмента
• Создание рабочих двоичных файлов
• Распространение вашего двоичного файла
К концу этой главы у вас будет портативный и производительный двоичный файл, который можно будет распространять среди конечных пользователей вашего приложения.
Технические требования
Требования к этой главе следующие:
• Рабочая установка Crystal
Пожалуйста, обратитесь к Главе 1 "Введение в Crystal" для получения инструкций по настройке Crystal.
Все примеры кода для этой главы можно найти в папке Chapter16 в репозитории этой книги на GitHub: https://github.com/PacktPublishing/Crystal-Programming/tree/main/Chapter16.
Управление версиями вашего shard
Первое, что вам нужно сделать, прежде чем вы сможете развернуть проект, — это создать новый выпуск. Как вы узнали из Главы 8 «Использование внешних библиотек», настоятельно рекомендуется, чтобы все сегменты Crystal, особенно библиотеки, следовали семантическому управлению версиями (https://semver.org), чтобы сделать зависимости более удобными в обслуживании, обеспечивая воспроизводимые установки и ожидая стабильности.
По этой причине любое несовместимое с обратной совместимостью изменение в общедоступном API должно привести к созданию новой основной версии сегмента. Примером этого может быть переименование метода, удаление метода, изменение имени параметра метода и т. д. Однако код может быть признан устаревшим как часть второстепенной версии с указанием, что он будет изменен/удален в следующей основной версии.
Crystal предоставляет аннотацию https://crystal-lang.org/api/Deprecated.html, которую можно использовать для создания предупреждений об устаревании при применении к методам или типам. В некоторых случаях программе может потребоваться поддержка нескольких основных версий сегмента одновременно. Эту проблему можно решить, проверив версию сегмента во время компиляции, а также некоторую условную логику для генерации правильного кода на основе текущей версии.
Константа VERSION доступна во время компиляции и является хорошим источником информации о текущей версии сегмента. Ниже приведен пример:
module MyShard
VERSION = "1.5.17"
end
{% if compare_versions(MyShard::VERSION, "2.0.0") >= 0 %}
puts "greater than or equal to 2.0.0"
{% else %}
puts "less than 2.0.0"
{% end %}
Если требуется несколько диапазонов версий, можно добавить дополнительные ветки.
Релиз — это не что иное, как тег Git для конкретного коммита. Как создать релиз, зависит от того, какой хост вы используете. Инструкции о том, как это сделать для вашего конкретного хоста, см. по следующим ссылкам: