full-view docs update

QUICKSTART

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

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

conf.d/README

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

features.in/00example/README

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

features.in/00example/README.en

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

features.in/README

 Этот каталог содержит т.н. фичи (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: пакетная база

features.in/bootloader/README

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

features.in/dos/README

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

features.in/hdt/README

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

features.in/pack/README

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

features.in/syslinux/README

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

image.in/README

 Этот каталог копируется из метапрофиля в профиль "как есть"
 и формирует "затравку" финальной стадии, собирающей собственно
-образ из результатов работы индивидуальных субпрофилей.
-
-Обратите внимание: в зависимости от того, какой образ нужен,
-требуется или 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/.

lib/README

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

sub.in/README

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

sub.in/main/README

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

sub.in/stage1/README

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

sub.in/stage2/README

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