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 2011-11-06 21:57:28 +02:00
parent 73f676f92c
commit ddf0c5b7c7
18 changed files with 80 additions and 125 deletions

View File

@ -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
View File

@ -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/ иначе

View File

@ -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) и востребовании
значений -- таким образом их значения могут изменяться до окончания
конфигурации, а также зависеть от значений других переменных.
конфигурации, а также зависеть от значений других переменных;

View File

@ -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).

View File

@ -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.

View File

@ -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: пакетная база

View File

@ -6,5 +6,5 @@
и требует пакет выбранного загрузчика.
Реализация экспериментальная (нужно модуляризовать installer-steps),
пока завязана на installer-distro-altlinux-generic. Возможно,
пока завязана на installer-distro-altlinux-generic (TODO). Возможно,
с использованием alterator-lilo связаны проблемы времени установки.

View File

@ -4,3 +4,6 @@
Для практического применения (в первую очередь это
перешивка firmware) требуется сделать подключение
CD и/или USB Flash с тем, чтобы класть туда прошивки.
Спасибо за идею и местами реализацию: Александру Бандуре,
Сергею Горенко, Николаю Гречуху и Алексею Фролову.

View File

@ -1,4 +1,4 @@
Добавление модуля hdt (Hardware Detection Tool COM32 module) к syslinux;
Добавление модуля hdt (Hardware Detection Tool) к syslinux;
может быть востребовано для инсталяторов, live/rescue.
Фича не только требует фичу syslinux (и соответствующий пакет,

View File

@ -1,3 +1,3 @@
Эта фича определяет формат упаковки создаваемого образа.
На данный момент поддерживаются iso (загрузочный ISO9660
для дистрибутивов) и tar (виртуальные окружения).
для дистрибутивов) и tar/tgz (виртуальные окружения).

View File

@ -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).

View File

@ -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/.

View File

@ -1,7 +1,7 @@
Этот каталог содержит вспомогательные makefiles,
обеспечивающие основную функциональность создания
конфигурации образа и генерации соответствующего
профиля для сборки.
профиля для сборки; см. тж. ../conf.d/.
Следует помнить, что будучи включаемыми в ../Makefile,
они работают в каталоге верхнего уровня.

View File

@ -1,7 +1,7 @@
Этот каталог содержит субпрофили; содержимое затребованных
(названия которых содержатся в значении переменной SUBPROFILES,
которую заполняют цели sub/* -- см. ../lib/distro.mk) будет
скопировано в каталог $(BUILDDIR)/image/ формируемого профиля.
скопировано в корневой каталог формируемого профиля.
Просьба ответственно относиться к изменению существующих субпрофилей
и вдумчиво -- к созданию новых; возможно, достаточно всего лишь

View File

@ -1,6 +1,7 @@
Этот каталог содержит субпрофиль main, собирающий пакетную базу
для локальной инсталяции дистрибутива из полученного образа,
включая необязательные пакеты.
включая необязательные пакеты; в live-builder применяется как
локальный репозиторий для сборки.
Подбирает:
- SYSTEM_PACKAGES, COMMON_PACKAGES, BASE_PACKAGES, BASE_LISTS:

View File

@ -13,6 +13,8 @@
STAGE1_KMODULES_REGEXP -- будет подмножество модулей
из kernel-image (упаковываются в syslinux/alt0/full.cz).
Требуется для инсталяционных, live- и rescue-образов.
Требуется для инсталяционных, live- и rescue-образов,
соответствующими фичами подключается автоматически
(в силу зависимости stage2 от stage1).
Результат -- каталог syslinux/ для копирования в образ.

View File

@ -2,6 +2,9 @@
используемый для сборки образов install2, live, rescue (возможно,
нескольких одновременно в составе одного дистрибутива).
Зависимость на него стоит прописывать в таких фичах;
сама по себе (без нужного stage2cfg.mk) смысла не имеет.
Результат -- соответственно названный файл со squashfs,
подлежащий копированию в итоговый образ.