summaryrefslogtreecommitdiffstats
path: root/bitbake/doc/user-manual/user-manual-ref-variables.xml
diff options
context:
space:
mode:
Diffstat (limited to 'bitbake/doc/user-manual/user-manual-ref-variables.xml')
-rw-r--r--bitbake/doc/user-manual/user-manual-ref-variables.xml336
1 files changed, 329 insertions, 7 deletions
diff --git a/bitbake/doc/user-manual/user-manual-ref-variables.xml b/bitbake/doc/user-manual/user-manual-ref-variables.xml
index baee024cca..c8c7257822 100644
--- a/bitbake/doc/user-manual/user-manual-ref-variables.xml
+++ b/bitbake/doc/user-manual/user-manual-ref-variables.xml
@@ -317,25 +317,99 @@
317 <glossentry id='var-BB_HASHCONFIG_WHITELIST'><glossterm>BB_HASHCONFIG_WHITELIST</glossterm> 317 <glossentry id='var-BB_HASHCONFIG_WHITELIST'><glossterm>BB_HASHCONFIG_WHITELIST</glossterm>
318 <glossdef> 318 <glossdef>
319 <para> 319 <para>
320 A list of variables that BitBake excludes from checksum 320 Lists variables that are excluded from checksum
321 comparisons. 321 comparisons to determine if the cache can be reused.
322 </para> 322 </para>
323 323
324 <para> 324 <para>
325 One of the ways BitBake determines whether to re-parse the 325 One of the ways BitBake determines whether to re-parse the
326 main metadata is by using a checksum of the variables in 326 main metadata is through checksums of the variables in the
327 the datastore of the base configuration data. 327 datastore of the base configuration data (see the
328 There are variables that you typically want to exclude from 328 <link linkend='var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></link>
329 these checksum comparisons. 329 variable).
330 There are variables that you typically want to exclude when
331 checking whether or not to re-parse and thus rebuild the
332 cache.
330 As an example, you would usually exclude 333 As an example, you would usually exclude
331 <filename>TIME</filename> and <filename>DATE</filename> 334 <filename>TIME</filename> and <filename>DATE</filename>
332 because these variables are always changing. 335 because these variables are always changing.
333 If you did not exclude them, BitBake would never use the 336 If you did not exclude them, BitBake would never reuse the
334 cache. 337 cache.
335 </para> 338 </para>
336 </glossdef> 339 </glossdef>
337 </glossentry> 340 </glossentry>
338 341
342 <glossentry id='var-BB_HASHBASE_WHITELIST'><glossterm>BB_HASHBASE_WHITELIST</glossterm>
343 <glossdef>
344 <para>
345 Lists variables that are excluded from checksum and
346 dependency data.
347 Variables that are excluded can therefore change without
348 affecting the checksum mechanism.
349 A common example would be the variable for the path of
350 the build.
351 BitBake's output should not (and usually does not) depend
352 on the directory in which it was built.
353 </para>
354 </glossdef>
355 </glossentry>
356
357 <glossentry id='var-BB_HASHCHECK_FUNCTION'><glossterm>BB_HASHCHECK_FUNCTION</glossterm>
358 <glossdef>
359 <para>
360 Specifies the name of the function to call during the
361 "setscene" part of the task's execution in order to
362 validate the list of task hashes.
363 The function returns the list of setscene tasks that should
364 be executed.
365 </para>
366
367 <para>
368 At this point in the execution of the code, the objective
369 is to quickly verify if a given setscene function is likely
370 to work or not.
371 It's easier to check the list of setscene functions in
372 one pass than to call many individual tasks.
373 The returned list need not be completely accurate.
374 A given setscene task can still later fail.
375 However, the more accurate the data returned, the more
376 efficient the build will be.
377 </para>
378 </glossdef>
379 </glossentry>
380
381 <glossentry id='var-BB_INVALIDCONF'><glossterm>BB_INVALIDCONF</glossterm>
382 <glossdef>
383 <para>
384 Used in combination with the
385 <filename>ConfigParsed</filename> event to trigger
386 re-parsing the base metadata (i.e. all the
387 recipes).
388 The <filename>ConfigParsed</filename> event can set the
389 variable to trigger the re-parse.
390 You must be careful to avoid recursive loops with this
391 functionality.
392 </para>
393 </glossdef>
394 </glossentry>
395
396 <glossentry id='var-BB_LOGFMT'><glossterm>BB_LOGFMT</glossterm>
397 <glossdef>
398 <para>
399 Specifies the name of the log files saved into
400 <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>.
401 By default, the <filename>BB_LOGFMT</filename> variable
402 is undefined and the log file names get created using the
403 following form:
404 <literallayout class='monospaced'>
405 log.{task}.{pid}
406 </literallayout>
407 If you want to force log files to take a specific name,
408 you can set this variable in a configuration file.
409 </para>
410 </glossdef>
411 </glossentry>
412
339 <glossentry id='var-BB_NICE_LEVEL'><glossterm>BB_NICE_LEVEL</glossterm> 413 <glossentry id='var-BB_NICE_LEVEL'><glossterm>BB_NICE_LEVEL</glossterm>
340 <glossdef> 414 <glossdef>
341 <para> 415 <para>
@@ -385,6 +459,231 @@
385 </glossdef> 459 </glossdef>
386 </glossentry> 460 </glossentry>
387 461
462 <glossentry id='var-BB_RUNFMT'><glossterm>BB_RUNFMT</glossterm>
463 <glossdef>
464 <para>
465 Specifies the name of the executable script files
466 (i.e. run files) saved into
467 <filename>${</filename><link linkend='var-T'><filename>T</filename></link><filename>}</filename>.
468 By default, the <filename>BB_RUNFMT</filename> variable
469 is undefined and the run file names get created using the
470 following form:
471 <literallayout class='monospaced'>
472 run.{task}.{pid}
473 </literallayout>
474 If you want to force run files to take a specific name,
475 you can set this variable in a configuration file.
476 </para>
477 </glossdef>
478 </glossentry>
479
480 <glossentry id='var-BB_RUNTASK'><glossterm>BB_RUNTASK</glossterm>
481 <glossdef>
482 <para>
483 Contains the name of the currently executing task.
484 The value does not include the "do_" prefix.
485 For example, if the currently executing task is
486 <filename>do_config</filename>, the value is
487 "config".
488 </para>
489 </glossdef>
490 </glossentry>
491
492 <glossentry id='var-BB_SCHEDULER'><glossterm>BB_SCHEDULER</glossterm>
493 <glossdef>
494 <para>
495 Selects the name of the scheduler to use for the
496 scheduling of BitBake tasks.
497 Three options exist:
498 <itemizedlist>
499 <listitem><para><emphasis>basic</emphasis> -
500 The basic framework from which everything derives.
501 Using this option causes tasks to be ordered
502 numerically as they are parsed.
503 </para></listitem>
504 <listitem><para><emphasis>speed</emphasis> -
505 Executes tasks first that have more tasks
506 depending on them.
507 The "speed" option is the default.
508 </para></listitem>
509 <listitem><para><emphasis>completion</emphasis> -
510 Causes the scheduler to try to complete a given
511 recipe once its build has started.
512 </para></listitem>
513 </itemizedlist>
514 </para>
515 </glossdef>
516 </glossentry>
517
518 <glossentry id='var-BB_SCHEDULERS'><glossterm>BB_SCHEDULERS</glossterm>
519 <glossdef>
520 <para>
521 Defines custom schedulers to import.
522 Custom schedulers need to be derived from the
523 <filename>RunQueueScheduler</filename> class.
524 </para>
525
526 <para>
527 For information how to select a scheduler, see the
528 <link linkend='var-BB_SCHEDULER'><filename>BB_SCHEDULER</filename></link>
529 variable.
530 </para>
531 </glossdef>
532 </glossentry>
533
534 <glossentry id='var-BB_SETSCENE_DEPVALID'><glossterm>BB_SETSCENE_DEPVALID</glossterm>
535 <glossdef>
536 <para>
537 Specifies a function BitBake calls that determines
538 whether BitBake requires a setscene dependency to be met.
539 </para>
540
541 <para>
542 When running a setscene task, BitBake needs to
543 know which dependencies of that setscene task also need
544 to be run.
545 Whether dependencies also need to be run is highly
546 dependent on the metadata.
547 The function specified by this variable returns a
548 "True" or "False" depending on whether the dependency needs
549 to be met.
550 </para>
551 </glossdef>
552 </glossentry>
553
554 <glossentry id='var-BB_SETSCENE_VERIFY_FUNCTION'><glossterm>BB_SETSCENE_VERIFY_FUNCTION</glossterm>
555 <glossdef>
556 <para>
557 Specifies a function to call that verifies the list of
558 planned task execution before the main task execution
559 happens.
560 The function is called once BitBake has a list of setscene
561 tasks that have run and either succeeded or failed.
562 </para>
563
564 <para>
565 The function allows for a task list check to see if they
566 make sense.
567 Even if BitBake was planning to skip a task, the
568 returned value of the function can force BitBake to run
569 the task, which is necessary under certain metadata
570 defined circumstances.
571 </para>
572 </glossdef>
573 </glossentry>
574
575 <glossentry id='var-BB_SIGNATURE_EXCLUDE_FLAGS'><glossterm>BB_SIGNATURE_EXCLUDE_FLAGS</glossterm>
576 <glossdef>
577 <para>
578 Lists flags that can be safely excluded from checksum
579 and dependency data for keys in the datastore.
580 When generating checksum or dependency data for keys in the
581 datastore, the flags set against that key are normally
582 included in the checksum.
583 </para>
584 </glossdef>
585 </glossentry>
586
587 <glossentry id='var-BB_SIGNATURE_HANDLER'><glossterm>BB_SIGNATURE_HANDLER</glossterm>
588 <glossdef>
589 <para>
590 Defines the name of the signature handler BitBake uses.
591 The signature handler defines the way stamp files are
592 created and handled, if and how the signature is
593 incorporated into the stamps, and how the signature
594 itself is generated.
595 </para>
596
597 <para>
598 A new signature handler can be added by injecting a class
599 derived from the
600 <filename>SignatureGenerator</filename> class into the
601 global namespace.
602 </para>
603 </glossdef>
604 </glossentry>
605
606 <glossentry id='var-BB_SRCREV_POLICY'><glossterm>BB_SRCREV_POLICY</glossterm>
607 <glossdef>
608 <para>
609 Defines the behavior of the fetcher when it interacts with
610 source control systems and dynamic source revisions.
611 The <filename>BB_SRCREV_POLICY</filename> variable is
612 useful when working without a network.
613 </para>
614
615 <para>
616 The variable can be set using one of two policies:
617 <itemizedlist>
618 <listitem><para><emphasis>cache</emphasis> -
619 Retains the value the system obtained previously
620 rather than querying the source control system
621 each time.
622 </para></listitem>
623 <listitem><para><emphasis>clear</emphasis> -
624 Queries the source controls system every time.
625 With this policy, there is no cache.
626 The "clear" policy is the default.
627 </para></listitem>
628 </itemizedlist>
629 </para>
630 </glossdef>
631 </glossentry>
632
633 <glossentry id='var-BB_STAMP_POLICY'><glossterm>BB_STAMP_POLICY</glossterm>
634 <glossdef>
635 <para>
636 Defines the mode used for how timestamps of stamp files
637 are compared.
638 You can set the variable to one of the following modes:
639 <itemizedlist>
640 <listitem><para><emphasis>perfile</emphasis> -
641 Timestamp comparisons are only made
642 between timestamps of a specific recipe.
643 This is the default mode.
644 </para></listitem>
645 <listitem><para><emphasis>full</emphasis> -
646 Timestamp comparisons are made for all
647 dependencies.
648 </para></listitem>
649 <listitem><para><emphasis>whitelist</emphasis> -
650 Identical to "full" mode except timestamp
651 comparisons are made for recipes listed in the
652 <link linkend='var-BB_STAMP_WHITELIST'><filename>BB_STAMP_WHITELIST</filename></link>
653 variable.
654 </para></listitem>
655 </itemizedlist>
656 <note>
657 Stamp policies are largely obsolete with the
658 introduction of setscene tasks.
659 </note>
660 </para>
661 </glossdef>
662 </glossentry>
663
664 <glossentry id='var-BB_STAMP_WHITELIST'><glossterm>BB_STAMP_WHITELIST</glossterm>
665 <glossdef>
666 <para>
667 Lists files whose stamp file timestamps are compared when
668 the stamp policy mode is set to "whitelist".
669 For information on stamp policies, see the
670 <link linkend='var-BB_STAMP_POLICY'><filename>BB_STAMP_POLICY</filename></link>
671 variable.
672 </para>
673 </glossdef>
674 </glossentry>
675
676 <glossentry id='var-BB_STRICT_CHECKSUM'><glossterm>BB_STRICT_CHECKSUM</glossterm>
677 <glossdef>
678 <para>
679 Sets a more strict checksum mechanism for non-local URLs.
680 Setting this variable to a value causes BitBake
681 to report an error if it encounters a non-local URL
682 that does not have at least one checksum specified.
683 </para>
684 </glossdef>
685 </glossentry>
686
388 <glossentry id='var-BB_TASK_NICE_LEVEL'><glossterm>BB_TASK_NICE_LEVEL</glossterm> 687 <glossentry id='var-BB_TASK_NICE_LEVEL'><glossterm>BB_TASK_NICE_LEVEL</glossterm>
389 <glossdef> 688 <glossdef>
390 <para> 689 <para>
@@ -404,6 +703,29 @@
404 </glossdef> 703 </glossdef>
405 </glossentry> 704 </glossentry>
406 705
706 <glossentry id='var-BB_VERBOSE_LOGS'><glossterm>BB_VERBOSE_LOGS</glossterm>
707 <glossdef>
708 <para>
709 Controls how verbose BitBake is during builds.
710 If set, shell scripts echo commands and shell script output
711 appears on standard out (stdout).
712 </para>
713 </glossdef>
714 </glossentry>
715
716 <glossentry id='var-BB_WORKERCONTEXT'><glossterm>BB_WORKERCONTEXT</glossterm>
717 <glossdef>
718 <para>
719 Specifies if the current context is executing a task.
720 BitBake sets this variable to "1" when a task is
721 being executed.
722 The value is not set when the task is in server context
723 during parsing or event handling.
724 </para>
725 </glossdef>
726 </glossentry>
727
728
407 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm> 729 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
408 <glossdef> 730 <glossdef>
409 <para> 731 <para>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-14 20:01:44 +0000