Перейти до основного вмісту

Artifacts Handler

Цей репозиторій містить засіб автоматизації на базі CMake для керування артефактами збірки та їхніми версіями в кількох репозиторіях. Система дозволяє користувачеві визначити, які артефакти й версії потрібні, а потім автоматично завантажує необхідні компоненти. Єдине програмне забезпечення, яке має бути в системі користувача, — це GIT і CMake. Усі інші компоненти, необхідні для збірки проєкту, мають бути доступні через цей модуль.

⚙️ Огляд​

Artifacts Manager використовує конфігураційний файл (ArtifactsConfig.txt), що містить список потрібних артефактів та їхніх версій. Під час запуску Artifacts Manager виконує такі кроки:

  1. Клонує кореневий репозиторій артефактів.
  2. Знаходить відповідний submodule артефакту.
  3. Виконує checkout репозиторію на цей точний коміт.
  4. Встановлює клонований артефакт. 5: Ініціалізує встановлений артефакт.

Такий підхід забезпечує мінімальне використання мережі та швидку синхронізацію між середовищем збірки й репозиторіями артефактів.

1: Клонування​

Кореневий репозиторій артефактів клонується (якщо ще не існує) без ініціалізації submodules. Це забезпечує мінімальне використання мережі та прискорює весь процес.

2: Пошук​

Система перебирає всі артефакти, налаштовані в ArtifactsConfig.txt, і знаходить потрібний артефакт, шукаючи в теках кореневого репозиторію артефактів. Пошук виконується без урахування регістру, щоб зменшити ймовірність проблем із конфігурацією.

3: Checkout​

Після знаходження submodule артефакту виконується checkout потрібної версії артефакту. Кожен реліз артефакту розміщено в окремій гілці. Якщо користувач вибирає latest замість числової версії, список гілок завантажується раз на добу, і перевіряється остання версія. Якщо знайдено новішу версію, система використає її. Користувач може вибрати підверсію артефакту. Вона відповідає версії допоміжної функціональності артефакту (власне handler артефакту). Ця функціональність містить усе необхідне для ініціалізації та використання артефакту. Назва гілки релізу складається з:

  • версії релізу (наприклад, 15.2.0)
  • цільової операційної системи (наприклад, Win, Unix, DarwinARM) Checkout виконується як shallow clone (--depth=1), щоб мінімізувати мережевий трафік і використання пам'яті та прискорити процес.

4: Встановлення​

Після checkout артефакт має бути встановлений. Процес встановлення складається з розпакування архіву артефакту в локальну теку встановлення та копіювання необхідних файлів handler артефакту з його репозиторію.

5: Ініціалізація​

Після встановлення артефакт має бути ініціалізований перед збіркою, щоб надати збірці необхідну інформацію. У більшості випадків ініціалізація оновлює системну змінну PATH, додаючи шлях до поточного артефакту. Цей шлях додається на початок системного PATH, щоб функціональність артефакту мала пріоритет над уже встановленою.

📄 Конфігурація артефактів​

Артефакти можна налаштувати кількома способами:

  • Використанням файлу ArtifactsConfig.txt, розташованого в ${CMAKE_SOURCE_DIR}
  • Вказанням розташування ArtifactsConfig.txt через параметр CONFIG_FILE_PATH
  • Вказанням списку артефактів через параметр ARTIFACTS_LIST

Використання файлу ArtifactsConfig.txt у ${CMAKE_SOURCE_DIR}​

Цей конфігураційний файл має розташовуватися в кореневій теці cmake (${CMAKE_SOURCE_DIR}). Конфігураційний файл має використовувати синтаксис ArtifactName;Version;Subversion, де:

  • ArtifactName – назва модуля артефакту (без урахування регістру)
  • Version – відповідає релізу артефакту (або latest для найновішої версії)
  • Subversion – відповідає версії handler артефакту (або latest для найновішого коміту)
gcc-arm-none-eabi;14.3.1;latest
ninja;latest;latest
doxygen;latest;latest

Шлях до розташування артефактів можна налаштувати в першому рядку ArtifactsConfig.txt. Якщо рядок починається з "ROOT_REPO_PATH=", система використає цей шлях як розташування артефактів.

ROOT_REPO_PATH=D:/Artifacts
gcc-arm-none-eabi;14.3.1;latest
ninja;latest;latest
doxygen;latest;latest

Вказання розташування ArtifactsConfig.txt через параметр CONFIG_FILE_PATH​

Якщо конфігураційний файл розташований не в ${CMAKE_SOURCE_DIR}, користувач може вказати шлях до нього через параметр CONFIG_FILE_PATH.

cmake -DCONFIG_FILE_PATH=/path/to/config/ -B ...

Вказання списку артефактів через параметр ARTIFACTS_LIST​

Якщо користувач не хоче використовувати конфігураційний файл ArtifactsConfig.txt, конфігурацію артефактів можна задати через параметр ARTIFACTS_LIST.

cmake -DARTIFACTS_LIST=gcc-arm-none-eabi;14.3.1,ninja;latest;latest,doxygen;latest;latest

Підтримка ОС​

  • У Windows менеджер автоматично вибирає гілки, що закінчуються на -Win.
  • У Linux він вибирає гілки, що закінчуються на -Unix.
  • У **MacOS ** він вибирає гілки, що закінчуються на -DarwinARM
  • Якщо гілку або коміт не вдається знайти, скрипт пропускає цей артефакт із попередженням.

Будь ласка, зверніться до адміністратора із запитом на підтримку іншої ОС.

🧠 Примітки щодо реалізації​

  • Система використовує execute_process() з CMake для виклику команд Git.
  • Репозиторії обробляються за допомогою shallow fetch (--depth=1) для мінімізації розміру.
  • Назви артефактів порівнюються без урахування регістру, що дозволяє гнучке форматування конфігурації.
  • Скрипт підтримує інкрементальну роботу — уже клоновані репозиторії використовуються повторно.

📁 Структура тек​

ArtifactsManager/
├── README.md              # Readme file.
├── ArtifactsHandler.cmake # The main management script
└── Cache/
    ├── RootRepo/          # Root repository with submodules
    └── Artifacts/         # Artifacts installation folder

🚀 Використання​

Запустіть скрипт CMake безпосередньо:

cmake -P ArtifactsHandler.cmake

За бажанням його можна інтегрувати в наявну збірку CMake або CI pipeline, щоб автоматично отримувати потрібні версії артефактів перед збіркою.

Користувач може налаштувати шлях до потрібного розташування артефактів, задавши аргумент "ROOT_REPO_PATH".

cmake -P -DROOT_REPO_PATH="D:/Artifacts" ArtifactsHandler.cmake

🧩 Приклад робочого процесу​

  1. Оновіть ArtifactsConfig.txt, указавши потрібні версії
  2. Виконайте: 
    cmake -P ArtifactsHandler.cmake
  3. Скрипт:
    • Клонує кореневий репозиторій артефактів (якщо ще не клоновано)
    • Знаходить і отримує правильну гілку та коміт для кожного артефакту
  4. Тепер ваше середовище готове з усіма потрібними версіями артефактів.

🛠️ Вимоги​

  • CMake ≥ 3.21
  • Git ≥ 2.20
  • Мережевий доступ до ваших репозиторіїв артефактів (наприклад, Azure DevOps)

Ліцензія​

Цей репозиторій об'єднує компоненти з пакетів STMicroelectronics. Окремі компоненти зберігають свої ліцензії. Докладніше дивіться в кожній теці.

Автори​

Запрошуємо до співпраці! Будь ласка, відкрийте pull request.