spt3

Описание работы с spt3

Общие понятия

spt3 представляет собой инструмент для создания решений на базе некоего репозитория (Sisyphus).

Механизм работы spt прост - в некоей рабочей директории (изначально чистой), создается профиль - директория с описаниями того, как и что собирать. Профиль включает в себя файл рецепта (recipe) - инструкции по сборке, выполняя которые пошагово, можно получить желаемый результат, а также все вспомогательные файлы, требующиеся для сборки. Шаги сборки (см. ниже - tasks) - маленькие скрипты, каждый из которых, в соответствии с общепринятым в Unix подходом, делает всего одну вещь. После того, как профиль готов, сама сборка выполяется запуском одной утилиты spt, которая выполняет по очереди все шаги, вызывая каждый из них с нужными опциями.

Примеры возможных рецептов

Примеры профилей можно найти в приложении к пакету [указано название]:

Live CD [live-cd] = развернутый образ + скрипты, исправляющие загрузку с readonly root и remount unionfs (механизм remounttab) + загрузчик + сворачивание в ISO.
Инсталляционный диск [installer] = развернутый образ мини-системы с инсталлятором + скрипты, исправляющие загрузку этой мини-системы и автоматический запуск инсталлятора + свернуть это все в squashfs + добавление на диск репозитория пакетов + загрузчик + сворачивание в ISO.
Инсталляционный диск "как Ubuntu" = Live CD + внутрь ставится пакет с инсталлятором.
Образ виртуального сервера для ovz = развернутый образ с нужным набором пакетов.
Ручная инсталляция системы [live-cd-manual-installer] = образ + установка fstab, lilo.conf, initrd + свертка в tarball + перенесение tarball на target-машину + распаковка там + прописывание загрузчика.
Тонкий клиент для загрузки по сети (appliance) = развернутый образ + загрузка с remounttab + загрузчик + некоторые части загрузчика подготавливаются для раскладывания в другие места, в частности, ядро и init на tftp-сервер.

Quickstart

Сделать чистую директорию и перейти туда (например, work).
Скопировать туда любой из понравившихся профилей из /usr/share/doc/spt3*/profiles/ как поддиректорию work/profile. При необходимости - доработать профиль под свои задачи.
Выполнить команду spt3.
Результат можно забрать в work/chroot, work/out и work/*.iso - в зависимости от того, что нужно.

Пример:

mkdir work
cd work
cp -r /usr/share/doc/spt3*/profiles/live-cd profile
spt3

Терминология

Рабочая директория или $work_dir - некая чистая директория, в которой будет производиться процесс сборки решения. Перед сборкой в нее должен быть помещена поддиректория profile с профилем - либо создана с нуля, либо скопирована из прилагаемых к пакету примеров. Профиль может донастраиваться под нужды пользователя
Профиль или profile - поддиректория в рабочей директории, содержащая сведения о том, что и как собирать.
Рецепт или recipe - файл в директории профиля ($work_dir/profile), описывающий процесс сборки путем перечисления некоего количество минимальных шагов сборки и, возможно, указания их опций.
task - такой минимальный шаг сборки; физически представляет собой небольшой скрипт, называющийся с spt- и лежащий в /usr/bin; в процессе полной сборки они вызываются автоматически по директивам из recipe - но возможен и их ручной вызов.
chroot - директория $work_dir/chroot, в которую распаковывается рабочий chroot системы.

Утилиты

spt3

Утилита spt3 прогоняет последовательно инструкции, записанные в файле recipe, запуская соответствующие им tasks с правильными опциями и т.п., отслеживает процесс выполнения или невыполнения каждого из task'ов и выводит в логи заметные (начинающеся с =====) записи о прогонке или ошибке на очередном этапе.

spt-deploy-lilo

Утилита spt-deploy-lilo предназначена для установки образа системы на жесткий диск (или иной загрузочный носитель) и настройки его загрузки с помощью LILO. Подразумевается, что эта часть инсталляции выполняется с правами root на той же машине, на которой потом с этого жесткого диска будут загружаться.

Вход:

TARBALL - указание на tarball с образом системы, полученный после упаковки chroot'а с помощь spt-pack-tarball. В случае, если этот параметр опущен, распаковки tarball'а проводиться не будет, будет просто настроена загрузка с помощью LILO. К образу систему предъявляются следующие требования:
- Установленный пакет lilo;
- Файл /etc/fstab, корректно созданный заранее с указанием как минимум точки монтирования корневого раздела;
- Файл /etc/lilo.conf, корректно созданный заранее с записью о том ядре или ядрах, которые предполагается загружать и устройствах, куда прописывать загрузчик;
ROOT_MOUNT - путь, куда примонтирована файловая система, которая будет / в новой системе. Файловая система должна совпадать с той, что указана в /etc/fstab в образе.
COMPRESSION - если способ сжатия tarball'а не может быть определен по расширению файлы (.tar.bz2 или .tar.gz), то в этом параметре можно указать опцию декомпрессии tar (-z для gzip или -j для bzip2).

Опции

Все tasks получают на вход некий набор опций (в виде имя=значение). Эти опции могут быть определены в следующих местах (места расположены в порядке перекрытия значений опций - в случае задания опций в нескольких местах, используется значение указанное в месте ниже по списку):

Конфигурационный файл пользователя ($HOME/.sptrc);
Конфигурационный файл профиля ($work_dir/profile/config);
Опции командной строки -o;

Специальные опции

Среди опций выделяется одна центральная и обязательная опция - это положение рабочей директории (work_dir). Она, очевидно, не может быть задана в файле конфигурации, зато может быть:

Задана из командной строки опцией -w;
Угадана, если текущая директория - рабочая или находится где-то внутри рабочей.

Кроме того, есть еще 2 опции, которые действуют на все task'и:

verbose [по умолчанию: пустое] - вывод большого количества отладочной информации при сборке образа (в случае, если verbose=-v).
quiet [по умолчанию: пустое] - сокращение вывода отладочной информации при сборке (при quiet=-q).

Эти 3 опции доступны везде и везде ниже это больше особо оговариваться не будет.

Глобальные опции

Опции, общие для создаваемого решения (т.е. такие, которые должны быть одинаковыми во всех task'ах), удобнее всего определять в файле $work_dir/profile/config. Рекомендуется определять следующие глобальные опции:

ARCH - архитектура конечного продукта. Пока возможны значения i586 и x86_64. На сборочной машине i586 возможно собирать решения только для i586, на x86_64 - для i586 и x86_64.
PUBLISHER
ORIGIN
SUITE
LABEL
CODENAME
VERSION
REPO
DESIGN
THEME
LANGS

Эти и остальные опции, относящиеся к определенным task'ам, описаны в соответствующих разделах task'ов.

Tasks

spt-clean

Корректно очищает в рабочей директории все наработки, кроме директории profile. Рекомендуется выполнять как аналог "make clean" перед полной пересборкой.

Вход: никакого. Выход: удаляется все, кроме $work_dir/profile.

spt-init-chroot

Инициализирует рабочую директорию, создавая в ней служебные поддиректории для работы hasher.

Вход:

ARCH
REPO
LANGS
apt_config
apt_prefix

Выход:

служебные директории в рабочей директории
- profile – директория с профилем?.
- aptbox – aptbox hasher, место, в котором работает apt, куда копируется его конфигурация из сборочной системы и в дальнейшем apt использует /etc и /var из этого aptbox.
- cache – кэш инсталлированных / скаченных пакетов hasher; нужен для сборок с пакетной базой на ftp.
- chroot – место, где будет строиться реальный root распаковываемой системы.
- out – место, куда будет положен результирующий продукт(ы) – как правило, это сжатые образы.
- tmp – временная директория.
минимальный chroot в $work_dir/chroot

spt-make-chroot

Распаковывает в инициализированный chroot пакеты по списку из файла packages в директории профиля (можно использовать другой файл, задав его имя опцией).

Вход:

рабочая директория с развернутой инфраструктурой (т.е. выполненным spt-init-chroot).
packages [по умолчанию: $work_dir/profile/packages] - указание на файл со списком пакетов, которые надо поставить; в файле допускается комментировать строчки символом #.
excludedocs - если установлена в --excludedocs, то файлы с документацией не ставятся.

Выход:

корректно распакованные пакеты в chroot, выполнены post-install scripts от этих пакетов.

spt-create-repo

Создает в $out_dir репозиторий с названием IDENT с индексами с пакетами по списку из файла $IDENT.packages.

Вход:

рабочая директория с развернутой инфраструктурой (т.е. выполненным spt-init-chroot).
packages [по умолчанию: $work_dir/profile/packages] - указание на файл со списком пакетов, которые надо поставить; в файле допускается комментировать строчки символом #.

Выход:

корректно распакованные пакеты в chroot, выполнены post-install scripts от этих пакетов.

spt-run-scripts

Запускает некие произвольные скрипты в созданном chroot'е. Как правило, используется для первоначальной настройки окружения в свежей системе - добавления пользователей, создания групп, установки локалей и т.п. Для LiveCD там же создается remounttab и т.п.

Вход:

рабочая директория с развернутыми пакетами в chroot'е (т.е. выполненным spt-make-chroot).
setup_dir [по умолчанию: $work_dir/profile/setup.d] - директория со скриптами; все скрипты оттуда выполняются по очереди. Порядок очередности - тот, в которым эти скрипты выводит globbing из shell (т.е., например, команда echo *). По умолчанию - это алфавитный порядок названий. Таким образом, очередность запуска скриптов удобно обычно регулировать (как и в SysVinit-скриптах) добавлением префиксов с 2 цифрами к их именам файлов, например, 01users, 02services, 03autologin и т.п.

Выход:

рабочая директория с развернутыми пакетами, над которыми произведены некие действия (как правило, первоначальная настройка окружения).

Семейство spt-copy-files

Семейство скриптов spt-copy-files занимается простым подкладыванием (копированием) заранее подготовленных файлов в различные каталоги в процессе сборки.

spt-copy-files-to-chroot

Копирует файлы из from в каталог to внутри chroot. Файлы перемещаются без головного каталога from, т.е. копируется именно его содержимое. По умолчанию to равен /, что означает копирование в корень chroot, что позволяет создавать в каталоге from дерево с обычными каталогами bin/, lib/, usr/ и т.п. и ожидать, что они правильно разложатся в chroot.

Вход:

chroot
from [по умолчанию: $work_dir/profile/files.d] - директория с файлами, которые нужно скопировать.
to [по умолчанию: /] - директория внутри chroot, куда нужно переместить файлы.

Выход:

chroot со скопированными файлами.

spt-copy-files-to-out

Копирует файлы из from в каталог to внутри $out_dir (выходного каталога, который будет упакован прямо в ISO). Файлы перемещаются без головного каталога from, т.е. копируется именно его содержимое. По умолчанию to равен /, что означает копирование в корень образа ISO.

Вход:

$out_dir
from [по умолчанию: $work_dir/profile/files.d] - директория с файлами, которые нужно скопировать.
to [по умолчанию: /] - директория внутри $out_dir, куда нужно переместить файлы.

Выход:

$out_dir со скопированными файлами.

Семейство spt-boot

Семейство скриптов spt-boot устанавливает/конфигурирует каким-то образом загрузчики, которые могут быть использованы для загрузки того образа, который собирался на предыдущих этапах.

spt-boot-propagator

Сложный скрипт, который подготавливает содержимое chroot к загрузке с помощью цепочки (syslinux / isolinux / pxelinux) - propagator.

Вход:

chroot;
profile/initfs.in - файл, перечисляющий содержимое initrd с propagator;
profile/modules - файл, перечисляющий модули ядра, которые войдут на initrd к propagator;
profile/isolinux.in и profile/syslinux.in - файлы конфигурации isolinux (и syslinux);

Выход:

Заполненная директория $out_dir/isolinux, где подготовлены конфигурационные файлы isolinux, а также ядро (vmlinuz) и initrd (full.cz) для загрузки.

spt-boot-gfxboot

Настраивает gfxboot для работы в загрузчике isolinux.

Вход:

chroot, в котором установлен пакет design-bootloader-$THEME.
THEME - указание на каталог в /usr/share/gfxboot/$THEME, в котором лежит графическая тема gfxboot.

Выход:

Настройки для isolinux/syslinux в $out_dir/isolinux в виде файла $out_dir/isolinux/bootlogo.

spt-boot-splash

Настраивает bootsplash для работы в загрузчике isolinux и в процессе загрузки системы.

Вход:

chroot, в котором установлен пакет design-bootsplash-$THEME.
THEME - указание на каталог в /usr/share/gfxboot/$THEME, в котором лежит графическая тема gfxboot.

Выход:

Настройки для isolinux/syslinux в $out_dir/isolinux, где подготовлены установленные файлы вида *.spl, по одному на поддерживаемое разрешение экрана.

Семейство spt-pack

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

spt-pack-squashfs

Упаковывает chroot в образ squashfs.

Вход: chroot Выход: $out_dir/altlinux - файл с образом

spt-pack-tarball

Упаковывать chroot в tarball.

Вход:

chroot
COMPRESSION [по умолчанию: пусто] - указание сжать образ - может быть пустым (никакой компрессии), gzip или bzip2.

Выход: $out_dir/image.tar[.gzip|.bz2] - файл с образом

spt-pack-cpio

Упаковывать chroot в архив cpio. Возможно сжатие получающегося архива.

Вход:

chroot
COMPRESSION [по умолчанию: пусто] - указание сжать образ - может быть пустым (никакой компрессии), gzip или bzip2.

Выход: $out_dir/image.cpio[.gzip|.bz2] - файл с образом

spt-pack-iso

Упаковывает out в образ загрузочного CD iso9660. Предполагается, что в каталоге isolinux создана инфраструктура для загрузчика.

Вход: содержимое $out_dir. Выход: ISO-файл CDFILENAME [по умолчанию: livecd.iso] в директории $work_dir.

Troubleshooting

Сборка любых комплексных решений - сложный процесс и всегда есть вероятность какой-то ошибки - например, как-то не так исправили профиль и т.п. Сам spt3 пытается прилагать максимум усилий к диагностированию подобных вещей (хотя бы к тому, чтобы ошибка была обнаружена на стадии сборки, а не после загрузки собранного образа), но, к сожалению, далеко не все ситуации легко диагностируются. Ниже представлены наиболее типовые симптомы и наиболее вероятные решения.

Симптом: образ с propagator собирается, но не загружается: при попытке propagator'ом грузить хотя бы обязательные модули IDE / CDROM / USB - в консолях 3 и 4 видны сообщения о попытке загрузке модуля и unknown symbol Проблема: файл зависимостей - modules.dep - генерируется неправильно. Решение: разбираться с вызовом mkmar; в частности, обязательно нужно наличие параметра -r /.

Примеры использования SPT3

Создание загрузочного USB Flash диска