From patchwork Sun Feb 2 12:11:16 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Thomas De Schampheleire X-Patchwork-Id: 315995 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from hemlock.osuosl.org (hemlock.osuosl.org [140.211.166.133]) by ozlabs.org (Postfix) with ESMTP id 3DBA62C0096 for ; Sun, 2 Feb 2014 23:11:41 +1100 (EST) Received: from localhost (localhost [127.0.0.1]) by hemlock.osuosl.org (Postfix) with ESMTP id 8C02C93A2E; Sun, 2 Feb 2014 12:11:40 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from hemlock.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id SPzLqFlRwaSX; Sun, 2 Feb 2014 12:11:39 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by hemlock.osuosl.org (Postfix) with ESMTP id 5E9B5884A5; Sun, 2 Feb 2014 12:11:39 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from whitealder.osuosl.org (whitealder.osuosl.org [140.211.166.138]) by ash.osuosl.org (Postfix) with ESMTP id 122031BF94F for ; Sun, 2 Feb 2014 12:11:38 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id 09B3A8B406 for ; Sun, 2 Feb 2014 12:11:38 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from whitealder.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id czQbg2XCKmzB for ; Sun, 2 Feb 2014 12:11:36 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wg0-f49.google.com (mail-wg0-f49.google.com [74.125.82.49]) by whitealder.osuosl.org (Postfix) with ESMTPS id 3CBC883A32 for ; Sun, 2 Feb 2014 12:11:36 +0000 (UTC) Received: by mail-wg0-f49.google.com with SMTP id a1so10635273wgh.4 for ; Sun, 02 Feb 2014 04:11:34 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=content-type:mime-version:content-transfer-encoding:subject :message-id:in-reply-to:references:user-agent:date:from:to; bh=uSsA1jA03+DQqMXQVvTzD/tB5v3OWXuyb+1pJtY857A=; b=nRWSmdTFOyPQ7g+4vf6+a+rnUnYEzhqumpoUIegWUEtHYcCX72SsMzyVT5IFEvPGDI nJbOU30Cwit9sS65zQkyFk+EOByEi7097vB0lRq0TYOZEANQnnuOx9yMY6PVfHyPyacv YEwnRr9ZpUaS6j5POnslEXY1hLBvx8NpmU7Rg0PsNscJyhLH+olOavnaD+fPkIH/SDgH DwvB/3FTReTEAZqyqDcTR4CYXtMo0JVNd/hiKTPj2jdH+2tJVEuNXTzpbuq4HxH+q6J2 JgFD2mp1rQwRBYAmKPDV3OX6NrGwQzLP1tk5zW2thf1eT2dfuiWFmBWY4sydQTx5bha6 S2fw== X-Received: by 10.194.84.144 with SMTP id z16mr20531973wjy.23.1391343094849; Sun, 02 Feb 2014 04:11:34 -0800 (PST) Received: from [127.0.1.1] (d54C62EEB.access.telenet.be. [84.198.46.235]) by mx.google.com with ESMTPSA id ea4sm15523490wib.7.2014.02.02.04.11.33 for (version=TLSv1.1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Sun, 02 Feb 2014 04:11:33 -0800 (PST) MIME-Version: 1.0 X-Mercurial-Node: 2267e0a51f62ee4cf4fb6a8d6941814ef11bff3a Message-Id: <2267e0a51f62ee4cf4fb.1391343076@argentina> In-Reply-To: References: User-Agent: Mercurial-patchbomb/2.2.2 Date: Sun, 02 Feb 2014 13:11:16 +0100 From: Thomas De Schampheleire To: buildroot@busybox.net Subject: [Buildroot] [PATCH 1 of 9] manual: split information about Config.in dependencies to a separate file X-BeenThere: buildroot@busybox.net X-Mailman-Version: 2.1.14 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: buildroot-bounces@busybox.net Sender: buildroot-bounces@busybox.net The information about expressing dependencies in Config.in files is becoming larger, and is more easily maintained from a separate file than from the current file 'adding-packages-directory.txt'. Signed-off-by: Thomas De Schampheleire --- docs/manual/adding-packages-dependencies.txt | 235 ++++++++++++++++++++++ docs/manual/adding-packages-directory.txt | 236 +---------------------- 2 files changed, 236 insertions(+), 235 deletions(-) diff --git a/docs/manual/adding-packages-dependencies.txt b/docs/manual/adding-packages-dependencies.txt new file mode 100644 --- /dev/null +++ b/docs/manual/adding-packages-dependencies.txt @@ -0,0 +1,235 @@ +[[depends-on-vs-select]] +Choosing +depends on+ or +select+ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The +Config.in+ file of your package must also ensure that +dependencies are enabled. Typically, Buildroot uses the following +rules: + +* 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. + The +select+ keyword expresses the dependency with a backward + semantic. + +* 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 target architecture, MMU support and + toolchain options (see xref:dependencies-target-toolchain-options[]), + or for dependencies on "big" things, such as the X.org system. + The +depends on+ keyword expresses the dependency with a forward + semantic. + +.Note +The current problem with the _kconfig_ language is that these two +dependency semantics are not internally linked. Therefore, it may be +possible to select a package, whom one of its dependencies/requirement +is not met. + +An example illustrates both the usage of +select+ and +depends on+. + +-------------------------- +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 needs a toolchain w/ largefile" + depends on !BR2_LARGEFILE +-------------------------- + + +Note that these two dependency types are only transitive with the +dependencies of the same kind. + +This means, in the following example: + +-------------------------- +config BR2_PACKAGE_A + bool "Package A" + +config BR2_PACKAGE_B + bool "Package B" + depends on BR2_PACKAGE_A + +config BR2_PACKAGE_C + bool "Package C" + depends on BR2_PACKAGE_B + +config BR2_PACKAGE_D + bool "Package D" + select BR2_PACKAGE_B + +config BR2_PACKAGE_E + bool "Package E" + select BR2_PACKAGE_D +-------------------------- + +* Selecting +Package C+ will be visible if +Package B+ has been + selected, which in turn is only visible if +Package A+ has been + selected. + +* 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+. + +* 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: + +-------------------------- +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 +-------------------------- + +Overall, for package library dependencies, +select+ should be +preferred. + +Note that such dependencies will ensure 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. + +Further formatting details: see xref:writing-rules-config-in[the +coding style]. + +[[dependencies-target-toolchain-options]] +Dependencies on target and toolchain options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Many packages depend on certain options of the toolchain: the choice of +C library, C++ support, largefile support, thread support, RPC support, +IPv6 support, wchar support, or dynamic library support. Some packages +can only be built on certain target architectures, or if an MMU is +available in the processor. + +These dependencies have to be expressed with the appropriate 'depends +on' statements in the Config.in file. Additionally, for dependencies on +toolchain options, a +comment+ should be displayed when the option is +not enabled, so that the user knows why the package is not available. +Dependencies on target architecture or MMU support should not be +made visible in a comment: since it is unlikely that the user can +freely choose another target, it makes little sense to show these +dependencies explicitly. + +The +comment+ should only be visible if the +config+ option itself would +be visible when the toolchain option dependencies are met. This means +that all other dependencies of the package (including dependencies on +target architecture and MMU support) have to be repeated on the ++comment+ definition. To keep it clear, the +depends on+ statement for +these non-toolchain option should be kept separate from the +depends on+ +statement for the toolchain options. +If there is a dependency on a config option in that same file (typically +the main package) it is preferable to have a global +if ... endif+ +construct rather than repeating the +depends on+ statement on the +comment and other config options. + +The general format of a dependency +comment+ for package foo is: +-------------------------- +foo needs a toolchain w/ featA, featB, featC +-------------------------- + +for example: +-------------------------- +aircrack-ng needs a toolchain w/ largefile, threads +-------------------------- + +Note that this text is kept brief on purpose, so that it will fit on a +80-character terminal. + +The rest of this section enumerates the different target and toolchain +options, the corresponding config symbols to depend on, and the text to +use in the comment. + +* Target architecture +** Dependency symbol: +BR2_powerpc+, +BR2_mips+, ... (see +arch/Config.in+) +** Comment string: no comment to be added + +* MMU support +** Dependency symbol: +BR2_USE_MMU+ +** Comment string: no comment to be added + +* C library +** Dependency symbol: +BR2_TOOLCHAIN_USES_GLIBC+, ++BR2_TOOLCHAIN_USES_UCLIBC+ +** Comment string: for the C library, a slightly different comment text + is used: +foo needs an (e)glibc toolchain+, or `foo needs an (e)glibc + toolchain w/ C++ support` + +* C++ support +** Dependency symbol: +BR2_INSTALL_LIBSTDCPP+ +** Comment string: `C++` + +* largefile support +** Dependency symbol: +BR2_LARGEFILE+ +** Comment string: +largefile+ + +* thread support +** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS+ +** Comment string: +threads+ + +* RPC support +** Dependency symbol: +BR2_TOOLCHAIN_HAS_NATIVE_RPC+ +** Comment string: +RPC+ + +* IPv6 support +** Dependency symbol: +BR2_INET_IPV6+ +** Comment string: +IPv6+ (lowercase v) + +* wchar support +** Dependency symbol: +BR2_USE_WCHAR+ +** Comment string: +wchar+ + +* dynamic library +** Dependency symbol: +!BR2_PREFER_STATIC_LIB+ +** Comment string: +dynamic library+ + +Dependencies on a Linux kernel built by buildroot +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Some packages need a Linux kernel to be built by buildroot. These are +typically kernel modules or firmware. A comment should be added in the +Config.in file to express this dependency, similar to dependencies on +toolchain options. The general format is: + +-------------------------- +foo needs a Linux kernel to be built +-------------------------- + +If there is a dependency on both toolchain options and the Linux +kernel, use this format: +-------------------------- +foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built +-------------------------- + +Dependencies on udev /dev management +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If a package needs udev /dev management, it should depend on symbol ++BR2_ROOTFS_DEVICE_CREATION_DYNAMIC_UDEV+, and the following comment +should be added: + +-------------------------- +foo needs udev /dev management +-------------------------- + +If there is a dependency on both toolchain options and udev /dev +management, use this format: + +-------------------------- +foo needs udev /dev management and a toolchain w/ featA, featB, featC +-------------------------- diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt --- a/docs/manual/adding-packages-directory.txt +++ b/docs/manual/adding-packages-directory.txt @@ -51,241 +51,7 @@ supposed to contain anything but the 'ba source "package/libfoo/Config.in" -------------------------- -[[depends-on-vs-select]] -Choosing +depends on+ or +select+ -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The +Config.in+ file of your package must also ensure that -dependencies are enabled. Typically, Buildroot uses the following -rules: - -* 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. - The +select+ keyword expresses the dependency with a backward - semantic. - -* 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 target architecture, MMU support and - toolchain options (see xref:dependencies-target-toolchain-options[]), - or for dependencies on "big" things, such as the X.org system. - The +depends on+ keyword expresses the dependency with a forward - semantic. - -.Note -The current problem with the _kconfig_ language is that these two -dependency semantics are not internally linked. Therefore, it may be -possible to select a package, whom one of its dependencies/requirement -is not met. - -An example illustrates both the usage of +select+ and +depends on+. - --------------------------- -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 needs a toolchain w/ largefile" - depends on !BR2_LARGEFILE --------------------------- - - -Note that these two dependency types are only transitive with the -dependencies of the same kind. - -This means, in the following example: - --------------------------- -config BR2_PACKAGE_A - bool "Package A" - -config BR2_PACKAGE_B - bool "Package B" - depends on BR2_PACKAGE_A - -config BR2_PACKAGE_C - bool "Package C" - depends on BR2_PACKAGE_B - -config BR2_PACKAGE_D - bool "Package D" - select BR2_PACKAGE_B - -config BR2_PACKAGE_E - bool "Package E" - select BR2_PACKAGE_D --------------------------- - -* Selecting +Package C+ will be visible if +Package B+ has been - selected, which in turn is only visible if +Package A+ has been - selected. - -* 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+. - -* 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: - --------------------------- -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 --------------------------- - -Overall, for package library dependencies, +select+ should be -preferred. - -Note that such dependencies will ensure 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. - -Further formatting details: see xref:writing-rules-config-in[the -coding style]. - -[[dependencies-target-toolchain-options]] -Dependencies on target and toolchain options -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Many packages depend on certain options of the toolchain: the choice of -C library, C++ support, largefile support, thread support, RPC support, -IPv6 support, wchar support, or dynamic library support. Some packages -can only be built on certain target architectures, or if an MMU is -available in the processor. - -These dependencies have to be expressed with the appropriate 'depends -on' statements in the Config.in file. Additionally, for dependencies on -toolchain options, a +comment+ should be displayed when the option is -not enabled, so that the user knows why the package is not available. -Dependencies on target architecture or MMU support should not be -made visible in a comment: since it is unlikely that the user can -freely choose another target, it makes little sense to show these -dependencies explicitly. - -The +comment+ should only be visible if the +config+ option itself would -be visible when the toolchain option dependencies are met. This means -that all other dependencies of the package (including dependencies on -target architecture and MMU support) have to be repeated on the -+comment+ definition. To keep it clear, the +depends on+ statement for -these non-toolchain option should be kept separate from the +depends on+ -statement for the toolchain options. -If there is a dependency on a config option in that same file (typically -the main package) it is preferable to have a global +if ... endif+ -construct rather than repeating the +depends on+ statement on the -comment and other config options. - -The general format of a dependency +comment+ for package foo is: --------------------------- -foo needs a toolchain w/ featA, featB, featC --------------------------- - -for example: --------------------------- -aircrack-ng needs a toolchain w/ largefile, threads --------------------------- - -Note that this text is kept brief on purpose, so that it will fit on a -80-character terminal. - -The rest of this section enumerates the different target and toolchain -options, the corresponding config symbols to depend on, and the text to -use in the comment. - -* Target architecture -** Dependency symbol: +BR2_powerpc+, +BR2_mips+, ... (see +arch/Config.in+) -** Comment string: no comment to be added - -* MMU support -** Dependency symbol: +BR2_USE_MMU+ -** Comment string: no comment to be added - -* C library -** Dependency symbol: +BR2_TOOLCHAIN_USES_GLIBC+, -+BR2_TOOLCHAIN_USES_UCLIBC+ -** Comment string: for the C library, a slightly different comment text - is used: +foo needs an (e)glibc toolchain+, or `foo needs an (e)glibc - toolchain w/ C++ support` - -* C++ support -** Dependency symbol: +BR2_INSTALL_LIBSTDCPP+ -** Comment string: `C++` - -* largefile support -** Dependency symbol: +BR2_LARGEFILE+ -** Comment string: +largefile+ - -* thread support -** Dependency symbol: +BR2_TOOLCHAIN_HAS_THREADS+ -** Comment string: +threads+ - -* RPC support -** Dependency symbol: +BR2_TOOLCHAIN_HAS_NATIVE_RPC+ -** Comment string: +RPC+ - -* IPv6 support -** Dependency symbol: +BR2_INET_IPV6+ -** Comment string: +IPv6+ (lowercase v) - -* wchar support -** Dependency symbol: +BR2_USE_WCHAR+ -** Comment string: +wchar+ - -* dynamic library -** Dependency symbol: +!BR2_PREFER_STATIC_LIB+ -** Comment string: +dynamic library+ - -Dependencies on a Linux kernel built by buildroot -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Some packages need a Linux kernel to be built by buildroot. These are -typically kernel modules or firmware. A comment should be added in the -Config.in file to express this dependency, similar to dependencies on -toolchain options. The general format is: - --------------------------- -foo needs a Linux kernel to be built --------------------------- - -If there is a dependency on both toolchain options and the Linux -kernel, use this format: --------------------------- -foo needs a toolchain w/ featA, featB, featC and a Linux kernel to be built --------------------------- - -Dependencies on udev /dev management -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If a package needs udev /dev management, it should depend on symbol -+BR2_ROOTFS_DEVICE_CREATION_DYNAMIC_UDEV+, and the following comment -should be added: - --------------------------- -foo needs udev /dev management --------------------------- - -If there is a dependency on both toolchain options and udev /dev -management, use this format: - --------------------------- -foo needs udev /dev management and a toolchain w/ featA, featB, featC --------------------------- +include::adding-packages-dependencies.txt[] The +.mk+ file ~~~~~~~~~~~~~~