- Колбешин Ф.А.
- Крылов М.А.
Builder - утилита для сборки клиентского кода проектов на платформе СБИС3. Сборка - процесс преобразования исходного кода в работающее приложение. Ответственны
Описаны в package.json. Запускаются из корневого каталога:
npm run <имя команды>
Перед любым запуском нужно выполнить
npm run fastInstall
Данная команда делает то же самое, что и "npm install", но выкачивает дополнительно через git платформенные репозитории, необходимые для работы шаблонизатора в билдере.
Т.к. в проекте есть .npmrc, то о флагах обычно можно не думать.
- build - основная задача сборки проекта. Запускает build:verify и build:only. Артефакты: папка dest (готовый builder для SDK), файл eslint-report.log (отчёт ESLint только об ошибках), xunit.log и xunit-result.xml (резултьтат тестирования)
- build:only - копирует нужные исходники в папку dest и устанавливает зависимости.
- build:verify - проверка кода через ESLint(build:lint) и юнит тесты(build:test). Артефакты: файл eslint-report.log, xunit.log и xunit-result.xml.
- test - запустить юнит тесты.
- test:coverage - узнать % покрытия кода юниттестами. Артефакт: файл отчёта coverage/index.html.
- lint - запустить ESLint. Если ESLint упал - точно будут проблемы при сборке. Варнинги можно игнорировать, но лучше поправить.
- lint:fix - запустить ESLint с флагом --fix. Поправит самые простые ошибки.
- lint:errors - выведет только ошибки, что уронят сборку.
Флаг --legacy-bundling нужен для корректной установки зависимостей пакета sbis3-json-generator.
package-lock.json нужен для фиксации конкретных версий пакетов для всего дерева зависимостей. Это нужно для:
- Повторяемой сборки
- Безопасности при обновлении минорных пакетов в глубине дерева зависимостей.
- Быстрой установки зависимости через "npm ci" (NPM 6+)
Основная задача сборки статики проекта.
Выполнить из папки builder'а:
node ./node_modules/gulp/bin/gulp.js --gulpfile ./gulpfile.js build --config=custom_config.json
Где custom_config.json - путь до JSON конфигурации в формате:
{
"cache": "путь до папки с кешем",
"output": "путь до папки с ресурсами статики стенда",
"localization": ["ru-RU", "en-US"] | false, //опционально. список локализаций
"default-localization": "ru-RU", //опционально, если нет "localization"
"logs": "путь до папки для записи логов", //опционально, используется для записи builder_report.json
"multi-service": false|true, //опционально. по умолчанию false. Собираем один сервис или несколько. От этого зависит будем ли мы менять константы в статических html и пакетах.
"url-service-path": "путь до текущего сервиса", //опционально. по умолчанию "/"
"typescript": true|false, //опционально, по умолчанию false. Задача компиляции TypeScript в модули AMD-формата.
"modules": [ //сортированный по графу зависимостей список модулей
{
"name": "имя модуля",
"path": "путь до папки модуля",
"responsible": "ответственный",
"preload_urls": ["url1", "url2"]
}
]
}
После сборки в папке с кешем создаётся файл "last_build_gulp_config.json" - копия последнего оригинального файла конфигурации.
Компиляция typescript в модули AMD-формата.
Принимаемые значения: false/true
Значение по умолчанию: false.
Для набора исходников(на примере модуля Data)результат работы сборщика будет иметь вид:
Компиляция less в css.
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере Controls/Button)результат работы сборщика будет иметь вид:
Генерация базовых мета-файлов сборщика, необходимых для работы Сервиса Представлений:
- "navigation-modules.json" -набор модулей для Серверного конфигурирования правого аккордеона
- "routes-info.json" -информация для работы роутинга на Сервисе Представлений
- "static_templates.json" -информация для корректной отдачи статических html в Сервисе Представлений
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере модуля Data)результат работы сборщика будет иметь вид:
Генерация мета-файла contents.json, необходимого для работы приложения.
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере модуля Data)результат работы сборщика будет иметь вид:
Генерация архивированных версий для каждого файла статики (для раздачи Диспетчером). Архивированные версии файла будут созданы только для минифицированных исходников(результат работы флага "minimize")
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере модуля WS.Core) результат работы сборщика будет иметь вид:
Сборка статических html, задаваемых через механизм webPage.
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере PersonalCertificates)результат работы сборщика будет иметь вид:
Cборка статических html на VDOM.
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере TestPlatform/TestsPlatform/File/Page)результат работы сборщика будет иметь вид:
Минификация модулей AMD-формата.
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере Controls/Application/TouchDetector) результат работы сборщика будет иметь вид:
Компиляция динамических(tmpl, wml) шаблонов.
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере Controls/Application/TouchDetector) результат работы сборщика будет иметь вид:
.min.wml содержит скомпилированный и минифицированный шаблон.
Компиляция динамических устаревших шаблонов xhtml.
Принимаемые значения: false/true.
Значение по умолчанию: false.
Результат работы сборщика аналогичен опции wml.
Упаковка вместе с компонентов его собственных шаблонных зависимостей.
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере Controls/Tabs)результат работы сборщика будет иметь вид:
.min.js содержит компонент с запакованными в него собственными шаблонными зависимостями.
.min.original.js содержит оригинальное содержимое компонента до паковки.\
Паковка статических html-страниц. Выполняется по аналогии с runtime-паковкой на Сервисе Представлений(rtpackage)
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере PersonalCertificates) результат работы сборщика будет иметь вид:
static_packages содержит пакеты для каждой построенной статической html.\
Паковка по созданной разработчиком пользовательской конфигурации - файл формата package.json
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере модуля WS.Core)результат работы сборщика будет иметь вид:
Генерация дерева AMD-зависимостей.\ Где используется:
- runtime паковка на Сервисе Представлений(rtpackage).
- Работа Chrome-плагина по анализу зависимостей SBIS Denendency Tree.
Принимаемые значения: false/true.
Значение по умолчанию: false.
Для набора исходников(на примере модуля WS.Core) результат работы сборщика будет иметь вид:
Копируем исходный код файлов в конечную директорию.
Принимаемые значения: false/true.
Значение по умолчанию: true.
Для набора исходников(на примере модуля View) результат работы сборщика будет иметь следующий вид:
Флаг установлен в значение false:
Флаг установлен в значение true:
Создаём символические ссылки для исходного кода проекта.
Принимаемые значения: false/true.
Значение по умолчанию: true.
Для набора исходников(на примере модуля Types) результат работы сборщика будет иметь следующий вид:
Флаг установлен в значение false:
Флаг установлен в значение true:
Создаём sourceMaps для ts/js/wml/tmpl/xhtml файлов. Примечание: sourceMaps на текущем этапе создаются только для минифицированного кода:
Принимаемые значения: false/true.
Значение по умолчанию: false.
Флаг установлен в значение false:
Флаг установлен в значение true:
Выполнение в сборке проекта команды компилятора typescript - tsc с флагом --noEmit
(компиляция typescript без сохранения результатов компиляции - для выявления ошибок в typescript-исходниках вашего проекта)
Принимаемые значения: false/true.
Значение по умолчанию: false.\
Адрес сервера статики, для которого сборщик сформирует POST-запрос со списком всех измененных
файлов в рамках текущего проекта.
Принимаемые значения: адрес хоста в виде строки. Пример: "localhost:8080".
Значение по умолчанию: false.\
Указывает сборщику, нужно ли проверять gulp_config на совместимость с текущим
кэшем сборки. При несовместимости весь кеш будет сброшен.
Принимаемые значения: false/true.
Значение по умолчанию: true.\
С помощью этого флага можно задать, какие темы надо собирать в рамках текущего проекта.
Пример:
Флаг themes: ["default__dark"] указывает билдеру, что во всех Интерфейсных модулях с темой
default нужно собрать только less внутри директории dark.
Флаг themes: ["default"] указывает билдеру, что во всех Интерфейсных модулях с темой
default нужно собрать все less.
Флаг themes: true указывает билдеру, что нужно собрать все less во всех Интерфейсных модулях
во всех темах.
Принимаемые значения: false/true/[<список тем, включая их модификаторы>].
Значение по умолчанию: true.\
Задача по обновлению одного файла в развёрнутом локальном стенде. Обычно вызывается из WebStorm.
Выполнить из папки builder'а:
node ./node_modules/gulp/bin/gulp.js --gulpfile ./gulpfile.js buildOnChange --config=last_build_gulp_config.json --filePath="FilePath"
Где last_build_gulp_config.json - путь до JSON конфигурации последней сборки, FilePath - файл который мы хотим обновить.
Задача по запуску typescript для модулей, описанных в gulp_config.
Выполнить из папки builder'а:
node ./node_modules/gulp/bin/gulp.js --gulpfile ./gulpfile.js runTypescript --config=gulp_config.json
Где gulp_config.json - путь до JSON конфигурации сборки, используемой в основной задаче сборки "build"
Задача сборa фраз для локализации статики. Нужно для genie.sbis.ru и wi.sbis.ru.
Выполнить из папки builder'а:
node ./node_modules/gulp/bin/gulp.js --gulpfile ./gulpfile.js collectWordsForLocalization --config=custom_config.json
Где custom_config.json - путь до JSON конфигурации в формате:
{
"cache": "путь до папки с кешем",
"output": "путь до результирующего json файла",
"modules": [{ //сортированный по графу зависимостей список модулей
"name": "имя модуля",
"path": "путь до папки модуля",
"responsible": "ответственный"
}]
}
Builder тестируем через модульные тесты с помощью mocha и chai. Для локальной отладки тестов нужно настроить среду разработки на запуск mochа в папке test. Нужно обязательно указать параметр "--timeout 600000". Такой огромный таймаут нужен по двум причинам:
- тесты на MacOS идут дольше, чем на windows и centos
- интеграционные тесты тоже пишем в терминах mocha. Возможно, это не совсем корректно и нужно переделать.
Стандарт разработки на JavaScript описан тут.
Чтобы эти требования соблюдались, написан конфиг для ESLint - файл ".eslintrc" в корне проекта. В конфиге нулевая толерантность к несоответствию style guide. Причины описаны тут и тут
Также не пренебрегайте функцией Inspect Code в WebStorm.
Логирование и вывод ошибок осуществляется через универсальный логгер: sbis3-builder/lib/logger.js Пример использования:
const logger = require('./lib/logger').logger();
logger.debug('Сообщение не будет видно пользователям, но будет в логах');
logger.info('Сообщение будет видно пользователям и будет в логах');
logger.warning('Текст предупреждения');
logger.error('Текст ошибки');
logger.error({ //аналогично можно вызывать logger.warning.
message: 'Текст ошибки', //если не задать, то будет выведено error.message
filePath: filePath, //полный путь до файла, крайне желательно
moduleInfo: moduleInfo, // экземпляр класса ModuleInfo, если есть. актуально для Gulp.
error: error //пойманное исключение, если есть
});
Вывод сообщений уровня debug включается при запуске утилиты с флагом -LLLL. Побробнее тут.
При запуске утилиты с флагом --log-level можно настроить уровень логгирования:
- info - выводить все сообщения, предупреждения и ошибки при работе утилиты.
- warning - выводить предупреждения и ошибки при работе утилиты.
- error - выводить только ошибки при работе утилиты.
По умолчанию выставляется уровень логгирования info. Пример запуска с логгированием исключительно ошибок:
node ./node_modules/gulp/bin/gulp.js --gulpfile=./gulpfile.js build --config=custom_config.json --log-level=error
После сборки записывается builder_report.json - отчёт об ошибках и предупреждениях сборки для автоматизации оформления ошибок в системе CI/CD. Флаг --log-level не влияет на builder_report.json, он будет содержать в себе все предупреждения и ошибки независимо от значения флага --log-level.
Также при работе Gulp записывает результаты работы каждого своего шага. Пример:
[12:32:33] Using gulpfile ~/work/repos/saby/Builder/gulpfile.js
[12:32:33] Starting 'build'...
..............................
[12:32:35] Finished 'build' after 1.56 s
Чтобы выключить запись таких логов, выполняйте запуск утилиты с флагом --silent.
"sbis3-builder": "git+https://git.sbis.ru/saby/Builder.git#rc-20.1000"
P.S. не забывайте об актуализации ветки Builder, обновлять её необходимо вручную.
3) Создайте в корне проекта файл builder.json. Это конфигурационный файл, по которому Builder будет собирать ваш проект.
Стандартная конфигурация имеет вид:
{
"cache": <путь до директории с кэшем сборщика>,
"output": <путь до директории с результатом сборки>,
"logs": <путь до папки с логами сборки>,
"modules": [
{
"name": <ммя интерфейсного модуля>,
"path": <путь до интерфейсного модуля>
}
]
}
Остаётся добавить нужные для решения ваших задач флаги Builder. Пример: при задании подобной конфигурации для сборки
{
"cache": ./.builder/cache,
"output": ./application,
"logs": ./.builder/logs,
"typescript": true,
"modules": [
{
"name": "Types",
"path": "./node_modules/saby-types/Types"
}
]
}
будет собран весь TypeScript-код интерфейсного модуля Types. Пример задания builder.json смотрите также здесь
node node_modules/gulp/bin/gulp build --gulpfile=gulpfile.js --config=../../builder.json
Примечание 1: Путь до builder.json необходимо указывать относительно директории npm-пакета sbis3-builder
Примечание 2: выполнять данную команду необходимо в корне вашего проекта.
Примечание 3: Чтобы каждый раз не выполнять длинную команду для Builder, вы можете описать её один раз в виде npm-скрипта
"build": "node node_modules/gulp/bin/gulp build --gulpfile=gulpfile.js --config=../../builder.json"
Пример подобного задания можете посмотреть здесь.