diff options
Diffstat (limited to 'import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml')
| -rw-r--r-- | import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml | 2319 |
1 files changed, 2319 insertions, 0 deletions
diff --git a/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml new file mode 100644 index 000000000..ae7e4cee8 --- /dev/null +++ b/import-layers/yocto-poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.xml @@ -0,0 +1,2319 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<!-- Dummy chapter --> +<chapter id='ref-variables-glos'> + +<title>Variables Glossary</title> + +<para> + This chapter lists common variables used by BitBake and gives an overview + of their function and contents. +</para> + +<note> + Following are some points regarding the variables listed in this glossary: + <itemizedlist> + <listitem><para>The variables listed in this glossary + are specific to BitBake. + Consequently, the descriptions are limited to that context. + </para></listitem> + <listitem><para>Also, variables exist in other systems that use BitBake + (e.g. The Yocto Project and OpenEmbedded) that have names identical + to those found in this glossary. + For such cases, the variables in those systems extend the + functionality of the variable as it is described here in + this glossary. + </para></listitem> + <listitem><para>Finally, there are variables mentioned in this + glossary that do not appear in the BitBake glossary. + These other variables are variables used in systems that use + BitBake. + </para></listitem> + </itemizedlist> +</note> + +<glossary id='ref-variables-glossary'> + + <para> + <link linkend='var-ASSUME_PROVIDED'>A</link> + <link linkend='var-B'>B</link> + <link linkend='var-CACHE'>C</link> + <link linkend='var-DEFAULT_PREFERENCE'>D</link> + <link linkend='var-EXCLUDE_FROM_WORLD'>E</link> + <link linkend='var-FAKEROOT'>F</link> + <link linkend='var-GITDIR'>G</link> + <link linkend='var-HGDIR'>H</link> +<!-- <link linkend='var-ICECC_DISABLED'>I</link> --> +<!-- <link linkend='var-glossary-j'>J</link> --> +<!-- <link linkend='var-KARCH'>K</link> --> + <link linkend='var-LAYERDEPENDS'>L</link> + <link linkend='var-MIRRORS'>M</link> +<!-- <link linkend='var-glossary-n'>N</link> --> + <link linkend='var-OVERRIDES'>O</link> + <link linkend='var-PACKAGES'>P</link> +<!-- <link linkend='var-QMAKE_PROFILES'>Q</link> --> + <link linkend='var-RDEPENDS'>R</link> + <link linkend='var-SECTION'>S</link> + <link linkend='var-T'>T</link> +<!-- <link linkend='var-UBOOT_CONFIG'>U</link> --> +<!-- <link linkend='var-glossary-v'>V</link> --> +<!-- <link linkend='var-WARN_QA'>W</link> --> +<!-- <link linkend='var-glossary-x'>X</link> --> +<!-- <link linkend='var-glossary-y'>Y</link> --> +<!-- <link linkend='var-glossary-z'>Z</link>--> + </para> + + <glossdiv id='var-glossary-a'><title>A</title> + + <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm> + <glossdef> + <para> + Lists recipe names + (<link linkend='var-PN'><filename>PN</filename></link> + values) BitBake does not attempt to build. + Instead, BitBake assumes these recipes have already been + built. + </para> + + <para> + In OpenEmbedded Core, <filename>ASSUME_PROVIDED</filename> + mostly specifies native tools that should not be built. + An example is <filename>git-native</filename>, which + when specified allows for the Git binary from the host to + be used rather than building + <filename>git-native</filename>. + </para> + </glossdef> + </glossentry> + + </glossdiv> + + + <glossdiv id='var-glossary-b'><title>B</title> + + <glossentry id='var-B'><glossterm>B</glossterm> + <glossdef> + <para> + The directory in which BitBake executes functions + during a recipe's build process. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_ALLOWED_NETWORKS'><glossterm>BB_ALLOWED_NETWORKS</glossterm> + <glossdef> + <para> + Specifies a space-delimited list of hosts that the fetcher + is allowed to use to obtain the required source code. + Following are considerations surrounding this variable: + <itemizedlist> + <listitem><para> + This host list is only used if + <link linkend='var-BB_NO_NETWORK'><filename>BB_NO_NETWORK</filename></link> + is either not set or set to "0". + </para></listitem> + <listitem><para> + Limited support for wildcard matching against the + beginning of host names exists. + For example, the following setting matches + <filename>git.gnu.org</filename>, + <filename>ftp.gnu.org</filename>, and + <filename>foo.git.gnu.org</filename>. + <literallayout class='monospaced'> + BB_ALLOWED_NETWORKS = "*.gnu.org" + </literallayout> + </para></listitem> + <listitem><para> + Mirrors not in the host list are skipped and + logged in debug. + </para></listitem> + <listitem><para> + Attempts to access networks not in the host list + cause a failure. + </para></listitem> + </itemizedlist> + Using <filename>BB_ALLOWED_NETWORKS</filename> in + conjunction with + <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link> + is very useful. + Adding the host you want to use to + <filename>PREMIRRORS</filename> results in the source code + being fetched from an allowed location and avoids raising + an error when a host that is not allowed is in a + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + statement. + This is because the fetcher does not attempt to use the + host listed in <filename>SRC_URI</filename> after a + successful fetch from the + <filename>PREMIRRORS</filename> occurs. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_CONSOLELOG'><glossterm>BB_CONSOLELOG</glossterm> + <glossdef> + <para> + Specifies the path to a log file into which BitBake's user + interface writes output during the build. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_CURRENTTASK'><glossterm>BB_CURRENTTASK</glossterm> + <glossdef> + <para> + Contains the name of the currently running task. + The name does not include the + <filename>do_</filename> prefix. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm> + <glossdef> + <para> + Defines how BitBake handles situations where an append + file (<filename>.bbappend</filename>) has no + corresponding recipe file (<filename>.bb</filename>). + This condition often occurs when layers get out of sync + (e.g. <filename>oe-core</filename> bumps a + recipe version and the old recipe no longer exists and the + other layer has not been updated to the new version + of the recipe yet). + </para> + + <para> + The default fatal behavior is safest because it is + the sane reaction given something is out of sync. + It is important to realize when your changes are no longer + being applied. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_DEFAULT_TASK'><glossterm>BB_DEFAULT_TASK</glossterm> + <glossdef> + <para> + The default task to use when none is specified (e.g. + with the <filename>-c</filename> command line option). + The task name specified should not include the + <filename>do_</filename> prefix. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm> + <glossdef> + <para> + Monitors disk space and available inodes during the build + and allows you to control the build based on these + parameters. + </para> + + <para> + Disk space monitoring is disabled by default. + When setting this variable, use the following form: + <literallayout class='monospaced'> + BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" + + where: + + <action> is: + ABORT: Immediately abort the build when + a threshold is broken. + STOPTASKS: Stop the build after the currently + executing tasks have finished when + a threshold is broken. + WARN: Issue a warning but continue the + build when a threshold is broken. + Subsequent warnings are issued as + defined by the + <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable, + which must be defined. + + <dir> is: + Any directory you choose. You can specify one or + more directories to monitor by separating the + groupings with a space. If two directories are + on the same device, only the first directory + is monitored. + + <threshold> is: + Either the minimum available disk space, + the minimum number of free inodes, or + both. You must specify at least one. To + omit one or the other, simply omit the value. + Specify the threshold using G, M, K for Gbytes, + Mbytes, and Kbytes, respectively. If you do + not specify G, M, or K, Kbytes is assumed by + default. Do not use GB, MB, or KB. + </literallayout> + </para> + + <para> + Here are some examples: + <literallayout class='monospaced'> + BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" + BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" + </literallayout> + The first example works only if you also set + the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable. + This example causes the build system to immediately + abort when either the disk space in <filename>${TMPDIR}</filename> drops + below 1 Gbyte or the available free inodes drops below + 100 Kbytes. + Because two directories are provided with the variable, the + build system also issues a + warning when the disk space in the + <filename>${SSTATE_DIR}</filename> directory drops + below 1 Gbyte or the number of free inodes drops + below 100 Kbytes. + Subsequent warnings are issued during intervals as + defined by the <filename>BB_DISKMON_WARNINTERVAL</filename> + variable. + </para> + + <para> + The second example stops the build after all currently + executing tasks complete when the minimum disk space + in the <filename>${TMPDIR}</filename> + directory drops below 1 Gbyte. + No disk monitoring occurs for the free inodes in this case. + </para> + + <para> + The final example immediately aborts the build when the + number of free inodes in the <filename>${TMPDIR}</filename> directory + drops below 100 Kbytes. + No disk space monitoring for the directory itself occurs + in this case. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm> + <glossdef> + <para> + Defines the disk space and free inode warning intervals. + </para> + + <para> + If you are going to use the + <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must + also use the + <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable + and define its action as "WARN". + During the build, subsequent warnings are issued each time + disk space or number of free inodes further reduces by + the respective interval. + </para> + + <para> + If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename> + variable and you do use <filename>BB_DISKMON_DIRS</filename> with + the "WARN" action, the disk monitoring interval defaults to + the following: + <literallayout class='monospaced'> + BB_DISKMON_WARNINTERVAL = "50M,5K" + </literallayout> + </para> + + <para> + When specifying the variable in your configuration file, + use the following form: + <literallayout class='monospaced'> + BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" + + where: + + <disk_space_interval> is: + An interval of memory expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + + <disk_inode_interval> is: + An interval of free inodes expressed in either + G, M, or K for Gbytes, Mbytes, or Kbytes, + respectively. You cannot use GB, MB, or KB. + </literallayout> + </para> + + <para> + Here is an example: + <literallayout class='monospaced'> + BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" + BB_DISKMON_WARNINTERVAL = "50M,5K" + </literallayout> + These variables cause BitBake to + issue subsequent warnings each time the available + disk space further reduces by 50 Mbytes or the number + of free inodes further reduces by 5 Kbytes in the + <filename>${SSTATE_DIR}</filename> directory. + Subsequent warnings based on the interval occur each time + a respective interval is reached beyond the initial warning + (i.e. 1 Gbytes and 100 Kbytes). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_ENV_WHITELIST'><glossterm>BB_ENV_WHITELIST</glossterm> + <glossdef> + <para> + Specifies the internal whitelist of variables to allow + through from the external environment into BitBake's + datastore. + If the value of this variable is not specified + (which is the default), the following list is used: + <link linkend='var-BBPATH'><filename>BBPATH</filename></link>, + <link linkend='var-BB_PRESERVE_ENV'><filename>BB_PRESERVE_ENV</filename></link>, + <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>, + and + <link linkend='var-BB_ENV_EXTRAWHITE'><filename>BB_ENV_EXTRAWHITE</filename></link>. + <note> + You must set this variable in the external environment + in order for it to work. + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_ENV_EXTRAWHITE'><glossterm>BB_ENV_EXTRAWHITE</glossterm> + <glossdef> + <para> + Specifies an additional set of variables to allow through + (whitelist) from the external environment into BitBake's + datastore. + This list of variables are on top of the internal list + set in + <link linkend='var-BB_ENV_WHITELIST'><filename>BB_ENV_WHITELIST</filename></link>. + <note> + You must set this variable in the external + environment in order for it to work. + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_FETCH_PREMIRRORONLY'><glossterm>BB_FETCH_PREMIRRORONLY</glossterm> + <glossdef> + <para> + When set to "1", causes BitBake's fetcher module to only + search + <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link> + for files. + BitBake will not search the main + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + or + <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_FILENAME'><glossterm>BB_FILENAME</glossterm> + <glossdef> + <para> + Contains the filename of the recipe that owns the currently + running task. + For example, if the <filename>do_fetch</filename> task that + resides in the <filename>my-recipe.bb</filename> is + executing, the <filename>BB_FILENAME</filename> variable + contains "/foo/path/my-recipe.bb". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm> + <glossdef> + <para> + Causes tarballs of the Git repositories, including the + Git metadata, to be placed in the + <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link> + directory. + Anyone wishing to create a source mirror would want to + enable this variable. + </para> + + <para> + For performance reasons, creating and placing tarballs of + the Git repositories is not the default action by BitBake. + <literallayout class='monospaced'> + BB_GENERATE_MIRROR_TARBALLS = "1" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_HASHCONFIG_WHITELIST'><glossterm>BB_HASHCONFIG_WHITELIST</glossterm> + <glossdef> + <para> + Lists variables that are excluded from base configuration + checksum, which is used to determine if the cache can + be reused. + </para> + + <para> + One of the ways BitBake determines whether to re-parse the + main metadata is through checksums of the variables in the + datastore of the base configuration data. + There are variables that you typically want to exclude when + checking whether or not to re-parse and thus rebuild the + cache. + As an example, you would usually exclude + <filename>TIME</filename> and <filename>DATE</filename> + because these variables are always changing. + If you did not exclude them, BitBake would never reuse the + cache. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_HASHBASE_WHITELIST'><glossterm>BB_HASHBASE_WHITELIST</glossterm> + <glossdef> + <para> + Lists variables that are excluded from checksum and + dependency data. + Variables that are excluded can therefore change without + affecting the checksum mechanism. + A common example would be the variable for the path of + the build. + BitBake's output should not (and usually does not) depend + on the directory in which it was built. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_HASHCHECK_FUNCTION'><glossterm>BB_HASHCHECK_FUNCTION</glossterm> + <glossdef> + <para> + Specifies the name of the function to call during the + "setscene" part of the task's execution in order to + validate the list of task hashes. + The function returns the list of setscene tasks that should + be executed. + </para> + + <para> + At this point in the execution of the code, the objective + is to quickly verify if a given setscene function is likely + to work or not. + It's easier to check the list of setscene functions in + one pass than to call many individual tasks. + The returned list need not be completely accurate. + A given setscene task can still later fail. + However, the more accurate the data returned, the more + efficient the build will be. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_INVALIDCONF'><glossterm>BB_INVALIDCONF</glossterm> + <glossdef> + <para> + Used in combination with the + <filename>ConfigParsed</filename> event to trigger + re-parsing the base metadata (i.e. all the + recipes). + The <filename>ConfigParsed</filename> event can set the + variable to trigger the re-parse. + You must be careful to avoid recursive loops with this + functionality. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_LOGFMT'><glossterm>BB_LOGFMT</glossterm> + <glossdef> + <para> + Specifies the name of the log files saved into + <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>. + By default, the <filename>BB_LOGFMT</filename> variable + is undefined and the log file names get created using the + following form: + <literallayout class='monospaced'> + log.{task}.{pid} + </literallayout> + If you want to force log files to take a specific name, + you can set this variable in a configuration file. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_NICE_LEVEL'><glossterm>BB_NICE_LEVEL</glossterm> + <glossdef> + <para> + Allows BitBake to run at a specific priority + (i.e. nice level). + System permissions usually mean that BitBake can reduce its + priority but not raise it again. + See + <link linkend='var-BB_TASK_NICE_LEVEL'><filename>BB_TASK_NICE_LEVEL</filename></link> + for additional information. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_NO_NETWORK'><glossterm>BB_NO_NETWORK</glossterm> + <glossdef> + <para> + Disables network access in the BitBake fetcher modules. + With this access disabled, any command that attempts to + access the network becomes an error. + </para> + + <para> + Disabling network access is useful for testing source + mirrors, running builds when not connected to the Internet, + and when operating in certain kinds of firewall + environments. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm> + <glossdef> + <para> + The maximum number of tasks BitBake should run in parallel + at any one time. + If your host development system supports multiple cores, + a good rule of thumb is to set this variable to twice the + number of cores. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_NUMBER_PARSE_THREADS'><glossterm>BB_NUMBER_PARSE_THREADS</glossterm> + <glossdef> + <para> + Sets the number of threads BitBake uses when parsing. + By default, the number of threads is equal to the number + of cores on the system. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_ORIGENV'><glossterm>BB_ORIGENV</glossterm> + <glossdef> + <para> + Contains a copy of the original external environment in + which BitBake was run. + The copy is taken before any whitelisted variable values + are filtered into BitBake's datastore. + <note> + The contents of this variable is a datastore object + that can be queried using the normal datastore + operations. + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_PRESERVE_ENV'><glossterm>BB_PRESERVE_ENV</glossterm> + <glossdef> + <para> + Disables whitelisting and instead allows all variables + through from the external environment into BitBake's + datastore. + <note> + You must set this variable in the external + environment in order for it to work. + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_RUNFMT'><glossterm>BB_RUNFMT</glossterm> + <glossdef> + <para> + Specifies the name of the executable script files + (i.e. run files) saved into + <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>. + By default, the <filename>BB_RUNFMT</filename> variable + is undefined and the run file names get created using the + following form: + <literallayout class='monospaced'> + run.{task}.{pid} + </literallayout> + If you want to force run files to take a specific name, + you can set this variable in a configuration file. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_RUNTASK'><glossterm>BB_RUNTASK</glossterm> + <glossdef> + <para> + Contains the name of the currently executing task. + The value does not include the "do_" prefix. + For example, if the currently executing task is + <filename>do_config</filename>, the value is + "config". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_SCHEDULER'><glossterm>BB_SCHEDULER</glossterm> + <glossdef> + <para> + Selects the name of the scheduler to use for the + scheduling of BitBake tasks. + Three options exist: + <itemizedlist> + <listitem><para><emphasis>basic</emphasis> - + The basic framework from which everything derives. + Using this option causes tasks to be ordered + numerically as they are parsed. + </para></listitem> + <listitem><para><emphasis>speed</emphasis> - + Executes tasks first that have more tasks + depending on them. + The "speed" option is the default. + </para></listitem> + <listitem><para><emphasis>completion</emphasis> - + Causes the scheduler to try to complete a given + recipe once its build has started. + </para></listitem> + </itemizedlist> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_SCHEDULERS'><glossterm>BB_SCHEDULERS</glossterm> + <glossdef> + <para> + Defines custom schedulers to import. + Custom schedulers need to be derived from the + <filename>RunQueueScheduler</filename> class. + </para> + + <para> + For information how to select a scheduler, see the + <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_SETSCENE_DEPVALID'><glossterm>BB_SETSCENE_DEPVALID</glossterm> + <glossdef> + <para> + Specifies a function BitBake calls that determines + whether BitBake requires a setscene dependency to be met. + </para> + + <para> + When running a setscene task, BitBake needs to + know which dependencies of that setscene task also need + to be run. + Whether dependencies also need to be run is highly + dependent on the metadata. + The function specified by this variable returns a + "True" or "False" depending on whether the dependency needs + to be met. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_SETSCENE_VERIFY_FUNCTION'><glossterm>BB_SETSCENE_VERIFY_FUNCTION</glossterm> + <glossdef> + <para> + Specifies a function to call that verifies the list of + planned task execution before the main task execution + happens. + The function is called once BitBake has a list of setscene + tasks that have run and either succeeded or failed. + </para> + + <para> + The function allows for a task list check to see if they + make sense. + Even if BitBake was planning to skip a task, the + returned value of the function can force BitBake to run + the task, which is necessary under certain metadata + defined circumstances. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_SIGNATURE_EXCLUDE_FLAGS'><glossterm>BB_SIGNATURE_EXCLUDE_FLAGS</glossterm> + <glossdef> + <para> + 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. + </para> + + <para> + For more information on varflags, see the + "<link linkend='variable-flags'>Variable Flags</link>" + section. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_SIGNATURE_HANDLER'><glossterm>BB_SIGNATURE_HANDLER</glossterm> + <glossdef> + <para> + Defines the name of the signature handler BitBake uses. + The signature handler defines the way stamp files are + created and handled, if and how the signature is + incorporated into the stamps, and how the signature + itself is generated. + </para> + + <para> + A new signature handler can be added by injecting a class + derived from the + <filename>SignatureGenerator</filename> class into the + global namespace. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_SRCREV_POLICY'><glossterm>BB_SRCREV_POLICY</glossterm> + <glossdef> + <para> + Defines the behavior of the fetcher when it interacts with + source control systems and dynamic source revisions. + The <filename>BB_SRCREV_POLICY</filename> variable is + useful when working without a network. + </para> + + <para> + The variable can be set using one of two policies: + <itemizedlist> + <listitem><para><emphasis>cache</emphasis> - + Retains the value the system obtained previously + rather than querying the source control system + each time. + </para></listitem> + <listitem><para><emphasis>clear</emphasis> - + Queries the source controls system every time. + With this policy, there is no cache. + The "clear" policy is the default. + </para></listitem> + </itemizedlist> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_STAMP_POLICY'><glossterm>BB_STAMP_POLICY</glossterm> + <glossdef> + <para> + Defines the mode used for how timestamps of stamp files + are compared. + You can set the variable to one of the following modes: + <itemizedlist> + <listitem><para><emphasis>perfile</emphasis> - + Timestamp comparisons are only made + between timestamps of a specific recipe. + This is the default mode. + </para></listitem> + <listitem><para><emphasis>full</emphasis> - + Timestamp comparisons are made for all + dependencies. + </para></listitem> + <listitem><para><emphasis>whitelist</emphasis> - + Identical to "full" mode except timestamp + comparisons are made for recipes listed in the + <link linkend='var-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link> + variable. + </para></listitem> + </itemizedlist> + <note> + Stamp policies are largely obsolete with the + introduction of setscene tasks. + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_STAMP_WHITELIST'><glossterm>BB_STAMP_WHITELIST</glossterm> + <glossdef> + <para> + Lists files whose stamp file timestamps are compared when + the stamp policy mode is set to "whitelist". + For information on stamp policies, see the + <link linkend='var-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_STRICT_CHECKSUM'><glossterm>BB_STRICT_CHECKSUM</glossterm> + <glossdef> + <para> + Sets a more strict checksum mechanism for non-local URLs. + Setting this variable to a value causes BitBake + to report an error if it encounters a non-local URL + that does not have at least one checksum specified. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_TASK_IONICE_LEVEL'><glossterm>BB_TASK_IONICE_LEVEL</glossterm> + <glossdef> + <para> + Allows adjustment of a task's Input/Output priority. + During Autobuilder testing, random failures can occur + for tasks due to I/O starvation. + These failures occur during various QEMU runtime timeouts. + You can use the <filename>BB_TASK_IONICE_LEVEL</filename> + variable to adjust the I/O priority of these tasks. + <note> + This variable works similarly to the + <link linkend='var-BB_TASK_NICE_LEVEL'><filename>BB_TASK_NICE_LEVEL</filename></link> + variable except with a task's I/O priorities. + </note> + </para> + + <para> + Set the variable as follows: + <literallayout class='monospaced'> + BB_TASK_IONICE_LEVEL = "<replaceable>class</replaceable>.<replaceable>prio</replaceable>" + </literallayout> + For <replaceable>class</replaceable>, the default value is + "2", which is a best effort. + You can use "1" for realtime and "3" for idle. + If you want to use realtime, you must have superuser + privileges. + </para> + + <para> + For <replaceable>prio</replaceable>, you can use any + value from "0", which is the highest priority, to "7", + which is the lowest. + The default value is "4". + You do not need any special privileges to use this range + of priority values. + <note> + In order for your I/O priority settings to take effect, + you need the Completely Fair Queuing (CFQ) Scheduler + selected for the backing block device. + To select the scheduler, use the following command form + where <replaceable>device</replaceable> is the device + (e.g. sda, sdb, and so forth): + <literallayout class='monospaced'> + $ sudo sh -c “echo cfq > /sys/block/<replaceable>device</replaceable>/queu/scheduler + </literallayout> + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_TASK_NICE_LEVEL'><glossterm>BB_TASK_NICE_LEVEL</glossterm> + <glossdef> + <para> + Allows specific tasks to change their priority + (i.e. nice level). + </para> + + <para> + You can use this variable in combination with task + overrides to raise or lower priorities of specific tasks. + For example, on the + <ulink url='http://www.yoctoproject.org'>Yocto Project</ulink> + autobuilder, QEMU emulation in images is given a higher + priority as compared to build tasks to ensure that images + do not suffer timeouts on loaded systems. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_TASKHASH'><glossterm>BB_TASKHASH</glossterm> + <glossdef> + <para> + Within an executing task, this variable holds the hash + of the task as returned by the currently enabled + signature generator. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_VERBOSE_LOGS'><glossterm>BB_VERBOSE_LOGS</glossterm> + <glossdef> + <para> + Controls how verbose BitBake is during builds. + If set, shell scripts echo commands and shell script output + appears on standard out (stdout). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BB_WORKERCONTEXT'><glossterm>BB_WORKERCONTEXT</glossterm> + <glossdef> + <para> + Specifies if the current context is executing a task. + BitBake sets this variable to "1" when a task is + being executed. + The value is not set when the task is in server context + during parsing or event handling. + </para> + </glossdef> + </glossentry> + + + <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm> + <glossdef> + <para> + Allows you to extend a recipe so that it builds variants + of the software. + Some examples of these variants for recipes from the + OpenEmbedded Core metadata are "natives" such as + <filename>quilt-native</filename>, which is a copy of + Quilt built to run on the build system; "crosses" such + as <filename>gcc-cross</filename>, which is a compiler + built to run on the build machine but produces binaries + that run on the target <filename>MACHINE</filename>; + "nativesdk", which targets the SDK machine instead of + <filename>MACHINE</filename>; and "mulitlibs" in the form + "<filename>multilib:</filename><replaceable>multilib_name</replaceable>". + </para> + + <para> + To build a different variant of the recipe with a minimal + amount of code, it usually is as simple as adding the + variable to your recipe. + Here are two examples. + The "native" variants are from the OpenEmbedded Core + metadata: + <literallayout class='monospaced'> + BBCLASSEXTEND =+ "native nativesdk" + BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBDEBUG'><glossterm>BBDEBUG</glossterm> + <glossdef> + <para> + Sets the BitBake debug output level to a specific value + as incremented by the <filename>-d</filename> command line + option. + <note> + You must set this variable in the external environment + in order for it to work. + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm> + <glossdef> + <para>Lists the names of configured layers. + These names are used to find the other <filename>BBFILE_*</filename> + variables. + Typically, each layer appends its name to this variable in its + <filename>conf/layer.conf</filename> file. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm> + <glossdef> + <para>Variable that expands to match files from + <link linkend='var-BBFILES'><filename>BBFILES</filename></link> + in a particular layer. + This variable is used in the <filename>conf/layer.conf</filename> file and must + be suffixed with the name of the specific layer (e.g. + <filename>BBFILE_PATTERN_emenlow</filename>).</para> + </glossdef> + </glossentry> + + <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm> + <glossdef> + <para>Assigns the priority for recipe files in each layer.</para> + <para>This variable is useful in situations where the same recipe appears in + more than one layer. + Setting this variable allows you to prioritize a + layer against other layers that contain the same recipe - effectively + letting you control the precedence for the multiple layers. + The precedence established through this variable stands regardless of a + recipe's version + (<link linkend='var-PV'><filename>PV</filename></link> variable). + For example, a layer that has a recipe with a higher <filename>PV</filename> value but for + which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a + lower precedence.</para> + <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher + precedence. + For example, the value 6 has a higher precedence than the value 5. + If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer + dependencies (see the + <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for + more information. + The default priority, if unspecified + for a layer with no dependencies, is the lowest defined priority + 1 + (or 1 if no priorities are defined).</para> + <tip> + You can use the command <filename>bitbake-layers show-layers</filename> to list + all configured layers along with their priorities. + </tip> + </glossdef> + </glossentry> + + <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm> + <glossdef> + <para>List of recipe files BitBake uses to build software.</para> + </glossdef> + </glossentry> + + <glossentry id='var-BBINCLUDED'><glossterm>BBINCLUDED</glossterm> + <glossdef> + <para> + Contains a space-separated list of all of all files that + BitBake's parser included during parsing of the current + file. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm> + <glossdef> + <para> + If set to a value, enables printing the task log when + reporting a failed task. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm> + <glossdef> + <para> + If + <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link> + 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 <filename>BBINCLUDELOGS_LINES</filename>, + the entire log is printed. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm> + <glossdef> + <para>Lists the layers to enable during the build. + This variable is defined in the <filename>bblayers.conf</filename> configuration + file in the build directory. + Here is an example: + <literallayout class='monospaced'> + BBLAYERS = " \ + /home/scottrif/poky/meta \ + /home/scottrif/poky/meta-yocto \ + /home/scottrif/poky/meta-yocto-bsp \ + /home/scottrif/poky/meta-mykernel \ + " + + </literallayout> + This example enables four layers, one of which is a custom, user-defined layer + named <filename>meta-mykernel</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBLAYERS_FETCH_DIR'><glossterm>BBLAYERS_FETCH_DIR</glossterm> + <glossdef> + <para> + Sets the base location where layers are stored. + By default, this location is set to + <filename>${COREBASE}</filename>. + This setting is used in conjunction with + <filename>bitbake-layers layerindex-fetch</filename> and + tells <filename>bitbake-layers</filename> where to place + the fetched layers. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm> + <glossdef> + <para> + Prevents BitBake from processing recipes and recipe + append files. + </para> + + <para> + You can use the <filename>BBMASK</filename> variable + to "hide" these <filename>.bb</filename> and + <filename>.bbappend</filename> files. + BitBake ignores any recipe or recipe append files that + match any of the expressions. + It is as if BitBake does not see them at all. + Consequently, matching files are not parsed or otherwise + used by BitBake.</para> + <para> + The values you provide are passed to Python's regular + expression compiler. + The expressions are compared against the full paths to + the files. + For complete syntax information, see Python's + documentation at + <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>. + </para> + + <para> + The following example uses a complete regular expression + to tell BitBake to ignore all recipe and recipe append + files in the <filename>meta-ti/recipes-misc/</filename> + directory: + <literallayout class='monospaced'> + BBMASK = "meta-ti/recipes-misc/" + </literallayout> + If you want to mask out multiple directories or recipes, + you can specify multiple regular expression fragments. + This next example masks out multiple directories and + individual recipes: + <literallayout class='monospaced'> + BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" + BBMASK += "/meta-oe/recipes-support/" + BBMASK += "/meta-foo/.*/openldap" + BBMASK += "opencv.*\.bbappend" + BBMASK += "lzma" + </literallayout> + <note> + When specifying a directory name, use the trailing + slash character to ensure you match just that directory + name. + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm> + <glossdef> + <para> + Used by BitBake to locate class + (<filename>.bbclass</filename>) and configuration + (<filename>.conf</filename>) files. + This variable is analogous to the + <filename>PATH</filename> variable. + </para> + + <para> + If you run BitBake from a directory outside of the + build directory, + you must be sure to set + <filename>BBPATH</filename> to point to the + build directory. + Set the variable as you would any environment variable + and then run BitBake: + <literallayout class='monospaced'> + $ BBPATH="<replaceable>build_directory</replaceable>" + $ export BBPATH + $ bitbake <replaceable>target</replaceable> + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm> + <glossdef> + <para> + Points to the server that runs memory-resident BitBake. + The variable is only used when you employ memory-resident + BitBake. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBTARGETS'><glossterm>BBTARGETS</glossterm> + <glossdef> + <para> + Allows you to use a configuration file to add to the list + of command-line target recipes you want to build. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBVERSIONS'><glossterm>BBVERSIONS</glossterm> + <glossdef> + <para> + Allows a single recipe to build multiple versions of a + project from a single recipe file. + You also able to specify conditional metadata + using the + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> + mechanism for a single version or for an optionally named + range of versions. + </para> + + <para> + For more information on <filename>BBVERSIONS</filename>, + see the + "<link linkend='variants-class-extension-mechanism'>Variants - Class Extension Mechanism</link>" + section. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BITBAKE_UI'><glossterm>BITBAKE_UI</glossterm> + <glossdef> + <para> + Used to specify the UI module to use when running BitBake. + Using this variable is equivalent to using the + <filename>-u</filename> command-line option. + <note> + You must set this variable in the external environment + in order for it to work. + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BUILDNAME'><glossterm>BUILDNAME</glossterm> + <glossdef> + <para> + A name assigned to the build. + The name defaults to a datetime stamp of when the build was + started but can be defined by the metadata. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BZRDIR'><glossterm>BZRDIR</glossterm> + <glossdef> + <para> + The directory in which files checked out of a Bazaar + system are stored. + </para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-c'><title>C</title> + + <glossentry id='var-CACHE'><glossterm>CACHE</glossterm> + <glossdef> + <para> + Specifies the directory BitBake uses to store a cache + of the metadata so it does not need to be parsed every + time BitBake is started. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-CVSDIR'><glossterm>CVSDIR</glossterm> + <glossdef> + <para> + The directory in which files checked out under the + CVS system are stored. + </para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-d'><title>D</title> + + <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm> + <glossdef> + <para> + Specifies a weak bias for recipe selection priority. + </para> + <para> + The most common usage of this is variable is to set + it to "-1" within a recipe for a development version of a + piece of software. + Using the variable in this way causes the stable version + of the recipe to build by default in the absence of + <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename> + being used to build the development version. + </para> + <note> + The bias provided by <filename>DEFAULT_PREFERENCE</filename> + is weak and is overridden by + <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename> + if that variable is different between two layers + that contain different versions of the same recipe. + </note> + </glossdef> + </glossentry> + + <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm> + <glossdef> + <para> + Lists a recipe's build-time dependencies + (i.e. other recipe files). + </para> + + <para> + Consider this simple example for two recipes named "a" and + "b" that produce similarly named packages. + In this example, the <filename>DEPENDS</filename> + statement appears in the "a" recipe: + <literallayout class='monospaced'> + DEPENDS = "b" + </literallayout> + Here, the dependency is such that the + <filename>do_configure</filename> task for recipe "a" + depends on the <filename>do_populate_sysroot</filename> + task of recipe "b". + This means anything that recipe "b" puts into sysroot + is available when recipe "a" is configuring itself. + </para> + + <para> + For information on runtime dependencies, see the + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm> + <glossdef> + <para> + A long description for the recipe. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm> + <glossdef> + <para> + The central download directory used by the build process to + store downloads. + By default, <filename>DL_DIR</filename> gets files + suitable for mirroring for everything except Git + repositories. + If you want tarballs of Git repositories, use the + <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link> + variable. + </para> + </glossdef> + + </glossentry> + </glossdiv> + + <glossdiv id='var-glossary-e'><title>E</title> + + <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm> + <glossdef> + <para> + Directs BitBake to exclude a recipe from world builds (i.e. + <filename>bitbake world</filename>). + During world builds, BitBake locates, parses and builds all + recipes found in every layer exposed in the + <filename>bblayers.conf</filename> configuration file. + </para> + + <para> + To exclude a recipe from a world build using this variable, + set the variable to "1" in the recipe. + </para> + + <note> + Recipes added to <filename>EXCLUDE_FROM_WORLD</filename> + may still be built during a world build in order to satisfy + dependencies of other recipes. + Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename> + only ensures that the recipe is not explicitly added + to the list of build targets in a world build. + </note> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-f'><title>F</title> + + <glossentry id='var-FAKEROOT'><glossterm>FAKEROOT</glossterm> + <glossdef> + <para> + Contains the command to use when running a shell script + in a fakeroot environment. + The <filename>FAKEROOT</filename> variable is obsolete + and has been replaced by the other + <filename>FAKEROOT*</filename> variables. + See these entries in the glossary for more information. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FAKEROOTBASEENV'><glossterm>FAKEROOTBASEENV</glossterm> + <glossdef> + <para> + Lists environment variables to set when executing + the command defined by + <link linkend='var-FAKEROOTCMD'><filename>FAKEROOTCMD</filename></link> + that starts the bitbake-worker process + in the fakeroot environment. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FAKEROOTCMD'><glossterm>FAKEROOTCMD</glossterm> + <glossdef> + <para> + Contains the command that starts the bitbake-worker + process in the fakeroot environment. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FAKEROOTDIRS'><glossterm>FAKEROOTDIRS</glossterm> + <glossdef> + <para> + Lists directories to create before running a task in + the fakeroot environment. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FAKEROOTENV'><glossterm>FAKEROOTENV</glossterm> + <glossdef> + <para> + Lists environment variables to set when running a task + in the fakeroot environment. + For additional information on environment variables and + the fakeroot environment, see the + <link linkend='var-FAKEROOTBASEENV'><filename>FAKEROOTBASEENV</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FAKEROOTNOENV'><glossterm>FAKEROOTNOENV</glossterm> + <glossdef> + <para> + Lists environment variables to set when running a task + that is not in the fakeroot environment. + For additional information on environment variables and + the fakeroot environment, see the + <link linkend='var-FAKEROOTENV'><filename>FAKEROOTENV</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FETCHCMD'><glossterm>FETCHCMD</glossterm> + <glossdef> + <para> + Defines the command the BitBake fetcher module + executes when running fetch operations. + You need to use an override suffix when you use the + variable (e.g. <filename>FETCHCMD_git</filename> + or <filename>FETCHCMD_svn</filename>). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FILE'><glossterm>FILE</glossterm> + <glossdef> + <para> + Points at the current file. + BitBake sets this variable during the parsing process + to identify the file being parsed. + BitBake also sets this variable when a recipe is being + executed to identify the recipe file. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FILESDIR'><glossterm>FILESDIR</glossterm> + <glossdef> + <para> + Specifies directories BitBake uses when searching for + patches and files. + The "local" fetcher module uses these directories when + handling <filename>file://</filename> URLs if the file + was not found using + <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>. + <note> + The <filename>FILESDIR</filename> variable is + deprecated and you should use + <filename>FILESPATH</filename> in all new code. + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm> + <glossdef> + <para> + Specifies directories BitBake uses when searching for + patches and files. + The "local" fetcher module uses these directories when + handling <filename>file://</filename> URLs. + The variable behaves like a shell <filename>PATH</filename> + environment variable. + The value is a colon-separated list of directories that + are searched left-to-right in order. + </para> + </glossdef> + </glossentry> + + </glossdiv> + + + <glossdiv id='var-glossary-g'><title>G</title> + + <glossentry id='var-GITDIR'><glossterm>GITDIR</glossterm> + <glossdef> + <para> + The directory in which a local copy of a Git repository + is stored when it is cloned. + </para> + </glossdef> + </glossentry> + + </glossdiv> + + + <glossdiv id='var-glossary-h'><title>H</title> + + <glossentry id='var-HGDIR'><glossterm>HGDIR</glossterm> + <glossdef> + <para> + The directory in which files checked out of a Mercurial + system are stored. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm> + <glossdef> + <para>Website where more information about the software the recipe is building + can be found.</para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-i'><title>I</title> + + <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> + <glossdef> + <para> + Causes the named class to be inherited at + this point during parsing. + The variable is only valid in configuration files. + </para> + </glossdef> + </glossentry> + + </glossdiv> + +<!-- + <glossdiv id='var-glossary-j'><title>J</title> + </glossdiv> + + <glossdiv id='var-glossary-k'><title>K</title> + </glossdiv> +--> + + <glossdiv id='var-glossary-l'><title>L</title> + + <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm> + <glossdef> + <para>Lists the layers, separated by spaces, upon which this recipe depends. + Optionally, you can specify a specific layer version for a dependency + by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" + to be compared against + <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename> + in this case). + BitBake produces an error if any dependency is missing or + the version numbers do not match exactly (if specified).</para> + <para> + You use this variable in the <filename>conf/layer.conf</filename> file. + You must also use the specific layer name as a suffix + to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para> + </glossdef> + </glossentry> + + <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm> + <glossdef> + <para>When used inside the <filename>layer.conf</filename> configuration + file, this variable provides the path of the current layer. + This variable is not available outside of <filename>layer.conf</filename> + and references are expanded immediately when parsing of the file completes.</para> + </glossdef> + </glossentry> + + <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm> + <glossdef> + <para>Optionally specifies the version of a layer as a single number. + You can use this variable within + <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link> + for another layer in order to depend on a specific version + of the layer.</para> + <para> + You use this variable in the <filename>conf/layer.conf</filename> file. + You must also use the specific layer name as a suffix + to the variable (e.g. <filename>LAYERDEPENDS_mylayer</filename>).</para> + </glossdef> + </glossentry> + + <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm> + <glossdef> + <para> + The list of source licenses for the recipe. + </para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-m'><title>M</title> + + <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm> + <glossdef> + <para> + Specifies additional paths from which BitBake gets source code. + When the build system searches for source code, it first + tries the local download directory. + If that location fails, the build system tries locations + defined by + <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>, + the upstream source, and then locations specified by + <filename>MIRRORS</filename> in that order. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-MULTI_PROVIDER_WHITELIST'><glossterm>MULTI_PROVIDER_WHITELIST</glossterm> + <glossdef> + <para> + Allows you to suppress BitBake warnings caused when + building two separate recipes that provide the same + output. + </para> + + <para> + Bitbake normally issues a warning when building two + different recipes where each provides the same output. + This scenario is usually something the user does not + want. + However, cases do exist where it makes sense, particularly + in the <filename>virtual/*</filename> namespace. + You can use this variable to suppress BitBake's warnings. + </para> + + <para> + To use the variable, list provider names (e.g. + recipe names, <filename>virtual/kernel</filename>, + and so forth). + </para> + </glossdef> + </glossentry> + + </glossdiv> + +<!-- + <glossdiv id='var-glossary-n'><title>N</title> + </glossdiv> +--> + + <glossdiv id='var-glossary-o'><title>O</title> + + <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm> + <glossdef> + <para> + BitBake uses <filename>OVERRIDES</filename> to control + what variables are overridden after BitBake parses + recipes and configuration files. + </para> + + <para> + Following is a simple example that uses an overrides + list based on machine architectures: + <literallayout class='monospaced'> + OVERRIDES = "arm:x86:mips:powerpc" + </literallayout> + You can find information on how to use + <filename>OVERRIDES</filename> in the + "<link linkend='conditional-syntax-overrides'>Conditional Syntax (Overrides)</link>" + section. + </para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id='var-glossary-p'><title>P</title> + + <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm> + <glossdef> + <para>The list of packages the recipe creates. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm> + <glossdef> + <para> + A promise that your recipe satisfies runtime dependencies + for optional modules that are found in other recipes. + <filename>PACKAGES_DYNAMIC</filename> + does not actually satisfy the dependencies, it only states that + they should be satisfied. + For example, if a hard, runtime dependency + (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>) + of another package is satisfied during the build + through the <filename>PACKAGES_DYNAMIC</filename> + variable, but a package with the module name is never actually + produced, then the other package will be broken. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PE'><glossterm>PE</glossterm> + <glossdef> + <para> + The epoch of the recipe. + By default, this variable is unset. + The variable is used to make upgrades possible when the + versioning scheme changes in some backwards incompatible + way. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PERSISTENT_DIR'><glossterm>PERSISTENT_DIR</glossterm> + <glossdef> + <para> + Specifies the directory BitBake uses to store data that + should be preserved between builds. + In particular, the data stored is the data that uses + BitBake's persistent data API and the data used by the + PR Server and PR Service. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PF'><glossterm>PF</glossterm> + <glossdef> + <para> + Specifies the recipe or package name and includes all version and revision + numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and + <filename>bash-4.2-r1/</filename>). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PN'><glossterm>PN</glossterm> + <glossdef> + <para>The recipe name.</para> + </glossdef> + </glossentry> + + <glossentry id='var-PR'><glossterm>PR</glossterm> + <glossdef> + <para>The revision of the recipe. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm> + <glossdef> + <para> + Determines which recipe should be given preference when + multiple recipes provide the same item. + You should always suffix the variable with the name of the + provided item, and you should set it to the + <link linkend='var-PN'><filename>PN</filename></link> + of the recipe to which you want to give precedence. + Some examples: + <literallayout class='monospaced'> + PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" + PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" + PREFERRED_PROVIDER_virtual/libgl ?= "mesa" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PREFERRED_PROVIDERS'><glossterm>PREFERRED_PROVIDERS</glossterm> + <glossdef> + <para> + Determines which recipe should be given preference for + cases where multiple recipes provide the same item. + Functionally, + <filename>PREFERRED_PROVIDERS</filename> is identical to + <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>. + However, the <filename>PREFERRED_PROVIDERS</filename> + variable lets you define preferences for multiple + situations using the following form: + <literallayout class='monospaced'> + PREFERRED_PROVIDERS = "xxx:yyy aaa:bbb ..." + </literallayout> + This form is a convenient replacement for the following: + <literallayout class='monospaced'> + PREFERRED_PROVIDER_xxx = "yyy" + PREFERRED_PROVIDER_aaa = "bbb" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm> + <glossdef> + <para> + If there are multiple versions of recipes available, this + variable determines which recipe should be given preference. + You must always suffix the variable with the + <link linkend='var-PN'><filename>PN</filename></link> + you want to select, and you should set + <link linkend='var-PV'><filename>PV</filename></link> + accordingly for precedence. + You can use the "<filename>%</filename>" character as a + wildcard to match any number of characters, which can be + useful when specifying versions that contain long revision + numbers that could potentially change. + Here are two examples: + <literallayout class='monospaced'> + PREFERRED_VERSION_python = "2.7.3" + PREFERRED_VERSION_linux-yocto = "3.10%" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm> + <glossdef> + <para> + Specifies additional paths from which BitBake gets source code. + When the build system searches for source code, it first + tries the local download directory. + If that location fails, the build system tries locations + defined by <filename>PREMIRRORS</filename>, the upstream + source, and then locations specified by + <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link> + in that order. + </para> + + <para> + Typically, you would add a specific server for the + build system to attempt before any others by adding + something like the following to your configuration: + <literallayout class='monospaced'> + PREMIRRORS_prepend = "\ + git://.*/.* http://www.yoctoproject.org/sources/ \n \ + ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ + http://.*/.* http://www.yoctoproject.org/sources/ \n \ + https://.*/.* http://www.yoctoproject.org/sources/ \n" + </literallayout> + These changes cause the build system to intercept + Git, FTP, HTTP, and HTTPS requests and direct them to + the <filename>http://</filename> sources mirror. + You can use <filename>file://</filename> URLs to point + to local directories or network shares as well. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm> + <glossdef> + <para> + A list of aliases by which a particular recipe can be + known. + By default, a recipe's own + <filename><link linkend='var-PN'>PN</link></filename> + is implicitly already in its <filename>PROVIDES</filename> + list. + If a recipe uses <filename>PROVIDES</filename>, the + additional aliases are synonyms for the recipe and can + be useful satisfying dependencies of other recipes during + the build as specified by + <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>. + </para> + + <para> + Consider the following example + <filename>PROVIDES</filename> statement from a recipe + file <filename>libav_0.8.11.bb</filename>: + <literallayout class='monospaced'> + PROVIDES += "libpostproc" + </literallayout> + The <filename>PROVIDES</filename> statement results in + the "libav" recipe also being known as "libpostproc". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm> + <glossdef> + <para> + The network based + <link linkend='var-PR'><filename>PR</filename></link> + service host and port. + </para> + + <para> + Following is an example of how the <filename>PRSERV_HOST</filename> variable is + set: + <literallayout class='monospaced'> + PRSERV_HOST = "localhost:0" + </literallayout> + You must set the variable if you want to automatically + start a local PR service. + You can set <filename>PRSERV_HOST</filename> to other + values to use a remote PR service. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PV'><glossterm>PV</glossterm> + <glossdef> + <para>The version of the recipe. + </para> + </glossdef> + </glossentry> + + </glossdiv> + +<!-- + <glossdiv id='var-glossary-q'><title>Q</title> + </glossdiv> +--> + + <glossdiv id='var-glossary-r'><title>R</title> + + <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> + <glossdef> + <para> + Lists a package's runtime dependencies (i.e. other packages) + that must be installed in order for the built package to run + correctly. + If a package in this list cannot be found during the build, + you will get a build error. + </para> + + <para> + Because the <filename>RDEPENDS</filename> variable applies + to packages being built, you should always use the variable + in a form with an attached package name. + For example, suppose you are building a development package + that depends on the <filename>perl</filename> package. + In this case, you would use the following + <filename>RDEPENDS</filename> statement: + <literallayout class='monospaced'> + RDEPENDS_${PN}-dev += "perl" + </literallayout> + In the example, the development package depends on + the <filename>perl</filename> package. + Thus, the <filename>RDEPENDS</filename> variable has the + <filename>${PN}-dev</filename> package name as part of the + variable. + </para> + + <para> + BitBake supports specifying versioned dependencies. + Although the syntax varies depending on the packaging + format, BitBake hides these differences from you. + Here is the general syntax to specify versions with + the <filename>RDEPENDS</filename> variable: + <literallayout class='monospaced'> + RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" + </literallayout> + For <filename>operator</filename>, you can specify the + following: + <literallayout class='monospaced'> + = + < + > + <= + >= + </literallayout> + For example, the following sets up a dependency on version + 1.2 or greater of the package <filename>foo</filename>: + <literallayout class='monospaced'> + RDEPENDS_${PN} = "foo (>= 1.2)" + </literallayout> + </para> + + <para> + For information on build-time dependencies, see the + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm> + <glossdef> + <para> + A list of package name aliases that a package also provides. + These aliases are useful for satisfying runtime dependencies + of other packages both during the build and on the target + (as specified by + <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>). + </para> + <para> + As with all package-controlling variables, you must always + use the variable in conjunction with a package name override. + Here is an example: + <literallayout class='monospaced'> + RPROVIDES_${PN} = "widget-abi-2" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm> + <glossdef> + <para> + A list of packages that extends the usability of a package + being built. + The package being built does not depend on this list of + packages in order to successfully build, but needs them for + the extended usability. + To specify runtime dependencies for packages, see the + <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> + variable. + </para> + + <para> + BitBake supports specifying versioned recommends. + Although the syntax varies depending on the packaging + format, BitBake hides these differences from you. + Here is the general syntax to specify versions with + the <filename>RRECOMMENDS</filename> variable: + <literallayout class='monospaced'> + RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" + </literallayout> + For <filename>operator</filename>, you can specify the + following: + <literallayout class='monospaced'> + = + < + > + <= + >= + </literallayout> + For example, the following sets up a recommend on version + 1.2 or greater of the package <filename>foo</filename>: + <literallayout class='monospaced'> + RRECOMMENDS_${PN} = "foo (>= 1.2)" + </literallayout> + </para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-s'><title>S</title> + + <glossentry id='var-SECTION'><glossterm>SECTION</glossterm> + <glossdef> + <para>The section in which packages should be categorized.</para> + </glossdef> + </glossentry> + + <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm> + <glossdef> + <para> + The list of source files - local or remote. + This variable tells BitBake which bits + to pull for the build and how to pull them. + For example, if the recipe or append file needs to + fetch a single tarball from the Internet, the recipe or + append file uses a <filename>SRC_URI</filename> + entry that specifies that tarball. + On the other hand, if the recipe or append file needs to + fetch a tarball and include a custom file, the recipe or + append file needs an <filename>SRC_URI</filename> variable + that specifies all those sources.</para> + <para>The following list explains the available URI protocols: + <itemizedlist> + <listitem><para><emphasis><filename>file://</filename> -</emphasis> + Fetches files, which are usually files shipped with + the metadata, + from the local machine. + The path is relative to the + <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> + variable.</para></listitem> + <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a + Bazaar revision control repository.</para></listitem> + <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a + Git revision control repository.</para></listitem> + <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from + an OSC (OpenSUSE Build service) revision control repository.</para></listitem> + <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from + a repo (Git) repository.</para></listitem> + <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from + the Internet using HTTP.</para></listitem> + <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files + from the Internet using HTTPS.</para></listitem> + <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files + from the Internet using FTP.</para></listitem> + <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from + a CVS revision control repository.</para></listitem> + <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from + a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem> + <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from + a Perforce (<filename>p4</filename>) revision control repository.</para></listitem> + <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from + a secure shell.</para></listitem> + <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from + a Subversion (<filename>svn</filename>) revision control repository.</para></listitem> + </itemizedlist> + </para> + <para>Here are some additional options worth mentioning: + <itemizedlist> + <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls + whether or not to unpack the file if it is an archive. + The default action is to unpack the file.</para></listitem> + <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file + (or extracts its contents) into the specified + subdirectory. + This option is useful for unusual tarballs or other archives that + do not have their files already in a subdirectory within the archive. + </para></listitem> + <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a + name to be used for association with <filename>SRC_URI</filename> checksums + when you have more than one file specified in <filename>SRC_URI</filename>. + </para></listitem> + <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies + the filename used when storing the downloaded file.</para></listitem> + </itemizedlist> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm> + <glossdef> + <para> + The date of the source code used to build the package. + This variable applies only if the source was fetched from a Source Code Manager (SCM). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm> + <glossdef> + <para> + The revision of the source code used to build the package. + This variable applies only when using Subversion, Git, Mercurial and Bazaar. + If you want to build a fixed revision and you want + to avoid performing a query on the remote repository every time + BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a + full revision identifier and not just a tag. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SRCREV_FORMAT'><glossterm>SRCREV_FORMAT</glossterm> + <glossdef> + <para> + Helps construct valid + <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + values when multiple source controlled URLs are used in + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>. + </para> + + <para> + The system needs help constructing these values under these + circumstances. + Each component in the <filename>SRC_URI</filename> + is assigned a name and these are referenced + in the <filename>SRCREV_FORMAT</filename> variable. + Consider an example with URLs named "machine" and "meta". + In this case, <filename>SRCREV_FORMAT</filename> could look + like "machine_meta" and those names would have the SCM + versions substituted into each position. + Only one <filename>AUTOINC</filename> placeholder is added + and if needed. + And, this placeholder is placed at the start of the + returned string. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-STAMP'><glossterm>STAMP</glossterm> + <glossdef> + <para> + Specifies the base path used to create recipe stamp files. + The path to an actual stamp file is constructed by evaluating this + string and then appending additional information. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-STAMPCLEAN'><glossterm>STAMPCLEAN</glossterm> + <glossdef> + <para> + Specifies the base path used to create recipe stamp files. + Unlike the + <link linkend='var-STAMP'><filename>STAMP</filename></link> + variable, <filename>STAMPCLEAN</filename> can contain + wildcards to match the range of files a clean operation + should remove. + BitBake uses a clean operation to remove any other stamps + it should be removing when creating a new stamp. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm> + <glossdef> + <para> + A short summary for the recipe, which is 72 characters or less. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm> + <glossdef> + <para> + The directory in which files checked out of a Subversion + system are stored. + </para> + </glossdef> + </glossentry> + + </glossdiv> + + <glossdiv id='var-glossary-t'><title>T</title> + + <glossentry id='var-T'><glossterm>T</glossterm> + <glossdef> + <para>Points to a directory were BitBake places + temporary files, which consist mostly of task logs and + scripts, when building a particular recipe. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm> + <glossdef> + <para> + Points to the build directory. + BitBake automatically sets this variable. + </para> + </glossdef> + </glossentry> + + </glossdiv> + +<!-- + <glossdiv id='var-glossary-u'><title>U</title> + </glossdiv> + + <glossdiv id='var-glossary-v'><title>V</title> + </glossdiv> + + <glossdiv id='var-glossary-w'><title>W</title> + </glossdiv> + + <glossdiv id='var-glossary-x'><title>X</title> + </glossdiv> + + <glossdiv id='var-glossary-y'><title>Y</title> + </glossdiv> + + <glossdiv id='var-glossary-z'><title>Z</title> + </glossdiv> +--> + + +</glossary> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |
