Шаблон молча не сработал: диагностика

Обновлено 5 ноября 2026

Самый частый вопрос — «я создал шаблон, запустил настройку, а файла нет». Шаблоны почти никогда не «ошибаются молча»: они просто не попадают в выборку. Ниже — причины в порядке убывания частоты, каждая с проверкой.

1. Неправильно названа директория события

Директория первого уровня обязана иметь заголовок с переменной действия — в файле .calculate_directory, например # Calculate append=skip env=install ac_install_merge==on. Сама же директория может называться как угодно: merge, xyz или 2_ac_install_merge наложение не различает, «похожих имён» утилиты не ищут и ничего не угадывают. Без переменной действия поддерево не применяется — в подробном выводе появится Пропущенные директории. Соглашение N_ac_<действие> нужно для другого: директории обходятся в лексикографическом порядке, поэтому номер в начале имени задаёт очерёдность наложения.

Проверка: сравните с фактическим набором в /var/db/repos/calculate/profiles/templates/ (см. карту событий).

2. На директории или файле первого уровня нет переменной действия

Для пользовательского слоя (/var/calculate/templates) правило жёсткое: каждый элемент первого уровня — и директория, и файл — должен иметь в заголовке переменную действия (ac_*) или cl_name==. Если её нет, поддерево пропускается, а процесс настройки помечается как неудачный; в подробном выводе вы увидите перечисление «Skipped templates» и подсказку про заголовок вида # Calculate ac_install_merge==on.

Деревья в репозиториях (/var/db/repos/…) из этого правила исключены — там env= и действие задаются на уровне директории события.

Двоичные файлы на первом уровне не допускаются в любом случае.

3. Не указано нужное условие действия

Классика: шаблон лежит в правильной директории, но в заголовке нет env=install ac_install_merge==on — и наоборот, есть условие ac_desktop_profile==on, а вы запускаете настройку пакета.

Проверьте значения переменных того запуска:

Переменные действия лежат в модуле install, поэтому без префикса cl-variable их не находит и отвечает Не найдена переменная. Пустая строка в ответе означает, что переменная определена, но значения не имеет (например, cl_merge_pkg вне настройки пакета).

4. Шаблон привязан к пакету, который сейчас не настраивается

Условия mergepkg(<категория>/<пакет>)!=, merge(...)!=, pkg(...)!= — это фильтры по пакету. Они истинны, если пакет настраивается сейчас или числится в кэше настройки:

/var/lib/calculate/calculate-core/cache/merge-setup.list   # настройка пакета
/var/lib/calculate/calculate-core/cache/merge-patch.list   # патчи

Отсюда две неочевидности. Первая: шаблон, привязанный к неустановленному пакету, не применится никогда — он сработает при первой установке этого пакета. Вторая: mergepkg() без аргументов берёт категорию и имя пакета из пути (<категория>/<пакет>/…), так что неверно названная директория пакета даёт тихо неработающий шаблон.

Имена пакетов в этих условиях можно проверить заранее, не запуская наложение: cl-check-templates (пакет sys-apps/calculate-toolkit, ставится в /usr/sbin/cl-check-templates) разбирает условия pkg() и merge() — а с ними и mergepkg() — и сверяет указанные пакеты с репозиториями и базой установленных пакетов, учитывая переименования. Опечатка в имени пакета — это не «шаблон не подошёл», а «никогда не подойдёт».

Проверка: запустите настройку именно этого пакета и смотрите подробный вывод:

В нём перечисляются применённые шаблоны и ошибки по каждому файлу.

5. Не указан доступный модуль переменных

Параметр env=<модуль> подключает переменные соответствующего пакета утилит. Если модуля в системе нет, шаблон пропускается без сообщения об ошибке. Признак: в cl-variable переменная не определена. То же касается условий по ini(...): они читают стек ini.env, и если нужной секции нет ни в одном слое — условие ложно. Многие «выключаемые» шаблоны в оверлеях устроены именно так: они помечены как выключенные и ждут, что администратор включит их значением в ini.env.

6. Ошибка в самом шаблоне

• incorrect header parameter: '<имя>' — параметр заголовка не существует для файла или директории (напомню: у директории набор параметров заметно короче);
• function of templates '<имя>' not found — в заголовке или теле использована функция, которой нет ни среди встроенных, ни среди функций оверлея: шаблон прерывается;
• Failed to apply custom function … — функция из scripts/functions вернула ошибку: подстановка станет пустой, шаблон применится, но «не туда»;
• Wrong option 'append=<значение>' in template <файл> — для patch и «исполняемых» форматов (diff, dconf, contents, sqlite, backgrounds) способ объединения обязан быть patch;
• Wrong value '<x>' in the template — некорректное значение параметра (например, относительный path=).

Как посмотреть, что создаст шаблон

Не дожидаясь реальной настройки системы, можно направить результаты в каталог: --pkg-path задаёт корневой путь для сохранённых конфигурационных файлов.

 * Конфигурация утилитами Calculate системных настроек baselayout ...
 * Утилиты Calculate изменили файлы:
 *      /tmp/clt-preview/etc/profile.d/editor.sh
 *      /tmp/clt-preview/etc/os-release

Настоящие файлы при этом не изменяются — проверьте ls -l /etc/profile.d/editor.sh. Это удобный способ посмотреть, что именно получится из вашего шаблона, включая служебный заголовок и раскладку по директориям.

Полезно заодно убедиться, что шаблон не создаёт лишних директорий: сравнив вывод find /tmp/clt-preview с ожиданиями. Директория-шаблон без .calculate_directory появляется в результате как реальная директория — если её быть не должно, добавьте в неё # Calculate append=skip. У директории первого уровня в /var/calculate/templates к этому добавляется ещё одно требование: в её заголовке обязана быть переменная действия, иначе молча пропустится всё поддерево (в подробном выводе — Пропущенные директории).

Порядок действий, если ничего не помогло

1. --pkg-path + -v: видите файл в результате — проблема не в шаблоне, а в выборке (пункты 1–5).
2. Уберите из заголовка все условия кроме env=install ac_install_merge==on и проверьте ещё раз: если заработало, «виновато» одно из снятых условий — возвращайте по одному.

3. Сравните с рабочим аналогом: в дереве calculate почти для любого пакета есть готовый шаблон; искать так:

   grep -rl 'format=kde' /var/db/repos/calculate/profiles/templates | head

См. также

• Кто и когда налагает шаблоны
• Переменные шаблонов
• Синтаксис шаблона