Исходный код Руководства по библиотекам

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

Начало работы

Вы можете создать новую библиотеку Elixir, выполнив команду mix new:

$ mix new my_library

Имя проекта задаётся в соответствии с соглашением snake_case, где все буквы строчные, а слова разделяются символом нижнего подчеркивания. Это то же соглашение, что используется для переменных, имён функций и атомов в Elixir. Дополнительную информацию см. в документе Соглашения об именовании.

Каждый проект имеет файл mix.exs, содержащий инструкции по сборке, компиляции, запуску тестов и т. д. Библиотеки обычно содержат директорию lib, которая включает исходный код Elixir, и директорию test. Также может существовать директория src для исходных файлов Erlang.

Дополнительную информацию о запуске вашего проекта можно найти в официальном руководстве Mix & OTP или в документации Mix.

Приложения с деревом контроля

Команда mix new также позволяет использовать опцию --sup для создания приложения с деревом контроля по умолчанию. Мы обсудим деревья контроля позднее, когда будем рассматривать один из распространённых антипаттернов при написании библиотек.

Публикация

Написание кода — это лишь первый из многих шагов в публикации пакета. Мы настоятельно рекомендуем разработчикам:

• Выбрать схему версионирования. Elixir требует, чтобы версии имели формат MAJOR.MINOR.PATCH, но смысл этих чисел зависит от вас. Большинство проектов выбирают Semantic Versioning.

• Выбрать лицензию. Наиболее распространёнными лицензиями в сообществе Elixir являются лицензия MIT и лицензия Apache 2.0. Последняя также используется самим Elixir.

• Запустить форматер кода. Форматер кода форматирует ваш код в соответствии с согласованным стилем, используемым в вашей библиотеке и всем сообществом, что облегчает другим разработчикам понимание и внесение изменений в ваш код.

• Написать тесты. Elixir поставляется с фреймворком для тестирования под названием ExUnit. Сгенерированный проектом mix new включает примеры тестов и doctests.

• Написать документацию. Сообщество Elixir гордится тем, что рассматривает документацию как объект первого класса и делает её легко доступной. Библиотеки поддерживают эту практику, предоставляя полную документацию API с примерами для своих модулей, типов и функций. Дополнительную информацию см. в главе «Написание документации» руководства «Начало работы». Такие проекты, как ExDoc, могут использоваться для генерации документов HTML и EPUB из документации. ExDoc также поддерживает «дополнительные страницы», такие как эта, которую вы сейчас читаете. Такие страницы дополняют документацию учебными материалами, руководствами, ссылками и даже шпаргалками.

• Следовать лучшим практикам. Проект Elixir документирует ряд антипаттернов, которых следует избегать в своём коде. Антипаттерны, связанные с процессами process-related anti-patterns и антипаттерны метапрограммирования macro-anti-patterns являются особо важными для авторов библиотек.

Проекты часто становятся доступными другим разработчикам путём публикации пакета Hex. Hex также поддерживает частные пакеты для организаций. Если ExDoc настроен для проекта Mix, то публикация пакета в Hex также автоматически опубликует сгенерированную документацию в HexDocs.

Управление зависимостями

Когда ваша библиотека опубликована и используется как зависимость, её файл блокировки (обычно имеющий имя mix.lock) игнорируется проектом-хостом. Выполнение команды mix deps.get в проекте-хосте пытается получить последние возможные версии зависимостей вашей библиотеки, как указано в требованиях в разделе deps вашего файла mix.exs. Эти версии могут быть больше, чем те, которые хранятся в вашем файле mix.lock (и, следовательно, используются в ваших тестах/CI).

С другой стороны, авторы вашей библиотеки нуждаются в детерминированной сборке, что подразумевает наличие файла mix.lock в вашей системе управления версиями (VCS).

Лучшей практикой управления файлом mix.lock является его хранение в системе управления версиями и запуск двух различных рабочих процессов непрерывной интеграции (CI): обычного детерминированного и другого, который начинается с mix deps.unlock --all и всегда компилирует вашу библиотеку и запускает тесты против последних версий зависимостей. Последний может выполняться даже ежедневно или периодически, чтобы следить за любыми возможными проблемами, связанными с обновлениями зависимостей.