From 9c61b6392c991363b0399ed36d6dec3f0d0d6bcf Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 4 Feb 2014 13:36:11 -0600 Subject: bitbake: user-manual-metadata.xml: Edits to the "Sharing Functionality" section. Applied some review edits from Paul to the section. (Bitbake rev: 56321b18808f5ed932543d907b9ebcfbf4420233) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- bitbake/doc/user-manual/user-manual-metadata.xml | 150 ++++++++++++++++++----- 1 file changed, 122 insertions(+), 28 deletions(-) (limited to 'bitbake') diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml index 9708bbb12f..621b376d37 100644 --- a/bitbake/doc/user-manual/user-manual-metadata.xml +++ b/bitbake/doc/user-manual/user-manual-metadata.xml @@ -484,49 +484,132 @@ -
- Inheritance +
+ Sharing Functionality -
- Inheritance Directive + + BitBake allows for metadata sharing through include files and + class files (.bbclass). + For example, suppose you have a piece of common functionality + such as a task definition that you want to share between + more than one recipe. + In this case, creating a .bbclass + file that contains the common functionality and uses the + inherit directive would be a common + way to share the task. + + + + This section presents the mechanisms BitBake provides to + allow you to share functionality between recipes. + Specifically, the mechanisms include include, + inherit, INHERIT, and + require statements. + + +
+ Locating Include and Class Files + + + BitBake uses the BBPATH variable + to locate needed class and configuration files. + The BBPATH variable is analogous to + the environment variable PATH. + Use of BBPATH is specific to the build + environment (e.g. Yocto Project, OpenEmbedded, and so forth). + +
- - This is only supported in .bb and - .bbclass files. - +
+ <filename>inherit</filename> Directive - The inherit directive is a means of specifying what classes - of functionality your .bb requires. - It is a rudimentary form of inheritance. + When writing a recipe or class file, you can use the + inherit directive to inherit the + functionality of a class (.bbclass). + BitBake only supports this directive when used within these + two types of files (i.e. .bb and + .bbclass files). + + + + The inherit directive is a rudimentary + means of specifying what classes of functionality your + recipe requires. For example, you can easily abstract out the tasks involved in - building a package that uses autoconf and automake, and put - that into a bbclass for your packages to make use of. - A given bbclass is located by searching for classes/filename.bbclass - in BBPATH, where filename is what you inherited. + building a package that uses Autoconf and Automake and put + those tasks into a class file that can be used by your package. + As an example, an autotools.bbclass file + could use the following directive to inherit needed + site information: + + inherit siteinfo + + In this case, BitBake would search for the directory + classes/siteinfo.bbclass + in BBPATH.
-
- Inclusion Directive +
+ <filename>include</filename> Directive + BitBake understands the include + directive. This directive causes BitBake to parse whatever file you specify, - and insert it at that location, which is not unlike Make. - However, if the path specified on the include line is a - relative path, BitBake will locate the first one it can find - within BBPATH. + and to insert that file at that location. + The directive is much like Make except that if the path specified + on the include line is a relative path, BitBake locates + the first file it can find within BBPATH. + + + + As an example, suppose you needed a recipe to include some + self-test files: + + include test_recipe.inc + + + The include directive does not + produce an error when the file cannot be found. + Consequently, it is recommended that if the file you + are including is expected to exist, you should use + require + instead of include. + Doing so makes sure that an error is produced if the + file cannot be found. +
-
- Requiring Inclusion +
+ <filename>require</filename> Directive - In contrast to the include directive, require will raise a - ParseError if the file to be included cannot + BitBake understands the require + directive. + This directive behaves just like the + include directive with the exception that + BitBake raises a parsing error if the file to be included cannot be found. - Otherwise it will behave just like the include directive. + Thus, any file you require is inserted into the file that is + being parsed at the location of the directive. + + + + Similar to how BitBake uses include, + if the path specified + on the require line is a relative path, BitBake locates + the first file it can find within BBPATH. + + + + As an example, suppose you needed a recipe to require some + self-test files: + + require test_recipe.inc +
@@ -534,9 +617,20 @@ <filename>INHERIT</filename> Configuration Directive + When creating a configuration file (.conf), + you can use the INHERIT directive to + inherit a class. + BitBake only supports this directive when used within + a configuration file. + + + + Suppose you needed to inherit a multilib global class. + + INHERIT += "multilib_global" + This configuration directive causes the named class to be inherited - at this point during parsing. - This variable is only valid in configuration files. + at the point of the directive during parsing.
-- cgit v1.2.3-54-g00ecf