Neat sccache Шпаргалка.

Neat використовує sccache як засіб для запуску компіляторів C і C++. Він кешує результати компіляції, а не кінцеві пакети Neat, результати тестування, завантаження залежностей або образи Docker.

Для більшості розробників не потрібно нічого встановлювати чи налаштовувати: використовуйте build.sh у звичайному режимі та перегляньте статистику кешу, яка відображається в кінці.

У двох словах

Створити	Рівні кешу	Пише	Виживає --clean.
Місцевий	Локальний диск користувача.	Локальний диск	Так
Vulcan develop або main.	Локальний диск для середовища виконання, а потім захищена гілка S3.	Локальний диск і захищений простір імен S3.	S3 робить.
Завантаження змін у гілку Vulcan.	Локальний диск для середовища виконання, потім гілка S3.	Локальний диск та його ізольована гілка простору імен.	До видалення гілки
Мітка Vulcan або непряме посилання.	Локальний диск для виконання коду, а потім найближчий захищений сховище S3.	Лише локальний диск.	Відсутній постійний стан програми, що виконується.

Підтримувана точка входу завжди така:

./build.sh <options>

Не використовуйте sccache як заміну компілятору або не додавайте параметри запуску вручну. build.sh містить обидва варіанти запуску CMake:

CMAKE_C_COMPILER_LAUNCHER
CMAKE_CXX_COMPILER_LAUNCHER

Локальні збірки

Звичайне використання.

Кешування ввімкнено в режимі auto:

./build.sh --dev-only
./build.sh --all --clean

Місце розташування та обсяг кешу за замовчуванням:

~/.cache/sima-neat/sccache
10 GiB

Кеш знаходиться за межами build/. Видалення build/ або виконання команди --clean не призведе до видалення кешованих результатів компіляції.

Якщо sccache не вказано в PATH, build.sh завантажує фіксовану версію в:

${XDG_CACHE_HOME:-$HOME/.cache}/sima-neat/tools/sccache/<version>/

Архів перевіряється на відповідність хешу SHA-256, який міститься у файлі scripts/configure_sccache.sh. Підтримуються операційні системи Linux і macOS на архітектурах arm64 та x86-64.

Загальні елементи керування

# Explicitly require sccache. Fail the build if it cannot be configured.
SIMANEAT_SCCACHE=on ./build.sh --all

# Disable caching for a reproducibility comparison.
SIMANEAT_SCCACHE=off ./build.sh --all --clean

# Put the local cache on a larger or faster volume.
SCCACHE_DIR=/mnt/nvme/sccache ./build.sh --all

# Change the local cache limit.
SCCACHE_CACHE_SIZE=20G ./build.sh --all

SIMANEAT_SCCACHE=auto є значенням за замовчуванням. У цьому режимі, у разі збою під час початкового завантаження, з’являється попередження, і процес збірки триває без кешування. on робить цей збій фатальним.

Перевірте або очистіть локальний кеш.

Використовуйте той самий бінарний файл, який було обрано скриптом build.sh, або sccache, якщо його розміщено в PATH:

sccache --show-stats
sccache --zero-stats
sccache --show-adv-stats

Щоб звільнити місце, зупиніть сервер і видаліть лише налаштовану директорію кешу:

sccache --stop-server
rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/sima-neat/sccache"

Підтвердіть правильність обраного шляху перед його видаленням. Не видаляйте всю теку кешу користувача.

Збірки Vulcan Cloud

Vulcan використовує той самий локальний кеш на диску, а також додає рівень зашифрованого сховища S3:

s3://sima-neat-compiler-cache-production/
  core/
    sccache-v1/
      <architecture>/
        <sdk-cache>/
          <build-mode>/
            develop/
              branches/<encoded-feature-branch>/
            main/
              branches/<encoded-feature-branch>/

Наприклад:

core/sccache-v1/arm64/sdk-develop/standard/develop/

Простір імен навмисно містить:

• sccache-v1: схема кешування, що дозволяє навмисно виконати глобальне скидання.
• архітектура: запобігає змішуванню результатів компіляції для arm64 та x86-64.
• Ідентифікатор кешу SDK: запобігає змішуванню несумісних результатів роботи SDK/набору інструментів.
• режим збирання: забезпечує розділення стандартних інструментів і інструментів для фаззінг-тестування.
• захищена базова гілка: запобігає можливості одночасного запису в один і той самий простір імен гілками develop і main.

S3-контейнер є приватним, зашифрованим за допомогою власного ключа KMS і відокремлений від контейнера для артефактів. Він не має розподілу CloudFront, оскільки об’єкти кешу компілятора є приватними та призначеними для одноразового використання. Термін дії об’єктів закінчується автоматично через 45 днів.

Доступ до відділення

Посилання Git	Роль OIDC	Режим S3
Точний refs/heads/develop	Захищений автор	READ_WRITE у develop/.
Точний refs/heads/main	Захищений автор	READ_WRITE у main/.
Пряме надсилання змін до окремої гілки функцій	Автор розділу	READ_WRITE нижче <base>/branches/<branch>/
Мітка або непряма посилання.	Читач	READ_ONLY з обраної захищеної базової версії.

Під час першої компіляції, гілка для нової функції копіює кеш з найближчого захищеного предка в Git (develop або main) у власний простір імен. Потім компіляція зчитує та записує лише в цей простір імен гілки. Наступні компіляції повторно використовують його, поки подія видалення гілки в GitHub не видалить усі простори імен для цієї гілки, включаючи архітектуру, SDK та режим компіляції. Гілки для нових функцій не можуть записувати дані в жоден із захищених кешів.

Автоматичне визначення предків порівнює відстань до спільного предка з develop та main. Робочий процес, який можна повторно використовувати або запускати вручну, може встановити cache_base_branch=develop|main, коли для певної гілки потрібна явна базова конфігурація. Аутентифікаційні дані AWS – це короткочасні облікові дані GitHub OIDC; довготривалі ключі AWS не зберігаються в GitHub або контейнері SDK.

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

Vulcan явно перевіряє запуск sccache перед налаштуванням CMake. Якщо S3, KMS, мережа або тимчасові облікові дані перешкоджають запуску кеш-сервера, робочий процес виводить попередження та виконує компіляцію без sccache. Таким чином, наявність віддаленого кешу є лише оптимізацією і не може блокувати компіляцію. Локальний кеш, що використовується безпосередньо на сервері, не використовується як резервний варіант, оскільки сервери Vulcan є тимчасовими. Локальні компіляції для розробників зберігають свій звичайний постійний кеш на диску.

Перегляд статистики збірки.

Кожна збережена версія збірки завершується виведенням, подібним до такого:

Compile requests                    623
Cache hits                          619
Cache misses                          4
Cache hits rate                   99.36 %
Cache timeouts                        0
Cache read errors                     0
Cache write errors                    0
Compilations                          4

Інтерпретуйте важливі поля наступним чином:

Поле	Значення
Зберіть запити.	Виклики компілятора, зафіксовані системою sccache.
Успішні звернення до кешу.	Запити відновлено без повторного запуску компілятора.
Помилки кешування.	Запити, для яких потрібна компіляція.
Компіляції	Компілятор обробляє фактично виконані процеси.
Запити, які не кешуються.	Виклики, які навмисно було оминати, використовуючи sccache.
Помилки під час читання/запису.	Збої в роботі кеш-сервера; слід з’ясувати причини, якщо їх наявність фіксується під час локальних або тестових збірок.
Місце розташування кешу.	Активний бекенд, наприклад, локальний диск або багаторівневий.

Низький відсоток успішних збірок є нормальним явищем для першої збірки нового набору інструментів, кешу SDK, архітектури, режиму збірки або суттєво зміненого дерева вихідного коду. Оцініть кеш, виконавши другу збірку з використанням того ж коміту та конфігурації.

Якщо будь-який рівень має режим лише для читання, sccache v0.16 може повідомляти про спроби запису як про помилки запису, навіть якщо збірка в режимі лише для читання завершується успішно. Це стосується тегів та інших непрямих контекстів. Прямі надсилання змін до гілок функцій повинні повідомляти про READ_WRITE; досліджуйте помилки запису в цих збірках.

Швидка перевірка

Перевірте можливість повторного використання на місцях.

Запустіть процес чистої збірки двічі:

SIMANEAT_SCCACHE=on SIMANEAT_SCCACHE_ZERO_STATS=ON \
  ./build.sh --dev-only --clean --no-dist

SIMANEAT_SCCACHE=on SIMANEAT_SCCACHE_ZERO_STATS=ON \
  ./build.sh --dev-only --clean --no-dist

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

Перевірте конфігурацію Vulcan.

У журналі збірки GitHub Actions зверніть увагу на:

sccache enabled: sccache <version>
sccache local cache: <path> (<limit>)
sccache remote cache: s3://<bucket>/<prefix> (READ_ONLY|READ_WRITE)

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

Усунення несправностей

sccache не ввімкнено.

• Підтвердьте, що для збірки використовується build.sh.
• Перевірте, чи SIMANEAT_SCCACHE не вимкнено (off).
• Запустіть повторно з увімкненою опцією SIMANEAT_SCCACHE=on, щоб помилки під час початкового завантаження призводили до фатальних наслідків.
• Переконайтеся, що встановлено curl, tar, а також наявна або sha256sum, або shasum.

Друга локальна збірка все ще містить пропуски.

• Переконайтеся, що для обох збірок використовується один і той самий компілятор, SDK, режим збірки та набір параметрів.
• Підтвердіть, що SCCACHE_DIR вказує на той самий постійний каталог.
• Шукайте згенеровані вхідні дані, що містять мітки часу або змінені абсолютні шляхи.
• Перевірте Non-cacheable calls та Unsupported compiler calls.
• Підтвердіть, що кеш не було видалено через обмеження, встановлене значенням SCCACHE_CACHE_SIZE.

«Вулкан» не фіксує жодних віддалених атак.

• Підтвердьте, що вибрана базова версія develop або main була заповнена.
• Для окремої гілки функціоналу перевірте, чи показує журнал очікувану базову гілку та його закодований префікс, що визначає конкретну гілку.
• Порівняйте архітектуру, ідентифікатор кешу SDK та режим збірки.
• Перевірте, чи відображаються в журналі очікуване ім’я контейнера та префікс.
• Ставтеся до «холодного» простору імен як до звичайного; порівнюйте дві ідентичні збірки.

Запуск S3 завершується невдало з помилкою AccessDenied.

Для кешованих ролей потрібен префікс, що визначає область дії, для запиту s3:ListBucket, а також права доступу до об’єктів для перевірки .sccache_check:

• читач: GetObject
• автор: GetObject та PutObject

Обидві ролі також вимагають відповідних дозволів KMS. Не додавайте дозволи S3 або KMS до ролі EC2 runner як тимчасове рішення; натомість, усуньте проблему з роллю кешування GitHub OIDC у Vulcan.

Під час діагностики помилки компілятора обійдіть кеш.

SIMANEAT_SCCACHE=off ./build.sh --all --clean

Якщо проблема не зникає, то вона не пов’язана зі збереженими результатами роботи компілятора.

Права власності та джерело істини.

Занепокоєння	Джерело
Локальна конфігурація, версія, контрольні суми, параметри кешу за замовчуванням.	scripts/configure_sccache.sh
Інтеграція з програмним середовищем CMake та статистика	build.sh
Вибір ролі гілки та простору імен кешу.	.github/workflows/vulcan-ci.yml
Повторно використовувані вхідні дані робочого процесу Vulcan і налаштування OIDC.	sima-neat/.github
Ролі IAM для S3, KMS, керування життєвим циклом і кешу.	sima-neat/vulcan

Під час зміни схеми кешування, меж сумісності інструментального комплексу або моделі доступу, одночасно оновіть усі відповідні репозиторії та цю сторінку.