Source Руководство по библиотекам

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

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

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

$ mix new my_library

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

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

Команда mix new также позволяет использовать опцию --sup для создания нового проекта с деревом надзора из коробки. Более подробную информацию о запуске вашего проекта см. в официальном руководстве Mix & OTP или в документации Mix.

Публикация

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

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

• Выбрать лицензию. Наиболее распространённые лицензии в сообществе Elixir — это MIT License и Apache License 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.

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

Когда ваша библиотека используется в качестве зависимости, она по умолчанию выполняется в среде :prod. Поэтому, если ваша библиотека имеет зависимости, которые полезны только в режиме разработки или тестирования, вы хотите указать эти зависимости с помощью опции :only. Вы также можете указать :optional зависимости в вашей библиотеке, которые не навязываются пользователям вашей библиотеки. В таких случаях вы также должны рассмотреть компиляцию своих проектов с mix compile --no-optional-deps --warnings-as-errors в ваших тестовых средах, чтобы убедиться, что ваша библиотека компилируется без предупреждений, даже если отсутствуют необязательные зависимости. См. mix deps для всех доступных вариантов.

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

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

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