docs day

ToC:
- introduced doc/
- features.in/00example/
- READMEs and TODO for more
- code comments clarified

Some unrelated minor fixes bundled either.

README

@@ -13,6 +13,11 @@ make distclean server-light.iso
 - для сборки подыскивается предпочтительно tmpfs
 - в профиль копируются только нужные объекты
 
+Стадии работы:
+- сборка конфигурации дистрибутива
+- порождение дистрибутивного профиля
+- сборка дистрибутива
+
 Объекты:
 - дистрибутивы: distro.mk, могут основываться один на другом;
   желательно избегать множественного наследования, используя
@@ -36,3 +41,7 @@ make distclean server-light.iso
   (из того же config.mk, который будет включён в distro.mk)
 - списки пакетов: большая человеческая просьба по возможности
   избегать дублирования и подумать над pkg/lists/tagged...
+
+NB: следует крайне осторожно пользоваться COMMON_PACKAGES,
+    т.к. указанные пакеты попадут во все стадии (в т.ч.
+    stage1 и install2, чувствительные к объёму).

TODO

@@ -0,0 +1 @@
+- кратко описать каждый субпрофиль и каждую фичу

distro.mk

@@ -1,4 +1,7 @@
 # build up distribution's configuration
+#
+# NB: distro/ targets should be defined here,
+# see toplevel Makefile's $(DISTRO) assignment
 CONFIG = $(BUILDDIR)/.config.mk
 
 # source initial feature snippets
@@ -25,7 +28,7 @@ distro/init:
 	@echo "** starting distro configuration build process"
 	@:> $(CONFIG)
 
-distro/base: distro/init sub/stage1 use/syslinux/localboot.cfg
+distro/base: distro/init sub/stage1 use/syslinux use/syslinux/localboot.cfg
 	@$(call set,KFLAVOUR,std-def)
 	@$(call set,IMAGE_INIT_LIST,+branding-$$(BRANDING)-release)
 	@$(call set,BRANDING,altlinux-desktop)	###

doc/features.txt

@@ -0,0 +1,21 @@
+Особенности дистрибутива, не учитываемые в пакетной базе
+или зависящие от переменных времени сборки/установки образа,
+могут быть оформлены несколькими образами:
+
+* scripts.d/ или image-scripts.d/ различных стадий;
+* пакеты installer-feature-*
+  (тж. http://www.altlinux.org/Installer/beans).
+
+В большинстве случаев можно рекомендовать создание feature
+средствами метапрофиля, поскольку при этом дерево кода более
+удобно для анализа и обновления (и в отличие от m-p-d, нет
+вынужденной необходимости либо контролировать включение нужных
+фич "вручную" в скриптах по косвенным признакам, либо выносить
+их в пакеты installer-feature-*).
+
+Создание и упаковку installer-feature-* можно рекомендовать, если:
+
+* необходимы пакетные зависимости;
+* требуется компилируемый платформозависимый код (для чего бы...);
+* код фичи достаточно специфичен, нетривиален и объёмен,
+  чтобы загромождать метапрофиль было не очень осмысленно.

features.in/00example/README

@@ -0,0 +1,46 @@
+Этот каталог содержит "заготовку" фичи в качестве примера
+и должен дать представление о том, какой код _может_ быть
+включён в настоящую фичу: статические файлы, два makefile
+для создания конфигурации и генерирования части профиля,
+а также шелл-скрипт для генерирования.
+
+Вовсе не требуется втягивать всё в свою фичу, лучше постараться
+сделать её минимальной, самодостаточной и полезной в качестве
+"кирпичика".
+
+Единственной необходимой частью фичи является файл config.mk,
+который включается в distro.mk верхнего уровня и предоставляет
+цель вида use/*, специфичную для данной фичи (а также добавляет
+её в переменную FEATURES -- к сожалению, реализовать добавление
+автоматом не представляется возможным).  Если название фичи не
+упоминается в списке, содержащемся в этой переменной, то она
+и не задействуется при построении профиля.
+
+Остальное содержимое является дополнительным и используется
+в таком порядке (см. features.in/Makefile):
+
+- сперва в $(BUILDDIR)/image/ копируются все подкаталоги,
+  соответствующие именам субпрофилей, запрошенных для
+  дистрибутивного профиля; при этом они сливаются с деревом,
+  которое уже сформировано субпрофилями (../sub.in/*) и уже
+  скопированными фичами; если какие-либо файлы перекрылись
+  по именам, rsync должен оставить резервные копии (*~),
+  которые должны просигнализировать о беспорядке;
+
+- затем запускается generate.sh, если существует и исполнимый;
+
+- затем используется generate.mk, если существует и непустой.
+
+Например, если дистрибутив требует субпрофили stage1, install2
+и main, вы можете решить собрать специфические для фичи скрипты
+инсталятора в install2/image-scripts.d/ (или необходимые для
+операций с пакетной базой -- в main/scripts.d/, смотря чего надо
+добиться; загляните также в документацию mkimage).
+
+А если требуются нетривиальные действия по конфигурированию
+(как при сборке syslinux.cfg из кусочков, в зависимости от того,
+что из запрошенных модулей оказалось в наличии) -- то их можно
+произвести из generate.sh и generate.mk.
+
+Пожалуйста, присылайте отзывы о (бес)полезности кода в этом каталоге
+mike@altlinux.

features.in/00example/README.en

@@ -0,0 +1,43 @@
+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/00example/config.mk

@@ -0,0 +1,13 @@
+# this Makefile snippet gets included from toplevel distro.mk;
+# it can add additional targets which could then be used there,
+# and which can depend on other targets defined in any makefile
+# included from toplevel Makefile
+#
+# see also toplevel functions.mk for the "add" function definition,
+# and distro.mk for usage examples
+#
+# for somewhat more involved example, see syslinux feature
+
+use/00example: sub/main use/anotherfeature
+	@$(call add,FEATURES,00example)
+	@$(call add,MAIN_PACKAGES,hello)

features.in/00example/generate.mk

@@ -0,0 +1,20 @@
+# this makefile is used as the last step during an individual
+# feature configuration (that is, while building the actual profile
+# from subprofiles and requested features)
+#
+# please note, it runs *after* copying subdirectories corresponding
+# to requested subprofiles and *after* running generate.sh, see also
+# features.in/Makefile
+#
+# for a real-world example, see syslinux feature
+
+include $(BUILDDIR)/.config.mk
+
+ifndef 00EXAMPLE
+$(warning this is an example, who might want to include it? :])
+endif
+
+EXAMPLE := hello, world
+
+all:
+	@echo $(EXAMPLE)

features.in/00example/generate.sh

@@ -0,0 +1,20 @@
+#!/bin/sh
+# this script is run during an individual feature configuration
+# (that is, while building the actual profile from subprofiles
+# and requested features); it can be more comfortable for extensive
+# shell scripting than embedding into a makefile recipe with all
+# the quoting and so on
+#
+# please note, it runs *after* copying subdirectories corresponding
+# to requested subprofiles and *before* running generate.sh, see also
+# features.in/Makefile
+#
+# for a real-world example, see syslinux feature
+
+# route stdout to stderr
+exec >&2
+
+# dump environment
+echo "--- $0 ---"
+env
+echo "--- $0 ---"

features.in/00example/main/scripts.d/89-example

@@ -0,0 +1,13 @@
+#!/bin/sh
+# example script executed by mkimage in _instrumental_ chroot
+# (image-scripts.d/* get executed in _work_ chroot)
+#
+# NB: to be executed, it must be marked executable first :)
+
+# let's do something very useful
+echo "$0: WORKDIR=$WORKDIR; directory listig:"
+ls -l "$WORKDIR"
+
+# and let's _not_ terminate with non-zero for no real reason;
+# ":" is a shell builtin command like true(1)
+:

features.in/README

@@ -0,0 +1,21 @@
+Этот каталог содержит т.н. фичи (features, особенности) --
+каталоги, содержимое каждого из которых реализует одну из
+подключаемых автономных возможностей дистрибутива.
+
+Каждая фича должна содержать файл config.mk, включаемый
+в ../distro.mk и как минимум содержащий добавление имени
+этой фичи в переменную FEATURES на этапе создания конфигурации
+профиля.
+
+На этапе создания собственно профиля этот каталог задействуется
+после инициализации профиля (см. ../image.in/) и копирования
+субпрофилей (см. ../sub.in/); обход его подкаталогов производится
+в порядке отсортированных по алфавиту имён из списка,
+содержащегося в переменной FEATURES.
+
+Для каждой фичи производится копирование подкаталогов,
+соответствующих запрошенным субпрофилям, а также выполняется
+скрипт generate.sh и задействуется generate.mk (при их наличии).
+
+Несложный пример содержится в 00example/, более близкий к жизни
+и нынешним пределам возможностей метапрофиля -- в syslinux/.

features.in/hdt/README

@@ -0,0 +1,5 @@
+Добавление модуля hdt (Hardware Detection Tool COM32 module) к syslinux;
+может быть востребовано для инсталяторов, live/rescue.
+
+TODO: недоступно Memory->memtest; может иметь смысл класть сжатые gzip
+pci.ids и modules.pcimap.

features.in/hdt/config.mk

@@ -1,5 +1,4 @@
-# no "Memory" in hdt's menu, weird
-use/hdt: use/memtest
+use/hdt: use/syslinux
 	@$(call add,SYSLINUX_MODULES,hdt)
 	@$(call add,SYSLINUX_FILES,/usr/share/pci.ids)
 

features.in/memtest/README

@@ -0,0 +1,5 @@
+Добавление memtest86+ в загрузку с образа и в устанавливаемую пакетную базу;
+востребовано для для инсталяторов, live/rescue.
+
+NB: интегрируется с syslinux (проверено/работает), но _не_ требует
+use/syslinux на случай, если прикрутим поддержку других загрузчиков.

features.in/syslinux/README

@@ -0,0 +1,11 @@
+Добавление поддержки syslinux; требуется для инсталяторов, live/rescue.
+
+Цели:
+
+* use/syslinux/ui-% -- конфигурирование интерфейса (см. cfg.in/00*.cfg);
+  при использовании автоматически добавляют syslinux в FEATURES
+
+* use/syslinux/%.com, use/syslinux/%.c32 -- подключение одноименных модулей
+  (копирование бинарников и включение кусочков конфигурации; экспериментальное)
+
+* use/syslinux/%.cfg -- подключение кусочков конфигурации (используется)

features.in/syslinux/config.mk

@@ -1,17 +1,19 @@
-# UI is overwritten and _does_ automatically enable the feature...
-use/syslinux/ui-%:
+# default is plain text prompt
+use/syslinux:
 	@$(call add,FEATURES,syslinux)
-	@$(call set,SYSLINUX_UI,$*)
 	@$(call add,STAGE1_PACKAGES,syslinux)
-	if [ "$*" == gfxboot ]; then \
+
+# UI is overwritten
+use/syslinux/ui-%: use/syslinux
+	@$(call set,SYSLINUX_UI,$*)
+	@if [ "$*" == gfxboot ]; then \
 		$(call add,STAGE1_PACKAGES,gfxboot); \
 		$(call add,STAGE1_PACKAGES,branding-$$(BRANDING)-bootloader); \
 	fi
 
-# ...while plain modules...
-use/syslinux/%.com use/syslinux/%.c32:
+# modules and config snippets just add up
+use/syslinux/%.com use/syslinux/%.c32: use/syslinux
 	@$(call add,SYSLINUX_MODULES,$*)
 
-# ...and menu items don't autoenable it (but stack up themselves)
-use/syslinux/%.cfg:
+use/syslinux/%.cfg: use/syslinux
 	@$(call add,SYSLINUX_CFG,$*)

features.in/syslinux/generate.mk

@@ -5,7 +5,7 @@ $(warning syslinux feature enabled but BOOTLOADER undefined)
 endif
 
 ifndef SYSLINUX_UI
-$(warning no syslinux ui module configured, falling back to plain text prompt)
+$(warning no syslinux ui configured, default is plain text prompt)
 SYSLINUX_UI := prompt
 endif
 
@@ -33,19 +33,19 @@ cfg = $(wildcard cfg.in/??$(1).cfg)
 
 # NB: list position determined by file numbering (*.cfg sorting)
 all: prep debug
-	cat $(sort \
+	@cat $(sort \
 		$(foreach C,$(SYSLINUX_CFG),$(call cfg,$(C))) \
 		$(foreach M,$(SYSLINUX_MODULES), \
 			$(shell cp -pLt $(DSTDIR) -- $(call sysmod,$(M)) && echo $(call cfg,$(M))))) \
 		/dev/null > $(CONFIG)
-	[ -z "$(SYSLINUX_FILES)" ] || { \
+	@[ -z "$(SYSLINUX_FILES)" ] || { \
 		cd $(MODDIR); \
 		cp -pLt $(DSTDIR) -- $(SYSLINUX_FILES); \
 	}
 
 # cat's argument gets evaluated before recipe body execution
 prep:
-	mkdir -p $(DSTDIR)
+	@mkdir -p $(DSTDIR)
 
 # for p in $...; do ls ??$p.cfg; done | sort
 debug:

image.in/README

@@ -0,0 +1,13 @@
+Этот каталог копируется из метапрофиля в профиль "как есть"
+и формирует "затравку", собирающую собственно образ из результатов
+работы индивидуальных субпрофилей (в т.ч. стадий инсталятора,
+см. ../sub.in/).
+
+Содержимое files/ копируется в корень образа.
+
+Пакетная база рабочего чрута минимальна; apt-utils включены
+ради genbasedir, который после завершения первоначального
+наполнения субпрофилей может переехать в ../sub.in/main/.
+
+Если требуется какая-либо иная обработка чрута, следует
+предпочитать scripts.d/.

pkg.in/README

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

pkg.in/groups/README

@@ -0,0 +1,6 @@
+Этот каталог содержит описания групп, копируемые из метапрофиля
+в создаваемый профиль по необходимости (только фигурирующие в
+списке, которым является значение переменной GROUPS).
+
+В данный момент перенесено почти 1:1 из mkimage-profiles-desktop,
+требует увязки с ../lists/tagged/.

pkg.in/lists/README

@@ -0,0 +1,12 @@
+Этот каталог содержит списки пакетов, копируемые из метапрофиля
+в создаваемый профиль по необходимости (определяется по наличию
+имён списков в переменных *_LISTS, см. реализацию в Makefile).
+
+Список .base является особенным (формирует базовую систему,
+см. http://www.altlinux.org/Alterator-pkg) и копируется безусловно.
+Это предполагается изменить в будущем -- возможно, генерацией .base
+по тегам.
+
+Подкаталог tagged/ стоит рассматривать как экспериментальный,
+хотя весь необходимый код уже на месте -- см. bin/tags2lists
+и distro.mk (в корневом каталоге).

pkg.in/lists/http-server

@@ -4,7 +4,6 @@ php5
 php5-cgi
 php5-curl
 php5-dba
-php5-dbase
 php5-dom
 php5-eaccelerator
 php5-exif
@@ -18,7 +17,6 @@ php5-mbstring
 php5-mcrypt
 php5-memcache
 php5-mhash
-php5-mime_magic
 php5-mysql
 php5-pgsql
 php5-rrdtool
@@ -28,6 +26,5 @@ php5-xsl
 php5-zip
 MySQL-bench
 MySQL-client
-MySQL-htmlhelp
 MySQL-server-perl
 

pkg.in/lists/mysql-server

@@ -1,6 +1,5 @@
 MySQL-bench
 MySQL-client
 MySQL-server
-MySQL-htmlhelp
 MySQL-server-perl
 

pkg.in/lists/tagged/README

@@ -0,0 +1,10 @@
+Этот каталог содержит тегированные списки; на данный момент
+реализация (bin/tags2lists) требует "терминирования" имени,
+а точнее -- каждого тега, ограничительным символом с каждой
+стороны; на данный момент в качестве такого символа выбрано
+подчёркивание "_", хотя ничто не мешает сменить его или же
+расширить список допустимых символов (с заменой -name на
+-path в скрипте может оказаться интересным вариант "/").
+
+Реализация является экспериментальной и требует утряски
+с ../groups/; комментарии и помощь всячески приветствуются.

sub.in/README

@@ -0,0 +1,21 @@
+Этот каталог содержит субпрофили; содержимое заказанных
+в формируемый профиль (названия которых содержатся в значении
+переменной SUBPROFILES, которую обычно заполняют цели sub/* --
+см. ditro.mk в корневом каталоге) будет скопировано в каталог
+$(BUILDDIR)/image/.
+
+Просьба ответственно относиться к модификации существующих
+и вдумчиво -- к созданию новых; возможно, достаточно всего лишь
+оформить нужное новой фичей (см. ../features.in/).
+
+Краткое описание существующих:
+
+- stage1: propagator и загрузчик (при подключении фичи syslinux);
+  типично требуется для инсталяторов, live- и rescue-образов
+
+- install2: installer, installer-feature-*-stage2 и прочее обычно
+  востребованное в инсталяционных образах
+
+- main: пакетная база, укладываемая на образ (NB: поскольку рабочий
+  чрут в этом случае не содержит ничего, кроме пакетов, добавлять
+  image-scripts.d/* смысла нет, только scripts.d/*)

sub.in/install2/README

@@ -0,0 +1,8 @@
+Этот каталог содержит субпрофиль второй стадии инсталятора,
+требующийся для сборки инсталяционных образов.
+
+При добавлении скриптов в image-scripts.d/ следует позаботиться,
+чтобы в компактном livecd, которым является инсталятор, оказались
+нужные утилиты (INSTALL2_PACKAGES).  Перегружать его не следует.
+
+Результат -- squashfs-образ в файле altinst.

sub.in/main/README

@@ -0,0 +1,11 @@
+Этот каталог содержит субпрофиль main, собирающий пакетную базу,
+которая затем укладывается в образ.
+
+Подбирает MAIN_PACKAGES, а также BASE_LISTS (в установку)
+и DISK_LISTS (дополнительные пакеты).
+
+В image-scripts.d/* смысла нет, только scripts.d/* --
+рабочий чрут не содержит исполняемых файлов.
+
+Результат -- каталог ALTLinux/RPMS.main, подлежащий копированию
+в образ.

sub.in/stage1/README

@@ -0,0 +1,9 @@
+Этот каталог содержит субпрофиль первой стадии загрузки;
+здесь место syslinux (загрузчик) и propagator (ориентировка
+на местности, вытягивание второй стадии с CD/FTP/...).
+
+Скрипты обычно запускаются извне формируемого образа,
+т.е. это scripts.d/; следует крайне бережно относиться
+к составу STAGE1_PACKAGES и объёму этой стадии.
+
+Требуется для инсталяционных, live- и rescue-образов.