From 40ab94036081f9fdc4ebf6126b077149c2a97c31 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 6 Mar 2014 09:48:37 -0600 Subject: bitbake: user-manual: Review edits applied from Paul Eggleton. Review of the entire manual by Paul. I have implemented his suggestions throughout. (Bitbake rev: 5cd310d1df194cd171691a4bcfb98024e2bc66b8) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- bitbake/doc/user-manual/user-manual-execution.xml | 62 +++++----------- bitbake/doc/user-manual/user-manual-fetching.xml | 11 ++- bitbake/doc/user-manual/user-manual-intro.xml | 81 +++++++++++---------- bitbake/doc/user-manual/user-manual-metadata.xml | 87 +++++++++++++---------- 4 files changed, 115 insertions(+), 126 deletions(-) (limited to 'bitbake') diff --git a/bitbake/doc/user-manual/user-manual-execution.xml b/bitbake/doc/user-manual/user-manual-execution.xml index d451ebb..6110a93 100644 --- a/bitbake/doc/user-manual/user-manual-execution.xml +++ b/bitbake/doc/user-manual/user-manual-execution.xml @@ -87,21 +87,6 @@ just constructed. The bitbake.conf file usually indicates all the other key include files to parse. - The usual convention is to have machine, distro, site, and local - configurations. - This means a user provides their own customizations - through a local.conf file. - - - - As mentioned in the previous paragraph, two of the other notable - configuration files are the distro and machine configuration - files. - These configuration files are normally identified by - variables unique to the build systems using BitBake. - For example, the Yocto Project uses the - DISTRO and MACHINE - variables, respectively. @@ -122,7 +107,7 @@ The base configuration metadata is global - and therefore affects all packages and tasks that are executed. + and therefore affects all recipes and tasks that are executed. @@ -161,10 +146,11 @@ These variables might have been set from the environment depending on the environment variables previously mentioned or set in the configuration files. - See the + The "Variables Glossary" - for a full list of variables. - The following list shows common variables set: + chapter presents a full list of variables. + @@ -305,7 +292,7 @@ - BitBake does not need all this information. + BitBake does not need all of this information. It only needs a small subset of the information to make decisions about the recipe. Consequently, BitBake caches the values in which it is @@ -375,7 +362,7 @@ PROVIDES += "virtual/package" - The recipe now provides both "package1" and "virtual/package. + The recipe now provides both "package1" and "virtual/package". The "virtual/" namespace is often used to denote cases where multiple providers are expected with the user choosing between them. @@ -395,20 +382,8 @@ The default PREFERRED_PROVIDER is the provider with the same name as the target. - - - - Bitbake iterates through each target it needs to build and resolve - them using this process. - As an example, suppose the target is - core-image-sato. - In this case, it would lead to - packagegroup-core-x11-sato, - which in turn leads to recipes like - matchbox-terminal, pcmanfm - and gthumb. - These recipes in turn depend on eglibc - and the toolchain. + Bitbake iterates through each target it needs to build and + resolves them and their dependencies using this process. @@ -418,21 +393,21 @@ Version comparisons are made using the same method as Debian. You can use the PREFERRED_VERSION - variable to specify a particular version (usually in the distro configuration). + variable to specify a particular version. You can influence the order by using the DEFAULT_PREFERENCE variable. By default, files have a preference of "0". Setting the DEFAULT_PREFERENCE to "-1" makes the - package unlikely to be used unless it is explicitly referenced. - Setting the DEFAULT_PREFERENCE to "1" makes it likely the package is used. + recipe unlikely to be used unless it is explicitly referenced. + Setting the DEFAULT_PREFERENCE to "1" makes it likely the recipe is used. PREFERRED_VERSION overrides any DEFAULT_PREFERENCE setting. - DEFAULT_PREFERENCE is often used to mark newer and more experimental package + DEFAULT_PREFERENCE is often used to mark newer and more experimental recipe versions until they have undergone sufficient testing to be considered stable. - When there are multiple “versions” of a given package, + When there are multiple “versions” of a given recipe, BitBake defaults to selecting the most recent version, unless otherwise specified. If the recipe in question has a @@ -573,12 +548,12 @@ Tasks can either be a shell task or a Python task. For shell tasks, BitBake writes a shell script to - ${WORKDIR}/temp/run.do_taskname.pid + ${T}/run.do_taskname.pid and then executes the script. The generated shell script contains all the exported variables, and the shell functions with all variables expanded. Output from the shell script goes to the file - ${WORKDIR}/temp/log.do_taskname.pid. + ${T}/log.do_taskname.pid. Looking at the expanded shell functions in the run file and the output in the log files is a useful debugging technique. @@ -831,9 +806,6 @@ a setscene task named xxx_setscene. The setscene version of the task executes and provides the necessary artifacts returning either success or failure. - - Artifacts might need to be fetched from the network. - diff --git a/bitbake/doc/user-manual/user-manual-fetching.xml b/bitbake/doc/user-manual/user-manual-fetching.xml index cbf08d9..c66596e 100644 --- a/bitbake/doc/user-manual/user-manual-fetching.xml +++ b/bitbake/doc/user-manual/user-manual-fetching.xml @@ -42,7 +42,7 @@ fetcher = bb.fetch2.Fetch(src_uri, d) fetcher.download() - This code sets up an instance of the fetch module. + This code sets up an instance of the fetch class. The instance uses a space-separated list of URLs from the SRC_URI variable and then calls the download @@ -155,14 +155,13 @@ SRC_URI variable with the appropriate varflags as follows: - SRC_URI[md5sum] - SRC_URI[sha256sum] + SRC_URI[md5sum] = "value" + SRC_URI[sha256sum] = "value" You can also specify the checksums as parameters on the SRC_URI as shown below: - SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07f -db994d" + SRC_URI = "http://example.com/foobar.tar.bz2;md5sum=4a8e0f237e961fd7785d19d07fdb994d" If multiple URIs exist, you can specify the checksums either directly as in the previous example, or you can name the URLs. @@ -578,7 +577,7 @@ db994d" Fetch submodules also exist for the following: - Bazzar (bzr://) + Bazaar (bzr://) Perforce (p4://) diff --git a/bitbake/doc/user-manual/user-manual-intro.xml b/bitbake/doc/user-manual/user-manual-intro.xml index 6f9ad20..d46e823 100644 --- a/bitbake/doc/user-manual/user-manual-intro.xml +++ b/bitbake/doc/user-manual/user-manual-intro.xml @@ -6,10 +6,10 @@ Welcome to the BitBake User Manual. - This manual provides information on BitBake. + This manual provides information on the BitBake tool. The information attempts to be as independent as possible regarding systems that use BitBake, such as the Yocto Project and - OpenEmbeddeded. + OpenEmbedded. In some cases, scenarios or examples that within the context of a build system are used in the manual to help with understanding. For these cases, the manual clearly states the context. @@ -88,7 +88,7 @@ an aspiring embedded Linux distribution. All of the build systems used by traditional desktop Linux distributions lacked important functionality, and none of the - ad-hoc buildroot systems, prevalent in the + ad-hoc Buildroot-based systems, prevalent in the embedded space, were scalable or maintainable. @@ -216,7 +216,7 @@ Within the context of BitBake, or any project utilizing BitBake - as it's build system, files with the .bb + as its build system, files with the .bb extension are referred to as recipes. The term "package" is also commonly used to describe recipes. @@ -282,7 +282,7 @@ To illustrate how you can use layers to keep things modular, - consider machine customizations. + consider customizations you might make to support a specific target machine. These types of customizations typically reside in a special layer, rather than a general layer, called a Board Specific Package (BSP) Layer. Furthermore, the machine customizations should be isolated from @@ -343,7 +343,7 @@ busybox_1.3.0.bb, the append name would not match. However, if you named the append file - busybox_1.%.bb, then you would have a match. + busybox_1.%.bbappend, then you would have a match. @@ -421,20 +421,10 @@ The BitBake Command - BitBake is the underlying piece of the build system. - Two excellent examples are the Yocto Project and the OpenEmbedded - build systems. - Each provide an environment in which to develop embedded Linux - images, and each use BitBake as their underlying build engine. - - - - BitBake facilitates executing tasks in a single .bb - file, or executing a given task on a set of multiple - .bb files, accounting for interdependencies - amongst them. - This section presents the BitBake syntax and provides some execution - examples. + The BitBake command is the primary interface to the BitBake + tool. + This section presents the BitBake command syntax and provides + several execution examples.
@@ -539,17 +529,21 @@ Options: - The following command runs the clean task on the - foo_1.0.bb recipe file: - - $ bitbake -b foo.bb -c clean - The following command runs the build task, which is the default task, on the foo_1.0.bb recipe file: $ bitbake -b foo_1.0.bb + The following command runs the clean task on the + foo_1.0.bb recipe file: + + $ bitbake -b foo.bb -c clean + + + The "-b" option explicitly does not handle recipe + dependencies. +
@@ -573,7 +567,7 @@ Options: The bitbake command, when not using - "--buildfile" or "-b" only accepts a "PROVIDER". + "--buildfile" or "-b" only accepts a "PROVIDES". You cannot provide anything else. By default, a recipe file generally "PROVIDES" its "packagename", "packagename-version", and @@ -581,10 +575,6 @@ Options: example: $ bitbake foo - - $ bitbake foo-1.0 - - $ bitbake foo-1.0-r0 This next example "PROVIDES" the package name and also uses the "-c" option to tell BitBake to just execute the @@ -600,22 +590,35 @@ Options: BitBake is able to generate dependency graphs using - the dot syntax. - You can convert these graphs into images using the dot - application from + the dot syntax. + You can convert these graphs into images using the + dot tool from Graphviz. - When you generate a dependency graph, BitBake writes two files + When you generate a dependency graph, BitBake writes four files to the current working directory: - depends.dot, which contains dependency information - at the package level, and task-depends.dot, - which contains a breakdown of the dependencies at the task level. + + package-depends.dot: + Shows BitBake's knowledge of dependencies between + runtime targets. + + pn-depends.dot: + Shows dependencies between build-time targets + (i.e. recipes). + + task-depends.dot: + Shows dependencies between tasks. + + pn-buildlist: + Shows a simple list of targets that are to be built. + + - To stop depending on common depends, use use the "-I" depend + To stop depending on common depends, use the "-I" depend option and BitBake omits them from the graph. Leaving this information out can produce more readable graphs. This way, you can remove from the graph @@ -629,7 +632,7 @@ Options: $ bitbake -g foo - $ bitbake -g -I virtual/whatever -I bloom foo + $ bitbake -g -I virtual/kernel -I eglibc foo diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml index 748b959..3a19b96 100644 --- a/bitbake/doc/user-manual/user-manual-metadata.xml +++ b/bitbake/doc/user-manual/user-manual-metadata.xml @@ -40,12 +40,15 @@ BitBake supports variables referencing one another's contents using a syntax that is similar to shell scripting. Following is an example that results in A - containing "aval" and B containing + containing "aval" and B evaluating to "preavalpost". A = "aval" B = "pre${A}post" + Because the expansion happens later, the value of + B expands differently if the value + of A changes. @@ -79,7 +82,7 @@ Setting a weak default value (??=) - It is possible to use a "weaker" assignment that in the + It is possible to use a "weaker" assignment than in the previous section by using the "??=" operator. This assignment behaves identical to "?=" except that the assignment is made at the end of the parsing process rather @@ -197,6 +200,13 @@ override syntax. + + + The operators "_append" and "_prepend" differ from + the operators ".=" and "=." in that they are deferred + until after parsing completes rather than being immediately + applied. +
@@ -519,7 +529,7 @@ recipes require. For example, you can easily abstract out the tasks involved in building a package that uses Autoconf and Automake and put - those tasks into a class file that can be used by your package. + those tasks into a class file that can be used by your recipe. @@ -549,9 +559,10 @@ directive. This directive causes BitBake to parse whatever file you specify, 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. + The directive is much like its equivalent in 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. @@ -588,7 +599,7 @@ - Similar to how BitBake uses + Similar to how BitBake handles include, if the path specified on the require line is a relative path, BitBake locates @@ -776,16 +787,17 @@ Tasks are only supported in recipe (.bb or .inc) and class (.bbclass) files. - By convention, tasks begin with the string "do_". + By convention, task names begin with the string "do_". Here is an example of a task that prints out the date: python do_printdate () { - import time print - time.strftime('%Y%m%d', time.gmtime()) + import time + print time.strftime('%Y%m%d', time.gmtime()) } + addtask printdate after do_fetch before do_build @@ -802,8 +814,8 @@ and defining some dependencies: python do_printdate () { - import time print - time.strftime('%Y%m%d', time.gmtime()) + import time + print time.strftime('%Y%m%d', time.gmtime()) } addtask printdate after do_fetch before do_build @@ -942,11 +954,6 @@ BitBake has a defined set of varflags available for recipes and classes. - You can discover the complete set by using grep - within a shell and search on the string "VarFlags". - - - Tasks support a number of these flags which control various functionality of the task: @@ -958,12 +965,13 @@ noexec: Marks the tasks as being empty and no execution required. - These flags are used as dependency placeholders or used when - added tasks need to be subsequently disabled. + The noexec flag can be used to set up + tasks as dependency placeholders, or to disable tasks defined + elsewhere that are not needed in a particular recipe. nostamp: Tells BitBake to not generate a stamp file for a task, - which implies the task is always executed. + which implies the task should always be executed. fakeroot: Causes a task to be run in a fakeroot environment, @@ -1027,7 +1035,7 @@ List of functions to call before the task executes. stamp-extra-info: - Extra stamp information to append to the task's stamp + Extra stamp information to append to the task's stamp. As an example, OpenEmbedded uses this flag to allow machine-specific tasks. @@ -1380,15 +1388,18 @@ d.setVar("X", value) - Sets the variable "X" to "value". + Sets the variable "X" to the value of the Python + variable called "value". d.appendVar("X", value) - Adds "value" to the end of the variable "X". + Adds the value of the Python variable called + "value" to the end of the variable "X". d.prependVar("X", value) - Adds "value" to the start of the variable "X". + Adds the value of the Python variable called + "value" to the start of the variable "X". d.delVar("X") @@ -1400,40 +1411,44 @@ d.getVarFlag("X", flag, expand=False) - Gets "flag" from the variable "X". - Using "expand=True" expands the flag. + Gets then named flag from the variable "X". + Using "expand=True" expands the named flag. d.setVarFlag("X", flag, value) - Sets "flag" for variable "X" to "value". - setVarFlags does not clear previous flags. - Think of this operation as addVarFlags. + Sets the named flag for variable "X" to the value + of the Python variable called "value". d.appendVarFlag("X", flag, value) - Need description. + Appends a value to the named flag on the + variable "X". d.prependVarFlag("X", flag, value) - Need description. + Prepends a value to the named flag on + the variable "X". d.delVarFlag("X", flag) - Need description. + Deletes the named flag on the variable + "X" from the datastore. d.setVarFlags("X", flagsdict) Sets the flags specified in - the dict() parameter. + the flagsdict() parameter. + setVarFlags does not clear previous flags. + Think of this operation as addVarFlags. d.getVarFlags("X") - Returns a dict of the flags for + Returns a flagsdict of the flags for the variable "X". - d.delVarFlags - Deletes all the flags for a variable. + d.delVarFlags("X") + Deletes all the flags for the variable "X". -- cgit v1.1