Я планирую, что это будет первый пост из серии, содержащей различные советы и рекомендации, связанные с эффективным использованием репозиториев Maven для управления зависимостями, хранения артефактов и т.д. для Java и других языков JDK, таких как Kotlin. Моим предпочтительным репозиторием Maven, конечно же, является репозиторий Maven Central по целому ряду причин, и я, вероятно, включу несколько постов о Maven Central позже в эту серию.

Однако сейчас я начну с совета, связанного с JitPack, а именно с того, как настроить сборку JitPack, если ваш проект требует последних версий JDK (например, JDK версии > 8), или если вы хотите собирать с определенным дистрибутивом JDK. Я не связан с JitPack, и эта статья основана на моем недавнем опыте настройки сборок JitPack в паре моих проектов, где документация по JitPack не полностью покрывала мои требования.

Оглавление: Остальная часть этой заметки организована следующим образом:

• О JitPack: Я должен начать с объяснения того, как работает JitPack, потому что он немного отличается от других репозиториев Maven.
• Почему JitPack?: Краткое объяснение того, почему я начал делать свои библиотеки доступными через JitPack в дополнение к другим репозиториям.
• Как указать зависимость от JitPack: Хотя это не является целью данной заметки, будет полезно объяснить, как указать зависимость для артефакта, обслуживаемого из JitPack.
• Как настраивать сборки JitPack: Объяснение и примеры настройки сборок JitPack, включая пример на живом проекте на GitHub.
• Где вы можете найти меня

О JitPack

JitPack работает немного иначе, чем большинство других репозиториев артефактов Maven. В большинстве репозиториев Maven, таких как Maven Central или GitHub Packages, вы сначала собираете артефакты либо локально на своей системе, либо, возможно, как часть рабочего процесса CI/CD (например, через GitHub Actions); а затем после сборки артефактов (например, различных jar-файлов скомпилированных файлов классов, исходного кода, документации и т.д.) вы развертываете их в выбранном вами репозитории артефактов Maven.

JitPack не работает подобным образом. Вместо этого JitPack предназначен для сборки артефактов по требованию непосредственно из репозитория исходного кода, размещенного на GitHub или любом другом git-хосте, таком как GitLab, Bitbucket и т. д. Сборка по требованию происходит в первый раз, когда запрашивается версия артефакта, а затем просто обслуживается.

Уникальный аспект JitPack, напрямую вытекающий из его подхода, заключается в том, что разработчики могут включать зависимости от любого публичного git-репозитория на GitHub, Bitbucket и других git-хостах, даже если сопровождающие этих репозиториев явно не публикуют артефакты в какой-либо репозиторий Maven.

Почему JitPack?

Я уже публикую артефакты всех поддерживаемых мной библиотек Java в Maven Central, возможно, самом главном репозитории Maven, так зачем мне публиковать их еще и в JitPack? JitPack позволяет указывать любой git-тег, ветку, запрос на притяжение или хэш коммита в качестве версии для зависимости. Вы не захотите полагаться на одну из этих версий в производстве. Однако во время разработки иногда может быть полезно собрать сборку на основе очень специфической невыпущенной версии зависимости. С помощью JitPack вы можете сделать это, указав хэш коммита в качестве версии или даже указав ветку. Разве это не похоже на использование сборки SNAPSHOT? Да, но в этом случае нет причин создавать SNAPSHOT-сборки, которые вам могут понадобиться или не понадобиться. Или, возможно, ваши SNAPSHOT-сборки собираются каждую ночь, но вы обнаруживаете необходимость в сборке по определённой точке в истории git, которая произошла между ночными сборками. Или, возможно, ваши ночные SNAPSHOT собираются из ветки по умолчанию, а вы хотите построить зависимость от ветки с функциями, которая является незавершенным процессом в зависимости, над которой вы также работаете.

По сути, именно поэтому я начал публиковать артефакты в JitPack в дополнение к Maven Central. По сути, это источник SNAPSHOT сборок для всех и каждого коммита, для всех и каждого ответвления, включая недолговечные ответвления pull-request, без какого-либо вмешательства с моей стороны.

Но подождите, вы только что сказали «начал публиковать артефакты в JitPack»? Я думал, вы сказали, что JitPack обрабатывает все это независимо от того, публикует ли мейнтейнер репозитория артефакты где-либо? Я сказал это, и это правда, при условии, что JitPack может найти файл сборки (например, Maven pom.xml или эквивалент Gradle), и при условии, что ваш проект может собираться с настройками JitPack по умолчанию. Мы перейдем к этому немного позже…..

Как указать зависимость JitPack

Детали указания зависимостей зависят от вашего инструмента сборки. Я использую Maven, поэтому в моих примерах будет использоваться Maven. По умолчанию Maven ищет артефакты зависимостей в центральном репозитории Maven. Если вы хотите импортировать зависимости из любого другого места, вам нужно добавить детали в раздел <repositories></repositories> вашего pom.xml. Для импорта из JitPack вставьте следующее в этот раздел вашего pom.xml (возможно, вам потребуется создать такой раздел, если в настоящее время вы импортируете только из Maven Central):

<repository>
  <id>jitpack.io</id>
  <url>https://jitpack.io</url>
</repository>

Чтобы импортировать зависимость из репозитория Maven, необходимо указать ее координаты, которые состоят из groupId, artifactId и version. groupId обычно является обратным доменом или поддоменом, контролируемым тем, кто публикует артефакты. Например, на Maven Central и GitHub Packages я использую org.cicirello в качестве groupId для всех моих Java-библиотек. Однако, хотя JitPack поддерживает такие пользовательские групповые идентификаторы, groupId для JitPack обычно формируется из домена git-хоста вместе с именем пользователя или названием организации, владеющей репозиторием, который вы хотите импортировать. artifactId — это имя артефакта, которое иногда является именем пакета или модуля внутри него, но это не обязательно. Для JitPack, artifactId — это имя репозитория. А version — это, ну, та версия, которая вам нужна.

В моих примерах предполагается, что вы указываете в качестве зависимости репозиторий GitHub, но вам понадобится что-то похожее для других хостов, например Bitbucket.

Для импорта с помощью тега, например, тега релиза v1.2.3 вставьте следующее в раздел <dependencies></dependencies> вашего pom.xml:

<dependency>
  <groupId>com.github.USERNAME</groupId>
  <artifactId>REPOSITORY_NAME</artifactId>
  <version>v1.2.3</version>
</dependency>

JitPack также автоматически поддерживает отбрасывание v, поэтому если вы хотите быть последовательным с другими репозиториями Maven, вы также можете использовать:

<dependency>
  <groupId>com.github.USERNAME</groupId>
  <artifactId>REPOSITORY_NAME</artifactId>
  <version>1.2.3</version>
</dependency>

Или если вы хотите собрать сборку на основе текущего состояния определенной ветки, возможно, «main», вы можете использовать:

<dependency>
  <groupId>com.github.USERNAME</groupId>
  <artifactId>REPOSITORY_NAME</artifactId>
  <version>main-SNAPSHOT</version>
</dependency>

Или даже хэш конкретного коммита:

<dependency>
  <groupId>com.github.USERNAME</groupId>
  <artifactId>REPOSITORY_NAME</artifactId>
  <version>COMMIT_HASH_GOES_HERE</version>
</dependency>

Какой бы из вышеперечисленных способов вы ни использовали, имейте в виду, что если версия, которую вы импортируете, ранее не была собрана, в вашей сборке будет задержка, пока Maven (или Gradle, или любой другой инструмент сборки, который вы используете) ожидает ответа от JitPack, поскольку JitPack должен сначала собрать зависимость, прежде чем предоставлять артефакты. Любой последующий импорт, будь то вами или кем-то другим, будет происходить без такой задержки.

Вот эквивалентные примеры, как выше, но с использованием одного из моих репозиториев, для поддерживаемой мной Java-библиотеки стохастического локального поиска и эволюционных алгоритмов, Chips-n-Salsa.

С тегом:

<dependency>
  <groupId>com.github.cicirello</groupId>
  <artifactId>chips-n-salsa</artifactId>
  <version>v5.2.0</version>
</dependency>

Убрать v из тега:

<dependency>
  <groupId>com.github.cicirello</groupId>
  <artifactId>chips-n-salsa</artifactId>
  <version>5.2.0</version>
</dependency>

Последний коммит в ветке по умолчанию:

<dependency>
  <groupId>com.github.cicirello</groupId>
  <artifactId>chips-n-salsa</artifactId>
  <version>master-SNAPSHOT</version>
</dependency>

Из хэша коммита:

<dependency>
  <groupId>com.github.cicirello</groupId>
  <artifactId>chips-n-salsa</artifactId>
  <version>278803985ceb0e3d1515eefb2a69d0601e0176cf</version>
</dependency>

Из pull-запроса:

<dependency>
  <groupId>com.github.cicirello</groupId>
  <artifactId>chips-n-salsa</artifactId>
  <version>PR451-SNAPSHOT</version>
</dependency>

JitPack также поддерживает настройку обратного домена:

Я также настроил обратный домен на JitPack, поэтому все вышеперечисленное будет работать с <groupId>org.cicirello</groupId> в дополнение к <groupId>com.github.cicirello</groupId>, что приятно для согласованности с Maven Central. Но только выпущенные версии доступны через Maven Central, например, через зависимость типа:

<dependency>
  <groupId>org.cicirello</groupId>
  <artifactId>chips-n-salsa</artifactId>
  <version>5.2.0</version>
</dependency>

Как настроить сборки JitPack

Вы можете настроить JitPack, а можете и не настраивать его вовсе. Если у вас есть Maven pom.xml в корне вашего репозитория (или эквивалент этого для Gradle), и если ваш проект может быть собран с Java 8, то, скорее всего, вам не потребуется никакой настройки. Вы, или кто-либо другой, уже можете использовать JitPack для импорта вашего репозитория в качестве зависимости Maven. Обнаружив pom.xml в корне вашего репозитория, JitPack попытается выполнить сборку с использованием Java 8 следующим образом:

mvn install -DskipTests

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

В моем случае большинство моих библиотек требуют Java 17, поэтому без конфигурации сборки JitPack не работают. Чтобы сконфигурировать для более нового JDK, вот шаги.

Шаг 1: Создайте файл с именем jitpack.yml в корне вашего репозитория. Здесь будет происходить вся настройка. Не стесняйтесь обращаться к jitpack.yml для проекта, на котором основана эта заметка, Chips-n-Salsa, для получения полной информации.

Шаг 2: Укажите версию JDK в jitpack.yml, например, так:

jdk:
  - openjdk17

Обратите внимание, что если вы предположите (как это сделал я), что вышеприведенного достаточно, вы ошибетесь. Теперь вам нужно установить дистрибутив JDK, который вы хотите использовать, а также явно указать, что вы хотите его использовать. Я использую Temurin дистрибутив OpenJDK в проекте, на котором основана эта заметка. Вам нужны оба утверждения, которые я добавил ниже. Без sdk use, JitPack будет продолжать использовать Java 8. Полный список доступных JDK вы можете найти на сайте sdkman.

jdk:
  - openjdk17
before_install:
  - sdk install java 17.0.3-tem
  - sdk use java 17.0.3-tem

Шаг 3: Обновите Maven. В некоторых случаях вышеописанных действий может быть достаточно. Для меня это было не так. В настоящее время (на момент написания этого поста) в JitPack установлен Maven 3.6.1. Maven 3.6.1 был выпущен более 3 лет назад, в апреле 2019 года. Свойство <release> для настройки версии Java тогда еще не существовало. Если вы используете его (как я), то сборка JitPack будет неудачной, если вы не обновите Maven. Вы можете сделать это, изменив вышеприведенный вариант на следующий (который на момент написания этого сообщения обновит Maven до версии 3.8.6):

jdk:
  - openjdk17
before_install:
  - sdk install java 17.0.3-tem
  - sdk use java 17.0.3-tem
  - sdk install maven
  - mvn -v

Вам на самом деле не нужен mvn -v выше. Я включил его, чтобы показать версию в журналах сборки.

Шаг 4: Настройте шаг установки. На этом этапе вы можете закончить, если команда сборки JitPack по умолчанию mvn install -DskipTests подходит для вашего проекта. В моем случае я хотел также отключить одну из функций JitPack. Одна из особенностей JitPack, которая, вероятно, нравится многим, заключается в том, что если в результате сборки получается jar с javadocs, JitPack автоматически извлекает javadocs и обслуживает их, включая поддержку javadocs для каждого релиза. Я бы предпочел, чтобы они просто предоставляли jar с javadocs, как это делает Maven Central, а не автоматически размещали их. Для библиотек, которые я поддерживаю, я также размещаю javadocs на сайте проекта, и я бы предпочел, чтобы окончательной версией javadocs однозначно была версия, размещенная на моем домене cicirello.org. Таким образом, для сборок JitPack я просто отключаю генерацию javadoc, что приводит к полному jitpack.yml ниже:

jdk:
  - openjdk17
before_install:
  - sdk install java 17.0.3-tem
  - sdk use java 17.0.3-tem
  - sdk install maven
  - mvn -v
install:
  - mvn install -Dmaven.javadoc.skip=true -DskipTests

Важное замечание: Из-за того, что JitPack по сути создает снимок вашего репозитория, даже для релизных сборок, jitpack.yml должен присутствовать в конкретном снимке вашего репозитория, чтобы применяться. Например, для библиотеки, на которой основан этот пост, Chips-n-Salsa, первый релиз, в котором репозиторий содержит файл конфигурации, — 5.0.1, поэтому JitPack не сможет собрать любую предыдущую версию, хотя более ранние версии доступны через Maven Central и GitHub Packages. Аналогично, если вы укажете хэш любого коммита, предшествующего коммиту, в котором был представлен этот конфигурационный файл, сборка JitPack также завершится неудачей.

Пример живой конфигурации: Смотрите этот jitpack.yml для полного и живого примера, который находится в следующем репозитории:

cicirello / Chips-n-Salsa

Java-библиотека настраиваемых, гибридизируемых, итеративных, параллельных, стохастических и самоадаптивных алгоритмов локального поиска

Chips-n-Salsa — Java-библиотека настраиваемых, гибридизируемых, итеративных, параллельных, стохастических и самоадаптивных алгоритмов локального поиска.

Copyright (C) 2002-2022 Vincent A. Cicirello.

Веб-сайт: https://chips-n-salsa.cicirello.org/

Документация по API: https://chips-n-salsa.cicirello.org/api/

Публикации О библиотеке
Пакеты и релизы
Статус сборки
Покрытие тестов JaCoCo
Безопасность
DOI
Лицензия
Поддержка

Как цитировать

Если вы используете эту библиотеку в своих исследованиях, пожалуйста, ссылайтесь на следующую работу:

Cicirello, V. A., (2020). Chips-n-Salsa: Java-библиотека настраиваемых, гибридизируемых, итеративных, параллельных, стохастических и самоадаптивных алгоритмов локального поиска. Journal of Open Source Software, 5(52), 2448, https://doi.org/10.21105/joss.02448 .

Обзор

Chips-n-Salsa — это Java-библиотека настраиваемых, гибридизируемых, итеративных, параллельных, стохастических и самоадаптивных алгоритмов локального поиска. Библиотека включает реализации нескольких стохастических алгоритмов локального поиска, включая имитационный отжиг, альпинистские алгоритмы, а также конструктивные алгоритмы поиска, такие как стохастическая выборка. Chips-n-Salsa теперь также включает генетические алгоритмы, а также эволюционные алгоритмы в целом. Библиотека очень широко поддерживает симулированные…

Посмотреть на GitHub

Где вы можете меня найти

В Интернете:

Винсент А. Цицирелло — профессор компьютерных наук

Винсент А. Чичирелло — профессор компьютерных наук в Стоктонском университете — исследователь в области искусственного интеллекта, эволюционных вычислений, роевого интеллекта и вычислительного интеллекта, доктор философии по робототехнике в Университете Карнеги-Меллон. Он является старшим членом ACM, старшим членом IEEE, пожизненным членом AAAI, заслуженным членом EAI и членом SIAM.

cicirello.org

Следите за мной на DEV:

Винсент А. Чичирелло

Исследователь и преподаватель в области А.И., алгоритмов, эволюционных вычислений, машинного обучения и роевого интеллекта.

Следите за мной на GitHub:

cicirello / cicirello

Мой профиль на GitHub

Vincent A Cicirello

Сайты, где вы можете найти меня или мои работы
Веб и социальные сети
Разработка программного обеспечения
Публикации

Если вы хотите сгенерировать эквивалент вышеуказанного для своего профиля на GitHub, ознакомьтесь с действием cicirello/user-statisticianGitHub.

Посмотреть на GitHub