README update

These have been proofread somewhat to correspond
to the current state of affairs; a missing one
was added for fonts feature.

README

@@ -1,5 +1,6 @@
-[float]
+== Welcome to m-p! ==
-=== Welcome to mkimage-profiles! ===
+
+*Brief summary*
 
   Configurables: ~/.mkimage/profiles.mk;
   see doc/params.txt and conf.d/README
@@ -43,7 +44,7 @@
 * субпрофили:
 ** список собирается в $(SUBPROFILES)
 ** базовые комплекты помещены в подкаталогах под sub.in/;
-    их наборы скриптов могут расширяться фичами
+   их наборы скриптов могут расширяться фичами
 * фичи:
 ** законченные блоки функциональности (или наборы таковых)
 ** описываются в индивидуальных features.in/*/config.mk

conf.d/README

@@ -1,7 +1,8 @@
 == conf.d ==
+
 Этот каталог содержит включаемые фрагменты конфигурации образов с тем,
-чтобы было удобнее параллельно разрабатывать специфические дистрибутивы
+чтобы было удобнее параллельно разрабатывать специфические образы
-и VE без излишних merge conflict'ов.
+без излишних merge conflict'ов.
 
 Следует понимать, что основная цель появления mkimage-profiles на свет
 -- это уменьшение "форков" внутри семейства дистрибутивных профилей.
@@ -13,47 +14,49 @@
 
 По переменным (см. тж. ../doc/pkglists.txt):
 
-- для пользовательского окружения (live, main) предназначены
+* для пользовательского окружения (live, main) предназначены
   THE_PACKAGES, THE_LISTS, THE_GROUPS, THE_PACKAGES_REGEXP
 
-- для "обычного общего" (live, main, rescue) есть COMMON_PACKAGES
+* для "обычного общего" (live, main, rescue) есть COMMON_PACKAGES
   (NB: тоже попадают в базовую установку)
 
-- SYSTEM_PACKAGES стоит применять крайне осторожно -- эти пакеты попадут
+* SYSTEM_PACKAGES стоит применять крайне осторожно -- эти пакеты попадут
   во все стадии, в том числе в образ чувствительной к объёму install2
   (в stage1 -- только в инструментальный чрут); применяйте для того,
   что обязано быть и в инсталяторе, и в готовой системе
 
-- для направленного действия служат:
+* для направленного действия служат:
-  * STAGE1_PACKAGES, STAGE1_PACKAGES_REGEXP (первая стадия загрузки)
+** STAGE1_PACKAGES, STAGE1_PACKAGES_REGEXP (первая стадия загрузки)
-  * STAGE2_PACKAGES (инсталятор и спасательная/"живая" система)
+** STAGE2_PACKAGES (инсталятор и спасательная/"живая" система)
-  * INSTALL2_PACKAGES (инсталятор)
+** INSTALL2_PACKAGES (инсталятор)
-  * BASE_PACKAGES, BASE_LISTS, BASE_PACKAGES_REGEXP (базовая система)
+** BASE_PACKAGES, BASE_LISTS, BASE_PACKAGES_REGEXP (базовая система)
-  * MAIN_PACKAGES, MAIN_LISTS, MAIN_PACKAGES_REGEXP (дополнительные пакеты)
+** MAIN_PACKAGES, MAIN_LISTS, MAIN_PACKAGES_REGEXP (дополнительные пакеты)
-  * LIVE_PACKAGES, LIVE_LISTS, LIVE_PACKAGES_REGEXP ("живая" система)
+** LIVE_PACKAGES, LIVE_LISTS, LIVE_PACKAGES_REGEXP ("живая" система)
 
-- аналогично по модулям ядра:
+* аналогично по модулям ядра:
-  * THE_KMODULES попадут в "пользовательскую" среду (live, main)
+** THE_KMODULES попадут в "пользовательскую" среду (live, main)
-  * STAGE1_KMODULES доступны в производных от stage2 (install2, live, rescue)
+** STAGE1_KMODULES доступны в производных от stage2 (install2, live, rescue)
-  * BASE_KMODULES попадут в установку по умолчанию
+** BASE_KMODULES попадут в установку по умолчанию
-  * MAIN_KMODULES будут доступны для установки с носителя
+** MAIN_KMODULES будут доступны для установки с носителя
-  * LIVE_KMODULES предназначены для LiveCD/LiveFlash
+** LIVE_KMODULES предназначены для LiveCD/LiveFlash
 
 Не стоит бояться такого разнообразия, для большинства задач достаточно THE_*.
 
 По подстановкам:
-- $(VAR) подставляются перед их записью в $(CONFIG), который distcfg.mk
+
-- $$(VAR) раскрываются позже, при включении $(CONFIG) и востребовании
+* $(VAR) подставляются перед их записью в $(CONFIG), который distcfg.mk
+* $$(VAR) раскрываются позже, при включении $(CONFIG) и востребовании
   значений; в этом случае их значения могут изменяться до окончания
   конфигурации, а также зависеть от значений других переменных
 
 По спискам пакетов:
-- на этапе экспериментирования можно забивать прямо в описание образа
+
-- при фиксации состояния стоит воспользоваться существующими списками,
+* на этапе экспериментирования можно забивать прямо в описание образа
+* при фиксации состояния стоит воспользоваться существующими списками,
   а дополнительные оформить как можно более чётко обособленными по тем
   задачам, для решения которых они и подобраны
-- повторяющиеся логически связанные группы списков может иметь смысл
+* повторяющиеся логически связанные группы списков может иметь смысл
   выделить в фичу (см., например, power или x11)
-- если явной фичи не наблюдается, но у группы дистрибутивов намечается
+* если явной фичи не наблюдается, но у группы дистрибутивов намечается
   заметная общая часть -- её можно выделить в промежуточную цель вида
   distro/.name, не являющуюся самостоятельно собираемой

doc/assumptions.txt

@@ -1,4 +1,7 @@
-== Предположения фрагментов кода об окружении ==
+== Предположения ==
+
+Некоторые фрагменты кода закладываются на определённое поведение
+других частей mkimage-profiles либо содержание переменных.
 
 NB: пути приводятся от верхнего уровня; проект в целом предполагает
 ALT Linux 6.0+ и GNU make 3.81+ (на которых и разрабатывается),

doc/debug.txt

@@ -10,12 +10,16 @@
 
 * build/build.log
 ** подробность зависит от значения переменной DEBUG,
-    которую можно передать при запуске make (см. params.txt);
+   которую можно передать при запуске make (см. params.txt);
 ** содержит коммит, из которого происходит сборка, и признак
-    "грязности" рабочего каталога при наличии модификаций после
+   "грязности" рабочего каталога при наличии модификаций после
-    этого коммита;
+   этого коммита;
 ** содержит список конфигурационных переменных и их конечных значений,
-    созданный на основании distcfg.mk (см. тж. build/vars.mk)
+   созданный на основании distcfg.mk (см. тж. build/vars.mk)
+* REPORT=1 включает генерацию дополнительного вывода:
+** build/reports/targets.png -- граф зависимостей между целями
+** build/reports/scripts.log -- порядок запуска скриптовых хуков
+** build/reports/cleanlog.log -- более пригодный для diff(1) журнал сборки
 
-Общая информация по отладке сборки профилей mkimage:
+Общая информация по отладке сборки профилей mkimage доступна на вики:
 http://www.altlinux.org/Mkimage/debug

doc/features.txt

@@ -11,14 +11,14 @@
 
 В большинстве случаев можно рекомендовать создание feature
 средствами метапрофиля, поскольку при этом дерево кода более
-удобно для анализа и обновления (и в отличие от m-p-d -- нет
+удобно для анализа и обновления (и в отличие от _m-p-d_ -- нет
 вынужденной необходимости либо контролировать включение нужных
 фич "вручную" в скриптах по косвенным признакам, либо выносить
 их в пакеты installer-feature-*).
 
 Создание и упаковку installer-feature-* можно рекомендовать, если:
 
-* необходимы пакетные зависимости;
+* необходимы пакетные зависимости (в т.ч. версии/конфликты);
 * требуется компилируемый платформозависимый код (для чего бы...);
 * код фичи достаточно специфичен, нетривиален и объёмен,
   чтобы загромождать метапрофиль было не очень осмысленно;

doc/mkimage-profiles.asciidoc

@@ -1,11 +1,11 @@
 = mkimage-profiles =
 Michael Shigorin <mike@altlinux.org>
-:DocVersion: v0.2.0
+:DocVersion: v1.0
-:DocDate:  Oct 2012
+:DocDate: Jun 2013
 
 = Введение =
 
-mkimage-profiles, или m-p — результат осмысления и обобщения опыта создания
+mkimage-profiles, или _m-p_ — результат осмысления и обобщения опыта создания
 семейств дистрибутивов свободного программного обеспечения на базе ALT Linux.
 
 *Цели*
@@ -29,40 +29,25 @@ mkimage-profiles, или m-p — результат осмысления и об
 
   git clone git://git.altlinux.org/people/mike/packages/mkimage-profiles.git
   cd mkimage-profiles
-  make distro/icewm.iso
+  make icewm.iso
-
-include::../README[]
 
 = Основы =
 
-include::assumptions.txt[]
+include::../README[]
-
-include::debug.txt[]
-
-include::features.txt[]
 
 include::params.txt[]
 
+include::features.txt[]
+
 include::pkglists.txt[]
 
-include::qemu.txt[]
-
-include::style.txt[]
-
-include::vm.txt[]
-
-
 = Каталоги =
 
 include::../conf.d/README[]
 
-include::../features.in/README[]
-
 include::../image.in/README[]
 
-include::../lib/README[]
+include::../features.in/README[]
-
-include::../pkg.in/README[]
 
 include::../sub.in/README[]
 
@@ -71,3 +56,26 @@ include::../sub.in/main/README[]
 include::../sub.in/stage1/README[]
 
 include::../sub.in/stage2/README[]
+
+include::../pkg.in/README[]
+
+include::../pkg.in/lists/README[]
+
+include::../pkg.in/lists/tagged/README[]
+
+include::../pkg.in/groups/README[]
+
+include::../lib/README[]
+
+= Приложения =
+
+include::assumptions.txt[]
+
+include::debug.txt[]
+
+include::style.txt[]
+
+include::vm.txt[]
+
+include::qemu.txt[]
+

doc/params.txt

@@ -114,4 +114,4 @@
 [float]
 === пример ===
 
-  make DEBUG=1 CLEAN=1 distro/syslinux.iso
+  make DEBUG=1 CLEAN=1 syslinux.iso

doc/pkglists.txt

@@ -1,10 +1,11 @@
 == Списки пакетов ==
 
 Состав пакетной базы субпрофилей определяется значенями
-следующих переменных профиля (см. тж. ../conf.d/README):
+следующих переменных профиля (см. тж. ../conf.d/README;
+некоторые "*" ниже заэкранированы ради парсера asciidoc):
 
 * main: пакетная база для установки
-** sub.in/main/Makefile, features.in/*/main/lib/*.mk
+** sub.in/main/Makefile, features.in/\*/main/lib/*.mk
 ** THE_LISTS, BASE_LISTS, MAIN_LISTS
 ** THE_GROUPS, MAIN_GROUPS
 ** THE_PACKAGES, BASE_PACKAGES, MAIN_PACKAGES,
@@ -14,7 +15,7 @@
 *** KFLAVOURS
 
 * stage2: общая часть installer, live, rescue
-** sub.in/stage2/Makefile, features.in/*/stage2/lib/*.mk
+** sub.in/stage2/Makefile, features.in/\*/stage2/lib/*.mk
 ** SYSTEM_PACKAGES, STAGE2_PACKAGES
 ** STAGE1_KMODULES, STAGE1_KMODULES_REGEXP,
     STAGE2_KMODULES, STAGE2_KMODULES_REGEXP
@@ -23,13 +24,13 @@
 * installer: компактная "живая" система, содержащая только инсталятор
 ** см. stage2
 *** features.in/install2/install2/stage2cfg.mk,
-    features.in/*/install2/lib/*.mk
+    features.in/\*/install2/lib/*.mk
 *** INSTALL2_PACKAGES
 
 * live: пользовательский LiveCD (может содержать также инсталятор)
 ** см. stage2
 ** features.in/live/live/stage2cfg.mk,
-    features.in/*/live/lib/*.mk
+    features.in/\*/live/lib/*.mk
 ** THE_LISTS, LIVE_LISTS
 ** THE_GROUPS, LIVE_GROUPS
 ** THE_PACKAGES, LIVE_PACKAGES, COMMON_PACKAGES
@@ -43,7 +44,7 @@
 ** RESCUE_LISTS
 
 * stage1: ядро и загрузчик второй стадии
-** sub.in/stage1/Makefile, features.in/*/stage1/lib/*.mk
+** sub.in/stage1/Makefile, features.in/\*/stage1/lib/*.mk
 ** STAGE1_PACKAGES, SYSTEM_PACKAGES
 ** STAGE1_PACKAGES_REGEXP
 ** STAGE1_KMODULES_REGEXP

doc/style.txt

@@ -1,4 +1,4 @@
-== Требования по оформлению кода ==
+== Оформление кода ==
 
 * постарайтесь не вносить без обсуждения разнобой стилей,
   если есть предметные пожелания по коррекции текущего --

doc/vm.txt

@@ -1,4 +1,4 @@
-== Сборка образов виртуальных машин ==
+== Сборка образов VM ==
 
 *ВНИМАНИЕ:* заключительная операция создания образа жёсткого диска
 из архива с содержимым корневой файловой системы требует доступа

features.in/00example/README

@@ -23,15 +23,15 @@
 Остальное содержимое является дополнительным и используется
 в таком порядке (см. ../Makefile):
 
-- сперва в $(BUILDDIR)/image/ копируются все подкаталоги,
+* сперва в $(BUILDDIR)/image/ копируются все подкаталоги,
   соответствующие итоговым именам субпрофилей, запрошенных
   для профиля образа; при этом они сливаются с деревом,
   которое уже сформировано субпрофилями (../sub.in/*) и уже
   скопированными фичами; если какие-либо файлы перекрылись
   по именам, rsync должен оставить резервные копии (*~),
   которые должны просигнализировать о беспорядке;
-- запускается generate.sh, если существует и исполнимый;
+* запускается generate.sh, если существует и исполнимый;
-- применяется generate.mk, если существует и непустой.
+* применяется generate.mk, если существует и непустой.
 
 Например, если используются субпрофили stage1, stage2/install2
 и main, можно решить собрать специфические для фичи скрипты

features.in/README

@@ -1,4 +1,5 @@
 == features.in ==
+
 Этот каталог содержит т.н. фичи (features, особенности).
 
 Фича -- отдельно подключаемая сущность, которая содержит
@@ -37,3 +38,5 @@
 
 Несложный пример содержится в 00example/, более близкий к жизни
 и нынешним пределам возможностей метапрофиля -- в syslinux/.
+
+См. тж. файлы README в каталогах фич (отсутствие -- баг!).

features.in/bootloader/README

@@ -12,6 +12,7 @@
 останется lilo как последняя "новая" цель с точки зрения make.
 
 При необходимости всё-таки "пересилить" последнее изменение можно
+
 	@$(call set,BASE_BOOTLOADER,grub_или_lilo)
 
 Реализация экспериментальная (нужно модуляризовать installer-steps).

features.in/branding/README

@@ -9,18 +9,18 @@
 
 Назначение и возможные значения (если требуются):
 
-- STAGE1_BRANDING
+* STAGE1_BRANDING
-  * относится к загрузке со сгенерированного образа (например, ISO)
+** относится к загрузке со сгенерированного образа (например, ISO)
-  * bootloader bootsplash (при старте)
+** bootloader bootsplash (при старте)
 
-- STAGE2_BRANDING
+* STAGE2_BRANDING
-  * общая часть для всех вариантов stage2
+** общая часть для всех вариантов stage2
-  * bootsplash (при выключении)
+** bootsplash (при выключении)
 
-- INSTALL2_BRANDING
+* INSTALL2_BRANDING
-  * специфические пакеты брендирования инсталятора
+** специфические пакеты брендирования инсталятора
-  * notes slideshow
+** notes slideshow
 
-- THE_BRANDING
+* THE_BRANDING
-  * общий список для использования в установленной системе и LiveCD
+** общий список для использования в установленной системе и LiveCD
-  * alterator bootsplash graphics indexhtml notes slideshow
+** alterator bootsplash graphics indexhtml notes slideshow

features.in/fonts/README

@@ -0,0 +1,5 @@
+Эта фича занимается конфигурированием подсистемы
+конфигурации шрифтов fontconfig (sic!); помимо
+возможности выставить желаемые кусочки вручную
+предлагаются и заранее заданные интегральные
+варианты, прошедшие обкатку в дистрибутивах.

features.in/pack/README

@@ -1,4 +1,6 @@
 Эта фича определяет формат упаковки создаваемого образа.
+
 На данный момент поддерживаются iso (загрузочный ISO9660
-для дистрибутивов) и tar/cpio с возможностью сжатия gz/xz
+для дистрибутивов), tar/cpio с возможностью сжатия gz/xz
-(виртуальные окружения).
+(виртуальные окружения), а также различные варианты для
+образов виртуальных машин, поддерживаемые qemu-img.

features.in/power/README

@@ -1,6 +1,3 @@
 Эта фича конфигурирует поддержку управления питанием
 -- выключение и регулировку частоты CPU для ACPI,
 засыпание для APM (не проверялось).
-
-TODO: учесть изложенное в https://bugzilla.altlinux.org/25018
-(для gnome & co)

features.in/systemd/README

@@ -1,3 +1,2 @@
 Эта фича заменяет в базовой системе sysvinit на systemd;
-в настоящее время является экспериментальной, читайте
+см. тж. http://www.altlinux.org/systemd
-http://www.altlinux.org/systemd

image.in/README

@@ -1,15 +1,17 @@
 == image.in ==
+
 Этот каталог копируется из метапрофиля в профиль "как есть"
 и формирует "заготовку" финальной стадии, собирающей собственно
 образ из результатов работы индивидуальных субпрофилей
-(для distro/*) либо непосредственно "на месте" (для ve/*).
+(для distro) либо непосредственно "на месте" (для ve, vm).
+
 Содержимое files/ копируется в корень образа.
 
-Соответственно для сборки также потребуется или
+Соответственно для сборки также потребуется одна из фич
-../features.in/build-distro, или ../features.in/build-ve.
+../features.in/build-*.
 
 Пакетная база рабочего чрута минимальна (может чуть расширяться
-фичами -- см. ../features.in/repo/lib/build-genbasedir.mk
+фичами -- см. ../features.in/repo/lib/50-genbasedir.mk
 в качестве примера).
 
 Если требуется какая-либо иная обработка чрута, следует

lib/README

@@ -1,4 +1,5 @@
 == lib ==
+
 Этот каталог содержит вспомогательные makefiles,
 обеспечивающие основную функциональность создания
 конфигурации образа и генерации соответствующего

pkg.in/README

@@ -1,4 +1,5 @@
 == pkg.in ==
+
 Этот каталог содержит все возможные списки пакетов и описания групп,
 которые по мере необходимости копируются из метапрофиля в формируемый
 профиль.

pkg.in/groups/README

@@ -1,5 +1,6 @@
 [float]
 === pkg.in/groups ===
+
 Этот каталог содержит описания групп, копируемые из метапрофиля
 в создаваемый профиль по необходимости (только фигурирующие в
 списке, которым является значение переменной MAIN_GROUPS).

pkg.in/lists/README

@@ -1,3 +1,5 @@
+=== pkg.in/lists ===
+
 Этот каталог содержит списки пакетов, копируемые из метапрофиля
 в создаваемый профиль по необходимости (определяется по наличию
 имён списков в переменных *_LISTS, см. реализацию в Makefile).

pkg.in/lists/tagged/README

@@ -1,9 +1,10 @@
 === pkg.in/lists/tagged ===
+
 Этот каталог содержит тегированные списки; на данный момент
 реализация (../../../bin/tags2lists) требует, чтобы каждый
 из тегов был отдельным словом, состоящим из символов из набора
-a-zA-Z0-9_ (внимание: не используйте в слове "-"); рекомендуется
+[a-zA-Z0-9_] (внимание: не используйте в слове "-");
-разделять слова "+".
+рекомендуется разделять слова "+".
 
 Применение: дополнение жёстко статически заданной функциональности
 более "плавающим" в долгосрочном плане результатом раскрытия

sub.in/README

@@ -17,19 +17,19 @@
 
 Краткое описание существующих вариантов:
 
-- stage1: propagator и загрузчик (совместно с фичей syslinux);
+* stage1: propagator и загрузчик (совместно с фичей syslinux);
   типично требуется для инсталяторов, live- и rescue-образов,
   но может использоваться без добавления таковых в образ,
   обеспечивая сетевую загрузку второй стадии
 
-- stage2: наиболее сложный технологически субпрофиль, поскольку
+* stage2: наиболее сложный технологически субпрофиль, поскольку
   он является только базовым для получения ряда итоговых частей
   дистрибутива (install2, live, rescue); задействуется для этого
   только опосредованно через use/stage2/* и модифицирует stage1
   в силу наличия связи между ними (в stage1 попадает образ ядра
   и firmware, в stage2 -- соответствующие модули)
 
-- main: пакетная база, укладываемая на образ (NB: поскольку рабочий
+* main: пакетная база, укладываемая на образ (NB: поскольку рабочий
   чрут в этом случае не содержит ничего, кроме пакетов, добавлять
   image-scripts.d/* смысла нет, только scripts.d/*)
 

sub.in/main/README

@@ -6,12 +6,13 @@
 как локальный репозиторий для сборки.
 
 Подбирает:
+
 * SYSTEM_PACKAGES, COMMON_PACKAGES, BASE_PACKAGES, BASE_LISTS:
   в установку по умолчанию;
 * MAIN_PACKAGES, MAIN_LISTS: дополнительные пакеты.
 
-В image-scripts.d/* смысла нет, только scripts.d/* --
+В image-scripts.d смысла нет, только scripts.d, т.к. рабочий чрут
-рабочий чрут не содержит исполняемых файлов.
+не содержит исполняемых файлов.
 
 Не следует использовать этот субпрофиль напрямую, для добавления
 пакетного репозитория в образ предназначена фича use/repo/main.

sub.in/stage1/README

@@ -1,4 +1,5 @@
 === sub.in/stage1 ===
+
 Этот каталог содержит субпрофиль первой стадии загрузки;
 здесь место syslinux (загрузчик) и propagator (ориентировка
 на местности, вытягивание второй стадии с CD/FTP/...).