Rush.js — как можно значительно ускорить сборку ваших проектов, используя кеширование

Кеширование сборок — это экспериментальная функция, позволяющая сохранять результаты последней успешной сборки и использовать их в качестве основы для последующих сборок. Это значительно ускоряет процесс, поскольку не пересобираются проекты, которые не изменились с момента последней сборки. Давайте посмотрим, как это работает.

В Rush по умолчанию реализован механизм инкрементной (ускоренной) сборки. При повторном вызове команды rush build пропускаются уже обновлённые проекты. Инкрементный анализ Rush опирается на хеши зависимостей. Их можно найти в файле project>/.rush/temp/shrinkwrap-deps.json внутри каждого проекта. Но результаты сборок никуда не сохраняются и поэтому, как правило, при переключении на другую ветку потребуется сделать полный rebuild.

Проект считается обновлённым в следующих случаях:

• проект создан локально;

• с момента последней сборки не изменились исходные файлы и npm-зависимости;

• проект зависит от других локальных проектов из монорепозитория и эти проекты обновлены;

• параметры командной строки не изменялись. Например, если сначала была выполнена команда rush build, а затем rush build --production, то в таком случае проекты требуют пересборки.

Механизм выбора проектов для rebuild

Предположим, что у нас есть монорепозиторий, состоящий из семи проектов: A, B, C, D, E, F, G.

Эти кружки представляют локальные проекты монорепозитория, а не внешние npm-пакеты. Проект D зависит от C и G, и это означает, что С и G нужно собрать до сборки D.

Если мы внесём изменения в проект B, то на момент вызова последующего build произойдёт rebuild сначала проекта B, потом C, и в последнюю очередь D, так как они зависят друг от друга. Все остальные проекты останутся без изменений.

В основе кеширования сборок лежит похожий механизм определения проектов, которые необходимо пересобрать. Разница в том, что результат успешной сборки помещается в tar-архив. Имя файла с архивом содержит специальный хеш. Созданный архив кешируется и помещается в хранилище.

Перед сборкой проекта вычисляется его хеш, который далее запрашивается в кеше. Если запись кеша есть в хранилище, то все существующие выходные папки удаляются, tar-архив из предыдущей сборки извлекается в папку проекта, а сборка пропускается. Кешируются не все папки проекта, а только те, которые указаны в конфигурации, например, папка dist.

Есть два варианта хранения закешированных архивов:

• В папке кеша на локальном диске. Расположение по умолчанию — common/temp/build-cache.

• В контейнере облачного хранилища. По умолчанию система CI будет настроена на запись в облачное хранилище, а отдельным пользователям будет предоставлен доступ только для чтения. Например, каждый раз, когда PR объединяется с основной ветвью, система CI получает архивы сборок и загружает их в облачное хранилище. И поэтому даже самая первая сборка после команды git clone будет очень быстрой.

Хеш формируется следующим образом. Создаётся хэш SHA1, и в него в определённом порядке добавляются данные:

• список названий output-папок в JSON-формате, которые должны быть закешированы;

• название последней введённой команды;

• хеш каждой зависимости проекта.

Сформированный хеш помещается в название файла с tar-архивом, который будет сохранён в хранилище. Исходный код получения хеша:

Включение функции кеширования сборок

Для того, чтобы кеширование заработало, необходимо добавить файл с конфигурацией build-cache.json. Он помещается в корень папки common/config/rush.

/**  * Пример конфигурации build-cache.json  */ {   "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/build-cache.schema.json",    /**    * Для в включения функции кеширования параметр buildCacheEnabled должен иметь значение true    */   "buildCacheEnabled": true,    /**    * (Обязательный параметр) определяется где будет храниться результат сборки проекта    *    * Доступные значения: "local-only", "azure-blob-storage", "amazon-s3"    */   "cacheProvider": "local-only",     /**    * Переопределение параметра cacheEntryNamePattern позволяет изменить формат названия файлов с кэшом проектов. По дефолту добавляется только hash      */   //"cacheEntryNamePattern": "[projectName:normalize]-[phaseName:normalize]-[hash]"     /**    *  azureBlobStorageConfiguration необходимо добавить, если "cacheProvider"="azure-blob-storage"    */   "azureBlobStorageConfiguration": {     /**      * (Required) The name of the the Azure storage account to use for build cache.      */     // "storageAccountName": "example",      /**      * (Required) The name of the container in the Azure storage account to use for build cache.      */     // "storageContainerName": "my-container",      /**      * The Azure environment the storage account exists in. Defaults to AzurePublicCloud.      *      * Possible values: "AzurePublicCloud", "AzureChina", "AzureGermany", "AzureGovernment"      */     // "azureEnvironment": "AzurePublicCloud",      /**      * An optional prefix for cache item blob names.      */     // "blobPrefix": "my-prefix",      /**      * If set to true, allow writing to the cache. Defaults to false.      */     // "isCacheWriteAllowed": true   },    /**    * amazonS3Configuration необходимо добавить, если "cacheProvider"="amazon-s3"    */   "amazonS3Configuration": {     /**      * (Required unless s3Endpoint is specified) The name of the bucket to use for build cache.      * Example: "my-bucket"      */     // "s3Bucket": "my-bucket",      /**      * (Required unless s3Bucket is specified) The Amazon S3 endpoint of the bucket to use for build cache.      * This should not include any path; use the s3Prefix to set the path.      * Examples: "my-bucket.s3.us-east-2.amazonaws.com" or "http://localhost:9000"      */     // "s3Endpoint": "https://my-bucket.s3.us-east-2.amazonaws.com",      /**      * (Required) The Amazon S3 region of the bucket to use for build cache.      * Example: "us-east-1"      */     // "s3Region": "us-east-1",      /**      * An optional prefix ("folder") for cache items. It should not start with "/".      */     // "s3Prefix": "my-prefix",      /**      * If set to true, allow writing to the cache. Defaults to false.      */     // "isCacheWriteAllowed": true   } }

Чтобы включить запись кеша на локальный диск, необходимо добавить в конфигурацию build-cache.json только два параметра: buildCacheEnabled со значением true и cacheProvider со значением local-only. При таком варианте tar-архивы для каждого проекта после запуска команды rush build помещаются в папку common/temp/build-cache.

На момент написания статьи, помимо сохранения кеша в локальном хранилище, доступны ещё два варианта хранения в облачных контейнерах: Microsoft Azure blob storage container и Amazon S3 bucket. Для них необходимо передать в параметр cacheProvider значения azure-blob-storage или amazon-s3 соответственно, а также настройки для конфигурации облачного контейнера azureBlobStorageConfiguration либо amazonS3Configuration (смотрите конфигурацию выше).

Настройка параметров кеширования отдельно для каждого проекта

Если на этом этапе запустить команду rush build --verbose (при добавлении флага --verbose в консоли отображаются логи, которые обычно скрыты во время сборки), то появится предупреждение:

Project does not have a rush-project.json configuration file, or one provided by a rig,
so it does not support caching.

Чтобы избавиться от этого предупреждения, дополнительно помимо конфигурации build-cache.json нужно внутри каждого проекта настроить, какие папки и при вызове каких команд нужно закешировать. Для этого в папку config внутри каждого проекта (важный момент, не в папке common, а в каждом проекте) добавляется файл rush-project.json.

<your-project>/config/rush-project.json

{   "incrementalBuildIgnoredGlobs": ["temp/**"],    "disableBuildCacheForProject": false,  // при необходимости можно выключить кеширование для отдельных проектов    "operationSettings": [       {       "operationName": "build", // operationName — это название команда или фаза, которая вызывается в проекте        // Название папок верхнего уровня, которые необходимо закешировать. Например: lib, dist        "outputFolderNames": ["output-folder-1", "output-folder-2"]     },     {       "operationName": "_phase:build", //фазы - это еще одна интересная эксперементальная функция, см. Enabling phased builds         "outputFolderNames": ["output-folder-a", "output-folder-b"]     },     {       "operationName": "test",       "disableBuildCacheForOperation": true     }   ] }

Также этот файл будет полезен при настройке ещё одной интересной экспериментальной функции — phased builds. Она позволяет определить некоторые отдельные операции как фазы, которые можно выполнять параллельно в один момент времени. Например одновременный запуск rush build и rush test. Скажем, если сборка проекта A завершилась, а он находится в зависимостях проектов B и С, то сначала соберётся проект A, затем одновременно со сборкой проекта C и B начнётся запуск unit-тестов в A. Подробнее про это можно прочитать здесь. И кстати, включение кеширования — одно из обязательных условий для этой фичи.

После добавления файлов rush-project.json в проекты при запуске команды rush build --verbose результат сборки запишется в хранилище, а в консоли появится запись:

This project was not found in the build cache.

Caching build output folders: dist
Successfully set cache entry.

Время сборки 31 проекта при настроенном локальном хранилище: 6 минут 10,7 секунды.

При повторном запуске rush build проверяется наличие проекта в кеше. Если запись кеша есть, то существующие выходные папки удаляются, tar-архив из предыдущей сборки извлекается в папку проекта, а сборка пропускается. В результате в терминале появится запись:

Build cache hit.
Clearing cached folders: dist
Successfully restored output from the build cache.

Время повторной сборки: 1,44 секунды.

Заключение

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

Главный плюс кеширования, на мой взгляд, — это возможность встроить этот механизм в процесс CI (в случае использования облачного хранилища) и значительно его ускорить. Также в качестве плюса можно выделить получение возможности на основе кеширования настроить фазы сборок и тем самым усилить параллелизм, благодаря чему выиграть время при комбинировании запуска некоторых команд.