Проект

Проект#

Директория на диске, хранящая файлы для сборки решения.

Структура проекта#

  • module1 - прикладной модуль.

  • module2 - прикладной модуль.

  • moduleN - прикладной модуль.

  • projectModule - проектный модуль.

  • project - метаинформация по сборке.

  • build - каталог, находящийся вне системы контроля версий и содержащий данные, специфичные для локальной сборки:

    • lib - локальные JAR-библиотеки для запуска сервера и утилит прикладной разработки.

    • config.yml - создаётся при необходимости локального переопределения конфигурации проекта.

  • build.sbt - декларация сборки для sbt.

  • build.bazel - декларация сборки для bazel.

  • project.yaml - конфигурация проекта.

Конфигурация проекта#

Файл project.yaml в корне прикладного проекта задает параметры его сборки: версии Java и Scala, источники компонентов, комплекты сборки и состав модулей.

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

Внимание

После отладки исправления необходимо создать pull request в ветку разработки соответствующего модуля и дождаться нового релиза.

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

Пример конфигурации#

# Основные параметры проекта
scalaFeatureRelease: 2.13
javaFeatureRelease: 21
commonLibConfigVersion: 2

baseBuildKit:
  name: "<имя_базового_комплекта>"
  version: "<версия_базового_комплекта>"

applicationServer:
  source: "base://"

sbtPlugin:
  source: "base://"

modules:
  - gtk:
      source: "base://"
  - btk:
      source: "base://"
  - <имя_модуля>:
      source: "<адрес_репозитория>"
      branch: "<ветка>"
      # Публикация и репликация исходного кода модуля
      isPublish: true
      mirrorSource: "<адрес_репозитория_реплики>"

# Необязательные параметры

# Публикация проекта в комплект сборки
buildKit:
  name: "<имя_публикуемого_комплекта>"
  version: SNAPSHOT

# Публикация исходного кода решения
isPublishSrcFolder: true

# Переменные окружения сборки
env:
  orm: dblink

# Загрузка коробочной конфигурации
baseSourceKit:
  url: "<адрес_репозитория>"
  branch: "<ветка>"

# Репликация комплекта исходников
mirrorSourceKit:
  isPublish: true
  mirrorConfigSource: "<адрес_репозитория_реплики>"

# Прикладные подпроекты — Technical Preview
subprojects:
  - <имя_подпроекта>:
      source: "<адрес_репозитория>"
      branch: "<ветка>"

Описание полей конфигурации#

Основные параметры

  • scalaFeatureRelease (строка) — функциональная версия Scala для сборки проекта. Если поле отсутствует, sbt-plugin использует версию по умолчанию. Между функциональными версиями Scala может отсутствовать бинарная и исходная совместимость.

  • javaFeatureRelease (строка) — функциональная версия Java. Если поле отсутствует, sbt-plugin использует версию по умолчанию. Значение также определяет подключение каталога src/main/java-<версия>, если такой каталог есть в модуле.

  • commonLibConfigVersion (целое число) — профиль совместимости общих библиотек и зависящего от них исходного кода. Если поле отсутствует, sbt-plugin использует профиль 1. Правила выбора профиля приведены ниже.

  • isPublishSrcFolder (логическое значение) — включает публикацию артефактов с исходным кодом решения.

  • env (объект) — произвольные переменные окружения сборки в формате «имя — строковое значение». Если поле отсутствует, используется пустой набор. Модули могут читать эти значения и изменять свое поведение при сборке.

Профиль общих библиотек

commonLibConfigVersion задает набор версий общих библиотек, с которым собирается проект. Каждый профиль рассчитан на определенные версии sbt-plugin и базовых модулей. При смене профиля также могут меняться версия Scala и используемый исходный код.

Профиль

Назначение

Основные отличия

1

Исходный профиль совместимости

Используется по умолчанию. Подключает варианты исходного кода *-lib-ver-1.

2

Обновленный набор общих библиотек

Обновляет зависимости sbt-plugin, gtk, btk, bs и edi, изменяет предоставление JasperReports в rpt и подключает исходный код *-lib-ver-2.

3

Переход на Scala 2.13.18 и Jackson 2.22.2

Наследует основной набор профиля 2, обновляет Jackson, фиксирует Scala 2.13.18 и подключает исходный код *-lib-ver-3.

Изменяйте профиль только вместе с переходом на согласованный комплект сборки или набор веток sbt-plugin и базовых модулей. Новый номер вводится при общем изменении зависимостей или инструментов сборки, которое требует одновременной адаптации нескольких компонентов. Добавление обычной зависимости одного прикладного модуля не требует нового профиля.

Внимание

Допустимые номера профилей не проверяются строго. Неизвестное значение может выбрать несовместимые ветки зависимостей и исходного кода. На 01.09.2026 Mill-конфигурации базовых модулей различают только профили 1 и 2, поэтому профиль 3 предназначен для согласованной sbt-сборки.

Полный состав профиля отдельно не публикуется. Актуальные версии библиотек проверяются в CommonSetting.scala и GtkSetting.scala репозитория sbt-plugin, а также в build.sbt, package.mill и каталогах *-lib-ver-N базовых модулей.

Комплекты сборки и исходников

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

  • buildKit — комплект, в который публикуются артефакты проекта. Содержит поля name и version. Блок требуется для публикации библиотек в комплект сборки. Информация о том, как определяется адрес публикации, приведена в разделе «Конфигурация репозиториев».

  • baseBuildKit — комплект, на котором основан проект. Содержит поля name и version. Из него можно получать сервер приложений, sbt-plugin и модули с источником base://.

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

  • mirrorSourceKit — настройки репликации комплекта исходников. Поле isPublish включает репликацию, mirrorConfigSource задает адрес назначения.

В блоках buildKit и baseBuildKit поле name необходимо для использования указанного комплекта. Поле version необязательно: если версия не указана, используется snapshot. В блоке baseSourceKit для загрузки комплекта исходников необходимы url и branch. В блоке mirrorSourceKit поле mirrorConfigSource необходимо при включенном isPublish; по умолчанию isPublish имеет значение false.

Сервер, sbt-plugin и модули

Эти параметры задают состав проекта и способ подключения его компонентов: из исходного кода или из базового комплекта сборки.

  • applicationServer — источник и параметры публикации сервера приложений.

  • sbtPlugin — источник и параметры публикации плагина сборки.

  • modules — именованный список прикладных модулей. Если поле отсутствует, используется пустой список.

  • subprojects — именованный список прикладных подпроектов. Находится в режиме Technical Preview.

applicationServer, sbtPlugin и каждый элемент modules или subprojects используют общий набор вложенных полей:

  • source — источник компонента. HTTP-адрес или отсутствие значения означает подключение исходного кода; значение с префиксом base, например base://, — подключение артефакта из базового комплекта сборки.

  • branch — ветка репозитория, из которой загружается исходный код.

  • isPublish — включает публикацию компонента при выпуске комплекта. По умолчанию имеет значение false.

  • mirrorSource — адрес репозитория, в который реплицируется исходный код компонента.

Имя каждого элемента modules или subprojects обязательно и является системным именем модуля или подпроекта.

Совет

Для массовой синхронизации модулей используйте утилиту gsf-cli.

Конфигурация репозиториев#

Чтобы обеспечить возможность сборки проекта в различных локальных сетях, настройка репозиториев вынесена в отдельный файл и может быть переопределена при необходимости.

По умолчанию настройка репозиториев берется из файла application/project/repositories/default.yaml.

Пример настройки:

repositories:
  - name: maven-global
    url: "https://repo.global-system.ru/artifactory/libs-release"

publishRepository:
  name: app-global
  url: "https://repo.global-system.ru/artifactory/build-kit"
  # Запрашивать данные авторизации из менеджера учетных данных для данного репозитория
  isLoginRequired: true

Работа в изолированной сети#

Если нужно использовать только корпоративные репозитории и исключить обращения sbt к Maven Central, настройте глобальный список репозиториев и параметры запуска sbt.

  1. Создайте или измените файл C:\Users\<user_name>\.sbt\repositories:

    [repositories]
  local
  mvn-student: https://repo.global-system.ru/artifactory/student/
  mvn-common: https://repo.global-system.ru/artifactory/common/
  mvn-central: https://repo.global-system.ru/artifactory/maven-central
  mvn-libs-release: https://repo.global-system.ru/artifactory/libs-release
  mvn-build-kit: https://repo.global-system.ru/artifactory/build-kit

    Репозиторий mvn-build-kit требуется только для проектов, использующих комплект сборки. Доступ к нему требует авторизации. Если проект не использует комплект сборки, этот репозиторий можно не указывать.

  2. Для авторизации создайте в той же директории файл C:\Users\<user_name>\.sbt\.credentials:

    realm=Artifactory
host=repo.global-system.ru
user=<username>
password=<password>

  3. Запускайте sbt с параметрами:

    -Dsbt.override.build.repos=true -Dsbt.repository.config=C:\Users\<user_name>\.sbt\repositories

    Для gsf-cli добавьте эти параметры в команду запуска sbt.

    Для IDEA укажите их в поле JVM parameters: Settings > Build, Execution, Deployment > Build Tools > sbt.

Внимание

При использовании -Dsbt.override.build.repos=true sbt обращается только к репозиториям, указанным в файле repositories. Если необходимого артефакта нет в корпоративных репозиториях, сборка может завершиться ошибкой.

Настройки репозиториев из application/project/repositories/default.yaml при этом также игнорируются.

Смотрите: Прокси репозитории.

Интеграция с VCS#

Исходный код проекта может располагаться в произвольной системе контроля версий.

Модули могут находиться как в репозитории самого проекта, так и в удалённом репозитории. При инициализации проекта код из удалённых репозиториев добавляется в каталог основного проекта.

Совет

Модули из удалённого репозитория рекомендуется добавлять в файл .gitignore или аналог основного репозитория проекта.

Стратегии ветвления#

После инициализации проекта можно пользоваться стандартными средствами ветвления используемой VCS.

Предупреждение

При внесении изменений, нарушающих обратную совместимость схемы базы данных, рекомендуется:

  • Вносить такие изменения в основную ветку (master/main), чтобы минимизировать конфликты схемы БД между разработчиками.

  • Если изменения слишком масштабны, для их тестирования следует использовать локальную базу данных разработчика.

Публикация решения#

Публикация решения происходит средствами CI, например Jenkins.

Команда sbt для публикации решения в локальный каталог:

sbt publishSolution

Публикация комплекта сборки#

Публикация комплекта сборки происходит средствами CI.

Команда sbt для публикации решения в репозиторий:

sbt publish
Содержание