forked from altcloud/mkimage-profiles
full-view docs update
- toplevel README received some long-needed refactoring
+ lowlevel detail moved, well, to lowlevel READMEs
- reflected more thoroughly that m-p is not about distros anymore
- dropped features.in/00example/README.en: it's already out-of-date
a bit, and there's no perceived need in thorough English docs so far
- wiki article got split into parts and somewhat rewritten, links updated
- mv doc/{CodingStyle,style.txt}
This commit is contained in:
Michael Shigorin
parent
73f676f92c
commit
ddf0c5b7c7
@ -30,4 +30,4 @@ $ make distro/icewm.iso
|
||||
- http://www.altlinux.org/tmpfs
|
||||
- http://www.altlinux.org/hasher
|
||||
- http://www.altlinux.org/mkimage
|
||||
- http://www.altlinux.org/Mkimage/Profiles/next
|
||||
- http://www.altlinux.org/Mkimage/Profiles/m-p
|
||||
|
||||
57
README
57
README
@ -8,15 +8,16 @@ see doc/profiles.mk.sample and libdistro.mk
|
||||
|
||||
License: GPLv2+, see COPYING.
|
||||
|
||||
Most docs in Russian, welcome to learn it or ask for English.
|
||||
См. тж. http://www.altlinux.org/Mkimage/Profiles/next
|
||||
Most docs are in Russian, welcome to learn it or ask for English.
|
||||
См. тж. http://www.altlinux.org/Mkimage/Profiles/m-p
|
||||
|
||||
Задача:
|
||||
- конфигурирование и создание образов на базе ALT Linux
|
||||
|
||||
Концепция:
|
||||
- конфигурация, как и образ -- объект постадийной сборки
|
||||
- метапрофиль служит репозиторием для построения индивидуального
|
||||
профиля, по которому создаётся итоговый дистрибутив
|
||||
- для одноразовых модификаций можно подправить сгенерированный
|
||||
профиль, для долгосрочной разработки стоит вливать правки
|
||||
в метапрофиль (что требует больше навыков и времени)
|
||||
профиля, по которому создаётся итоговый образ
|
||||
|
||||
Особенности:
|
||||
- метапрофиль может быть полностью read-only при сборке
|
||||
@ -25,52 +26,36 @@ Most docs in Russian, welcome to learn it or ask for English.
|
||||
он автономен относительно метапрофиля
|
||||
|
||||
Стадии работы:
|
||||
- инициализация дистрибутивного профиля
|
||||
- сборка конфигурации дистрибутива
|
||||
- наполнение дистрибутивного профиля
|
||||
- сборка дистрибутива
|
||||
- инициализация сборочного профиля
|
||||
- сборка конфигурации образа
|
||||
- наполнение сборочного профиля
|
||||
- сборка образа
|
||||
|
||||
Объекты:
|
||||
- виртуальные окружения:
|
||||
+ описываются в lib/ve.mk
|
||||
- дистрибутивы и виртуальные окружения:
|
||||
+ описываются в conf.d/*.mk или соответственно lib/{distro,ve}.mk
|
||||
+ могут основываться одно на другом
|
||||
- дистрибутивы:
|
||||
+ описываются в lib/distro.mk
|
||||
+ могут основываться один на другом
|
||||
+ включают один или более субпрофилей по надобности
|
||||
+ дистрибутивы также:
|
||||
- включают один или более субпрофилей по надобности
|
||||
+ желательно избегать множественного наследования, см. тж. фичи
|
||||
- субпрофили:
|
||||
+ список собирается в $(SUBPROFILES)
|
||||
+ базовые комплекты помещены в подкаталогах под sub.in/;
|
||||
их наборы скриптов могут расширяться фичами
|
||||
- stage1: propagator, ядро инсталятора и initrd в т.ч. с firmware
|
||||
- stage2: базовый live-образ (и модули ядра, соответствующие stage1);
|
||||
используется только с модификаторами (см. соответствующие фичи):
|
||||
+ stage2/install2: инсталятор
|
||||
+ stage2/live: LiveCD
|
||||
+ stage2/rescue: спасательная система
|
||||
- main: пакетная база к инсталяции (обязательная и дополнительная)
|
||||
- фичи:
|
||||
+ список собирается в $(FEATURES)
|
||||
+ законченные блоки функциональности (или наборы таковых)
|
||||
+ описываются в индивидуальных features.in/*/config.mk
|
||||
+ могут требовать другие фичи, а также субпрофили
|
||||
+ при сборке $(BUILDDIR) содержимое указанных в $(FEATURES) фич
|
||||
(подкаталоги, соответствующие входящим в дистрибутив субпрофилям
|
||||
под их итоговыми названиями -- например, live, а не stage2/live)
|
||||
добавляется в профиль; затем выполняются generate.sh, generate.mk
|
||||
- списки пакетов (*_LISTS): просьба по возможности избегать дублирования;
|
||||
NB: перечисленные в этих переменных файлы автоматически копируются
|
||||
в порождаемый профиль => не следует указывать пакаджлисты напрямую
|
||||
- индивидуальные пакеты (*_PACKAGES): следует крайне осторожно пользоваться
|
||||
SYSTEM_PACKAGES -- эти пакеты попадут во все стадии, в том числе в образ
|
||||
чувствительной к объёму install2 (в stage1 -- только в инструментальный
|
||||
чрут); применяйте для того, что обязано быть и в инсталяторе, и в готовой
|
||||
системе -- и не путайте с COMMON_PACKAGES (main, live, rescue)
|
||||
добавляется в профиль с постобработкой (generate.*)
|
||||
- списки пакетов (*_LISTS):
|
||||
+ просьба по возможности избегать дублирования
|
||||
- индивидуальные пакеты (*_PACKAGES): см. тж. conf.d/README
|
||||
|
||||
Результат:
|
||||
- при успешном завершении сборки образ называется сообразно
|
||||
дистрибутиву и укладывается в $(IMAGEDIR):
|
||||
- при успешном завершении сборки образ называется по имени цели
|
||||
и укладывается в $(IMAGEDIR):
|
||||
+ указанный явно,
|
||||
+ либо ~/out/ (если возможно),
|
||||
+ или $(BUILDDIR)/out/ иначе
|
||||
|
||||
@ -1,17 +1,24 @@
|
||||
Этот каталог содержит включаемые фрагменты конфигурации образов с тем,
|
||||
чтобы было удобнее параллельно разрабатывать специфические дистрибутивы
|
||||
без излишних merge conflict'ов.
|
||||
и VE без излишних merge conflict'ов.
|
||||
|
||||
Следует понимать, что основная цель появления mkimage-profiles на свет
|
||||
-- это уменьшение "форков" внутри семейства дистрибутивных профилей.
|
||||
Поэтому при возможности следует всё-таки работать над общей базовой
|
||||
частью, включая скриптовые хуки и списки пакетов, а также оптимизировать
|
||||
граф зависимостей между дистрибутивными конфигурациями.
|
||||
граф зависимостей между конфигурациями образов.
|
||||
|
||||
Попросту говоря, copy-paste -- тревожный признак.
|
||||
|
||||
NB: по переменным:
|
||||
По переменным:
|
||||
* SYSTEM_PACKAGES стоит применять крайне осторожно -- эти пакеты попадут
|
||||
во все стадии, в том числе в образ чувствительной к объёму install2
|
||||
(в stage1 -- только в инструментальный чрут); применяйте для того,
|
||||
что обязано быть и в инсталяторе, и в готовой системе;
|
||||
* для "обычного общего" (main, live, rescue) есть COMMON_PACKAGES.
|
||||
|
||||
По подстановкам:
|
||||
* $(VAR) подставляются перед их записью в $(CONFIG), который distcfg.mk;
|
||||
* $$(VAR) раскрываются позже, при включении $(CONFIG) и востребовании
|
||||
значений -- таким образом их значения могут изменяться до окончания
|
||||
конфигурации, а также зависеть от значений других переменных.
|
||||
конфигурации, а также зависеть от значений других переменных;
|
||||
|
||||
@ -2,38 +2,34 @@
|
||||
и должен дать представление о том, какой код _может_ быть
|
||||
включён в настоящую фичу: статические файлы, два makefile
|
||||
для создания конфигурации и генерирования части профиля,
|
||||
а также шелл-скрипт для генерирования.
|
||||
а также шелл-скрипт для такого генерирования.
|
||||
|
||||
Вовсе не требуется втягивать всё в свою фичу, лучше постараться
|
||||
Вовсе не требуется втягивать всё в свою фичу: лучше постараться
|
||||
сделать её минимальной, самодостаточной и полезной в качестве
|
||||
"кирпичика".
|
||||
|
||||
Единственной необходимой частью фичи является файл config.mk,
|
||||
Единственной обязательной частью фичи является файл config.mk,
|
||||
который включается в distro.mk верхнего уровня и предоставляет
|
||||
цель вида use/*, специфичную для данной фичи (а также добавляет
|
||||
её в переменную FEATURES -- к сожалению, реализовать добавление
|
||||
автоматом не представляется возможным). Если название фичи не
|
||||
упоминается в списке, содержащемся в этой переменной, то она
|
||||
не задействуется при построении профиля, а только при сборке
|
||||
конфигурации дистрибутива.
|
||||
цель вида use/*, специфичную для данной фичи, а также добавляет
|
||||
её в переменную FEATURES. Если название фичи не упоминается
|
||||
в списке, содержащемся в этой переменной, то она не задействуется
|
||||
при построении профиля, а только при сборке конфигурации.
|
||||
|
||||
Остальное содержимое является дополнительным и используется
|
||||
в таком порядке (см. features.in/Makefile):
|
||||
в таком порядке (см. ../Makefile):
|
||||
|
||||
- сперва в $(BUILDDIR)/image/ копируются все подкаталоги,
|
||||
соответствующие именам субпрофилей, запрошенных для
|
||||
дистрибутивного профиля; при этом они сливаются с деревом,
|
||||
соответствующие итоговым именам субпрофилей, запрошенных
|
||||
для профиля образа; при этом они сливаются с деревом,
|
||||
которое уже сформировано субпрофилями (../sub.in/*) и уже
|
||||
скопированными фичами; если какие-либо файлы перекрылись
|
||||
по именам, rsync должен оставить резервные копии (*~),
|
||||
которые должны просигнализировать о беспорядке;
|
||||
|
||||
- затем запускается generate.sh, если существует и исполнимый;
|
||||
|
||||
- затем используется generate.mk, если существует и непустой.
|
||||
- запускается generate.sh, если существует и исполнимый;
|
||||
- применяется generate.mk, если существует и непустой.
|
||||
|
||||
Например, если используются субпрофили stage1, stage2/install2
|
||||
и main, вы можете решить собрать специфические для фичи скрипты
|
||||
и main, можно решить собрать специфические для фичи скрипты
|
||||
инсталятора в install2/image-scripts.d/ (или необходимые для
|
||||
операций с пакетной базой -- в main/scripts.d/, смотря чего
|
||||
надо добиться; загляните также в документацию mkimage).
|
||||
|
||||
@ -1,43 +0,0 @@
|
||||
This directory contains phony example feature and should provide
|
||||
you with a minimal idea what code _can_ be included into a real
|
||||
feature: static files, configuration and generation makefiles,
|
||||
and a generation shell script.
|
||||
|
||||
It's not neccessary to toss all of those into your feature,
|
||||
better try to keep it minimalistic, self-contained and useful
|
||||
as a building block.
|
||||
|
||||
The only requisite part of the feature is config.mk which
|
||||
is included in toplevel distro.mk and which provides the
|
||||
use/* target specific for the feature (and also registers
|
||||
it in FEATURES variable -- sorry, it's not feasible to do
|
||||
automatically). If the feature's name isn't mentioned in
|
||||
the list contained in that variable, then it's not examined
|
||||
while building up the profile either.
|
||||
|
||||
The rest of content is optional and used in this order
|
||||
(see features.in/Makefile):
|
||||
|
||||
- first all subdirectories corresponding to subprofile names
|
||||
requested for the distribution profile being made are copied
|
||||
over to $(BUILDDIR)/image/; thus they get merged with the tree
|
||||
which is already formed by subprofiles (../sub.in/*) and preceding
|
||||
features; in case of overlapping files rsync should leave backup
|
||||
copies which are to be treated as a signal of disorder;
|
||||
|
||||
- then generate.sh is run, if found and executable;
|
||||
|
||||
- then generate.mk is used, if found and non-empty.
|
||||
|
||||
e.g., if the distro needs stage1, install2 and main subprofiles,
|
||||
you might want to collect feature-specific scripts for installer
|
||||
into install2/image-scripts.d/ (or main/scripts.d/, depending on
|
||||
what is to be achieved -- see also mkimage docs).
|
||||
|
||||
And if some non-trivial configuration actions are to be done
|
||||
(like syslinux config file being compiled from pieces depending
|
||||
on what bits are present of the functionality asked for...) then
|
||||
you can perform them in generate.* code.
|
||||
|
||||
Please feel free to comment on what's useful here and what's crap
|
||||
to mike@altlinux.
|
||||
@ -1,15 +1,15 @@
|
||||
Этот каталог содержит т.н. фичи (features, особенности) --
|
||||
каталоги, содержимое каждого из которых реализует одну из
|
||||
подключаемых автономных возможностей дистрибутива.
|
||||
подключаемых автономных возможностей образа.
|
||||
|
||||
Каждая фича должна содержать задействуемый при построении
|
||||
конфигурации будущего образа файл config.mk, включаемый
|
||||
в ../Makefile; он может описывать одну или более целей
|
||||
вида use/*, дополняющих конфигурацию дистрибутива, и при
|
||||
наличии дополнительных хуков для копирования или generate.*
|
||||
вида use/*, дополняющих конфигурацию, и при наличии
|
||||
дополнительных хуков для копирования или generate.*
|
||||
должен добавить имя фичи в $(FEATURES).
|
||||
|
||||
На этапе генерации дистрибутивного профиля фичи рассматриваются
|
||||
На этапе генерации сборочного профиля фичи рассматриваются
|
||||
после инициализации профиля (см. ../image.in/) и копирования
|
||||
субпрофилей (см. ../sub.in/). Для каждой фичи, указанной
|
||||
в $(FEATURES), копируются подкаталоги сообразно субпрофилям,
|
||||
@ -25,7 +25,13 @@ generate.sh и задействуется generate.mk (при их наличи
|
||||
с именем исходного базового субпрофиля (см. $src, $dst в Makefile).
|
||||
|
||||
Каталог lib/ является специфическим для фич, определяющих
|
||||
построение образа -- см. build-*/.
|
||||
построение конкретного вида образа -- см. build-*/.
|
||||
|
||||
Несложный пример содержится в 00example/, более близкий к жизни
|
||||
и нынешним пределам возможностей метапрофиля -- в syslinux/.
|
||||
|
||||
Основные фичи для построения дистрибутивных образов:
|
||||
- stage1: propagator, ядро инсталятора и initrd в т.ч. с firmware
|
||||
- stage2: базовый live-образ (и модули ядра, соответствующие stage1);
|
||||
используется фичами install2, live, rescue
|
||||
- main: пакетная база
|
||||
|
||||
@ -6,5 +6,5 @@
|
||||
и требует пакет выбранного загрузчика.
|
||||
|
||||
Реализация экспериментальная (нужно модуляризовать installer-steps),
|
||||
пока завязана на installer-distro-altlinux-generic. Возможно,
|
||||
пока завязана на installer-distro-altlinux-generic (TODO). Возможно,
|
||||
с использованием alterator-lilo связаны проблемы времени установки.
|
||||
|
||||
@ -4,3 +4,6 @@
|
||||
Для практического применения (в первую очередь это
|
||||
перешивка firmware) требуется сделать подключение
|
||||
CD и/или USB Flash с тем, чтобы класть туда прошивки.
|
||||
|
||||
Спасибо за идею и местами реализацию: Александру Бандуре,
|
||||
Сергею Горенко, Николаю Гречуху и Алексею Фролову.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
Добавление модуля hdt (Hardware Detection Tool COM32 module) к syslinux;
|
||||
Добавление модуля hdt (Hardware Detection Tool) к syslinux;
|
||||
может быть востребовано для инсталяторов, live/rescue.
|
||||
|
||||
Фича не только требует фичу syslinux (и соответствующий пакет,
|
||||
|
||||
@ -1,3 +1,3 @@
|
||||
Эта фича определяет формат упаковки создаваемого образа.
|
||||
На данный момент поддерживаются iso (загрузочный ISO9660
|
||||
для дистрибутивов) и tar (виртуальные окружения).
|
||||
для дистрибутивов) и tar/tgz (виртуальные окружения).
|
||||
|
||||
@ -2,18 +2,14 @@
|
||||
реализуется в рамках stage1.
|
||||
|
||||
Цели config.mk:
|
||||
|
||||
* use/syslinux/ui-% -- конфигурирование интерфейса (см. cfg.in/00*.cfg);
|
||||
при использовании автоматически добавляют syslinux в FEATURES;
|
||||
|
||||
* use/syslinux/%.com, use/syslinux/%.c32 -- подключение одноименных модулей
|
||||
(копирование бинарников и включение кусочков конфигурации; экспериментальное);
|
||||
|
||||
* use/syslinux/%.cfg -- подключение кусочков конфигурации.
|
||||
|
||||
Переменные generate.mk:
|
||||
|
||||
* BOOTLOADER -- isolinux (TODO: добавить поддержку syslinux для флэшек);
|
||||
* BOOTLOADER -- isolinux (реализовано с оглядкой на syslinux/syslinux4);
|
||||
* SYSLINUX_UI -- модуль интерфейса (если не указан, то внутренний prompt);
|
||||
* SYSLINUX_MODULES -- модули .com или .c32 (перечисляются без расширения);
|
||||
* SYSLINUX_CFG -- дополнительные кусочки конфигурации (например, localboot).
|
||||
|
||||
@ -1,16 +1,15 @@
|
||||
Этот каталог копируется из метапрофиля в профиль "как есть"
|
||||
и формирует "затравку" финальной стадии, собирающей собственно
|
||||
образ из результатов работы индивидуальных субпрофилей.
|
||||
|
||||
Обратите внимание: в зависимости от того, какой образ нужен,
|
||||
требуется или features.in/build-distro (для дистрибутивов),
|
||||
или use/build-ve (для образов виртуальных окружений).
|
||||
|
||||
образ из результатов работы индивидуальных субпрофилей
|
||||
(для distro/*) либо непосредственно "на месте" (для ve/*).
|
||||
Содержимое files/ копируется в корень образа.
|
||||
|
||||
Соответственно для сборки требуется или features.in/build-distro,
|
||||
или use/build-ve.
|
||||
|
||||
Пакетная база рабочего чрута минимальна; apt-utils включены
|
||||
ради genbasedir, который после завершения первоначального
|
||||
наполнения субпрофилей может переехать в ../sub.in/main/.
|
||||
наполнения субпрофилей может переехать в ../sub.in/main/ (TODO).
|
||||
|
||||
Если требуется какая-либо иная обработка чрута, следует
|
||||
предпочитать scripts.d/.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
Этот каталог содержит вспомогательные makefiles,
|
||||
обеспечивающие основную функциональность создания
|
||||
конфигурации образа и генерации соответствующего
|
||||
профиля для сборки.
|
||||
профиля для сборки; см. тж. ../conf.d/.
|
||||
|
||||
Следует помнить, что будучи включаемыми в ../Makefile,
|
||||
они работают в каталоге верхнего уровня.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
Этот каталог содержит субпрофили; содержимое затребованных
|
||||
(названия которых содержатся в значении переменной SUBPROFILES,
|
||||
которую заполняют цели sub/* -- см. ../lib/distro.mk) будет
|
||||
скопировано в каталог $(BUILDDIR)/image/ формируемого профиля.
|
||||
скопировано в корневой каталог формируемого профиля.
|
||||
|
||||
Просьба ответственно относиться к изменению существующих субпрофилей
|
||||
и вдумчиво -- к созданию новых; возможно, достаточно всего лишь
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
Этот каталог содержит субпрофиль main, собирающий пакетную базу
|
||||
для локальной инсталяции дистрибутива из полученного образа,
|
||||
включая необязательные пакеты.
|
||||
включая необязательные пакеты; в live-builder применяется как
|
||||
локальный репозиторий для сборки.
|
||||
|
||||
Подбирает:
|
||||
- SYSTEM_PACKAGES, COMMON_PACKAGES, BASE_PACKAGES, BASE_LISTS:
|
||||
|
||||
@ -13,6 +13,8 @@
|
||||
STAGE1_KMODULES_REGEXP -- будет подмножество модулей
|
||||
из kernel-image (упаковываются в syslinux/alt0/full.cz).
|
||||
|
||||
Требуется для инсталяционных, live- и rescue-образов.
|
||||
Требуется для инсталяционных, live- и rescue-образов,
|
||||
соответствующими фичами подключается автоматически
|
||||
(в силу зависимости stage2 от stage1).
|
||||
|
||||
Результат -- каталог syslinux/ для копирования в образ.
|
||||
|
||||
@ -2,6 +2,9 @@
|
||||
используемый для сборки образов install2, live, rescue (возможно,
|
||||
нескольких одновременно в составе одного дистрибутива).
|
||||
|
||||
Зависимость на него стоит прописывать в таких фичах;
|
||||
сама по себе (без нужного stage2cfg.mk) смысла не имеет.
|
||||
|
||||
Результат -- соответственно названный файл со squashfs,
|
||||
подлежащий копированию в итоговый образ.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user