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

Wippy использует систему зависимостей на основе файла блокировки. Модули публикуются в хаб, объявляются как зависимости в исходном коде и разрешаются в файл wippy.lock, который отслеживает точные версии.

Файлы проекта

wippy.lock

Файл блокировки отслеживает структуру каталогов проекта и закреплённые зависимости:

directories:
  modules: .wippy
  src: ./src
modules:
  - name: acme/http
    version: v1.2.0
    hash: 4ea816fe84ca58a1f0869e5ca6afa93d6ddd72fa09e1162d9e600a7fbf39f0a2
  - name: acme/sql
    version: v2.0.1
    hash: b3f9c8e12a456d7890abcdef1234567890abcdef1234567890abcdef12345678
Поле Описание
directories.modules Где хранятся загруженные модули (по умолчанию: .wippy)
directories.src Где находится исходный код (по умолчанию: ./src)
modules[].name Идентификатор модуля в формате org/module
modules[].version Закреплённая семантическая версия
modules[].hash Хэш содержимого для проверки целостности

wippy.yaml

Метаданные модуля для публикации. Требуется только при публикации собственного модуля:

organization: acme
module: http
version: 1.2.0
description: HTTP utilities for Wippy
license: MIT
repository: https://github.com/acme/wippy-http
keywords:
  - http
  - web
Поле Обязательное Описание
organization Да Строчные буквы, буквенно-цифровые с дефисами
module Да Строчные буквы, буквенно-цифровые с дефисами
version Нет Семантическая версия (устанавливается при публикации)
description Нет Описание модуля
license Нет Идентификатор лицензии SPDX
repository Нет URL репозитория с исходным кодом
homepage Нет Домашняя страница проекта
keywords Нет Ключевые слова для поиска
authors Нет Список авторов

Объявление зависимостей

Добавьте записи ns.dependency в ваш _index.yaml:

version: "1.0"
namespace: app
entries:
  - name: dependency.http
    kind: ns.dependency
    component: acme/http
    version: "^1.0.0"

  - name: dependency.sql
    kind: ns.dependency
    component: acme/sql
    version: ">=2.0.0"

Ограничения версий

Ограничение Пример Совпадает
Точная 1.2.3 Только 1.2.3
Каретка ^1.2.0 >=1.2.0, <2.0.0
Тильда ~1.2.0 >=1.2.0, <1.3.0
Диапазон >=1.0.0 1.0.0 и выше
Подстановочный знак * Любая версия (выбирается наивысшая)
Комбинированное >=1.0.0 <2.0.0 Между 1.0.0 и 2.0.0

Правила разрешения

  • Каждый модуль разрешается по пересечению всех объявленных диапазонов в графе зависимостей. Несовместимые диапазоны (diamond-конфликты) приводят к явной ошибке разрешения, а не к молчаливому выбору одной из сторон.
  • Зависимости разрешаются из объявленных диапазонов, а не из ранее разрешённых закреплённых версий.
  • Объявления корня выигрывают у транзитивных: когда ваше приложение и зависимость тянут один и тот же модуль или требование, приоритет у вашего объявления. Запись зависимости с meta.module считается транзитивной, если явно не помечена как корневая — опубликованные приложения сохраняют объявленные в исходниках зависимости как корневые.
  • Один и тот же компонент может быть объявлен корневой зависимостью только один раз — повторное объявление отклоняется с ошибкой конфликта. Вместо этого обновите существующую зависимость.

Среда выполнения сохраняет каждый разрешённый граф в истории своего реестра и воспроизводит его при загрузке вместо повторного разрешения, поэтому развёрнутое приложение загружается ровно с теми версиями, которые были разрешены при применении изменения зависимостей. wippy.lock остаётся переносимым снимком для исходных проектов.

Рабочий процесс

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

wippy init

Создаёт wippy.lock с каталогами по умолчанию.

Добавление зависимостей

wippy add acme/http               # Последняя версия
wippy add acme/http@1.2.3         # Точная версия
wippy add acme/http@latest         # Метка latest

Это обновляет файл блокировки. Затем установите:

wippy install

Разрешение из исходного кода

Если ваш исходный код уже содержит записи ns.dependency:

wippy update

Эта команда сканирует каталог с исходным кодом, разрешает все ограничения зависимостей, обновляет файл блокировки и устанавливает модули.

Обновление зависимостей

wippy update                       # Переразрешить все зависимости
wippy update acme/http             # Обновить только acme/http
wippy update acme/http acme/sql    # Обновить конкретные модули

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

Установка из файла блокировки

wippy install                      # Установить всё из файла блокировки
wippy install --refresh            # Повторно загрузить каждый модуль (--force и --repair — алиасы)

Хранение модулей

Загруженные модули хранятся в каталоге .wippy/vendor/:

project/
  wippy.lock
  src/
    _index.yaml
  .wippy/
    vendor/
      acme/
        http-v1.2.0.wapp
        sql-v2.0.1.wapp

По умолчанию модули хранятся как файлы .wapp. Для распаковки в каталоги:

# wippy.lock
options:
  unpack_modules: true

С включённой распаковкой:

.wippy/
  vendor/
    acme/
      http/
        wippy.yaml
        src/
          _index.yaml
          ...

Локальная разработка с заменами

Замените модули из хаба локальными каталогами для разработки. Замены объявляются в секции workspace файла конфигурации среды выполнения — обычно приватного, игнорируемого git и компонуемого поверх .wippy.yaml:

# .wippy.workspace.yaml
version: "1.0"
workspace:
  replacements:
    acme/http: ../local-http
    acme/sql: ../local-sql

wippy run --config .wippy.yaml --config .wippy.workspace.yaml

Ключи — это org/module, значения — каталоги (относительные пути разрешаются относительно каталога первого файла --config; путь должен существовать и быть каталогом). Установка замены в null отключает замену, унаследованную из более раннего слоя конфигурации или профиля. Замены также могут находиться внутри профиля, чтобы активироваться только с --profile workspace.

Замены рабочего пространства влияют на граф загрузки при старте и никогда не записываются в wippy.lock. Изменения локальных исходников подхватываются напрямую, без обращения к хабу. Глобы exclude: из исходного wippy.yaml модуля применяются и к каталогам замен — как при загрузке записей, так и при хешировании содержимого.

Секция replacements: в wippy.lock устарела: она всё ещё загружается, но выводит предупреждение. Перенесите эти записи в workspace.replacements файла конфигурации.

Порядок загрузки

При запуске Wippy загружает записи из каталогов в следующем порядке:

  1. Каталог с исходным кодом (src)
  2. Каталоги замен
  3. Каталоги вендорных модулей

Модули с активными заменами пропускают свой вендорный путь.

Проверка целостности

Каждый модуль в файле блокировки имеет хеш содержимого. При установке загруженные модули проверяются на соответствие ожидаемым хешам. Несовпадающие модули отклоняются и повторно загружаются из реестра.

Смотрите также