diff --git a/README b/README index 5de70835..0067ae9e 100644 --- a/README +++ b/README @@ -1,5 +1,6 @@ -[float] -=== Welcome to mkimage-profiles! === +== Welcome to m-p! == + +*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 diff --git a/conf.d/README b/conf.d/README index e61fea4b..9569ce3c 100644 --- a/conf.d/README +++ b/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 (первая стадия загрузки) - * STAGE2_PACKAGES (инсталятор и спасательная/"живая" система) - * INSTALL2_PACKAGES (инсталятор) - * BASE_PACKAGES, BASE_LISTS, BASE_PACKAGES_REGEXP (базовая система) - * MAIN_PACKAGES, MAIN_LISTS, MAIN_PACKAGES_REGEXP (дополнительные пакеты) - * LIVE_PACKAGES, LIVE_LISTS, LIVE_PACKAGES_REGEXP ("живая" система) +* для направленного действия служат: +** STAGE1_PACKAGES, STAGE1_PACKAGES_REGEXP (первая стадия загрузки) +** STAGE2_PACKAGES (инсталятор и спасательная/"живая" система) +** INSTALL2_PACKAGES (инсталятор) +** BASE_PACKAGES, BASE_LISTS, BASE_PACKAGES_REGEXP (базовая система) +** MAIN_PACKAGES, MAIN_LISTS, MAIN_PACKAGES_REGEXP (дополнительные пакеты) +** LIVE_PACKAGES, LIVE_LISTS, LIVE_PACKAGES_REGEXP ("живая" система) -- аналогично по модулям ядра: - * THE_KMODULES попадут в "пользовательскую" среду (live, main) - * STAGE1_KMODULES доступны в производных от stage2 (install2, live, rescue) - * BASE_KMODULES попадут в установку по умолчанию - * MAIN_KMODULES будут доступны для установки с носителя - * LIVE_KMODULES предназначены для LiveCD/LiveFlash +* аналогично по модулям ядра: +** THE_KMODULES попадут в "пользовательскую" среду (live, main) +** STAGE1_KMODULES доступны в производных от stage2 (install2, live, rescue) +** BASE_KMODULES попадут в установку по умолчанию +** MAIN_KMODULES будут доступны для установки с носителя +** LIVE_KMODULES предназначены для LiveCD/LiveFlash Не стоит бояться такого разнообразия, для большинства задач достаточно THE_*. По подстановкам: -- $(VAR) подставляются перед их записью в $(CONFIG), который distcfg.mk -- $$(VAR) раскрываются позже, при включении $(CONFIG) и востребовании + +* $(VAR) подставляются перед их записью в $(CONFIG), который distcfg.mk +* $$(VAR) раскрываются позже, при включении $(CONFIG) и востребовании значений; в этом случае их значения могут изменяться до окончания конфигурации, а также зависеть от значений других переменных По спискам пакетов: -- на этапе экспериментирования можно забивать прямо в описание образа -- при фиксации состояния стоит воспользоваться существующими списками, + +* на этапе экспериментирования можно забивать прямо в описание образа +* при фиксации состояния стоит воспользоваться существующими списками, а дополнительные оформить как можно более чётко обособленными по тем задачам, для решения которых они и подобраны -- повторяющиеся логически связанные группы списков может иметь смысл +* повторяющиеся логически связанные группы списков может иметь смысл выделить в фичу (см., например, power или x11) -- если явной фичи не наблюдается, но у группы дистрибутивов намечается +* если явной фичи не наблюдается, но у группы дистрибутивов намечается заметная общая часть -- её можно выделить в промежуточную цель вида distro/.name, не являющуюся самостоятельно собираемой diff --git a/doc/assumptions.txt b/doc/assumptions.txt index 7a2673ee..4fb76a63 100644 --- a/doc/assumptions.txt +++ b/doc/assumptions.txt @@ -1,4 +1,7 @@ -== Предположения фрагментов кода об окружении == +== Предположения == + +Некоторые фрагменты кода закладываются на определённое поведение +других частей mkimage-profiles либо содержание переменных. NB: пути приводятся от верхнего уровня; проект в целом предполагает ALT Linux 6.0+ и GNU make 3.81+ (на которых и разрабатывается), diff --git a/doc/debug.txt b/doc/debug.txt index 5c900c24..418a6841 100644 --- a/doc/debug.txt +++ b/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 diff --git a/doc/features.txt b/doc/features.txt index 52382baf..89a0507a 100644 --- a/doc/features.txt +++ b/doc/features.txt @@ -11,14 +11,14 @@ В большинстве случаев можно рекомендовать создание feature средствами метапрофиля, поскольку при этом дерево кода более -удобно для анализа и обновления (и в отличие от m-p-d -- нет +удобно для анализа и обновления (и в отличие от _m-p-d_ -- нет вынужденной необходимости либо контролировать включение нужных фич "вручную" в скриптах по косвенным признакам, либо выносить их в пакеты installer-feature-*). Создание и упаковку installer-feature-* можно рекомендовать, если: -* необходимы пакетные зависимости; +* необходимы пакетные зависимости (в т.ч. версии/конфликты); * требуется компилируемый платформозависимый код (для чего бы...); * код фичи достаточно специфичен, нетривиален и объёмен, чтобы загромождать метапрофиль было не очень осмысленно; diff --git a/doc/mkimage-profiles.asciidoc b/doc/mkimage-profiles.asciidoc index 9b8ab2ad..c5df7467 100644 --- a/doc/mkimage-profiles.asciidoc +++ b/doc/mkimage-profiles.asciidoc @@ -1,11 +1,11 @@ = mkimage-profiles = Michael Shigorin -:DocVersion: v0.2.0 -:DocDate: Oct 2012 +:DocVersion: v1.0 +: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 - -include::../README[] + make icewm.iso = Основы = -include::assumptions.txt[] - -include::debug.txt[] - -include::features.txt[] +include::../README[] 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::../pkg.in/README[] +include::../features.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[] + diff --git a/doc/params.txt b/doc/params.txt index c1914953..d2c94be1 100644 --- a/doc/params.txt +++ b/doc/params.txt @@ -114,4 +114,4 @@ [float] === пример === - make DEBUG=1 CLEAN=1 distro/syslinux.iso + make DEBUG=1 CLEAN=1 syslinux.iso diff --git a/doc/pkglists.txt b/doc/pkglists.txt index bd53eed6..c2f01295 100644 --- a/doc/pkglists.txt +++ b/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 diff --git a/doc/style.txt b/doc/style.txt index 783f1d32..38f37ab0 100644 --- a/doc/style.txt +++ b/doc/style.txt @@ -1,4 +1,4 @@ -== Требования по оформлению кода == +== Оформление кода == * постарайтесь не вносить без обсуждения разнобой стилей, если есть предметные пожелания по коррекции текущего -- diff --git a/doc/vm.txt b/doc/vm.txt index 2f4bdc5c..d7b727a3 100644 --- a/doc/vm.txt +++ b/doc/vm.txt @@ -1,4 +1,4 @@ -== Сборка образов виртуальных машин == +== Сборка образов VM == *ВНИМАНИЕ:* заключительная операция создания образа жёсткого диска из архива с содержимым корневой файловой системы требует доступа diff --git a/features.in/00example/README b/features.in/00example/README index bc8801f1..aeac203b 100644 --- a/features.in/00example/README +++ b/features.in/00example/README @@ -23,15 +23,15 @@ Остальное содержимое является дополнительным и используется в таком порядке (см. ../Makefile): -- сперва в $(BUILDDIR)/image/ копируются все подкаталоги, +* сперва в $(BUILDDIR)/image/ копируются все подкаталоги, соответствующие итоговым именам субпрофилей, запрошенных для профиля образа; при этом они сливаются с деревом, которое уже сформировано субпрофилями (../sub.in/*) и уже скопированными фичами; если какие-либо файлы перекрылись по именам, rsync должен оставить резервные копии (*~), которые должны просигнализировать о беспорядке; -- запускается generate.sh, если существует и исполнимый; -- применяется generate.mk, если существует и непустой. +* запускается generate.sh, если существует и исполнимый; +* применяется generate.mk, если существует и непустой. Например, если используются субпрофили stage1, stage2/install2 и main, можно решить собрать специфические для фичи скрипты diff --git a/features.in/README b/features.in/README index eec1ff22..c0cf46ed 100644 --- a/features.in/README +++ b/features.in/README @@ -1,4 +1,5 @@ == features.in == + Этот каталог содержит т.н. фичи (features, особенности). Фича -- отдельно подключаемая сущность, которая содержит @@ -37,3 +38,5 @@ Несложный пример содержится в 00example/, более близкий к жизни и нынешним пределам возможностей метапрофиля -- в syslinux/. + +См. тж. файлы README в каталогах фич (отсутствие -- баг!). diff --git a/features.in/bootloader/README b/features.in/bootloader/README index 73da9799..5a0337c1 100644 --- a/features.in/bootloader/README +++ b/features.in/bootloader/README @@ -12,6 +12,7 @@ останется lilo как последняя "новая" цель с точки зрения make. При необходимости всё-таки "пересилить" последнее изменение можно + @$(call set,BASE_BOOTLOADER,grub_или_lilo) Реализация экспериментальная (нужно модуляризовать installer-steps). diff --git a/features.in/branding/README b/features.in/branding/README index ad3d6673..2fce91d0 100644 --- a/features.in/branding/README +++ b/features.in/branding/README @@ -9,18 +9,18 @@ Назначение и возможные значения (если требуются): -- STAGE1_BRANDING - * относится к загрузке со сгенерированного образа (например, ISO) - * bootloader bootsplash (при старте) +* STAGE1_BRANDING +** относится к загрузке со сгенерированного образа (например, ISO) +** bootloader bootsplash (при старте) -- STAGE2_BRANDING - * общая часть для всех вариантов stage2 - * bootsplash (при выключении) +* STAGE2_BRANDING +** общая часть для всех вариантов stage2 +** bootsplash (при выключении) -- INSTALL2_BRANDING - * специфические пакеты брендирования инсталятора - * notes slideshow +* INSTALL2_BRANDING +** специфические пакеты брендирования инсталятора +** notes slideshow -- THE_BRANDING - * общий список для использования в установленной системе и LiveCD - * alterator bootsplash graphics indexhtml notes slideshow +* THE_BRANDING +** общий список для использования в установленной системе и LiveCD +** alterator bootsplash graphics indexhtml notes slideshow diff --git a/features.in/fonts/README b/features.in/fonts/README new file mode 100644 index 00000000..564dd2b2 --- /dev/null +++ b/features.in/fonts/README @@ -0,0 +1,5 @@ +Эта фича занимается конфигурированием подсистемы +конфигурации шрифтов fontconfig (sic!); помимо +возможности выставить желаемые кусочки вручную +предлагаются и заранее заданные интегральные +варианты, прошедшие обкатку в дистрибутивах. diff --git a/features.in/pack/README b/features.in/pack/README index 678a1219..4d154d0d 100644 --- a/features.in/pack/README +++ b/features.in/pack/README @@ -1,4 +1,6 @@ Эта фича определяет формат упаковки создаваемого образа. + На данный момент поддерживаются iso (загрузочный ISO9660 -для дистрибутивов) и tar/cpio с возможностью сжатия gz/xz -(виртуальные окружения). +для дистрибутивов), tar/cpio с возможностью сжатия gz/xz +(виртуальные окружения), а также различные варианты для +образов виртуальных машин, поддерживаемые qemu-img. diff --git a/features.in/power/README b/features.in/power/README index 2cee4a71..a499391c 100644 --- a/features.in/power/README +++ b/features.in/power/README @@ -1,6 +1,3 @@ Эта фича конфигурирует поддержку управления питанием -- выключение и регулировку частоты CPU для ACPI, засыпание для APM (не проверялось). - -TODO: учесть изложенное в https://bugzilla.altlinux.org/25018 -(для gnome & co) diff --git a/features.in/systemd/README b/features.in/systemd/README index 5e8d09a9..821ca23a 100644 --- a/features.in/systemd/README +++ b/features.in/systemd/README @@ -1,3 +1,2 @@ Эта фича заменяет в базовой системе sysvinit на systemd; -в настоящее время является экспериментальной, читайте -http://www.altlinux.org/systemd +см. тж. http://www.altlinux.org/systemd diff --git a/image.in/README b/image.in/README index ff59b9b5..8f9addb7 100644 --- a/image.in/README +++ b/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 в качестве примера). Если требуется какая-либо иная обработка чрута, следует diff --git a/lib/README b/lib/README index f592cb27..e847ff98 100644 --- a/lib/README +++ b/lib/README @@ -1,4 +1,5 @@ == lib == + Этот каталог содержит вспомогательные makefiles, обеспечивающие основную функциональность создания конфигурации образа и генерации соответствующего diff --git a/pkg.in/README b/pkg.in/README index e1ffd8db..e54904a6 100644 --- a/pkg.in/README +++ b/pkg.in/README @@ -1,4 +1,5 @@ == pkg.in == + Этот каталог содержит все возможные списки пакетов и описания групп, которые по мере необходимости копируются из метапрофиля в формируемый профиль. diff --git a/pkg.in/groups/README b/pkg.in/groups/README index f16a007d..1554d1b2 100644 --- a/pkg.in/groups/README +++ b/pkg.in/groups/README @@ -1,5 +1,6 @@ [float] === pkg.in/groups === + Этот каталог содержит описания групп, копируемые из метапрофиля в создаваемый профиль по необходимости (только фигурирующие в списке, которым является значение переменной MAIN_GROUPS). diff --git a/pkg.in/lists/README b/pkg.in/lists/README index 10d323a8..e74ce952 100644 --- a/pkg.in/lists/README +++ b/pkg.in/lists/README @@ -1,3 +1,5 @@ +=== pkg.in/lists === + Этот каталог содержит списки пакетов, копируемые из метапрофиля в создаваемый профиль по необходимости (определяется по наличию имён списков в переменных *_LISTS, см. реализацию в Makefile). diff --git a/pkg.in/lists/tagged/README b/pkg.in/lists/tagged/README index d7e01335..d0ba9f1e 100644 --- a/pkg.in/lists/tagged/README +++ b/pkg.in/lists/tagged/README @@ -1,9 +1,10 @@ === pkg.in/lists/tagged === + Этот каталог содержит тегированные списки; на данный момент реализация (../../../bin/tags2lists) требует, чтобы каждый из тегов был отдельным словом, состоящим из символов из набора -a-zA-Z0-9_ (внимание: не используйте в слове "-"); рекомендуется -разделять слова "+". +[a-zA-Z0-9_] (внимание: не используйте в слове "-"); +рекомендуется разделять слова "+". Применение: дополнение жёстко статически заданной функциональности более "плавающим" в долгосрочном плане результатом раскрытия diff --git a/sub.in/README b/sub.in/README index adb6b144..a49df6a0 100644 --- a/sub.in/README +++ b/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/*) diff --git a/sub.in/main/README b/sub.in/main/README index f91902fe..85a57df4 100644 --- a/sub.in/main/README +++ b/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. diff --git a/sub.in/stage1/README b/sub.in/stage1/README index d4eb9b19..289fe339 100644 --- a/sub.in/stage1/README +++ b/sub.in/stage1/README @@ -1,4 +1,5 @@ === sub.in/stage1 === + Этот каталог содержит субпрофиль первой стадии загрузки; здесь место syslinux (загрузчик) и propagator (ориентировка на местности, вытягивание второй стадии с CD/FTP/...).