Скрипты проекта

Документация CI

• CI_PIPELINE.md — конвейер GitLab, стадии, архитектура
• CI_SCRIPTS.md — справочник по каждому файлу в scripts/ci
• Обслуживание диска Windows (runner): scripts/ci/docker-prune-keep-bases.ps1 — CI_SCRIPTS.md §7 (RU), EN

Структура

scripts/
  config/
    supported-os.sh
  ci/
    lint.sh
    sanitize.sh
    static-analysis.sh
    coverage.sh
    tests.sh
    examples.sh
    docs.sh
    run-task.sh
    run-all.sh
    generate-gitlab-os-matrix.sh
    docker-build-ci.sh
    docker-build-dev.sh
    docker-build-release.sh
    os-image-build-push.sh
    os-full-check.sh
  dev/
    build-debug.sh
    build-docs.sh
    build-examples.sh
    coverage.sh
    pre-push.sh
    pre-push-docker.sh
  docker/
    docker-paths.sh
    build-ci-image.sh
    build-dev-only-image.sh
    build-release-only-image.sh
    build-images.sh
  release/
    build.sh
    build-examples.sh
    test.sh
    install.sh
  setup/
    install-doxygen-llvm.sh
    install-deps-ubuntu-22.04.sh
    install-deps-ubuntu-24.04.sh
    install-deps-debian-13.sh
    install-deps-fedora-42.sh
    install-deps-fedora-43.sh
    verify-installers-docker.sh
    install-deps-for-current-os.sh

Помеченные секции джобов по одной ОС в .gitlab-ci.yml (между комментариями BEGIN generated / END generated) генерируются из scripts/config/supported-os.sh (см. ниже); правьте только supported-os.sh и скрипты установки install-deps-<slug>.sh, затем выполните generate-gitlab-os-matrix.sh --write.

Поддерживаемые ОС и GitLab matrix

Единый список целевых ОС (slug и образ ID:VERSION для Docker) задается в scripts/config/supported-os.sh (SUPPORTED_OS_ENTRIES, DEFAULT_TARGET_OS_SLUG). Его используют scripts/docker/docker-paths.sh, Docker helper-скрипты и проверки установщиков.

В GitLab CI для каждой ОС задан отдельный джоб (docker-images-<slug>, os-system-validation-main-<slug>) в .gitlab-ci.yml между маркерами BEGIN generated / END generated (без parallel.matrix, чтобы схемы в IDE не ругались). Не правьте сгенерированные строки вручную — они должны совпадать с выводом генератора.

Путь: scripts/ci/generate-gitlab-os-matrix.sh

• без аргументов — печатает сгенерированные блоки в stdout;
• --write — перезаписывает помеченные секции в .gitlab-ci.yml;
• --check — сравнивает маркеры в закоммиченном файле с выводом генератора (используется в джобе gitlab-os-matrix-check в .gitlab-ci.yml).

После изменения scripts/config/supported-os.sh (или добавления scripts/setup/install-deps-<slug>.sh) выполните:

bash scripts/ci/generate-gitlab-os-matrix.sh --write

и закоммитьте обновленный .gitlab-ci.yml вместе с правками.

Общие рекомендации

• Запускайте скрипты из корня репозитория.
• Для надежности используйте явный вызов через bash.
• Большинство параметров настраивается через переменные окружения.
• Для полного набора скриптов требуются инструменты: cmake, ninja, clang-format (пин 18.1.8 через PyPI в install-clang-format-ci.sh), codespell, doxygen, graphviz, LaTeX toolchain (pdflatex/makeindex), docker (для docker-скриптов).

Скрипт: pre-push проверки

Путь: scripts/dev/pre-push.sh

Назначение:

• проверка базовых инструментов (cmake, ninja, codespell);
• чистая локальная сборка;
• format-check и spell-check;
• сборка и тесты для dev и release-ci.

Запуск:

bash scripts/dev/pre-push.sh

Параметры:

• JOBS — количество потоков для сборки (по умолчанию nproc).

Пример:

JOBS=8 bash scripts/dev/pre-push.sh

Скрипт: простая Debug-сборка

Путь: scripts/dev/build-debug.sh

Назначение:

• конфигурация preset dev;
• сборка проекта в режиме Debug.

Запуск:

bash scripts/dev/build-debug.sh

Параметры:

• JOBS — количество потоков для сборки.

Скрипт: локальная сборка документации

Путь: scripts/dev/build-docs.sh

Назначение:

• конфигурация preset dev (для compile_commands.json, нужного libclang в Doxygen);
• запуск scripts/docs/build-doxygen-lang-variants.sh — тот же пайплайн, что и scripts/ci/docs.sh, с выводом в build/dev/docs/{html,xml,latex,pdf}/{en,ru}/ (по умолчанию английский и русский).

Запуск:

bash scripts/dev/build-docs.sh

Параметры:

• DOXYGEN_LANG_VARIANTS — необязательно; по умолчанию en=english;ru=russian. Пример одного языка: DOXYGEN_LANG_VARIANTS=en=english.
• DOXYGEN_SKIP_DOT_GRAPHS, DOXYGEN_SKIP_REFMAN_PDF — как в CI (ускорение итераций).

Вывод в духе CI в build/docs/.../{en,ru}/: bash scripts/ci/docs.sh.

Цель CMake docs (только при BUILD_MCSS_DOCS=ON) использует cmake/docs.cmake для одного языка в build/dev/docs/html (плоская структура); язык — DOXYGEN_DOCUMENTATION_LANGUAGE.

Скрипт: локальное покрытие

Путь: scripts/dev/coverage.sh

Назначение:

• конфигурация и сборка preset coverage;
• запуск тестов;
• генерация отчета покрытия.

Запуск:

bash scripts/dev/coverage.sh

Параметры:

• JOBS — количество потоков для сборки.

Скрипт: pre-push проверки в Docker

Путь: scripts/dev/pre-push-docker.sh

Назначение:

• запускает тот же набор проверок, что и scripts/dev/pre-push.sh;
• выполняет проверки внутри локального dev-образа Docker;
• монтирует текущий репозиторий в контейнер и запускает с вашим UID/GID.

Запуск:

bash scripts/dev/pre-push-docker.sh

Параметры:

• DEV_IMAGE_TAG — полное имя dev-образа (по умолчанию через scripts/docker/docker-paths.sh, например circuitgen/generator/ubuntu-24.04/dev:local);
• TARGET_OS — см. scripts/docker/docker-paths.sh;
• JOBS — количество потоков для сборки внутри контейнера.

Пример:

TARGET_OS=ubuntu-22.04 DEV_IMAGE_TAG=circuitgen/generator/ubuntu-22.04/dev:local JOBS=8 bash scripts/dev/pre-push-docker.sh

Вспомогательный модуль: пути Docker-образов

Путь: scripts/docker/docker-paths.sh

Назначение:

• единые правила имен образов, совпадающие с .gitlab-ci.yml: $DOCKER_URL/$IMAGE_OS_SUFFIX/ci:<tag>, $DOCKER_URL/$IMAGE_OS_SUFFIX/dev:<tag>, $DOCKER_URL/$IMAGE_OS_SUFFIX/release:<tag>;
• выбор ОС через TARGET_OS или DOCKER_CI_SYSTEM;
• используется скриптами в scripts/docker/, scripts/ci/docker-build-*.sh, scripts/ci/docs.sh, scripts/ci/run-task.sh, scripts/dev/pre-push-docker.sh.

Скрипт: сборка Docker образов (CI + DEV + RELEASE)

Путь: scripts/docker/build-images.sh

Назначение:

• собрать локальный CI-образ из dockerfile/Dockerfile.ci;
• собрать локальный dev-образ из dockerfile/Dockerfile.dev на базе CI-образа;
• собрать локальный release-образ из dockerfile/Dockerfile.release на легком базовом образе ОС (только компилятор, CMake, Ninja, git и т.п. — без Doxygen/TeX и прочего dev/CI-стека).

Имена образов задаются через scripts/docker/docker-paths.sh и совпадают с .gitlab-ci.yml: $DOCKER_URL/$IMAGE_OS_SUFFIX/ci:<tag>, $DOCKER_URL/$IMAGE_OS_SUFFIX/dev:<tag>, $DOCKER_URL/$IMAGE_OS_SUFFIX/release:<tag>.

Запуск:

bash scripts/docker/build-images.sh

Переменные окружения:

• DOCKERFILE_CI_NAME (по умолчанию dockerfile/Dockerfile.ci);
• DOCKERFILE_DEV_NAME (по умолчанию dockerfile/Dockerfile.dev);
• DOCKERFILE_RELEASE_NAME (по умолчанию dockerfile/Dockerfile.release);
• DOCKERFILE_CI (алиас для обратной совместимости, приоритетнее DOCKERFILE_CI_NAME);
• DOCKERFILE_DEV (алиас для обратной совместимости, приоритетнее DOCKERFILE_DEV_NAME);
• DOCKERFILE_RELEASE (алиас для обратной совместимости, приоритетнее DOCKERFILE_RELEASE_NAME);
• DOCKER_URL (по умолчанию circuitgen/generator, либо ${REGISTRY_URL}/${GROUP_NAME}/${REPO_NAME} если заданы);
• TARGET_OS — slug из scripts/config/supported-os.sh (задает DOCKER_CI_SYSTEM);
• DOCKER_CI_SYSTEM (по умолчанию ubuntu:24.04; из него выводится IMAGE_OS_SUFFIX);
• LOCAL_IMAGE_TAG — суффикс тега для локальных образов (по умолчанию local);
• CI_IMAGE_TAG / DEV_IMAGE_TAG / RELEASE_IMAGE_TAG — полные имена образов (если не заданы, вычисляются из путей выше).

Пример:

TARGET_OS=fedora-42 bash scripts/docker/build-images.sh

Скрипт: сборка только Docker CI-образа

Путь: scripts/docker/build-ci-image.sh

Назначение:

• собрать только локальный CI-образ из dockerfile/Dockerfile.ci.

Запуск:

bash scripts/docker/build-ci-image.sh

Скрипт: сборка только Docker dev-образа

Путь: scripts/docker/build-dev-only-image.sh

Назначение:

• собрать только локальный dev-образ из dockerfile/Dockerfile.dev;
• использовать уже существующий CI-образ как базовый.

Запуск:

bash scripts/docker/build-dev-only-image.sh

Скрипт: сборка только Docker release-образа

Путь: scripts/docker/build-release-only-image.sh

Назначение:

• собрать только локальный release-образ из dockerfile/Dockerfile.release;
• базовый образ задается через DOCKER_CI_SYSTEM / TARGET_OS (BASE_IMAGE в Dockerfile), не через fat CI-образ.

Запуск:

bash scripts/docker/build-release-only-image.sh

Скрипты Release

• scripts/release/build.sh
  Оптимизированная release-сборка без тестов.
• scripts/release/test.sh
  Release-сборка с тестами через preset release-ci.
• scripts/release/install.sh
  Установка артефактов release-сборки.
• scripts/release/suggest-next-version.sh
  Предлагаемый тег vX.Y.Z по коммитам после последнего SemVer-тега (Conventional Commits); см. Versioning.md.

Примеры:

bash scripts/release/build.sh
bash scripts/release/test.sh
INSTALL_PREFIX=prefix/release bash scripts/release/install.sh
bash scripts/release/suggest-next-version.sh --verbose

Скрипты установки зависимостей

• scripts/setup/install-deps-ubuntu-22.04.sh
  Устанавливает недостающие зависимости для Ubuntu 22.04.
• scripts/setup/install-deps-ubuntu-24.04.sh
  Устанавливает недостающие зависимости для Ubuntu 24.04.
• scripts/setup/install-deps-debian-13.sh
  Устанавливает недостающие зависимости для Debian 13 (trixie). Пин clang-format 18.1.8 через install-clang-format-ci.sh (колесо PyPI), как в остальных образах CI.
• scripts/setup/install-deps-fedora-42.sh
  Устанавливает недостающие зависимости для Fedora Workstation 42.
• scripts/setup/install-deps-fedora-43.sh
  Устанавливает недостающие зависимости для Fedora Workstation 43.

Все install-скрипты:

• проверяют текущий дистрибутив и версию;
• проверяют, какие пакеты уже установлены;
• устанавливают только недостающие пакеты;
• проверяют наличие codespell и ставят его через pip, если пакетный менеджер его не дал;
• устанавливают doxygen из исходников с -Duse_libclang=ON (версия по умолчанию 1.13.2), как в dockerfile/Dockerfile.ci.

Отдельный скрипт:

• scripts/setup/install-doxygen-llvm.sh
  Сборка и установка Doxygen с LLVM/libclang поддержкой.

Проверка install-скриптов в Docker-образах:

bash scripts/setup/verify-installers-docker.sh

Проверка в одном конкретном образе:

bash scripts/setup/verify-installers-docker.sh ubuntu-24.04

Проверяемые системы совпадают со списком slug в scripts/config/supported-os.sh (и с матрицей в помеченных секциях .gitlab-ci.yml после generate-gitlab-os-matrix.sh --write).

CI скрипты

Скрипты в scripts/ci/ используются в .gitlab-ci.yml и являются единым интерфейсом для CI-джобов.

Для локального запуска CI-этапов доступны два режима:

• CI_RUNNER=local — запуск в текущей системе;
• CI_RUNNER=docker — запуск внутри локального CI-образа Docker.

Для scripts/ci/docs.sh дополнительно доступны параметры:

• DOCS_RUNNER=auto|local|docker (по умолчанию auto).
• DOXYGEN_LANG_VARIANTS — по умолчанию en=english;ru=russian. Формат abbr=section1 section2;abbr2=...; для каждого варианта — отдельное дерево build/docs/{html,xml,latex,pdf}/<abbr>/.
• DOXYGEN_SKIP_DOT_GRAPHS, DOXYGEN_SKIP_REFMAN_PDF — передаются в cmake/docs-ci.cmake.
• DOXYGEN_ENABLED_SECTIONS — устаревшее значение по умолчанию english, если явно не заданы варианты; при использовании DOXYGEN_LANG_VARIANTS секции задаются для каждого варианта. В cmake/docs-ci.cmake выставляется OUTPUT_LANGUAGE (русский, если для варианта секции ровно russian, иначе английский).

# Запуск этапа в текущей системе
CI_RUNNER=local bash scripts/ci/run-task.sh lint

# Запуск этапа внутри локального Docker CI-образа
CI_RUNNER=docker CI_IMAGE_TAG=circuitgen/generator/ubuntu-24.04/ci:local bash scripts/ci/run-task.sh tests

# Полный прогон CI-этапов в Docker
CI_RUNNER=docker CI_IMAGE_TAG=circuitgen/generator/ubuntu-24.04/ci:local bash scripts/ci/run-all.sh