@kontur.candy/tools v2.204.0

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.

• --no-reformat

  Отлючает форматирование генерируемого кода. Работает, только если версия генератора поддерживает эту опцию. Используется для ускорения сборки форм. (default: true)

• --gfvs (-g)

  Одна или несколько GFV или GFV-масок для пересборки. Может содержать значки ? и *.

• --use-version-from-cache

  Использовать версию движка и генератора из файловой системы

• --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. В этом случае будет выбрана последняя подходящая версия.

Файл form.json должен выглядеть следующим образом:

{
    // Опционально
    "themes": ["имя-темы", ...],
    "dependencies": {
        "engine": "[версия-движка]",
        "generator": "[версия-генератора]"
    }
}

версия-движка, версия-генератора - Соответственно, диапазоны версий. На данный момент всегда совпадают.

Допустимые варианты версий:

• Версия в формате semver.
• Версия с префиксом 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-движка. Для отладки результатов генерации.

• --no-reformat

  Отлючает форматирование генерируемого кода. Работает, только если версия генератора поддерживает эту опцию. Используется для ускорения сборки форм.

• --continue-on-error

  Не генерирует код ошибки в случае ошибки при генерации или компиляции формы.

• --debug-only (-d)

  Собирать только debug-сборки движка и форм. ВНИМАНИЕ: при работе в браузере необходимо использовать параметр ?debug=true

• --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. В этом случае не будет работать отображение логов сборки и ожидания сборки формы.

• --reformat (-r)

  Включает форматирование генерируемого кода. Работает, только если версия генератора поддерживает эту опцию. Используется для отладки и просмотра сгенерированных форм в отдадчике. (default: false)

• --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. В этом случае не будет работать отображение логов сборки и ожидания сборки формы.

• --reformat (-r)

  Включает форматирование генерируемого кода. Работает, только если версия генератора поддерживает эту опцию. Используется для отладки и просмотра сгенерированных форм в отдадчике. (default: false)

• --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/ke/candy-utils/blob/new-candy-tool-cli/README.md

Опции

• --gfvs (-g)

  Одна или несколько GFV или GFV-масок для пересобрки.

• --by-engine

  Показать статискиу пе версиям движка.

• --development-mode

  Используется только в режиме разработки cli.

• --verbose (-v)

  Выводить отладочную информацию на консоль.