diff options
Diffstat (limited to 'docs/manual/writing-rules.txt')
-rw-r--r-- | docs/manual/writing-rules.txt | 125 |
1 files changed, 125 insertions, 0 deletions
diff --git a/docs/manual/writing-rules.txt b/docs/manual/writing-rules.txt new file mode 100644 index 000000000..e0a5a2afd --- /dev/null +++ b/docs/manual/writing-rules.txt @@ -0,0 +1,125 @@ +// -*- mode:doc; -*- + +Writing rules +------------- + +Overall, those writing rules are here to help you add new files in +Buildroot or refactor existing ones. + +If you slightly modify some existing file, the important thing is +keeping the consistency of the whole file, so you can: +* either follow the potentially deprecated rules used all over this +file +* or entirely rework it in order to make it comply with those rules. + +[[writing-rules-config-in]] + ++Config.in+ file +~~~~~~~~~~~~~~~~ + ++Config.in+ files contain entries for almost anything configurable in +Buildroot. + +An entry has the following pattern: + +--------------------- +config BR2_PACKAGE_LIBFOO + bool "libfoo" + depends on BR2_PACKAGE_LIBBAZ + select BR2_PACKAGE_LIBBAR + help + This is a comment that explains what libfoo is. + + http://foosoftware.org/libfoo/ +--------------------- + +* The +bool+, +depends on+, +select+ and +help+ lines are indented + with one tab. + +* The help text itself should be indented with one tab and two + spaces. + +The configuration system used in Buildroot, so the content of the ++Config.in+ files, is regular _Kconfig_. Further details about +_Kconfig_: refer to +http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[]. + +[[writing-rules-mk]] + +The +.mk+ file +~~~~~~~~~~~~~~ + +* Assignment: use +=+ preceded and followed by one space: ++ +--------------------- +LIBFOO_VERSION = 1.0 +LIBFOO_CONF_OPT += --without-python-support +--------------------- + +* Indentation: use tab only: ++ +--------------------- +define LIBFOO_REMOVE_DOC +$(RM) -fr $(TARGET_DIR)/usr/share/libfoo/doc \ + $(TARGET_DIR)/usr/share/man/man3/libfoo* +endef +--------------------- + +* Optional dependency: + +** Prefer multi-line syntax. ++ +YES: ++ +--------------------- +ifeq ($(BR2_PACKAGE_PYTHON),y) +LIBFOO_CONF_OPT += --with-python-support +LIBFOO_DEPENDENCIES += python +else +LIBFOO_CONF_OPT += --without-python-support +endif +--------------------- ++ +NO: ++ +--------------------- +LIBFOO_CONF_OPT += --with$(if $(BR2_PACKAGE_PYTHON),,out)-python-support +LIBFOO_DEPENDENCIES += $(if $(BR2_PACKAGE_PYTHON),python,) +--------------------- + +** Keep configure options and dependencies close together. + +* Optional hooks: keep hook definition and assignment together in one + if block. ++ +YES: ++ +--------------------- +ifneq ($(BR2_LIBFOO_INSTALL_DATA),y) +define LIBFOO_REMOVE_DATA + $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data +endef +LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA +endif +--------------------- ++ +NO: ++ +--------------------- +define LIBFOO_REMOVE_DATA + $(RM) -fr $(TARGET_DIR)/usr/share/libfoo/data +endef + +ifneq ($(BR2_LIBFOO_INSTALL_DATA),y) +LIBFOO_POST_INSTALL_TARGET_HOOKS += LIBFOO_REMOVE_DATA +endif +--------------------- + +The documentation +~~~~~~~~~~~~~~~~~ + +The documentation uses the +http://www.methods.co.nz/asciidoc/[asciidoc] format. + +Further details about the http://www.methods.co.nz/asciidoc/[asciidoc] +syntax: refer to http://www.methods.co.nz/asciidoc/userguide.html[]. |