From c08e86afc56b73ab70bb3be2276fc65291bff3f7 Mon Sep 17 00:00:00 2001 From: Michael Shigorin Date: Sat, 11 Aug 2012 21:45:26 +0300 Subject: [PATCH] features: hopefully better README Thanks both drool@ for his mild frustration with the current documentation as well as Greg Kroah-Hartman, Heikki Orsila and Neil Brown for http://lwn.net/Articles/504814/ -- the docs should really emphasize *why* something is done, not *how*, as the "how" part is better documented with the code itself (that doesn't mean that "the big picture" isn't needed). --- features.in/README | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/features.in/README b/features.in/README index 45064db3..8683c666 100644 --- a/features.in/README +++ b/features.in/README @@ -1,28 +1,28 @@ -Этот каталог содержит т.н. фичи (features, особенности) -- -каталоги, содержимое каждого из которых реализует одну из -подключаемых автономных возможностей образа. +Этот каталог содержит т.н. фичи (features, особенности). -Каждая фича должна содержать задействуемый при построении -конфигурации будущего образа файл config.mk, включаемый -в ../main.mk; он может описывать одну или более целей -вида use/*, дополняющих конфигурацию, и при наличии -дополнительных хуков для копирования или generate.* -обязан добавить имя фичи в $(FEATURES), для чего -создана функция add_feature без аргументов. +Фича -- отдельно подключаемая сущность, которая содержит +повторно используемые конфигурацию/код и определяет одну +из особенностей создаваемого образа. Может зависеть от +других фич либо субпрофилей. + +Каждая фича должна содержать файл config.mk, включаемый +в ../main.mk при построении конфигурации будущего профиля; +он может описывать одну или более целей вида use/*, +дополняющих конфигурацию, и обязан добавить имя фичи +в $(FEATURES), для чего создана функция add_feature. На этапе генерации сборочного профиля фичи рассматриваются после инициализации профиля (см. ../image.in/) и копирования субпрофилей (см. ../sub.in/). Для каждой фичи, указанной -в $(FEATURES), копируются подкаталоги сообразно субпрофилям, -а также производится обработка {image-,}scripts.d/; затем -выполняется скрипт generate.sh и задействуется generate.mk -(при их наличии). +в $(FEATURES), копируются подкаталоги сообразно включенным +субпрофилям, а также lib/ и {image-,}scripts.d/; затем +выполняются generate.sh и generate.mk при их наличии. Если фича дополняет хуками семейство целевых субпрофилей, построенных на одном базовом, можно воспользоваться подкаталогом с именем исходного базового субпрофиля (см. $src, $dst в Makefile). -Наиболее употребительные цели можно снабжать "ярлычками" вроде +Наиболее востребованные цели можно снабжать "ярлычками" вроде "+icewm" с тем, чтобы сделать более краткими и выразительными использующие их правила. Просьба не злоупотреблять количеством.