# Candy Tools ## Перед началом работы Все операции выполняются через запуск ``` candy [имя-команды] [...опции] ``` ## Имена основных команд: * `build` * `upgrade` * `dev-build` * `dev-build-server` * `build-server` * `localize` * `init-form` * `form-stats` ## `candy build` Основной сценарий: выполняет сборку форм в каталог с ресурсами. Действия, которые выполняет команда: * Получение движка форм версии указанной в `form.json`, * получение генератора форм версии указанной в `form.json`, * генерация и компиляция формы в каталог ресурсов, * создание файлов `{gfv}.metas.json` в каталоге ресурсов * копирование конвертеров в каталог ресурсов, * копирование схемы в каталог ресурсов. ### Опции * `--watch (-w)` Watch-режим. Выполняет сборку форм, а затем пересобирает при изменениях. В том числе движка, генератора и статических ресурсов. * `--clean` Полностью очищает целевой каталог ресурсов. Используется при полной сборке форм для продакшена * `--mode` Разделение сборок на продовую (mode=production) и не продовую (mode=development). По умолчанию development * `--upgrade-form-json` Форсирует изменение формата файла form.json на новый * `--build-cache` Задаёт режим использования кэша сборки. Возможные значения: disabled - не использовать кэш readonly - использовать кэш для сборки, но не обновляет его (значение по умолчанию) update - использовать кэш для сборки и презаписывать, если не совпадает force-update - всегда выполнять сборку и обновить значения в кэше Отключается при использовании watch-режима * `--use-last-stable-version` Устанавливает версию движка в файла `form.json` в последнюю стабильную версию. Аналогичен запуску candy-build с параметром -ge master * `--use-prerelease-version` Устанавливает версию движка в файла form.json в последнюю пререлизную версию в заданным preid. В файле версии генератора и движка будут установлены в pre:some-preid. * `--gfvs (-g)` Одна или несколько GFV или GFV-масок для пересборки. Может содержать значки `?` и `*`. * `--use-version-from-cache` Использовать версию движка и генератора из файловой системы * `--build-candy-widget` Собирать candy-виджет * `--development-mode` Используется только в режиме разработки cli. * `--verbose (-v)` Выводить отладочную информацию на консоль. ### Примеры использования ``` # Сборка формы 104816 candy build 104816 ``` ``` # Сборка все формы группы 1 candy build 1????? ``` ``` # Собрать форму 104816 и следить за изменениями candy build 104816 -w ``` ``` # Использовать последнюю пререлизную версию движка с preid=bso candy build 104816 --use-prerelease-version bso ``` ### Версионирование При сборке форм, учитывается версия движка и генератора указанные файле form.json. Версии могут указывать не на конкретную версию, а адресовать диапазон в соответствии с [semver](https://semver.org/lang/ru/). В этом случае будет выбрана последняя подходящая версия. Файл form.json должен выглядеть следующим образом: ``` { // Опционально "themes": ["имя-темы", ...], "dependencies": { "engine": "[версия-движка]", "generator": "[версия-генератора]" } } ``` `версия-движка`, `версия-генератора` - Соответственно, диапазоны версий. На данный момент всегда совпадают. Допустимые варианты версий: * Версия в формате [semver](https://semver.org/lang/ru/). * Версия с префиксом pre. Например, `pre:my-stange-branch-name`, где `my-stange-branch-name` - название предрелизной версии, выпускаемой разработчиками Candy, для предварительного выпуска форм. Версия с префиксом pre используются для движков, которые не являются стабильными и используются для предварительных сборок форм. ## `candy upgrade` Обновление формата форм или режима одной или нескольких форм. ### Опции * `--gfvs (-g)` Одна или несколько GFV или GFV-масок для обновления. * `--use-ci-build` Приготовить форму к сборке на CI, без необходимости локальной пересборки. * `--skip-pre-versions` При обновлении версий форм не обновлять формы с нестабильными версиями. * `--engine` Обновляет движок до заданной версии. Можно использовать кокретную версию движка (например, 0.4.82) или latest, для обновления до последней стабильной версии. * `--preid` Обновляет движок до последней пререлизной версии указанной в preid. * `--development-mode` Используется только в режиме разработки cli. * `--verbose (-v)` Выводить отладочную информацию на консоль. ### Примеры использования ### Перевод формы на сборку в CI Выполнить: ``` candy upgrade --use-ci-build 9900101 ``` Эта команда удалит и заигнорит генерируемые файлы в каталоге farm и поменит форму как собираемую на CI. После этого не требуется далть комиты в репозиторий resources. Обновлять версию движка формы надо командой: ``` candy upgrade --engine latest 9900101 ``` ## `candy dev-build` Выполняет сборку форм с ипользованием локальных исходников движка и генератора. ### **ВАЖНО** Эта команда собирает выполняет сборку форм в каталог ресурсов, но результаты сборки не являеются корректными для выкатывания в продакшен. ### Опции * `--watch (-w)` Watch-режим. Выполняет сборку форм, а затем пересобирает при изменениях. В том числе движка, генератора и статических ресурсов. * `--gfvs (-g)` Одна или несколько GFV или GFV-масок для пересобрки. * `--skip-generation (-n)` Не выполнять генарцию формы из сахара, будет выполняться только компиляция исходников формы из каталога форм. * `--skip-webpack` Не запускать компиляцию сгенерированного кода. Для отладки результатов генерации. * `--skip-engine` Не запускать сборку runtime-движка. Для отладки результатов генерации. * `--continue-on-error` Не генерирует код ошибки в случае ошибки при генерации или компиляции формы. * `--debug-only (-d)` Собирать только debug-сборки движка и форм. ВНИМАНИЕ: при работе в браузере необходимо использовать параметр ?debug=true * `--build-candy-widget` Собирать candy-виджет * `--development-mode` Используется только в режиме разработки cli. * `--verbose (-v)` Выводить отладочную информацию на консоль. ### Примеры использования ### Написание и просмотр форм В каталоге candy.farm запустить команды ``` candy build 123456 -w ``` ``` candy local-server ``` * Переход на url http://localhost:9080/123456/form -- создаст черновик и откроет редактор * Inner черновиков находится в каталоге candy.resources/.data ### Сборка формы для релиза ``` candy build 123456 ``` ### Переключение и сборка формы на использование последней стабильной ``` candy build 123456 --use-last-stable-version ``` Затем можно использовать пункт 'Написание и просмотр форм' ### Отладка форм с локальным движком В каталоге candy.farm запустить команды ``` candy dev-build 123456 -w ``` ``` candy local-server ``` * Переход на url http://localhost:9080/123456/form -- создаст черновик и откроет редактор * Inner черновиков находится в каталоге candy.resources/.data ### Разработка и отладка движка В этом случае удобно использовать сборку только отладочных скриптов. ``` candy dev-build 123456 --watch --debug-only ``` ``` candy local-server --redirect-to-debug-scripts ``` * Переход на url http://localhost:9080/123456/form -- создаст черновик и откроет редактор * Inner черновиков находится в каталоге candy.resources/.data ## `candy dev-build-server` Magic ### Опции * `--gfvs (-g)` Одна или несколько GFV или GFV-масок для пересобрки. * `--all-farm-dir (-a)` Позволяет передать массив путей до всех фармов candy, чтобы открывать из всех них формы. Путь передавать относительно candy * `--no-client-override` Отключает перехват client.js. В этом случае не будет работать отображение логов сборки и ожидания сборки формы. * `--debug-only (-d)` Собирать только debug-сборки движка и форм. ВНИМАНИЕ: при работе в браузере необходимо использовать параметр ?debug=true * `--development-mode` Используется только в режиме разработки cli. * `--verbose (-v)` Выводить отладочную информацию на консоль. ## `candy build-server` Magic ### Опции * `--gfvs (-g)` Опция устарела. Оставлена для обратной совместимости. * `--all-farm-dir (-a)` Позволяет передать массив путей до всех фармов candy, чтобы открывать из всех них формы. Путь передавать относительно candy * `--nightly` Включает сборку форм на движке nightly. * `--no-client-override` Отключает перехват client.js. В этом случае не будет работать отображение логов сборки и ожидания сборки формы. * `--debug-only (-d)` Собирать только debug-сборки движка и форм. ВНИМАНИЕ: при работе в браузере необходимо использовать параметр ?debug=true * `--development-mode` Используется только в режиме разработки cli. * `--verbose (-v)` Выводить отладочную информацию на консоль. ## `candy localize` Локализация формы. Подготавливает текстовые поля в сахаре для перевода и создает словарь ### Опции * `--gfv (-g)` GFV формы для локализации * `--dictionary-only (-d)` Создать словарь локализации без изменения сахара * `--use-local-generator-sources` Использовать исходный код генератора из локальной рабочей копии. Используется в режиме разработке. * `--development-mode` Используется только в режиме разработки cli. * `--verbose (-v)` Выводить отладочную информацию на консоль. ## `candy init-form` Создание заготовок для новых форм ### Опции * `--gfvs (-g)` Одна или несколько GFV для которых будет создана заготовка. * `--development-mode` Используется только в режиме разработки cli. * `--verbose (-v)` Выводить отладочную информацию на консоль. * `--hlrng` Копировать схему rng из highlander.farm. ## `candy form-stats` Выполняет сборку одной или нескольких форм. Подробнее: https://git.skbkontur.ru/forms/candy/-/blob/master/Tools/README.md#candy-form-stats ### Опции * `--gfvs (-g)` Одна или несколько GFV или GFV-масок для пересобрки. * `--by-engine` Показать статискиу пе версиям движка. * `--development-mode` Используется только в режиме разработки cli. * `--verbose (-v)` Выводить отладочную информацию на консоль.