From da6926bc6a17478bd38f0df176116b6552c124f6 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 7 Mar 2014 12:41:08 -0600 Subject: bitbake: user-manual: Review edits applied throughout from Paul Eggleton. Applied review edits from Paul Eggleton spanning the entire book. Small areas affected in all chapters except the "Hello World" Appendix. Noteworthy changes in the variables chapter where I added two new variables: BBINCLUDELOGS_LINES and BB_CONSOLELOG. (Bitbake rev: 2d4b09be70c6df0c1605f7e291149c682999cf50) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- bitbake/doc/user-manual/user-manual-execution.xml | 12 +++-- bitbake/doc/user-manual/user-manual-fetching.xml | 2 +- bitbake/doc/user-manual/user-manual-intro.xml | 16 ++++--- bitbake/doc/user-manual/user-manual-metadata.xml | 40 ++++++++-------- .../doc/user-manual/user-manual-ref-variables.xml | 53 ++++++++++++++-------- 5 files changed, 71 insertions(+), 52 deletions(-) diff --git a/bitbake/doc/user-manual/user-manual-execution.xml b/bitbake/doc/user-manual/user-manual-execution.xml index 6110a93e2a..a67516e858 100644 --- a/bitbake/doc/user-manual/user-manual-execution.xml +++ b/bitbake/doc/user-manual/user-manual-execution.xml @@ -85,8 +85,10 @@ Next, the bitbake.conf file is searched using the BBPATH variable that was just constructed. - The bitbake.conf file usually indicates - all the other key include files to parse. + The bitbake.conf file may also include other + configuration files using the + include or + require directives. @@ -358,11 +360,11 @@ As an example of adding an extra provider, suppose a recipe named - package1.bb contained the following: + foo_1.0.bb contained the following: - PROVIDES += "virtual/package" + PROVIDES += "virtual/bar_1.0" - The recipe now provides both "package1" and "virtual/package". + The recipe now provides both "foo_1.0" and "virtual/bar_1.0". The "virtual/" namespace is often used to denote cases where multiple providers are expected with the user choosing between them. diff --git a/bitbake/doc/user-manual/user-manual-fetching.xml b/bitbake/doc/user-manual/user-manual-fetching.xml index c66596ed6e..5aa53defc4 100644 --- a/bitbake/doc/user-manual/user-manual-fetching.xml +++ b/bitbake/doc/user-manual/user-manual-fetching.xml @@ -50,7 +50,7 @@ - The instance of the fetch module is usually followed by: + The instantiation of the fetch class is usually followed by: rootdir = l.getVar('WORKDIR', True) fetcher.unpack(rootdir) diff --git a/bitbake/doc/user-manual/user-manual-intro.xml b/bitbake/doc/user-manual/user-manual-intro.xml index d46e823c72..c7f01ad726 100644 --- a/bitbake/doc/user-manual/user-manual-intro.xml +++ b/bitbake/doc/user-manual/user-manual-intro.xml @@ -421,8 +421,8 @@ The BitBake Command - The BitBake command is the primary interface to the BitBake - tool. + The bitbake command is the primary interface + to the BitBake tool. This section presents the BitBake command syntax and provides several execution examples. @@ -536,13 +536,16 @@ Options: $ bitbake -b foo_1.0.bb The following command runs the clean task on the - foo_1.0.bb recipe file: + foo.bb recipe file: $ bitbake -b foo.bb -c clean The "-b" option explicitly does not handle recipe dependencies. + Other than for debugging purposes, it is instead + recommended that you use the syntax presented in the + next section. @@ -570,9 +573,7 @@ Options: "--buildfile" or "-b" only accepts a "PROVIDES". You cannot provide anything else. By default, a recipe file generally "PROVIDES" its - "packagename", "packagename-version", and - "packagename-version-revision" as shown in the following - example: + "packagename" as shown in the following example: $ bitbake foo @@ -628,7 +629,8 @@ Options: Here are two examples that create dependency graphs. - The second example omits common depends from the graph: + The second example omits depends common in OpenEmbedded from + the graph: $ bitbake -g foo diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml index 3a19b96303..f7682c0fed 100644 --- a/bitbake/doc/user-manual/user-manual-metadata.xml +++ b/bitbake/doc/user-manual/user-manual-metadata.xml @@ -41,14 +41,18 @@ contents using a syntax that is similar to shell scripting. Following is an example that results in A containing "aval" and B evaluating to - "preavalpost". + "preavalpost" based on that current value of + A. A = "aval" B = "pre${A}post" - Because the expansion happens later, the value of - B expands differently if the value - of A changes. + You should realize that whenever B is + referenced, its evaluation will depend on the state of + A at that time. + Thus, later evaluations of B in the + previous example could result in different values + depending on the value of A. @@ -1387,19 +1391,16 @@ Using "expand=True" expands the value. - d.setVar("X", value) - Sets the variable "X" to the value of the Python - variable called "value". + d.setVar("X", "value") + Sets the variable "X" to "value". - d.appendVar("X", value) - Adds the value of the Python variable called - "value" to the end of the variable "X". + d.appendVar("X", "value") + Adds "value" to the end of the variable "X". - d.prependVar("X", value) - Adds the value of the Python variable called - "value" to the start of the variable "X". + d.prependVar("X", "value") + Adds "value" to the start of the variable "X". d.delVar("X") @@ -1415,18 +1416,17 @@ Using "expand=True" expands the named flag. - d.setVarFlag("X", flag, value) - Sets the named flag for variable "X" to the value - of the Python variable called "value". + d.setVarFlag("X", flag, "value") + Sets the named flag for variable "X" to "value". - d.appendVarFlag("X", flag, value) - Appends a value to the named flag on the + d.appendVarFlag("X", flag, "value") + Appends "value" to the named flag on the variable "X". - d.prependVarFlag("X", flag, value) - Prepends a value to the named flag on + d.prependVarFlag("X", flag, "value") + Prepends "value" to the named flag on the variable "X". diff --git a/bitbake/doc/user-manual/user-manual-ref-variables.xml b/bitbake/doc/user-manual/user-manual-ref-variables.xml index b785f04aba..6a5af89ffa 100644 --- a/bitbake/doc/user-manual/user-manual-ref-variables.xml +++ b/bitbake/doc/user-manual/user-manual-ref-variables.xml @@ -102,6 +102,15 @@ + BB_CONSOLELOG + + + Specifies the path to a log file into which BitBake's user + interface writes output during the build. + + + + BB_CURRENTTASK @@ -681,12 +690,19 @@ BB_SIGNATURE_EXCLUDE_FLAGS - Lists flags that can be safely excluded from checksum + Lists variable flags (varflags) + that can be safely excluded from checksum and dependency data for keys in the datastore. When generating checksum or dependency data for keys in the datastore, the flags set against that key are normally included in the checksum. + + + For more information on varflags, see the + "Variable Flags" + section. + @@ -959,7 +975,23 @@ BBINCLUDELOGS - Variable that controls how BitBake displays logs on build failure. + + If set to a value, enables printing the task log when + reporting a failed task. + + + + + BBINCLUDELOGS_LINES + + + If + BBINCLUDELOGS + is set, specifies the maximum number of lines from the + task log file to print when reporting a failed task. + If you do not set BBINCLUDELOGS_LINES, + the entire log is printed. + @@ -1483,14 +1515,6 @@ the upstream source, and then locations specified by MIRRORS in that order. - - - Assuming your distribution (DISTRO) - is "poky", the default value for - MIRRORS is defined in the - conf/distro/poky.conf file in the - meta-yocto Git repository. - @@ -1696,15 +1720,6 @@ in that order. - - Assuming your distribution - (DISTRO) - is "poky", the default value for - PREMIRRORS is defined in the - conf/distro/poky.conf file in the - meta-yocto Git repository. - - Typically, you would add a specific server for the build system to attempt before any others by adding -- cgit v1.2.3-54-g00ecf