documentation: use paths relative to toplevel dir

This change is done to reduce ambiguity in some cases;
the previous intention has been to ease navigation when
staying in a particular directory, now it's been changed
in favour of convenient toplevel `git grep' in fact.

Both variants have their pros and cons, I just find myself
leaning to this one by now hence the commit.  Feel free to
provide constructive criticism :)

Some path-related bitrot has also been fixed while at that.
This commit is contained in:
Michael Shigorin 2014-03-05 18:09:56 +04:00
parent 4fff399b35
commit 3f547e2504
25 changed files with 67 additions and 61 deletions

3
README
View File

@ -71,6 +71,9 @@
** pkglists.txt: формирование состава образа
** features.txt: обзор подключаемых особенностей
Примечание: пути в документации задаются от каталога верхнего уровня,
если не указаны как относительные в явном виде (./) или по смыслу.
Удачи; что не так -- пишите.
Michael Shigorin <mike@altlinux.org>

View File

@ -12,7 +12,7 @@
Попросту говоря, copy-paste -- тревожный признак.
По переменным (см. тж. ../doc/pkglists.txt):
По переменным (см. тж. doc/pkglists.txt):
* для пользовательского окружения (live, main) предназначены
THE_PACKAGES, THE_LISTS, THE_GROUPS, THE_PACKAGES_REGEXP

View File

@ -5,7 +5,7 @@ mixin/p7:
ifeq (distro,$(IMAGE_CLASS))
### kludge compatibility: introspection stub for ../main.mk :-/
### kludge compatibility: introspection stub for main.mk :-/
distro/altlinux-p7-cinnamon: distro/regular-cinnamon mixin/p7; @:
distro/altlinux-p7-e17: distro/regular-e17 mixin/p7; @:
distro/altlinux-p7-icewm: distro/regular-icewm mixin/p7; @:

View File

@ -6,91 +6,91 @@
* APTCONF
** задаёт путь к требуемому apt.conf
** значение: пусто (по умолчанию системный) либо строка
** см. ../image.in/Makefile, apt.conf.sample
** см. image.in/Makefile, doc/apt.conf.sample
* ARCH
** задаёт целевую архитектуру образов
** значение: пусто (по умолчанию авто), i586, x86_64, arm, ppc
** см. ../lib/build.mk
** см. lib/build.mk
* ARCHES
** задаёт набор целевых архитектур при параметрическом задании APTCONF
** значение: пусто (по умолчанию авто) либо список через пробел
** см. ../Makefile, profiles.mk.sample
** см. Makefile, doc/profiles.mk.sample
* BELL
** подаёт сигнал после завершения сборки
** значение: пусто (по умолчанию нет) либо любая строка
** см. ../lib/build.mk
** см. lib/build.mk
* BUILDDIR
** задаёт каталог генерируемого профиля и сборки
** значение: пусто (по умолчанию авто) либо строка
** см. ../lib/profile.mk
** см. lib/profile.mk
* BUILDDIR_PREFIX
** задаёт префикс каталога генерируемого профиля и сборки
** значение: строка; по умолчанию выбирается алгоритмически
** см. ../main.mk
** см. main.mk
* BUILDLOG
** задаёт путь к файлу журнала сборки/очистки
** значение: по умолчанию $(BUILDDIR)/build.log либо строка
** см. ../lib/log.mk
** значение: $(BUILDDIR)/build.log (по умолчанию) либо строка
** см. lib/log.mk
* CHECK
** включает режим проверки сборки конфигурации (без сборки образа)
** значение: пусто (по умолчанию) либо любая строка
** см. ../lib/build.mk, ../lib/clean.mk
** см. lib/build.mk, lib/clean.mk
* CLEAN
** экономия RAM+swap при сборке в tmpfs, иначе места на диске
** очистка рабочего каталога после успешной сборки очередной стадии
** может помешать использовать некоторые варианты отладки
** значение: пусто, 0, 1, 2; по умолчанию пусто при DEBUG, иначе 1
** см. ../lib/clean.mk
** см. lib/clean.mk
* DEBUG
** включает средства отладки, может отключить зачистку после сборки
** значение: пусто (по умолчанию), 1 или 2
** см. ../lib/log.mk, ../lib/clean.mk
** см. lib/log.mk, lib/clean.mk
* HOMEPAGE, HOMENAME, HOMEWAIT
** указывают адрес, название и таймаут перехода для домашней страницы
** значение: корректный URL, строка, целое неотрицательное число
** см. ../features.in/live/generate.mk (тж. по умолчаниям)
** см. features.in/live/generate.mk (тж. по умолчаниям)
* ISOHYBRID
** включает создание гибриднго ISO-образа
** значение: пусто (по умолчанию) либо любая строка
** см. ../features.in/pack/config.mk
** см. features.in/pack/config.mk, features.in/isohybrid/config.mk
* NICE
** понижает нагрузку системы сборочной задачей
** значение: пусто (по умолчанию) либо любая строка
** см. ../lib/build.mk
** см. lib/build.mk
* REPORT
** запрашивает создание отчётов о собранном образе
** значение: пусто (по умолчанию) либо любая строка
** NB: в силу специфики обработки передаётся только явно
** см. ../Makefile, ../report.mk, ../lib/report.mk
** см. Makefile, report.mk, lib/report.mk
* ROOTPW
** устанавливает пароль root по умолчанию для образов виртуальных машин
** значение: пусто (по умолчанию root) либо строка
** см. ../features.in/build-vm/image-scripts.d/00root
** см. features.in/deflogin/rootfs/image-scripts.d/50-root
* SAVE_PROFILE
** сохраняет архив сгенерированного профиля в .disk/
** значение: пусто (по умолчанию) либо любая строка
** см. ../image.in/Makefile
** см. image.in/Makefile
* SORTDIR
** дополнительно структурирует каталог собранных образов
** значение: пусто (по умолчанию) либо строка
*** например, '$(IMAGE_NAME)/$(DATE)'
** см. ../image.in/Makefile
** см. image.in/Makefile
* SQUASHFS
** определяет характер сжатия squashfs для stage2
@ -98,18 +98,18 @@
*** пусто (по умолчанию) либо normal: xz
*** tight: xz с -Xbcj по платформе (лучше, но дольше -- подбор в два прохода)
*** fast: gzip/lzo (быстрее запаковывается и распаковывается, меньше степень)
** см. ../features.in/stage2/stage1/scripts.d/03-test-kernel
** см. features.in/stage2/stage1/scripts.d/03-test-kernel
* STATUS
** добавляет в имя образа указанный префикс
** значение:
*** пусто (по умолчанию) либо строка (например, "alpha", "beta")
** см. ../image.in/Makefile
** см. image.in/Makefile
* VM_SIZE
** задаёт размер несжатого образа виртуальной машины в байтах
** значение: пусто (по умолчанию двойной размер чрута) или целое
** см. ../features.in/build-vm/lib/90-build-vm.mk, ../bin/tar2fs
** см. features.in/build-vm/lib/90-build-vm.mk, bin/tar2vm
[float]
=== пример ===

View File

@ -1,7 +1,7 @@
== Списки пакетов ==
Состав пакетной базы субпрофилей определяется значенями
следующих переменных профиля (см. тж. ../conf.d/README;
Состав пакетной базы субпрофилей определяется значениями
следующих переменных профиля (см. тж. conf.d/README;
некоторые "*" ниже заэкранированы ради парсера asciidoc):
* main: пакетная база для установки

View File

@ -21,12 +21,12 @@
цели в UI конфигурирования образа.
Остальное содержимое является дополнительным и используется
в таком порядке (см. ../Makefile):
в таком порядке (см. features.in/Makefile):
* сперва в $(BUILDDIR)/image/ копируются все подкаталоги,
соответствующие итоговым именам субпрофилей, запрошенных
для профиля образа; при этом они сливаются с деревом,
которое уже сформировано субпрофилями (../sub.in/*) и уже
которое уже сформировано субпрофилями (sub.in/*) и уже
скопированными фичами; если какие-либо файлы перекрылись
по именам, rsync должен оставить резервные копии (*~),
которые должны просигнализировать о беспорядке;

View File

@ -8,14 +8,14 @@
других фич либо субпрофилей.
Каждая фича должна содержать файл config.mk, включаемый
в ../main.mk при построении конфигурации будущего профиля;
в main.mk при построении конфигурации будущего профиля;
он может описывать одну или более целей вида use/*,
дополняющих конфигурацию, и обязан добавить имя фичи
в $(FEATURES), для чего создана функция add_feature.
На этапе генерации сборочного профиля фичи рассматриваются
после инициализации профиля (см. ../image.in/) и копирования
субпрофилей (см. ../sub.in/). Для каждой фичи, указанной
после инициализации профиля (см. image.in/) и копирования
субпрофилей (см. sub.in/). Для каждой фичи, указанной
в $(FEATURES), копируются подкаталоги сообразно включенным
субпрофилям, а также lib/ и {image-,}scripts.d/; затем
выполняются generate.sh и generate.mk при их наличии.

View File

@ -1,3 +1,3 @@
# hooked from ../../lib/sugar.mk
# hooked from lib/sugar.mk
use/build-distro:
@$(call add_feature)

View File

@ -1,3 +1,3 @@
# hooked from ../../lib/sugar.mk
# hooked from lib/sugar.mk
use/build-ve: sub/rootfs@/
@$(call add_feature)

View File

@ -1,3 +1,3 @@
Эта фича конфигурирует создание образа виртуальной машины (VM).
Дополняет финальную стадию сборки (lib/, image-scripts.d/).
Требует для работы sudo(8) -- см. тж. ../../doc/vm.txt .
Требует для работы sudo(8) -- см. тж. doc/vm.txt

View File

@ -1,3 +1,3 @@
# hooked from ../../lib/sugar.mk
# hooked from lib/sugar.mk
use/build-vm: sub/rootfs@/ use/kernel use/deflogin
@$(call add_feature)

View File

@ -1,6 +1,6 @@
#!/bin/sh
# predictable file locations make bootloader configuration simple;
# this script relates to .../features.in/stage2/stage1/scripts.d/80-make-initfs
# this script relates to features.in/stage2/stage1/scripts.d/80-make-initfs
kver="$(rpm -qa 'kernel-image*' \
--qf '%{installtime} %{version}-%{name}-%{release}\n' \

View File

@ -2,7 +2,7 @@
Конфигурируется заданием загрузчика (EFI_BOOTLOADER)
и файла сертификата (EFI_CERT) при помощи целей;
пример использования доступен в ../../conf.d/regular.mk
пример использования доступен в conf.d/regular.mk
См. тж.:
* http://www.altlinux.org/UEFI

View File

@ -5,7 +5,7 @@
Можно указать в цепочке зависимостей дистрибутива явно с тем,
чтобы гарантировать гибридный вид образа, либо запросить включение
этой фичи при сборке конфигурации произвольного дистрибутива
(ISOHYBRID=1, см. ../pack/config.mk).
(ISOHYBRID=1, см. features.in/pack/config.mk).
Обратите внимание: в propagator до 20101130-alt15 поддержка
автоматической загрузки с флэш-носителя, содержащего ISO-образ,

View File

@ -3,7 +3,7 @@
# package lists are needed for installer and live-install images
METADIR := files/Metadata
# preparation targets of ../../build-distro/lib/build-distro.mk
# preparation targets of features.in/build-distro/lib/build-distro.mk
WHATEVER += metadata
# handle these too

View File

@ -1,6 +1,6 @@
#!/bin/sh
# gather syslinux configuration from snippets;
# copy modules; see also ../../generate.mk
# copy modules; see also this feature's generate.mk
MODDIR="/usr/lib/syslinux"
CFG="$GLOBAL_BOOTLOADER.cfg"
@ -48,4 +48,4 @@ fi
if [ "$DEBUG" != 2 ]; then rm -r .in/; fi
# NB: there will be final macro expansion based on actual image sizes
# (done by ../../scripts.d/10-propagator-ramdisk)
# done by features.in/syslinux/scripts.d/20-propagator-ramdisk

View File

@ -1,2 +1,4 @@
Эта фича заменяла в базовой системе sysvinit на systemd;
в настоящее время является устаревшей, см. ../init/
в настоящее время является устаревшей, см. features.in/init
# TODO: DROP

View File

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

View File

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

View File

@ -6,4 +6,4 @@
списке, которым является значение переменной MAIN_GROUPS).
В данный момент перенесено почти 1:1 из mkimage-profiles-desktop,
требует увязки с ../lists/tagged/.
требует увязки с pkg.in/lists/tagged/

View File

@ -2,14 +2,14 @@
Этот каталог содержит списки пакетов, копируемые из метапрофиля
в создаваемый профиль по необходимости (определяется по наличию
имён списков в переменных *_LISTS, см. реализацию в Makefile).
имён списков в переменных *_LISTS, см. реализацию в ./Makefile).
Список .base является особенным (формирует базовую систему,
см. http://www.altlinux.org/Alterator-pkg); он создаётся из
содержимого ряда переменных (см. Makefile).
содержимого ряда переменных (см. реализацию).
Подкаталог tagged/ содержит тегированные списки, имена которых
удобно получать функцией tags() (см. ../../lib/functions.mk).
Подкаталог tagged содержит тегированные списки, имена которых
удобно получать функцией tags() (см. lib/functions.mk).
Для выявления дубликатов в составе списков служит `make pkgdups';
пытаться избежать дублей на 100% скорее бесполезно, но бродячие

View File

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

View File

@ -2,12 +2,12 @@
Этот каталог содержит субпрофили; содержимое затребованных
(названия которых содержатся в значении переменной SUBPROFILES,
которую заполняют цели sub/* -- см. ../lib/sugar.mk) будет
которую заполняют цели sub/* -- см. lib/sugar.mk) будет
скопировано в корневой каталог формируемого профиля.
Просьба ответственно относиться к изменению существующих субпрофилей
и вдумчиво -- к созданию новых; возможно, достаточно всего лишь
оформить нужное новой фичей (см. ../features.in/).
оформить нужное новой фичей (см. features.in/).
Обратите внимание: поскольку сборка частей дистрибутивного образа
и происходит в каталогах субпрофилей, то повторное использование
@ -35,4 +35,4 @@
* main: пакетная база, укладываемая на образ (NB: поскольку рабочий
чрут в этом случае не содержит ничего, кроме пакетов, добавлять
image-scripts.d/* смысла нет, только scripts.d/*)
что-либо в image-scripts.d смысла нет, только в scripts.d)

View File

@ -44,7 +44,7 @@ GLOBAL_SQUASHFS := $(SQUASHFS)
-include $(sort $(wildcard lib/*.mk))
# scripts prepare bootloader configuration, too
# NB: we pass tested squashfs options for ../stage2/Makefile to include
# NB: we pass tested squashfs options for sub.in/stage2/Makefile to include
all: | debug prepare-workdir copy-tree run-scripts $(BUILD_PROPAGATOR) \
copy-$(BOOTLOADER) $(COPY_SQUASHCFG) pack-image $(GLOBAL_CLEAN_WORKDIR)
@if [ -s $(OUTDIR)/squashcfg.mk ]; then \

View File

@ -13,7 +13,8 @@ include $(GLOBAL_BUILDDIR)/distcfg.mk
include $(GLOBAL_BUILDDIR)/functions.mk
include $(MKIMAGE_PREFIX)/config.mk
# this might have been prepared by ../stage1/scripts.d/03-test-kernel
# this might have been prepared
# by features.in/stage2/stage1/scripts.d/03-test-kernel
-include $(GLOBAL_BUILDDIR)/squashcfg.mk
# this should be brought in by corresponding specific stage2 feature
@ -39,7 +40,7 @@ IMAGE_PACKAGES_REGEXP += $(call kpackages, \
-include $(sort $(wildcard lib/*.mk))
# see also scripts.d/99-elf-stats
# see also ./scripts.d/99-elf-stats
ifdef GLOBAL_SQUASHFS_SORT
ifeq (tight,$(SQUASHFS))
CHROOT_PACKAGES += file