From patchwork Sun Sep 9 23:40:46 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: [1/7] docs/manual: update 'adding packages' with the new _AVAILABLE symbol Date: Sun, 09 Sep 2012 13:40:46 -0000 From: "Yann E. MORIN" X-Patchwork-Id: 182756 Message-Id: <1347234052-10527-2-git-send-email-yann.morin.1998@free.fr> To: buildroot@busybox.net Cc: Thomas Petazzoni , "Yann E. MORIN" Signed-off-by: "Yann E. MORIN" --- docs/manual/adding-packages-autotools.txt | 48 ++++++-- docs/manual/adding-packages-directory.txt | 190 +++++++++++++++-------------- docs/manual/adding-packages-generic.txt | 85 ++++++++----- 3 files changed, 191 insertions(+), 132 deletions(-) diff --git a/docs/manual/adding-packages-autotools.txt b/docs/manual/adding-packages-autotools.txt index 9fb0918..0f14489 100644 --- a/docs/manual/adding-packages-autotools.txt +++ b/docs/manual/adding-packages-autotools.txt @@ -20,10 +20,24 @@ package, with an example : 08: LIBFOO_SITE = http://www.foosoftware.org/download 09: LIBFOO_INSTALL_STAGING = YES 10: LIBFOO_INSTALL_TARGET = YES -11: LIBFOO_CONF_OPT = --enable-shared -12: LIBFOO_DEPENDENCIES = libglib2 host-pkg-config -13: -14: $(eval $(autotools-package)) +11: LIBFOO_DEPENDENCIES = host-libaaa libbbb +12: +13: ifeq ($(BR2_PACKAGE_LIBFOO_FROBBLE),y) +14: LIBFOO_CONF_OPT += --enable-frobble +15: else +16: LIBFOO_CONF_OPT += --disable-frobble +17: endif +18: +19: LIBFOO_CONF_OPT += --with-gazzle-level=$(BR2_PACKAGE_LIBFOO_GAZZLE_LEVEL) +20: +21: ifeq ($(BR2_PACKAGE_LIBFOO_GOO),y) +22: LIBFOO_DEPENDENCIES += goo +23: LIBFOO_CONF_OPT += --enable-goo +24: else +25: LIBFOO_CONF_OPT += --disable-goo +26: endif +27: +28: $(eval $(autotools-package)) ------------------------ On line 6, we declare the version of the package. @@ -50,16 +64,26 @@ installation is enabled, so in fact, this line is not strictly necessary. Also by default, packages are installed in this location using the +make install+ command. -On line 11, we tell Buildroot to pass a custom configure option, that -will be passed to the +./configure+ script before configuring -and building the package. +On line 11, we declare our dependencies, so that they are built before the +build process of our package starts. -On line 12, we declare our dependencies, so that they are built -before the build process of our package starts. +On lines 13 to 17, if the user selected the option 'frobble' ++BR2_PACKAGE_LIBFOO_FROBBLE+, we add the corresponding configure option +to enable 'frobble' (line 14), or disable it (line 16), that will be +passed to the +./configure+ script before configuring and building the +package. -Finally, on line line 14, we invoke the +autotools-package+ -macro that generates all the Makefile rules that actually allows the -package to be built. +Similarly, on line 19, we add the configure option that defines the +'bazzle level' +BR2_PACKAGE_LIBFOO_GAZZLE_LEVEL+. + +On lines 21 to 26, if user selected the option 'goo' +BR2_PACKAGE_LIBFOO_GOO+, +we add a dependency on the package +goo+ (line 22), and add the corresponding +configure option to enable 'goo' (line 23); or if 'goo' support is not +selected, we pass the configure option to disable it (line 25). + +Finally, on line line 28, we invoke the +autotools-package+ macro that +generates all the Makefile rules that actually allows the package to be +built. [[autotools-package-reference]] diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt index 4a96415..4863332 100644 --- a/docs/manual/adding-packages-directory.txt +++ b/docs/manual/adding-packages-directory.txt @@ -12,30 +12,37 @@ one of these categories, then create your package directory in these. +Config.in+ file ~~~~~~~~~~~~~~~~ -Then, create a file named +Config.in+. This file will contain the -option descriptions related to our +libfoo+ software that will be used -and displayed in the configuration tool. It should basically contain: +Then, create a file named +Config.in+. This file will contain the option +descriptions related to our +libfoo+ software that will be used and +displayed in the configuration tool. It should basically contain: --------------------------- +config BR2_PACKAGE_LIBFOO_AVAILABLE + def_bool y + config BR2_PACKAGE_LIBFOO bool "libfoo" + depends on BR2_PACKAGE_LIBFOO_AVAILABLE help This is a comment that explains what libfoo is. http://foosoftware.org/libfoo/ --------------------------- -The +bool+ line, +help+ line and other meta-informations about the -configuration option must be indented with one tab. The help text -itself should be indented with one tab and two spaces, and it must -mention the upstream URL of the project. +*Notes* + +* This is a very simple example, not really complete, for a very simple + package with no dependency. + +* The syntax of the +Config.in+ file is the same as the one for the kernel + Kconfig file. The documentation for this syntax is available at: + https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=Documentation/kbuild/kconfig-language.txt[] + +* The +bool+ line, +help+ line and other meta-informations about the + configuration option must be indented with one tab. The help text + itself should be indented with one tab and two spaces, and it must + mention the upstream URL of the project. -Of course, you can add other sub-options into a +if -BR2_PACKAGE_LIBFOO...endif+ statement to configure particular things -in your software. You can look at examples in other packages. The -syntax of the +Config.in+ file is the same as the one for the kernel -Kconfig file. The documentation for this syntax is available at -http://lxr.free-electrons.com/source/Documentation/kbuild/kconfig-language.txt[] Finally you have to add your new +libfoo/Config.in+ to +package/Config.in+ (or in a category subdirectory if you decided to @@ -47,103 +54,108 @@ supposed to contain anything but the 'bare' name of the package. source "package/libfoo/Config.in" -------------------------- -The +Config.in+ file of your package must also ensure that -dependencies are enabled. Typically, Buildroot uses the following -rules: +The +Config.in+ file for your package must also ensure that its +dependencies are available. This is done in four steps: -* Use a +select+ type of dependency for dependencies on - libraries. These dependencies are generally not obvious and it - therefore make sense to have the kconfig system ensure that the - dependencies are selected. For example, the _libgtk2_ package uses - +select BR2_PACKAGE_LIBGLIB2+ to make sure this library is also - enabled. +1. The +BR2_PACKAGE_LIBFOO_AVAILABLE+ symbol shall +depends on+ any +other package's +_AVAILABLE+ symbol. It may also depend on any other +symbol, such as toolchain features, but should not directly depend on +any package's main symbol. -* Use a +depends on+ type of dependency when the user really needs to - be aware of the dependency. Typically, Buildroot uses this type of - dependency for dependencies on toolchain options (large file - support, RPC support, IPV6 support), or for dependencies on "big" - things, such as the X.org system. In some cases, especially - dependency on toolchain options, it is recommended to add a - +comment+ displayed when the option is not enabled, so that the user - knows why the package is not available. +1. The main +BR2_PACKAGE_LIBFOO+ symbol should directly +depends +on+ it's own +_AVAILABLE+ symbol, +BR2_PACKAGE_LIBFOO_AVAILABLE+, and +should not depend on any other symbol. -An example illustrates both the usage of +select+ and +depends on+. +1. For each +_AVAILABLE+ symbol your package's own +_AVAILABLE+ +symbol depends on, your package's main symbol should +select+ the +corresponding package's main symbol. + +1. Add a +comment+ briefly explaining why your package is not +available. That +comment+ shall have a single negative dependency on +your package's +_AVAILABLE+ symbol. + +The example below illustrates this mechanism for our libfoo package: -------------------------- -config BR2_PACKAGE_ACL - bool "acl" - select BR2_PACKAGE_ATTR - depends on BR2_LARGEFILE - help - POSIX Access Control Lists, which are used to define more - fine-grained discretionary access rights for files and - directories. - This package also provides libacl. - - http://savannah.nongnu.org/projects/acl - -comment "acl requires a toolchain with LARGEFILE support" - depends on !BR2_LARGEFILE +config BR2_PACKAGE_LIBFOO_AVAILABLE + def_bool y + depends on BR2_LARGEFILE + depends on BR2_PACKAGE_LIBBAR + +comment "libfoo requires libbar, and a toolchain with support for LARGEFILEs" + depends on !BR2_PACKAGE_LIBFOO_AVAILABLE + +config BR2_PACKAGE_LIBFOO + bool "libfoo" + depends on BR2_PACKAGE_LIBFOO_AVAILABLE + select BR2_PACKAGE_LIBBAR + help + This is a comment that explains what libfoo is. + + http://foosoftware.org/libfoo/ -------------------------- +*Notes* + +* Even if your package does not have any dependency, you should anyway + add the corresponding +_AVAILABLE+ symbol. This way, other packages can + safely use the mechanism above to select your package, even if it is later + updated and dependencies are added (eg. a new version of the package is + released; or features, initially disabled, are now enabled...) + +* The symbols and the comment should be in this order, so that the + +menuconfig+ will be properly laid out. + +* The dependencies in +Config.in+ will make sure that your package's + dependencies options are also enabled, but they will not necessarily be + built before your package. To do so, these dependencies also need to be + expressed in the +.mk+ file of the package (see below). -Note that these two dependency types are only transitive with the -dependencies of the same kind. +If your package can be fine-tuned, you can add sub-options, enclosed inside +an +if BR2_PACKAGE_LIBFOO ... endif+ block. You can even have each option +depend on other packages, using the +_AVAILABLE+ and main symbols for +those pacakges. -This means, in the following example: +Finally, here's our now-complete example package: -------------------------- -config BR2_PACKAGE_A - bool "Package A" +config BR2_PACKAGE_LIBFOO_AVAILABLE + def_bool y + depends on BR2_LARGEFILE + depends on BR2_PACKAGE_LIBBAR -config BR2_PACKAGE_B - bool "Package B" - depends on BR2_PACKAGE_A +comment "libfoo requires libbar" + depends on !BR2_PACKAGE_LIBFOO_AVAILABLE -config BR2_PACKAGE_C - bool "Package C" - depends on BR2_PACKAGE_B +config BR2_PACKAGE_LIBFOO + bool "libfoo" + depends on BR2_PACKAGE_LIBFOO_AVAILABLE + select BR2_PACKAGE_LIBBAR + help + This is a comment that explains what libfoo is. -config BR2_PACKAGE_D - bool "Package D" - select BR2_PACKAGE_B + http://foosoftware.org/libfoo/ -config BR2_PACKAGE_E - bool "Package E" - select BR2_PACKAGE_D --------------------------- +if BR2_PACKAGE_LIBFOO -* Selecting +Package C+ will be visible if +Package B+ has been - selected, which in turn is only visible if +Package A+ has been - selected. +config BR2_PACKAGE_LIBFOO_FROBBLE + bool "Frobble the foo" -* Selecting +Package E+ will select +Package D+, which will select - +Package B+, it will not check for the dependencies of +Package B+, - so it will not select +Package A+. +config BR2_PACKAGE_LIBFOO_GAZZLE_LEVEL + int "Gazzle level" + range 0 10 -* Since +Package B+ is selected but +Package A+ is not, this violates - the dependency of +Package B+ on +Package A+. Therefore, in such a - situation, the transitive dependency has to be added explicitly: +comment "goo option requires package goo" + depends on !BR2_PACKAGE_GOO_AVAILABLE --------------------------- -config BR2_PACKAGE_D - bool "Package D" - select BR2_PACKAGE_B - depends on BR2_PACKAGE_A - -config BR2_PACKAGE_E - bool "Package E" - select BR2_PACKAGE_D - depends on BR2_PACKAGE_A --------------------------- +config BR2_PACKAGE_LIBFOO_GOO + bool "goo" + depends on BR2_PACKAGE_GOO_AVAILABLE + select BR2_PACKAGE_GOO -Overall, for package library dependencies, +select+ should be -preferred. +endif +-------------------------- -Note that such dependencies will make sure that the dependency option -is also enabled, but not necessarily built before your package. To do -so, the dependency also needs to be expressed in the +.mk+ file of the -package. The +.mk+ file ~~~~~~~~~~~~~~ diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt index d3a4abb..3e4c864 100644 --- a/docs/manual/adding-packages-generic.txt +++ b/docs/manual/adding-packages-generic.txt @@ -23,30 +23,45 @@ system is based on hand-written Makefiles or shell scripts. 09: LIBFOO_INSTALL_STAGING = YES 10: LIBFOO_DEPENDENCIES = host-libaaa libbbb 11: -12: define LIBFOO_BUILD_CMDS -13: $(MAKE) CC="$(TARGET_CC)" LD="$(TARGET_LD)" -C $(@D) all -14: endef +12: ifeq ($(BR2_PACKAGE_LIBFOO_FROBBLE),y) +13: LIBFOO_CFLAGS += -DFROBBLE +14: endif 15: -16: define LIBFOO_INSTALL_STAGING_CMDS -17: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a -18: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h -19: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib -20: endef -21: -22: define LIBFOO_INSTALL_TARGET_CMDS -23: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib -24: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d -25: endef -26: -27: define LIBFOO_DEVICES -28: /dev/foo c 666 0 0 42 0 - - - +16: LIBFOO_CFLAGS += -DGAZZLE_LEVEL=$(BR2_PACKAGE_LIBFOO_GAZZLE_LEVEL) +17: +18: ifeq ($(BR2_PACKAGE_LIBFOO_GOO),y) +19: LIBFOO_DEPENDENCIES += goo +20: LIBFOO_CFLAGS += -DGOO +21: LIBFOO_LDFLAGS += -lgoo +22: endif +23: +24: define LIBFOO_BUILD_CMDS +25: $(MAKE) -C $(@D) \ +26: CC="$(TARGET_CC)" CFLAGS="$(LIBFOO_CFLAGS)" \ +27: LD="$(TARGET_LD)" LDFLAGS="$(LIBFOO_LDFLAGS)" \ +28: all 29: endef 30: -31: define LIBFOO_PERMISSIONS -32: /bin/foo f 4755 0 0 - - - - - -33: endef -34: -35: $(eval $(generic-package)) +31: define LIBFOO_INSTALL_STAGING_CMDS +32: $(INSTALL) -D -m 0755 $(@D)/libfoo.a $(STAGING_DIR)/usr/lib/libfoo.a +33: $(INSTALL) -D -m 0644 $(@D)/foo.h $(STAGING_DIR)/usr/include/foo.h +34: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(STAGING_DIR)/usr/lib +35: endef +36: +37: define LIBFOO_INSTALL_TARGET_CMDS +38: $(INSTALL) -D -m 0755 $(@D)/libfoo.so* $(TARGET_DIR)/usr/lib +39: $(INSTALL) -d -m 0755 $(TARGET_DIR)/etc/foo.d +40: endef +41: +42: define LIBFOO_DEVICES +43: /dev/foo c 666 0 0 42 0 - - - +44: endef +45: +46: define LIBFOO_PERMISSIONS +47: /bin/foo f 4755 0 0 - - - - - +48: endef +49: +50: $(eval $(generic-package)) -------------------------------- The Makefile begins on line 6 to 8 with metadata information: the @@ -64,12 +79,20 @@ install header files and other development files in the staging space. This will ensure that the commands listed in the +LIBFOO_INSTALL_STAGING_CMDS+ variable will be executed. -On line 10, we specify the list of dependencies this package relies -on. These dependencies are listed in terms of lower-case package names, -which can be packages for the target (without the +host-+ -prefix) or packages for the host (with the +host-+) prefix). -Buildroot will ensure that all these packages are built and installed -'before' the current package starts its configuration. +On line 10, we specify the list of dependencies this package relies on. +These dependencies are listed in terms of lower-case package names, which +can be packages for the target (without the +host-+ prefix) or packages +for the host (with the +host-+ prefix). Buildroot will ensure that all +these packages are built and installed 'before' the current package starts +its configuration. + +On lines 12 to 14, if the user did select the option ++BR2_PACKAGE_LIBFOO_FROBBLE+ (see above, in the +Config.in+), we +conditionnally add a value to the +CFLAGS+. On line 16, we add the 'gazzle +level' +BR2_PACKAGE_LIBFOO_GAZZLE_LEVEL+ to the +CFLAGS+. And on lines 18 +to 22, if the user selected 'goo' support, +BR2_PACKAGE_LIBFOO_GOO+, we +add a dependency on the package +goo+, and add appropriate +CFLAGS+ and ++LDFLAGS+. The rest of the Makefile defines what should be done at the different steps of the package configuration, compilation and installation. @@ -79,11 +102,11 @@ steps should be performed to install the package in the staging space. +LIBFOO_INSTALL_TARGET_CMDS+ tells what steps should be performed to install the package in the target space. -All these steps rely on the +$(@D)+ variable, which -contains the directory where the source code of the package has been -extracted. +All these steps rely on the +$(@D)+ variable, which contains the directory +where the source code of the package has been extracted, and where the +package is being built. -Finally, on line 35, we call the +generic-package+ which +Finally, on line 50, we call the +generic-package+ which generates, according to the variables defined previously, all the Makefile code necessary to make your package working.