Blame - poky/documentation/ref-manual/ref-variables.xml - stefanberger/openbmc

ASSUME_SHLIBS[doc] = "Provides additional shlibs provider mapping information, which adds to or overwrites the information provided automatically by the system."

361

</info>

362

363

364

Provides additional <filename>shlibs</filename> provider

365

mapping information, which adds to or overwrites the

366

information provided automatically by the system.

367

Separate multiple entries using spaces.

</para>

<para>

As an example, use the following form to add an

372

<filename>shlib</filename> provider of

373

<replaceable>shlibname</replaceable> in

374

<replaceable>packagename</replaceable> with the optional

375

<replaceable>version</replaceable>:

376

377

<replaceable>shlibname:packagename</replaceable>[_<replaceable>version</replaceable>]

</literallayout>

</para>

<para>

Here is an example that adds a shared library named

383

<filename>libEGL.so.1</filename> as being provided by

384

the <filename>libegl-implementation</filename> package:

385

386

ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>

393

<info>

394

AUTHOR[doc] = "Email address used to contact the original author or authors in order to send patches and forward bugs."

</info>

The email address used to contact the original author

399

or authors in order to send patches and forward bugs.

</para>

</glossdef>

</glossentry>

<glossentry id='var-AUTO_LIBNAME_PKGS'><glossterm>AUTO_LIBNAME_PKGS</glossterm>

405

<info>

406

AUTO_LIBNAME_PKGS[doc] = "Specifies which packages should be checked for libraries and renamed according to Debian library package naming."

</info>

When the

class is inherited, which is the default behavior,

413

<filename>AUTO_LIBNAME_PKGS</filename> specifies which

414

packages should be checked for libraries and renamed

415

according to Debian library package naming.

</para>

<para>

The default value is "${PACKAGES}", which causes the

420

debian class to act on all packages that are

421

explicitly generated by the recipe.

</para>

</glossdef>

</glossentry>

<glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm>

427

<info>

428

AUTO_SYSLINUXMENU[doc] = "Enables creating an automatic menu for the syslinux bootloader."

</info>

Enables creating an automatic menu for the syslinux

433

bootloader.

434

You must set this variable in your recipe.

435

The

436

437

class checks this variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>

443

<info>

444

AUTOREV[doc] = "When SRCREV is set to the value of this variable, it specifies to use the latest source revision in the repository."

</info>

When

<filename><link linkend='var-SRCREV'>SRCREV</link></filename>

450

is set to the value of this variable, it specifies to use

451

the latest source revision in the repository.

452

Here is an example:

453

454

SRCREV = "${AUTOREV}"

</literallayout>

</para>

<para>

If you use the previous statement to retrieve the latest

460

version of software, you need to be sure

461

462

contains

463

<filename>${</filename><link linkend='var-SRCPV'><filename>SRCPV</filename></link><filename>}</filename>.

464

For example, suppose you have a kernel recipe that

465

inherits the

466

467

and you use the previous statement.

468

In this example, <filename>${SRCPV}</filename> does not

469

automatically get into <filename>PV</filename>.

470

Consequently, you need to change <filename>PV</filename>

471

in your recipe so that it does contain

472

<filename>${SRCPV}</filename>.

</para>

<para>

For more information see the

477

"<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"

478

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-AVAILABLE_LICENSES'><glossterm>AVAILABLE_LICENSES</glossterm>

484

<info>

485

AVAILABLE_LICENSES[doc] = "List of licenses found in the directories specified by COMMON_LICENSE_DIR and LICENSE_PATH."

</info>

List of licenses found in the directories specified

491

by <link linkend='var-COMMON_LICENSE_DIR'><filename>COMMON_LICENSE_DIR</filename></link>

492

and <link linkend='var-LICENSE_PATH'><filename>LICENSE_PATH</filename></link>.

493

494

<note>

495

It is assumed that all changes

496

to <filename>COMMON_LICENSE_DIR</filename>

497

and <filename>LICENSE_PATH</filename> have been done

498

before <filename>AVAILABLE_LICENSES</filename> is

499

defined

500

(in <link linkend='ref-classes-license'>license.bbclass</link>).

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-AVAILTUNES'><glossterm>AVAILTUNES</glossterm>

507

<info>

508

AVAILTUNES[doc] = "The list of defined CPU and Application Binary Interface (ABI) tunings (i.e. "tunes") available for use by the OpenEmbedded build system."

</info>

The list of defined CPU and Application Binary Interface

513

(ABI) tunings (i.e. "tunes") available for use by the

514

OpenEmbedded build system.

</para>

<para>

The list simply presents the tunes that are available.

519

Not all tunes may be compatible with a particular

520

machine configuration, or with each other in a

521

<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Multilib</ulink>

configuration.

</para>

<para>

To add a tune to the list, be sure to append it with

527

spaces using the "+=" BitBake operator.

528

Do not simply replace the list by using the "=" operator.

529

See the

530

"<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"

531

section in the BitBake User Manual for more information.

</para>

</glossdef>

</glossentry>

</glossdiv>

<info>

B[doc] = "The Build Directory. The OpenEmbedded build system places generated objects into the Build Directory during a recipe's build process."

</info>

The directory within the

547

548

in which the OpenEmbedded build system places generated

549

objects during a recipe's build process.

550

By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>

551

directory, which is defined as:

552

553

S = "${WORKDIR}/${BP}"

</literallayout>

</para>

<para>

You can separate the (<filename>S</filename>) directory

559

and the directory pointed to by the <filename>B</filename>

560

variable.

561

Most Autotools-based recipes support separating these

562

directories.

563

The build system defaults to using separate directories for

564

<filename>gcc</filename> and some kernel recipes.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>

570

<info>

571

BAD_RECOMMENDATIONS[doc] = "A list of packages not to install despite being recommended by a recipe. Support for this variable exists only when using the IPK packaging backend."

</info>

Lists "recommended-only" packages to not install.

576

Recommended-only packages are packages installed only

through the

variable.

You can prevent any of these "recommended" packages from

581

being installed by listing them with the

582

<filename>BAD_RECOMMENDATIONS</filename> variable:

583

584

BAD_RECOMMENDATIONS = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."

</literallayout>

</para>

<para>

You can set this variable globally in your

590

<filename>local.conf</filename> file or you can attach it to

591

a specific image recipe by using the recipe name override:

592

593

BAD_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"

</literallayout>

</para>

<para>

It is important to realize that if you choose to not install

599

packages using this variable and some other packages are

600

dependent on them (i.e. listed in a recipe's

601

602

variable), the OpenEmbedded build system ignores your

603

request and will install the packages to avoid dependency

errors.

</para>

<para>

Support for this variable exists only when using the

609

IPK and RPM packaging backend.

610

Support does not exist for DEB.

</para>

<para>

See the

and the

variables for related information.

</para>

</glossdef>

</glossentry>

<info>

BASE_LIB[doc] = "The library directory name for the CPU or Application Binary Interface (ABI) tune."

</info>

The library directory name for the CPU or Application

630

Binary Interface (ABI) tune.

631

The <filename>BASE_LIB</filename> applies only in the

632

Multilib context.

633

See the

634

"<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"

635

section in the Yocto Project Development Tasks Manual for

636

information on Multilib.

</para>

<para>

The <filename>BASE_LIB</filename> variable is defined in

641

the machine include files in the

642

643

If Multilib is not being used, the value defaults to "lib".

</para>

</glossdef>

</glossentry>

<glossentry id='var-BASE_WORKDIR'><glossterm>BASE_WORKDIR</glossterm>

649

<info>

650

BASE_WORKDIR[doc] = "Points to the base of the work directory for all recipes."

</info>

Points to the base of the work directory for all recipes.

655

The default value is "${TMPDIR}/work".

</para>

</glossdef>

</glossentry>

<glossentry id='var-BB_ALLOWED_NETWORKS'><glossterm>BB_ALLOWED_NETWORKS</glossterm>

661

<info>

662

BB_ALLOWED_NETWORKS[doc] = "A list of hosts that the fetcher is allowed to use to obtain the required source code."

</info>

<para>

Specifies a space-delimited list of hosts that the fetcher

667

is allowed to use to obtain the required source code.

668

Following are considerations surrounding this variable:

669

670

671

This host list is only used if

672

<filename>BB_NO_NETWORK</filename> is either not

set or set to "0".

</para></listitem>

Limited support for wildcard matching against the

677

beginning of host names exists.

678

For example, the following setting matches

679

<filename>git.gnu.org</filename>,

680

<filename>ftp.gnu.org</filename>, and

681

<filename>foo.git.gnu.org</filename>.

682

683

BB_ALLOWED_NETWORKS = "*.gnu.org"

684

</literallayout>

685

<note><title>Important</title>

686

<para>The use of the "<filename>*</filename>"

687

character only works at the beginning of

688

a host name and it must be isolated from

689

the remainder of the host name.

690

You cannot use the wildcard character in any

691

other location of the name or combined with

692

the front part of the name.</para>

693

694

<para>For example,

695

<filename>*.foo.bar</filename> is supported,

696

while <filename>*aa.foo.bar</filename> is not.

</para>

</note>

</para></listitem>

Mirrors not in the host list are skipped and

logged in debug.

</para></listitem>

Attempts to access networks not in the host list

cause a failure.

</para></listitem>

</itemizedlist>

Using <filename>BB_ALLOWED_NETWORKS</filename> in

conjunction with

is very useful.

Adding the host you want to use to

714

<filename>PREMIRRORS</filename> results in the source code

715

being fetched from an allowed location and avoids raising

716

an error when a host that is not allowed is in a

717

718

statement.

719

This is because the fetcher does not attempt to use the

720

host listed in <filename>SRC_URI</filename> after a

721

successful fetch from the

722

<filename>PREMIRRORS</filename> occurs.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>

728

<info>

729

BB_DANGLINGAPPENDS_WARNONLY[doc] = "Defines how BitBake handles situations where an append file (.bbappend) has no corresponding recipe file (.bb)."

</info>

Defines how BitBake handles situations where an append

734

file (<filename>.bbappend</filename>) has no

735

corresponding recipe file (<filename>.bb</filename>).

736

This condition often occurs when layers get out of sync

737

(e.g. <filename>oe-core</filename> bumps a

738

recipe version and the old recipe no longer exists and the

739

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

745

the sane reaction given something is out of sync.

746

It is important to realize when your changes are no longer

being applied.

</para>

<para>

You can change the default behavior by setting this

752

variable to "1", "yes", or "true"

753

in your <filename>local.conf</filename> file, which is

located in the

Here is an example:

BB_DANGLINGAPPENDS_WARNONLY = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>

765

<info>

766

BB_DISKMON_DIRS[doc] = "Monitors disk space and available inodes during the build and allows you to control the build based on these parameters."

</info>

Monitors disk space and available inodes during the build

771

and allows you to control the build based on these

parameters.

</para>

<para>

Disk space monitoring is disabled by default.

777

To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>

778

variable to your <filename>conf/local.conf</filename> file found in the

779

780

Use the following form:

781

782

BB_DISKMON_DIRS = "<replaceable>action</replaceable>,<replaceable>dir</replaceable>,<replaceable>threshold</replaceable> [...]"

where:

<replaceable>action</replaceable> is:

787

ABORT: Immediately abort the build when

788

a threshold is broken.

789

STOPTASKS: Stop the build after the currently

790

executing tasks have finished when

791

a threshold is broken.

792

WARN: Issue a warning but continue the

793

build when a threshold is broken.

794

Subsequent warnings are issued as

795

defined by the BB_DISKMON_WARNINTERVAL

796

variable, which must be defined in

797

the conf/local.conf file.

798

799

<replaceable>dir</replaceable> is:

800

Any directory you choose. You can specify one or

801

more directories to monitor by separating the

802

groupings with a space. If two directories are

803

on the same device, only the first directory

804

is monitored.

805

806

<replaceable>threshold</replaceable> is:

807

Either the minimum available disk space,

808

the minimum number of free inodes, or

809

both. You must specify at least one. To

810

omit one or the other, simply omit the value.

811

Specify the threshold using G, M, K for Gbytes,

812

Mbytes, and Kbytes, respectively. If you do

813

not specify G, M, or K, Kbytes is assumed by

814

default. Do not use GB, MB, or KB.

</literallayout>

</para>

<para>

Here are some examples:

820

821

BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"

822

BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"

823

BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"

824

</literallayout>

825

The first example works only if you also provide

826

the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable

827

in the <filename>conf/local.conf</filename>.

828

This example causes the build system to immediately

829

abort when either the disk space in <filename>${TMPDIR}</filename> drops

830

below 1 Gbyte or the available free inodes drops below

831

100 Kbytes.

832

Because two directories are provided with the variable, the

833

build system also issue a

834

warning when the disk space in the

835

<filename>${SSTATE_DIR}</filename> directory drops

836

below 1 Gbyte or the number of free inodes drops

837

below 100 Kbytes.

838

Subsequent warnings are issued during intervals as

839

defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>

variable.

</para>

<para>

The second example stops the build after all currently

845

executing tasks complete when the minimum disk space

846

in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>

847

directory drops below 1 Gbyte.

848

No disk monitoring occurs for the free inodes in this case.

</para>

<para>

The final example immediately aborts the build when the

853

number of free inodes in the <filename>${TMPDIR}</filename> directory

854

drops below 100 Kbytes.

855

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>

862

<info>

863

BB_DISKMON_WARNINTERVAL[doc] = "Defines the disk space and free inode warning intervals. To set these intervals, define the variable in the conf/local.conf file in the Build Directory."

</info>

Defines the disk space and free inode warning intervals.

868

To set these intervals, define the variable in your

869

<filename>conf/local.conf</filename> file in the

</para>

<para>

If you are going to use the

875

<filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must

876

also use the

877

878

and define its action as "WARN".

879

During the build, subsequent warnings are issued each time

880

disk space or number of free inodes further reduces by

881

the respective interval.

</para>

<para>

If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>

886

variable and you do use <filename>BB_DISKMON_DIRS</filename> with

887

the "WARN" action, the disk monitoring interval defaults to

888

the following:

889

890

BB_DISKMON_WARNINTERVAL = "50M,5K"

</literallayout>

</para>

<para>

When specifying the variable in your configuration file,

896

use the following form:

897

898

BB_DISKMON_WARNINTERVAL = "<replaceable>disk_space_interval</replaceable>,<replaceable>disk_inode_interval</replaceable>"

where:

<replaceable>disk_space_interval</replaceable> is:

903

An interval of memory expressed in either

904

G, M, or K for Gbytes, Mbytes, or Kbytes,

905

respectively. You cannot use GB, MB, or KB.

906

907

<replaceable>disk_inode_interval</replaceable> is:

908

An interval of free inodes expressed in either

909

G, M, or K for Gbytes, Mbytes, or Kbytes,

910

respectively. You cannot use GB, MB, or KB.

</literallayout>

</para>

<para>

Here is an example:

BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"

918

BB_DISKMON_WARNINTERVAL = "50M,5K"

919

</literallayout>

920

These variables cause the OpenEmbedded build system to

921

issue subsequent warnings each time the available

922

disk space further reduces by 50 Mbytes or the number

923

of free inodes further reduces by 5 Kbytes in the

924

<filename>${SSTATE_DIR}</filename> directory.

925

Subsequent warnings based on the interval occur each time

926

a respective interval is reached beyond the initial warning

927

(i.e. 1 Gbytes and 100 Kbytes).

</para>

</glossdef>

</glossentry>

<glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>

933

<info>

934

BB_GENERATE_MIRROR_TARBALLS[doc] = "Causes tarballs of the source control repositories to be placed in the DL_DIR directory."

</info>

Causes tarballs of the source control repositories

939

(e.g. Git repositories), including metadata, to be placed

in the

directory.

</para>

<para>

For performance reasons, creating and placing tarballs of

947

these repositories is not the default action by the

948

OpenEmbedded build system.

949

950

BB_GENERATE_MIRROR_TARBALLS = "1"

951

</literallayout>

952

Set this variable in your <filename>local.conf</filename>

file in the

</para>

<para>

Once you have the tarballs containing your source files,

959

you can clean up your <filename>DL_DIR</filename>

960

directory by deleting any Git or other source control

work directories.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>

967

<info>

968

BB_NUMBER_THREADS[doc] = "The maximum number of tasks BitBake should run in parallel at any one time. This variable is automatically configured to be equal to the number of build system cores."

</info>

The maximum number of tasks BitBake should run in parallel

973

at any one time.

974

The OpenEmbedded build system automatically configures

975

this variable to be equal to the number of cores on the

976

build system.

977

For example, a system with a dual core processor that

978

also uses hyper-threading causes the

979

<filename>BB_NUMBER_THREADS</filename> variable to default

to "4".

</para>

<para>

For single socket systems (i.e. one CPU), you should not

985

have to override this variable to gain optimal parallelism

986

during builds.

987

However, if you have very large systems that employ

988

multiple physical CPUs, you might want to make sure the

989

<filename>BB_NUMBER_THREADS</filename> variable is not

990

set higher than "20".

</para>

<para>

For more information on speeding up builds, see the

995

"<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"

996

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BB_SERVER_TIMEOUT'><glossterm>BB_SERVER_TIMEOUT</glossterm>

1002

<info>

1003

BB_SERVER_TIMEOUT [doc] = "Specifies the time (in seconds) after which to unload the BitBake server due to inactivity."

</info>

Specifies the time (in seconds) after which to unload the

1008

BitBake server due to inactivity.

1009

Set <filename>BB_SERVER_TIMEOUT</filename> to determine how

1010

long the BitBake server stays resident between invocations.

</para>

<para>

For example, the following statement in your

1015

<filename>local.conf</filename> file instructs the server

1016

to be unloaded after 20 seconds of inactivity:

1017

1018

BB_SERVER_TIMEOUT = "20"

1019

</literallayout>

1020

If you want the server to never be unloaded, set

1021

<filename>BB_SERVER_TIMEOUT</filename> to "-1".

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>

1027

<info>

1028

BBCLASSEXTEND[doc] = "Allows you to extend a recipe so that it builds variants of the software. Common variants for recipes are 'native', 'cross', 'nativesdk', and multilibs."

</info>

Allows you to extend a recipe so that it builds variants of the software.

1033

Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,

1034

which is a copy of Quilt built to run on the build system;

1035

"crosses" such as <filename>gcc-cross</filename>,

1036

which is a compiler built to run on the build machine but produces binaries

1037

that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;

1038

"nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;

1039

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

1044

is as simple as adding the following to your recipe:

1045

1046

BBCLASSEXTEND =+ "native nativesdk"

1047

BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>"

</literallayout>

<note>

<para>

Internally, the <filename>BBCLASSEXTEND</filename>

1052

mechanism generates recipe variants by rewriting

1053

variable values and applying overrides such as

1054

<filename>_class-native</filename>.

1055

For example, to generate a native version of a recipe,

1056

a

1057

1058

on "foo" is rewritten to a <filename>DEPENDS</filename>

on "foo-native".

</para>

<para>

Even when using <filename>BBCLASSEXTEND</filename>, the

1064

recipe is only parsed once.

1065

Parsing once adds some limitations.

1066

For example, it is not possible to

1067

include a different file depending on the variant,

1068

since <filename>include</filename> statements are

1069

processed when the recipe is parsed.

</para>

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>

1077

<info>

1078

BBFILE_COLLECTIONS[doc] = "Lists the names of configured layers. These names are used to find the other BBFILE_* variables."

</info>

Lists the names of configured layers.

1083

These names are used to find the other <filename>BBFILE_*</filename>

1084

variables.

1085

Typically, each layer will append its name to this variable in its

1086

<filename>conf/layer.conf</filename> file.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>

1092

<info>

1093

BBFILE_PATTERN[doc] = "Variable that expands to match files from BBFILES in a particular layer. This variable is used in the layer.conf file and must be suffixed with the name of a layer."

</info>

Variable that expands to match files from

1098

1099

in a particular layer.

1100

This variable is used in the <filename>conf/layer.conf</filename> file and must

1101

be suffixed with the name of the specific layer (e.g.

1102

<filename>BBFILE_PATTERN_emenlow</filename>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>

1108

<info>

1109

BBFILE_PRIORITY[doc] = "Assigns the priority for recipe files in each layer. Setting this variable allows you to prioritize a layer against other layers that contain the same recipe."

</info>

Assigns the priority for recipe files in each layer.

</para>

<para>

This variable is useful in situations where the same recipe appears in

1118

more than one layer.

1119

Setting this variable allows you to prioritize a

1120

layer against other layers that contain the same recipe - effectively

1121

letting you control the precedence for the multiple layers.

1122

The precedence established through this variable stands regardless of a

1123

recipe's version

1124

(<link linkend='var-PV'><filename>PV</filename></link> variable).

1125

For example, a layer that has a recipe with a higher <filename>PV</filename> value but for

1126

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

1132

precedence.

1133

For example, the value 6 has a higher precedence than the value 5.

1134

If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer

1135

dependencies (see the

1136

<filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for

1137

more information.

1138

The default priority, if unspecified

1139

for a layer with no dependencies, is the lowest defined priority + 1

1140

(or 1 if no priorities are defined).

1141

</para>

1142

<tip>

1143

You can use the command <filename>bitbake-layers show-layers</filename> to list

1144

all configured layers along with their priorities.

</tip>

</glossdef>

</glossentry>

<glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>

1150

<info>

1151

BBFILES[doc] = "A space-separated list of recipe files BitBake uses to build software."

</info>

A space-separated list of recipe files BitBake uses to

build software.

</para>

<para>

When specifying recipe files, you can pattern match using

Python's

syntax.

For details on the syntax, see the documentation by

1165

following the previous link.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBFILES_DYNAMIC'><glossterm>BBFILES_DYNAMIC</glossterm>

1171

<info>

1172

BBFILES_DYNAMIC[doc] = "Activates content when identified layers are present."

</info>

Activates content when identified layers are present.

1177

You identify the layers by the collections that the layers

define.

</para>

<para>

Use the <filename>BBFILES_DYNAMIC</filename> variable to

1183

avoid <filename>.bbappend</filename> files whose

1184

corresponding <filename>.bb</filename> file is in a layer

1185

that attempts to modify other layers through

1186

<filename>.bbappend</filename> but does not want to

1187

introduce a hard dependency on those other layers.

</para>

<para>

Use the following form for

1192

<filename>BBFILES_DYNAMIC</filename>:

1193

1194

<replaceable>collection_name</replaceable>:<replaceable>filename_pattern</replaceable>

1195

</literallayout>

1196

The following example identifies two collection names and

1197

two filename patterns:

1198

1199

BBFILES_DYNAMIC += " \

1200

clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \

1201

core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \

1202

"

1203

</literallayout>

1204

This next example shows an error message that occurs

1205

because invalid entries are found, which cause parsing to

1206

abort:

1207

1208

ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not:

1209

/work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend

1210

/work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>

1217

<info>

1218

BBINCLUDELOGS[doc] = "Variable that controls how BitBake displays logs on build failure."

</info>

Variable that controls how BitBake displays logs on build failure.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>

1228

<info>

1229

BBINCLUDELOGS_LINES[doc] = "Amount of log lines printed on failure."

</info>

If

is set, specifies the maximum number of lines from the

1236

task log file to print when reporting a failed task.

1237

If you do not set <filename>BBINCLUDELOGS_LINES</filename>,

1238

the entire log is printed.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>

1244

<info>

1245

BBLAYERS[doc] = "Lists the layers to enable during the build. This variable is defined in the bblayers.conf configuration file."

</info>

Lists the layers to enable during the build.

1250

This variable is defined in the <filename>bblayers.conf</filename> configuration

file in the

Here is an example:

BBLAYERS = " \

/home/scottrif/poky/meta \

1257

/home/scottrif/poky/meta-poky \

1258

/home/scottrif/poky/meta-yocto-bsp \

1259

/home/scottrif/poky/meta-mykernel \

"

</literallayout>

</para>

<para>

This example enables four layers, one of which is a custom, user-defined layer

1266

named <filename>meta-mykernel</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>

1272

<info>

1273

BBMASK[doc] = "Prevents BitBake from processing specific recipes or recipe append files."

</info>

Prevents BitBake from processing recipes and recipe

append files.

</para>

<para>

You can use the <filename>BBMASK</filename> variable

1283

to "hide" these <filename>.bb</filename> and

1284

<filename>.bbappend</filename> files.

1285

BitBake ignores any recipe or recipe append files that

1286

match any of the expressions.

1287

It is as if BitBake does not see them at all.

1288

Consequently, matching files are not parsed or otherwise

used by BitBake.

</para>

<para>

The values you provide are passed to Python's regular

1294

expression compiler.

1295

Consequently, the syntax follows Python's Regular

1296

Expression (re) syntax.

1297

The expressions are compared against the full paths to

1298

the files.

1299

For complete syntax information, see Python's

1300

documentation at

1301

<ulink url='http://docs.python.org/3/library/re.html#re'></ulink>.

</para>

<para>

The following example uses a complete regular expression

1306

to tell BitBake to ignore all recipe and recipe append

1307

files in the <filename>meta-ti/recipes-misc/</filename>

1308

directory:

1309

1310

BBMASK = "meta-ti/recipes-misc/"

1311

</literallayout>

1312

If you want to mask out multiple directories or recipes,

1313

you can specify multiple regular expression fragments.

1314

This next example masks out multiple directories and

1315

individual recipes:

1316

1317

BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"

1318

BBMASK += "/meta-oe/recipes-support/"

1319

BBMASK += "/meta-foo/.*/openldap"

1320

BBMASK += "opencv.*\.bbappend"

BBMASK += "lzma"

</literallayout>

<note>

When specifying a directory name, use the trailing

1325

slash character to ensure you match just that directory

name.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm>

1333

<info>

1334

BBMULTICONFIG[doc] = "Specifies each additional separate configuration when you are building targets with multiple configurations."

</info>

Specifies each additional separate configuration when you

1339

are building targets with multiple configurations.

1340

Use this variable in your

1341

<filename>conf/local.conf</filename> configuration file.

1342

Specify a <replaceable>multiconfigname</replaceable> for

1343

each configuration file you are using.

1344

For example, the following line specifies three

1345

configuration files:

1346

1347

BBMULTICONFIG = "configA configB configC"

1348

</literallayout>

1349

Each configuration file you use must reside in the

1350

1351

<filename>conf/multiconfig</filename> directory

1352

(e.g.

1353

<replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>).

</para>

<para>

For information on how to use

1358

<filename>BBMULTICONFIG</filename> in an environment that

1359

supports building targets with multiple configurations,

1360

see the

1361

"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-images-for-multiple-targets-using-multiple-configurations'>Building Images for Multiple Targets Using Multiple Configurations</ulink>"

1362

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>

1368

<info>

1369

BBPATH[doc] = "Used by BitBake to locate .bbclass and configuration files. This variable is analogous to the PATH variable."

</info>

Used by BitBake to locate

1374

<filename>.bbclass</filename> and configuration files.

1375

This variable is analogous to the

1376

<filename>PATH</filename> variable.

1377

<note>

1378

If you run BitBake from a directory outside of the

1379

1380

you must be sure to set

1381

<filename>BBPATH</filename> to point to the

1382

Build Directory.

1383

Set the variable as you would any environment variable

1384

and then run BitBake:

1385

1386

$ BBPATH = "<replaceable>build_directory</replaceable>"

1387

$ export BBPATH

1388

$ bitbake <replaceable>target</replaceable>

</literallayout>

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>

1396

<info>

1397

BBSERVER[doc] = "Points to the BitBake remote server."

</info>

If defined in the BitBake environment,

1402

<filename>BBSERVER</filename> points to the BitBake

remote server.

</para>

<para>

Use the following format to export the variable to the

1408

BitBake environment:

1409

1410

export BBSERVER=localhost:$port

</literallayout>

</para>

<para>

By default, <filename>BBSERVER</filename> also appears in

1416

<ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>.

1417

Consequently, <filename>BBSERVER</filename> is excluded

1418

from checksum and dependency data.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BINCONFIG'><glossterm>BINCONFIG</glossterm>

1424

<info>

1425

BINCONFIG[doc] = "When inheriting the binconfig-disabled class, this variable specifies binary configuration scripts to disable in favor of using pkg-config to query the information."

</info>

When inheriting the

class, this variable specifies binary configuration

1432

scripts to disable in favor of using

1433

<filename>pkg-config</filename> to query the information.

1434

The <filename>binconfig-disabled</filename> class will

1435

modify the specified scripts to return an error so that

1436

calls to them can be easily found and replaced.

</para>

<para>

To add multiple scripts, separate them by spaces.

1441

Here is an example from the <filename>libpng</filename>

1442

recipe:

1443

1444

BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>

1451

<info>

1452

BINCONFIG_GLOB[doc] = "When inheriting binconfig.bbclass from a recipe, this variable specifies a wildcard for configuration scripts that need editing."

</info>

When inheriting the

class, this variable specifies a wildcard for

1459

configuration scripts that need editing.

1460

The scripts are edited to correct any paths that have been

1461

set up during compilation so that they are correct for

1462

use when installed into the sysroot and called by the

1463

build processes of other recipes.

1464

<note>

1465

The <filename>BINCONFIG_GLOB</filename> variable

1466

uses

1467

<ulink url='http://tldp.org/LDP/abs/html/globbingref.html'>shell globbing</ulink>,

1468

which is recognition and expansion of wildcards during

1469

pattern matching.

1470

Shell globbing is very similar to

1471

<ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>

1472

and

1473

<ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>.

</note>

</para>

<para>

For more information on how this variable works, see

1479

<filename>meta/classes/binconfig.bbclass</filename> in the

1480

1481

You can also find general information on the class in the

1482

"<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"

section.

</para>

</glossdef>

</glossentry>

<info>

BP[doc] = "The base recipe name and version but without any special recipe name suffix (i.e. -native, lib64-, and so forth). BP is comprised of ${BPN}-${PV}"

</info>

The base recipe name and version but without any special

1495

recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,

1496

and so forth).

1497

<filename>BP</filename> is comprised of the following:

${BPN}-${PV}

</literallayout>

</para>

</glossdef>

</glossentry>

<info>

BPN[doc] = "This variable is a version of the PN variable but removes common suffixes and prefixes."

</info>

This variable is a version of the

1512

1513

variable with common prefixes and suffixes

1514

removed, such as <filename>nativesdk-</filename>,

1515

<filename>-cross</filename>,

1516

<filename>-native</filename>, and multilib's

1517

<filename>lib64-</filename> and

1518

<filename>lib32-</filename>.

1519

The exact lists of prefixes and suffixes removed are

specified by the

and

variables, respectively.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>

1530

<info>

1531

BUGTRACKER[doc] = "Specifies a URL for an upstream bug tracking website for a recipe."

</info>

Specifies a URL for an upstream bug tracking website for

1536

a recipe.

1537

The OpenEmbedded build system does not use this variable.

1538

Rather, the variable is a useful pointer in case a bug

1539

in the software being built needs to be manually reported.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_ARCH'><glossterm>BUILD_ARCH</glossterm>

1545

<info>

1546

BUILD_ARCH[doc] = "The name of the building architecture (e.g. i686)."

</info>

Specifies the architecture of the build host

1551

(e.g. <filename>i686</filename>).

1552

The OpenEmbedded build system sets the value of

1553

<filename>BUILD_ARCH</filename> from the machine name

1554

reported by the <filename>uname</filename> command.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_AS_ARCH'><glossterm>BUILD_AS_ARCH</glossterm>

1560

<info>

1561

BUILD_AS_ARCH[doc] = "Specifies the architecture-specific assembler flags for the build host."

</info>

Specifies the architecture-specific assembler flags for

1566

the build host. By default, the value of

1567

<filename>BUILD_AS_ARCH</filename> is empty.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_CC_ARCH'><glossterm>BUILD_CC_ARCH</glossterm>

1573

<info>

1574

BUILD_CC_ARCH[doc] = "Specifies the architecture-specific C compiler flags for the build host."

</info>

Specifies the architecture-specific C compiler flags for

1579

the build host. By default, the value of

1580

<filename>BUILD_CC_ARCH</filename> is empty.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_CCLD'><glossterm>BUILD_CCLD</glossterm>

1586

<info>

1587

BUILD_CCLD[doc] = "Specifies the linker command to be used for the build host when the C compiler is being used as the linker."

</info>

Specifies the linker command to be used for the build host

1592

when the C compiler is being used as the linker. By default,

1593

<filename>BUILD_CCLD</filename> points to GCC and passes as

1594

arguments the value of

1595

1596

assuming <filename>BUILD_CC_ARCH</filename> is set.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_CFLAGS'><glossterm>BUILD_CFLAGS</glossterm>

1602

<info>

1603

BUILD_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the build host."

</info>

Specifies the flags to pass to the C compiler when building

1608

for the build host.

1609

When building in the <filename>-native</filename> context,

1610

1611

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm>

1617

<info>

1618

BUILD_CPPFLAGS[doc] = "Specifies the flags to pass to the C preprocessor (i.e. to both the C and the C++ compilers) when building for the build host."

</info>

Specifies the flags to pass to the C preprocessor

1623

(i.e. to both the C and the C++ compilers) when building

1624

for the build host.

1625

When building in the <filename>-native</filename> context,

1626

1627

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_CXXFLAGS'><glossterm>BUILD_CXXFLAGS</glossterm>

1633

<info>

1634

BUILD_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the build host."

</info>

Specifies the flags to pass to the C++ compiler when

1639

building for the build host.

1640

When building in the <filename>-native</filename> context,

1641

1642

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_FC'><glossterm>BUILD_FC</glossterm>

1648

<info>

1649

BUILD_FC[doc] = "Specifies the Fortran compiler command for the build host."

</info>

Specifies the Fortran compiler command for the build host.

1654

By default, <filename>BUILD_FC</filename> points to

1655

Gfortran and passes as arguments the value of

1656

1657

assuming <filename>BUILD_CC_ARCH</filename> is set.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_LD'><glossterm>BUILD_LD</glossterm>

1663

<info>

1664

BUILD_LD[doc] = "Specifies the linker command for the build host."

</info>

Specifies the linker command for the build host. By default,

1669

<filename>BUILD_LD</filename> points to the GNU linker (ld)

1670

and passes as arguments the value of

1671

1672

assuming <filename>BUILD_LD_ARCH</filename> is set.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_LD_ARCH'><glossterm>BUILD_LD_ARCH</glossterm>

1678

<info>

1679

BUILD_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the build."

</info>

Specifies architecture-specific linker flags for the build

1684

host. By default, the value of

1685

<filename>BUILD_LD_ARCH</filename> is empty.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm>

1691

<info>

1692

BUILD_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the build host."

</info>

Specifies the flags to pass to the linker when building

1697

for the build host.

1698

When building in the <filename>-native</filename> context,

1699

1700

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_OPTIMIZATION'><glossterm>BUILD_OPTIMIZATION</glossterm>

1706

<info>

1707

BUILD_OPTIMIZATION[doc] = "Specifies the optimization flags passed to the C compiler when building for the build host or the SDK."

</info>

Specifies the optimization flags passed to the C compiler

1712

when building for the build host or the SDK.

1713

The flags are passed through the

and

default values.

</para>

<para>

The default value of the

1722

<filename>BUILD_OPTIMIZATION</filename> variable is

"-O2 -pipe".

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_OS'><glossterm>BUILD_OS</glossterm>

1729

<info>

1730

BUILD_OS[doc] = "The operating system (in lower case) of the building architecture (e.g. Linux)."

</info>

Specifies the operating system in use on the build

1735

host (e.g. "linux").

1736

The OpenEmbedded build system sets the value of

1737

<filename>BUILD_OS</filename> from the OS reported by

1738

the <filename>uname</filename> command - the first word,

1739

converted to lower-case characters.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_PREFIX'><glossterm>BUILD_PREFIX</glossterm>

1745

<info>

1746

BUILD_PREFIX[doc] = "The toolchain binary prefix used for native recipes."

</info>

The toolchain binary prefix used for native recipes.

1751

The OpenEmbedded build system uses the

1752

<filename>BUILD_PREFIX</filename> value to set the

1753

1754

when building for <filename>native</filename> recipes.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_STRIP'><glossterm>BUILD_STRIP</glossterm>

1760

<info>

1761

BUILD_STRIP[doc] = "Specifies the command to be used to strip debugging symbols from binaries produced for the build host."

</info>

Specifies the command to be used to strip debugging symbols

1766

from binaries produced for the build host. By default,

1767

<filename>BUILD_STRIP</filename> points to

1768

<filename>${</filename><link linkend='var-BUILD_PREFIX'><filename>BUILD_PREFIX</filename></link><filename>}strip</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_SYS'><glossterm>BUILD_SYS</glossterm>

1774

<info>

1775

BUILD_SYS[doc] = "The toolchain binary prefix used for native recipes."

</info>

Specifies the system, including the architecture and

1780

the operating system, to use when building for the build

1781

host (i.e. when building <filename>native</filename>

recipes).

</para>

<para>

The OpenEmbedded build system automatically sets this

variable based on

and

You do not need to set the <filename>BUILD_SYS</filename>

variable yourself.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILD_VENDOR'><glossterm>BUILD_VENDOR</glossterm>

1799

<info>

1800

BUILD_VENDOR[doc] = "The vendor name to use when building for the build host."

</info>

Specifies the vendor name to use when building for the

1805

build host.

1806

The default value is an empty string ("").

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>

1812

<info>

1813

BUILDDIR[doc] = "Points to the location of the Build Directory."

</info>

Points to the location of the

1818

1819

You can define this directory indirectly through the

1820

1821

script by passing in a Build Directory path when you run

1822

the script.

1823

If you run the script and do not provide a Build Directory

1824

path, the <filename>BUILDDIR</filename> defaults to

1825

<filename>build</filename> in the current directory.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>

1831

<info>

1832

BUILDHISTORY_COMMIT[doc] = "When inheriting the buildhistory class, this variable specifies whether or not to commit the build history output in a local Git repository."

</info>

When inheriting the

class, this variable specifies whether or not to commit the

1839

build history output in a local Git repository.

1840

If set to "1", this local repository will be maintained

1841

automatically by the

1842

<filename>buildhistory</filename>

1843

class and a commit will be created on every

1844

build for changes to each top-level subdirectory of the

1845

build history output (images, packages, and sdk).

1846

If you want to track changes to build history over

1847

time, you should set this value to "1".

</para>

<para>

By default, the <filename>buildhistory</filename> class

1852

does not commit the build history output in a local

1853

Git repository:

1854

1855

BUILDHISTORY_COMMIT ?= "0"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>

1862

<info>

1863

BUILDHISTORY_COMMIT_AUTHOR[doc] = "When inheriting the buildhistory class, this variable specifies the author to use for each Git commit."

</info>

When inheriting the

class, this variable specifies the author to use for each

1870

Git commit.

1871

In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>

1872

variable to work, the

1873

1874

variable must be set to "1".

</para>

<para>

Git requires that the value you provide for the

1879

<filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable

1880

takes the form of "name <replaceable>email@host</replaceable>".

1881

Providing an email address or host that is not valid does

1882

not produce an error.

</para>

<para>

By default, the <filename>buildhistory</filename> class

1887

sets the variable as follows:

1888

1889

BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>

1896

<info>

1897

BUILDHISTORY_DIR[doc] = "When inheriting the buildhistory class, this variable specifies the directory in which build history information is kept."

</info>

When inheriting the

class, this variable specifies the directory in which

1904

build history information is kept.

1905

For more information on how the variable works, see the

1906

<filename>buildhistory.class</filename>.

</para>

<para>

By default, the <filename>buildhistory</filename> class

1911

sets the directory as follows:

1912

1913

BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>

1920

<info>

1921

BUILDHISTORY_FEATURES[doc] = "When inheriting the buildhistory class, this variable specifies the build history features to be enabled."

</info>

When inheriting the

class, this variable specifies the build history features

1928

to be enabled.

1929

For more information on how build history works, see the

1930

"<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"

1931

section in the Yocto Project Development Tasks Manual.

</para>

<para>

You can specify these features in the form of a

1936

space-separated list:

1937

1938

<listitem><para><emphasis>image:</emphasis>

1939

Analysis of the contents of images, which

1940

includes the list of installed packages among other

1941

things.

1942

</para></listitem>

1943

<listitem><para><emphasis>package:</emphasis>

1944

Analysis of the contents of individual packages.

1945

</para></listitem>

1946

1947

Analysis of the contents of the software

1948

development kit (SDK).

1949

</para></listitem>

1950

1951

Save output file signatures for

1952

<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>

1953

(sstate) tasks.

1954

This saves one file per task and lists the SHA-256

1955

checksums for each file staged (i.e. the output of

the task).

</para></listitem>

</itemizedlist>

</para>

<para>

By default, the <filename>buildhistory</filename> class

1963

enables the following features:

1964

1965

BUILDHISTORY_FEATURES ?= "image package sdk"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>

1972

<info>

1973

BUILDHISTORY_IMAGE_FILES[doc] = "When inheriting the buildhistory class, this variable specifies a list of paths to files copied from the image contents into the build history directory under an "image-files" directory in the directory for the image, so that you can track the contents of each file."

</info>

When inheriting the

class, this variable specifies a list of paths to files

1980

copied from the

1981

image contents into the build history directory under

1982

an "image-files" directory in the directory for

1983

the image, so that you can track the contents of each file.

1984

The default is to copy <filename>/etc/passwd</filename>

1985

and <filename>/etc/group</filename>, which allows you to

1986

monitor for changes in user and group entries.

1987

You can modify the list to include any file.

1988

Specifying an invalid path does not produce an error.

1989

Consequently, you can include files that might

1990

not always be present.

</para>

<para>

By default, the <filename>buildhistory</filename> class

1995

provides paths to the following files:

1996

1997

BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>

2004

<info>

2005

BUILDHISTORY_PUSH_REPO[doc] = "When inheriting the buildhistory class, this variable optionally specifies a remote repository to which build history pushes Git changes."

</info>

When inheriting the

class, this variable optionally specifies a remote

2012

repository to which build history pushes Git changes.

2013

In order for <filename>BUILDHISTORY_PUSH_REPO</filename>

to work,

must be set to "1".

</para>

<para>

The repository should correspond to a remote

2021

address that specifies a repository as understood by

2022

Git, or alternatively to a remote name that you have

2023

set up manually using <filename>git remote</filename>

2024

within the local repository.

</para>

<para>

By default, the <filename>buildhistory</filename> class

2029

sets the variable as follows:

2030

2031

BUILDHISTORY_PUSH_REPO ?= ""

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm>

2038

<info>

2039

BUILDSDK_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the SDK."

</info>

Specifies the flags to pass to the C compiler when building

2044

for the SDK.

2045

When building in the <filename>nativesdk-</filename>

2046

context,

2047

2048

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>BUILDSDK_CPPFLAGS</glossterm>

2054

<info>

2055

BUILDSDK_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the SDK."

</info>

Specifies the flags to pass to the C pre-processor

2060

(i.e. to both the C and the C++ compilers) when building

2061

for the SDK.

2062

When building in the <filename>nativesdk-</filename>

2063

context,

2064

2065

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm>

2071

<info>

2072

BUILDSDK_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the SDK."

</info>

Specifies the flags to pass to the C++ compiler when

2077

building for the SDK.

2078

When building in the <filename>nativesdk-</filename>

2079

context,

2080

2081

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm>

2087

<info>

2088

BUILDSDK_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the SDK."

</info>

Specifies the flags to pass to the linker when building

2093

for the SDK.

2094

When building in the <filename>nativesdk-</filename>

2095

context,

2096

2097

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>

2103

<info>

2104

BUILDSTATS_BASE[doc] = "Points to the location of the directory that holds build statistics when you use and enable the buildstats class."

</info>

Points to the location of the directory that holds build

2109

statistics when you use and enable the

2110

2111

class.

2112

The <filename>BUILDSTATS_BASE</filename> directory defaults

2113

to

2114

<filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>

2120

<info>

2121

BUSYBOX_SPLIT_SUID[doc] = "For the BusyBox recipe, specifies whether to split the output executable file into two parts: one for features that require setuid root, and one for the remaining features."

</info>

For the BusyBox recipe, specifies whether to split the

2126

output executable file into two parts: one for features

2127

that require <filename>setuid root</filename>, and one for

2128

the remaining features (i.e. those that do not require

2129

<filename>setuid root</filename>).

</para>

<para>

The <filename>BUSYBOX_SPLIT_SUID</filename> variable

2134

defaults to "1", which results in splitting the output

2135

executable file.

2136

Set the variable to "0" to get a single output executable

file.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-CACHE'><glossterm>CACHE</glossterm>

2147

<info>

2148

CACHE[doc] = "The directory BitBake uses to store a cache of the metadata."

</info>

Specifies the directory BitBake uses to store a cache

2153

of the

2154

2155

so it does not need to be parsed every time BitBake is

started.

</para>

</glossdef>

</glossentry>

<info>

CC[doc] = "Minimum command and arguments to run the C compiler."

</info>

The minimal command and arguments used to run the C

compiler.

</para>

</glossdef>

</glossentry>

<glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>

2174

<info>

2175

CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as TARGET_CFLAGS."

</info>

Specifies the flags to pass to the C compiler.

2180

This variable is exported to an environment

2181

variable and thus made visible to the software being

2182

built during the compilation step.

</para>

<para>

Default initialization for <filename>CFLAGS</filename>

2187

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

2196

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

2201

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>

2209

<info>

2210

CLASSOVERRIDE[doc] = "An internal variable specifying the special class override that should currently apply (e.g. "class-target", "class-native", and so forth)."

</info>

An internal variable specifying the special class override

2215

that should currently apply (e.g. "class-target",

2216

"class-native", and so forth).

2217

The classes that use this variable (e.g.

2218

2219

2220

and so forth) set the variable to appropriate values.

2221

<note>

2222

<filename>CLASSOVERRIDE</filename> gets its default

2223

"class-target" value from the

2224

<filename>bitbake.conf</filename> file.

</note>

</para>

<para>

As an example, the following override allows you to install

2230

extra files, but only when building for the target:

2231

2232

do_install_append_class-target() {

2233

install my-extra-file ${D}${sysconfdir}

2234

}

2235

</literallayout>

2236

Here is an example where <filename>FOO</filename>

2237

is set to "native" when building for the build host, and

2238

to "other" when not building for the build host:

2239

2240

FOO_class-native = "native"

2241

FOO = "other"

2242

</literallayout>

2243

The underlying mechanism behind

2244

<filename>CLASSOVERRIDE</filename> is simply that it is

2245

included in the default value of

</para>

</glossdef>

</glossentry>

<glossentry id='var-CLEANBROKEN'><glossterm>CLEANBROKEN</glossterm>

2252

<info>

2253

CLEANBROKEN[doc] = "Prevents the build system from running 'make clean' during the do_configure task."

</info>

If set to "1" within a recipe,

2258

<filename>CLEANBROKEN</filename> specifies that

2259

the <filename>make clean</filename> command does

2260

not work for the software being built.

2261

Consequently, the OpenEmbedded build system will not try

2262

to run <filename>make clean</filename> during the

2263

2264

task, which is the default behavior.

</para>

</glossdef>

</glossentry>

<glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>

2270

<info>

2271

COMBINED_FEATURES[doc] = "A set of features common between MACHINE_FEATURES and DISTRO_FEATURES."

</info>

Provides a list of hardware features that are enabled in

both

and

This select list of features contains features that make

2281

sense to be controlled both at the machine and distribution

2282

configuration level.

2283

For example, the "bluetooth" feature requires hardware

2284

support but should also be optional at the distribution

2285

level, in case the hardware supports Bluetooth but you

2286

do not ever intend to use it.

</para>

</glossdef>

</glossentry>

<glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>

2292

<info>

2293

COMMON_LICENSE_DIR[doc] = "Points to meta/files/common-licenses in the Source Directory, which is where generic license files reside."

</info>

Points to <filename>meta/files/common-licenses</filename>

2298

in the

2299

2300

which is where generic license files reside.

</para>

</glossdef>

</glossentry>

<glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>

2306

<info>

2307

COMPATIBLE_HOST[doc] = "A regular expression that resolves to one or more hosts (when the recipe is native) or one or more targets (when the recipe is non-native) with which a recipe is compatible."

</info>

A regular expression that resolves to one or more hosts

2312

(when the recipe is native) or one or more targets (when

2313

the recipe is non-native) with which a recipe is compatible.

2314

The regular expression is matched against

2315

2316

You can use the variable to stop recipes from being built

2317

for classes of systems with which the recipes are not

2318

compatible.

2319

Stopping these builds is particularly useful with kernels.

2320

The variable also helps to increase parsing speed

2321

since the build system skips parsing recipes not

2322

compatible with the current system.

</para>

</glossdef>

</glossentry>

<glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>

2328

<info>

2329

COMPATIBLE_MACHINE[doc] = "A regular expression that resolves to one or more target machines with which a recipe is compatible."

</info>

A regular expression that resolves to one or more

2334

target machines with which a recipe is compatible.

2335

The regular expression is matched against

2336

2337

You can use the variable to stop recipes from being built

2338

for machines with which the recipes are not compatible.

2339

Stopping these builds is particularly useful with kernels.

2340

The variable also helps to increase parsing speed

2341

since the build system skips parsing recipes not

2342

compatible with the current machine.

</para>

</glossdef>

</glossentry>

<glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>

2348

<info>

2349

COMPLEMENTARY_GLOB[doc] = "Defines wildcards to match when installing a list of complementary packages for all the packages installed in an image."

</info>

Defines wildcards to match when installing a list of

2354

complementary packages for all the packages explicitly

2355

(or implicitly) installed in an image.

2356

<note>

2357

The <filename>COMPLEMENTARY_GLOB</filename> variable

2358

uses Unix filename pattern matching

2359

(<ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>),

2360

which is similar to the Unix style pathname pattern

2361

expansion

2362

(<ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>).

2363

</note>

2364

The resulting list of complementary packages is associated

2365

with an item that can be added to

2366

2367

An example usage of this is the "dev-pkgs" item that when

2368

added to <filename>IMAGE_FEATURES</filename> will

2369

install -dev packages (containing headers and other

2370

development files) for every package in the image.

</para>

<para>

To add a new feature item pointing to a wildcard, use a

2375

variable flag to specify the feature item name and

2376

use the value to specify the wildcard.

2377

Here is an example:

2378

2379

COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-COMPONENTS_DIR'><glossterm>COMPONENTS_DIR</glossterm>

2386

<info>

2387

COMPONENTS_DIR[doc] = "Stores sysroot components for each recipe."

</info>

Stores sysroot components for each recipe.

2392

The OpenEmbedded build system uses

2393

<filename>COMPONENTS_DIR</filename> when constructing

2394

recipe-specific sysroots for other recipes.

</para>

<para>

The default is

"<filename>${</filename><link linkend='var-STAGING_DIR'><filename>STAGING_DIR</filename></link><filename>}-components</filename>."

2400

(i.e. "<filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots-components</filename>").

</para>

</glossdef>

</glossentry>

<glossentry id='var-CONF_VERSION'><glossterm>CONF_VERSION</glossterm>

2406

<info>

2407

CONF_VERSION[doc] = "Tracks the version of local.conf. Increased each time build/conf/ changes incompatibly."

</info>

Tracks the version of the local configuration file

2412

(i.e. <filename>local.conf</filename>).

2413

The value for <filename>CONF_VERSION</filename>

2414

increments each time <filename>build/conf/</filename>

2415

compatibility changes.

</para>

</glossdef>

</glossentry>

<glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>

2421

<info>

2422

CONFFILES[doc] = "Identifies editable or configurable files that are part of a package."

</info>

Identifies editable or configurable files that are part of a package.

2427

If the Package Management System (PMS) is being used to update

2428

packages on the target system, it is possible that

2429

configuration files you have changed after the original installation

2430

and that you now want to remain unchanged are overwritten.

2431

In other words, editable files might exist in the package that you do not

2432

want reset as part of the package update process.

2433

You can use the <filename>CONFFILES</filename> variable to list the files in the

2434

package that you wish to prevent the PMS from overwriting during this update process.

</para>

<para>

To use the <filename>CONFFILES</filename> variable, provide a package name

2439

override that identifies the resulting package.

2440

Then, provide a space-separated list of files.

2441

Here is an example:

2442

2443

CONFFILES_${PN} += "${sysconfdir}/file1 \

2444

${sysconfdir}/file2 ${sysconfdir}/file3"

</literallayout>

</para>

<para>

A relationship exists between the <filename>CONFFILES</filename> and

2450

<filename><link linkend='var-FILES'>FILES</link></filename> variables.

2451

The files listed within <filename>CONFFILES</filename> must be a subset of

2452

the files listed within <filename>FILES</filename>.

2453

Because the configuration files you provide with <filename>CONFFILES</filename>

2454

are simply being identified so that the PMS will not overwrite them,

2455

it makes sense that

2456

the files must already be included as part of the package through the

2457

<filename>FILES</filename> variable.

</para>

<note>

When specifying paths as part of the <filename>CONFFILES</filename> variable,

2462

it is good practice to use appropriate path variables.

2463

For example, <filename>${sysconfdir}</filename> rather than

2464

<filename>/etc</filename> or <filename>${bindir}</filename> rather

2465

than <filename>/usr/bin</filename>.

2466

You can find a list of these variables at the top of the

2467

<filename>meta/conf/bitbake.conf</filename> file in the

</note>

</glossdef>

</glossentry>

<glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>

2474

<info>

2475

CONFIG_INITRAMFS_SOURCE[doc] = "Identifies the initial RAM filesystem (initramfs) source files. The OpenEmbedded build system receives and uses this kernel Kconfig variable as an environment variable."

</info>

Identifies the initial RAM filesystem (initramfs) source

2480

files.

2481

The OpenEmbedded build system receives and uses

2482

this kernel Kconfig variable as an environment variable.

2483

By default, the variable is set to null ("").

</para>

<para>

The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be

2488

either a single cpio archive with a

2489

<filename>.cpio</filename> suffix or a

2490

space-separated list of directories and files for building

2491

the initramfs image.

2492

A cpio archive should contain a filesystem archive

2493

to be used as an initramfs image.

2494

Directories should contain a filesystem layout to be

2495

included in the initramfs image.

2496

Files should contain entries according to the format

2497

described by the

2498

<filename>usr/gen_init_cpio</filename> program in the

kernel tree.

</para>

<para>

If you specify multiple directories and files, the

2504

initramfs image will be the aggregate of all of them.

</para>

<para>

For information on creating an initramfs, see the

2509

"<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"

2510

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>

2516

<info>

2517

CONFIG_SITE[doc] = "A list of files that contains autoconf test results relevant to the current build. This variable is used by the Autotools utilities when running configure."

</info>

A list of files that contains <filename>autoconf</filename> test results relevant

2522

to the current build.

2523

This variable is used by the Autotools utilities when running

2524

<filename>configure</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-CONFIGURE_FLAGS'><glossterm>CONFIGURE_FLAGS</glossterm>

2530

<info>

2531

CONFIGURE_FLAGS[doc] = "The minimal arguments for GNU configure."

</info>

The minimal arguments for GNU configure.

</para>

</glossdef>

</glossentry>

<glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>

2541

<info>

2542

CONFLICT_DISTRO_FEATURES[doc] = "When a recipe inherits the distro_features_check class, this variable identifies distribution features that would be in conflict should the recipe be built."

</info>

When inheriting the

class, this

variable identifies distribution features that would

2550

be in conflict should the recipe

2551

be built.

2552

In other words, if the

2553

<filename>CONFLICT_DISTRO_FEATURES</filename> variable

2554

lists a feature that also appears in

2555

<filename>DISTRO_FEATURES</filename> within the

2556

current configuration, an error occurs and the

build stops.

</para>

</glossdef>

</glossentry>

<glossentry id='var-COPYLEFT_LICENSE_EXCLUDE'><glossterm>COPYLEFT_LICENSE_EXCLUDE</glossterm>

2563

<info>

2564

COPYLEFT_LICENSE_EXCLUDE[doc] = "Licenses to exclude in the source archived by the archiver class."

</info>

A space-separated list of licenses to exclude from the

2569

source archived by the

2570

2571

class.

2572

In other words, if a license in a recipe's

2573

2574

value is in the value of

2575

<filename>COPYLEFT_LICENSE_EXCLUDE</filename>, then its

2576

source is not archived by the class.

2577

<note>

2578

The <filename>COPYLEFT_LICENSE_EXCLUDE</filename>

2579

variable takes precedence over the

variable.

</note>

The default value, which is "CLOSED Proprietary", for

2584

<filename>COPYLEFT_LICENSE_EXCLUDE</filename> is set

2585

by the

2586

2587

class, which is inherited by the

2588

<filename>archiver</filename> class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-COPYLEFT_LICENSE_INCLUDE'><glossterm>COPYLEFT_LICENSE_INCLUDE</glossterm>

2594

<info>

2595

COPYLEFT_LICENSE_INCLUDE[doc] = "Licenses to include in the source archived by the archiver class."

</info>

A space-separated list of licenses to include in the

2600

source archived by the

2601

2602

class.

2603

In other words, if a license in a recipe's

2604

2605

value is in the value of

2606

<filename>COPYLEFT_LICENSE_INCLUDE</filename>, then its

2607

source is archived by the class.

</para>

<para>

The default value is set by the

2612

2613

class, which is inherited by the

2614

<filename>archiver</filename> class.

2615

The default value includes "GPL*", "LGPL*", and "AGPL*".

</para>

</glossdef>

</glossentry>

<glossentry id='var-COPYLEFT_PN_EXCLUDE'><glossterm>COPYLEFT_PN_EXCLUDE</glossterm>

2621

<info>

2622

COPYLEFT_PN_EXCLUDE[doc] = "Recipes to exclude in the source archived by the archiver class."

</info>

A list of recipes to exclude in the source archived

by the

class.

The <filename>COPYLEFT_PN_EXCLUDE</filename> variable

2631

overrides the license inclusion and exclusion caused

through the

and

variables, respectively.

</para>

<para>

The default value, which is "" indicating to not explicitly

2641

exclude any recipes by name, for

2642

<filename>COPYLEFT_PN_EXCLUDE</filename> is set

2643

by the

2644

2645

class, which is inherited by the

2646

<filename>archiver</filename> class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-COPYLEFT_PN_INCLUDE'><glossterm>COPYLEFT_PN_INCLUDE</glossterm>

2652

<info>

2653

COPYLEFT_PN_INCLUDE[doc] = "Recipes to include in the source archived by the archiver class."

</info>

A list of recipes to include in the source archived

by the

class.

The <filename>COPYLEFT_PN_INCLUDE</filename> variable

2662

overrides the license inclusion and exclusion caused

through the

and

variables, respectively.

</para>

<para>

The default value, which is "" indicating to not explicitly

2672

include any recipes by name, for

2673

<filename>COPYLEFT_PN_INCLUDE</filename> is set

2674

by the

2675

2676

class, which is inherited by the

2677

<filename>archiver</filename> class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-COPYLEFT_RECIPE_TYPES'><glossterm>COPYLEFT_RECIPE_TYPES</glossterm>

2683

<info>

2684

COPYLEFT_RECIPE_TYPES[doc] = "Recipe types to include in the source archived by the archiver class."

</info>

A space-separated list of recipe types to include

2689

in the source archived by the

2690

2691

class.

2692

Recipe types are <filename>target</filename>,

2693

<filename>native</filename>,

2694

<filename>nativesdk</filename>,

2695

<filename>cross</filename>,

2696

<filename>crosssdk</filename>, and

2697

<filename>cross-canadian</filename>.

</para>

<para>

The default value, which is "target*", for

2702

<filename>COPYLEFT_RECIPE_TYPES</filename> is set

2703

by the

2704

2705

class, which is inherited by the

2706

<filename>archiver</filename> class.

</para>

</glossdef>

</glossentry>

<info>

COPY_LIC_DIRS[doc] = "If set to "1" along with the COPY_LIC_MANIFEST variable, the OpenEmbedded build system copies into the image the license files, which are located in /usr/share/common-licenses, for each package."

</info>

If set to "1" along with the

2718

2719

variable, the OpenEmbedded build system copies

2720

into the image the license files, which are located in

2721

<filename>/usr/share/common-licenses</filename>,

2722

for each package.

2723

The license files are placed

2724

in directories within the image itself during build time.

2725

<note>

2726

The <filename>COPY_LIC_DIRS</filename> does not

2727

offer a path for adding licenses for newly installed

2728

packages to an image, which might be most suitable

2729

for read-only filesystems that cannot be upgraded.

2730

See the

2731

2732

variable for additional information.

2733

You can also reference the

2734

"<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"

2735

section in the Yocto Project Development Tasks Manual

2736

for information on providing license text.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>

2743

<info>

2744

COPY_LIC_MANIFEST[doc] = "If set to "1", the OpenEmbedded build system copies the license manifest for the image to /usr/share/common-licenses/license.manifest within the image itself."

</info>

If set to "1", the OpenEmbedded build system copies

2749

the license manifest for the image to

2750

<filename>/usr/share/common-licenses/license.manifest</filename>

2751

within the image itself during build time.

2752

<note>

2753

The <filename>COPY_LIC_MANIFEST</filename> does not

2754

offer a path for adding licenses for newly installed

2755

packages to an image, which might be most suitable

2756

for read-only filesystems that cannot be upgraded.

2757

See the

2758

2759

variable for additional information.

2760

You can also reference the

2761

"<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"

2762

section in the Yocto Project Development Tasks Manual

2763

for information on providing license text.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>

2770

<info>

2771

CORE_IMAGE_EXTRA_INSTALL[doc] = "Specifies the list of packages to be added to the image. You should only set this variable in the conf/local.conf file in the Build Directory."

</info>

Specifies the list of packages to be added to the image.

2776

You should only set this variable in the

2777

<filename>local.conf</filename> configuration file found

in the

</para>

<para>

This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.

</para>

</glossdef>

</glossentry>

<glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>

2789

<info>

2790

COREBASE[doc] = "Specifies the parent directory of the OpenEmbedded-Core Metadata layer (i.e. meta)."

</info>

Specifies the parent directory of the OpenEmbedded-Core

2795

Metadata layer (i.e. <filename>meta</filename>).

</para>

<para>

It is an important distinction that

2800

<filename>COREBASE</filename> points to the parent of this

2801

layer and not the layer itself.

2802

Consider an example where you have cloned the Poky Git

2803

repository and retained the <filename>poky</filename>

2804

name for your local copy of the repository.

2805

In this case, <filename>COREBASE</filename> points to

2806

the <filename>poky</filename> folder because it is the

2807

parent directory of the <filename>poky/meta</filename>

layer.

</para>

</glossdef>

</glossentry>

<glossentry id='var-COREBASE_FILES'><glossterm>COREBASE_FILES</glossterm>

2814

<info>

2815

COREBASE_FILES[doc] = "Lists files from the COREBASE directory that should be copied other than the layers listed in the bblayers.conf file."

</info>

Lists files from the

directory that should be copied other than the layers

2822

listed in the <filename>bblayers.conf</filename> file.

2823

The <filename>COREBASE_FILES</filename> variable exists

2824

for the purpose of copying metadata from the

2825

OpenEmbedded build system into the extensible

SDK.

</para>

<para>

Explicitly listing files in <filename>COREBASE</filename>

2831

is needed because it typically contains build

2832

directories and other files that should not normally

2833

be copied into the extensible SDK.

2834

Consequently, the value of

2835

<filename>COREBASE_FILES</filename> is used in order to

2836

only copy the files that are actually needed.

</para>

</glossdef>

</glossentry>

<info>

CPP[doc] = "Minimum command and arguments to run the C preprocessor."

</info>

The minimal command and arguments used to run the C

preprocessor.

</para>

</glossdef>

</glossentry>

<glossentry id='var-CPPFLAGS'><glossterm>CPPFLAGS</glossterm>

2854

<info>

2855

CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers)."

</info>

Specifies the flags to pass to the C pre-processor

2860

(i.e. to both the C and the C++ compilers).

2861

This variable is exported to an environment

2862

variable and thus made visible to the software being

2863

built during the compilation step.

</para>

<para>

Default initialization for <filename>CPPFLAGS</filename>

2868

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

2877

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

2882

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-CROSS_COMPILE'><glossterm>CROSS_COMPILE</glossterm>

2890

<info>

2891

CROSS_COMPILE[doc] = "The toolchain binary prefix for the target tools."

</info>

The toolchain binary prefix for the target tools.

2896

The <filename>CROSS_COMPILE</filename> variable is the

same as the

variable.

<note>

The OpenEmbedded build system sets the

2902

<filename>CROSS_COMPILE</filename> variable only in

2903

certain contexts (e.g. when building for kernel

2904

and kernel module recipes).

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-CVSDIR'><glossterm>CVSDIR</glossterm>

2911

<info>

2912

CVSDIR[doc] = "The directory where cvs checkouts will be stored in."

</info>

The directory in which files checked out under the

2917

CVS system are stored.

</para>

</glossdef>

</glossentry>

<info>

CXX[doc] = "Minimum command and arguments to run the C++ compiler."

</info>

The minimal command and arguments used to run the C++

compiler.

</para>

</glossdef>

</glossentry>

<glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm>

2935

<info>

2936

CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler."

</info>

Specifies the flags to pass to the C++ compiler.

2941

This variable is exported to an environment

2942

variable and thus made visible to the software being

2943

built during the compilation step.

</para>

<para>

Default initialization for <filename>CXXFLAGS</filename>

2948

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

2957

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

2962

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

</glossdiv>

<info>

D[doc] = "The destination directory."

</info>

The destination directory.

2980

The location in the

2981

2982

where components are installed by the

2983

2984

task.

2985

This location defaults to:

${WORKDIR}/image

</literallayout>

<note><title>Caution</title>

2990

Tasks that read from or write to this directory should

2991

run under

2992

<ulink url='&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo'>fakeroot</ulink>.

</note>

</para>

</glossdef>

</glossentry>

<info>

DATE[doc] = "The date the build was started using YMD format."

</info>

The date the build was started.

3005

Dates appear using the year, month, and day (YMD) format

3006

(e.g. "20150209" for February 9th, 2015).

</para>

</glossdef>

</glossentry>

<glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>

3012

<info>

3013

DATETIME[doc] = "The date and time the build was started."

</info>

The date and time on which the current build started.

3018

The format is suitable for timestamps.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEBIAN_NOAUTONAME'><glossterm>DEBIAN_NOAUTONAME</glossterm>

3024

<info>

3025

DEBIAN_NOAUTONAME[doc] = "Prevents a particular package from being renamed according to Debian package naming."

</info>

When the

class is inherited, which is the default behavior,

3032

<filename>DEBIAN_NOAUTONAME</filename> specifies a

3033

particular package should not be renamed according to

3034

Debian library package naming.

3035

You must use the package name as an override when you

3036

set this variable.

3037

Here is an example from the <filename>fontconfig</filename>

3038

recipe:

3039

3040

DEBIAN_NOAUTONAME_fontconfig-utils = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEBIANNAME'><glossterm>DEBIANNAME</glossterm>

3047

<info>

3048

DEBIANNAME[doc] = "Allows you to override the library name for an individual package for Debian library package renaming."

</info>

When the

class is inherited, which is the default behavior,

3055

<filename>DEBIANNAME</filename> allows you to override the

3056

library name for an individual package.

3057

Overriding the library name in these cases is rare.

3058

You must use the package name as an override when you

3059

set this variable.

3060

Here is an example from the <filename>dbus</filename>

3061

recipe:

3062

3063

DEBIANNAME_${PN} = "dbus-1"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>

3070

<info>

3071

DEBUG_BUILD[doc] = "Specifies to build packages with debugging information. This influences the value of the SELECTED_OPTIMIZATION variable."

</info>

Specifies to build packages with debugging information.

3076

This influences the value of the

3077

<filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>

3084

<info>

3085

DEBUG_OPTIMIZATION[doc] = "The options to pass in TARGET_CFLAGS and CFLAGS when compiling a system for debugging. This variable defaults to '-O -fno-omit-frame-pointer -g'."

</info>

The options to pass in

3090

<filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>

3091

and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling

3092

a system for debugging.

3093

This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>

3099

<info>

3100

DEFAULT_PREFERENCE[doc] = "Specifies a weak bias for recipe selection priority."

</info>

Specifies a weak bias for recipe selection priority.

</para>

<para>

The most common usage of this is variable is to set

3109

it to "-1" within a recipe for a development version of a

3110

piece of software.

3111

Using the variable in this way causes the stable version

3112

of the recipe to build by default in the absence of

3113

<filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>

3114

being used to build the development version.

</para>

<note>

The bias provided by <filename>DEFAULT_PREFERENCE</filename>

3119

is weak and is overridden by

3120

<filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>

3121

if that variable is different between two layers

3122

that contain different versions of the same recipe.

</note>

</glossdef>

</glossentry>

<glossentry id='var-DEFAULTTUNE'><glossterm>DEFAULTTUNE</glossterm>

3128

<info>

3129

DEFAULTTUNE[doc] = "The default CPU and Application Binary Interface (ABI) tunings (i.e. the "tune") used by the OpenEmbedded build system."

</info>

The default CPU and Application Binary Interface (ABI)

3134

tunings (i.e. the "tune") used by the OpenEmbedded build

3135

system.

3136

The <filename>DEFAULTTUNE</filename> helps define

</para>

<para>

The default tune is either implicitly or explicitly set

3142

by the machine

3143

(<link linkend='var-MACHINE'><filename>MACHINE</filename></link>).

3144

However, you can override the setting using available tunes

as defined with

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>

3152

<info>

3153

DEPENDS[doc] = "Lists a recipe's build-time dependencies (i.e. other recipe files)."

</info>

Lists a recipe's build-time dependencies.

3158

These are dependencies on other recipes whose

3159

contents (e.g. headers and shared libraries) are needed

3160

by the recipe at build time.

</para>

<para>

As an example, consider a recipe <filename>foo</filename>

3165

that contains the following assignment:

DEPENDS = "bar"

</literallayout>

The practical effect of the previous assignment is that

3170

all files installed by bar will be available in the

3171

appropriate staging sysroot, given by the

3172

3173

variables, by the time the

3174

3175

task for <filename>foo</filename> runs.

3176

This mechanism is implemented by having

3177

<filename>do_configure</filename> depend on the

3178

3179

task of each recipe listed in <filename>DEPENDS</filename>,

3180

through a

3181

<filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>

declaration in the

class.

<note>

It seldom is necessary to reference, for example,

3187

<filename>STAGING_DIR_HOST</filename> explicitly.

3188

The standard classes and build-related variables are

3189

configured to automatically use the appropriate staging

3190

sysroots.

3191

</note>

3192

As another example, <filename>DEPENDS</filename> can also

3193

be used to add utilities that run on the build machine

3194

during the build.

3195

For example, a recipe that makes use of a code generator

3196

built by the recipe <filename>codegen</filename> might have

3197

the following:

3198

3199

DEPENDS = "codegen-native"

3200

</literallayout>

3201

For more information, see the

class and the

variable.

<note>

<title>Notes</title>

<filename>DEPENDS</filename> is a list of

3211

recipe names.

3212

Or, to be more precise, it is a list of

3213

3214

names, which usually match recipe names.

3215

Putting a package name such as "foo-dev" in

3216

<filename>DEPENDS</filename> does not make

3217

sense.

3218

Use "foo" instead, as this will put files

3219

from all the packages that make up

3220

<filename>foo</filename>, which includes

3221

those from <filename>foo-dev</filename>, into

the sysroot.

</para></listitem>

One recipe having another recipe in

3226

<filename>DEPENDS</filename> does not by itself

3227

add any runtime dependencies between the

3228

packages produced by the two recipes.

3229

However, as explained in the

3230

"<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"

3231

section in the Yocto Project Overview and

3232

Concepts Manual, runtime dependencies will

3233

often be added automatically, meaning

3234

<filename>DEPENDS</filename> alone is

3235

sufficient for most recipes.

</para></listitem>

Counterintuitively,

<filename>DEPENDS</filename> is often necessary

3240

even for recipes that install precompiled

3241

components.

3242

For example, if <filename>libfoo</filename>

3243

is a precompiled library that links against

3244

<filename>libbar</filename>, then

3245

linking against <filename>libfoo</filename>

3246

requires both <filename>libfoo</filename>

3247

and <filename>libbar</filename> to be available

3248

in the sysroot.

3249

Without a <filename>DEPENDS</filename> from the

3250

recipe that installs <filename>libfoo</filename>

3251

to the recipe that installs

3252

<filename>libbar</filename>, other recipes might

3253

fail to link against

3254

<filename>libfoo</filename>.

</para></listitem>

</itemizedlist>

</note>

</para>

<para>

For information on runtime dependencies, see the

variable.

You can also see the

"<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and

3266

"<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"

3267

sections in the BitBake User Manual for additional

3268

information on tasks and dependencies.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>

3274

<info>

3275

DEPLOY_DIR[doc] = "Points to the general area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."

</info>

Points to the general area that the OpenEmbedded build

3280

system uses to place images, packages, SDKs, and other output

3281

files that are ready to be used outside of the build system.

3282

By default, this directory resides within the

3283

3284

as <filename>${TMPDIR}/deploy</filename>.

</para>

<para>

For more information on the structure of the Build

3289

Directory, see

3290

"<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"

3291

section.

3292

For more detail on the contents of the

3293

<filename>deploy</filename> directory, see the

3294

"<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>",

3295

"<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>",

3296

and

3297

"<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"

3298

sections all in the Yocto Project Overview and Concepts

Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEPLOY_DIR_DEB'><glossterm>DEPLOY_DIR_DEB</glossterm>

3305

<info>

3306

DEPLOY_DIR_DEB[doc] = "Points to a Debian-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."

</info>

Points to the area that the OpenEmbedded build system uses

3311

to place Debian packages that are ready to be used outside

3312

of the build system.

3313

This variable applies only when

3314

3315

contains "package_deb".

</para>

<para>

The BitBake configuration file initially defines the

3320

<filename>DEPLOY_DIR_DEB</filename> variable as a

sub-folder of

DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"

</literallayout>

</para>

<para>

The

class uses the

<filename>DEPLOY_DIR_DEB</filename> variable to make sure

3333

the

3334

3335

task writes Debian packages into the appropriate folder.

3336

For more information on how packaging works, see the

3337

"<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"

3338

section in the Yocto Project Overview and Concepts Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>

3344

<info>

3345

DEPLOY_DIR_IMAGE[doc] = "Points to the area that the OpenEmbedded build system uses to place images and other associated output files that are ready to be deployed onto the target machine."

</info>

Points to the area that the OpenEmbedded build system uses

3350

to place images and other associated output files that are

3351

ready to be deployed onto the target machine.

3352

The directory is machine-specific as it contains the

3353

<filename>${MACHINE}</filename> name.

3354

By default, this directory resides within the

3355

3356

as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.

</para>

<para>

For more information on the structure of the Build

3361

Directory, see

3362

"<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"

3363

section.

3364

For more detail on the contents of the

3365

<filename>deploy</filename> directory, see the

3366

"<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"

3367

and

3368

"<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"

3369

sections both in the Yocto Project Overview and Concepts

Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEPLOY_DIR_IPK'><glossterm>DEPLOY_DIR_IPK</glossterm>

3376

<info>

3377

DEPLOY_DIR_IPK[doc] = "Points to a IPK-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."

</info>

Points to the area that the OpenEmbedded build system uses

3382

to place IPK packages that are ready to be used outside of

3383

the build system.

3384

This variable applies only when

3385

3386

contains "package_ipk".

</para>

<para>

The BitBake configuration file initially defines this

3391

variable as a sub-folder of

3392

3393

3394

DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"

</literallayout>

</para>

<para>

The

class uses the

<filename>DEPLOY_DIR_IPK</filename> variable to make sure

3403

the

3404

3405

task writes IPK packages into the appropriate folder.

3406

For more information on how packaging works, see the

3407

"<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"

3408

section in the Yocto Project Overview and Concepts Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEPLOY_DIR_RPM'><glossterm>DEPLOY_DIR_RPM</glossterm>

3414

<info>

3415

DEPLOY_DIR_RPM[doc] = "Points to a RPM-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."

</info>

Points to the area that the OpenEmbedded build system uses

3420

to place RPM packages that are ready to be used outside

3421

of the build system.

3422

This variable applies only when

3423

3424

contains "package_rpm".

</para>

<para>

The BitBake configuration file initially defines this

3429

variable as a sub-folder of

3430

3431

3432

DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"

</literallayout>

</para>

<para>

The

class uses the

<filename>DEPLOY_DIR_RPM</filename> variable to make sure

3441

the

3442

3443

task writes RPM packages into the appropriate folder.

3444

For more information on how packaging works, see the

3445

"<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"

3446

section in the Yocto Project Overview and Concepts Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEPLOY_DIR_TAR'><glossterm>DEPLOY_DIR_TAR</glossterm>

3452

<info>

3453

DEPLOY_DIR_TAR[doc] = "Points to a tarball area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."

</info>

Points to the area that the OpenEmbedded build system uses

3458

to place tarballs that are ready to be used outside of

3459

the build system.

3460

This variable applies only when

3461

3462

contains "package_tar".

</para>

<para>

The BitBake configuration file initially defines this

3467

variable as a sub-folder of

3468

3469

3470

DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"

</literallayout>

</para>

<para>

The

class uses the

<filename>DEPLOY_DIR_TAR</filename> variable to make sure

3479

the

3480

3481

task writes TAR packages into the appropriate folder.

3482

For more information on how packaging works, see the

3483

"<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"

3484

section in the Yocto Project Overview and Concepts Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>

3490

<info>

3491

DEPLOYDIR[doc] = "For recipes that inherit the deploy class, the DEPLOYDIR points to a temporary work area for deployed files."

</info>

When inheriting the

class, the <filename>DEPLOYDIR</filename> points to a

3498

temporary work area for deployed files that is set in the

3499

<filename>deploy</filename> class as follows:

3500

3501

DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"

</literallayout>

</para>

<para>

Recipes inheriting the <filename>deploy</filename> class

3507

should copy files to be deployed into

3508

<filename>DEPLOYDIR</filename>, and the class will take

3509

care of copying them into

afterwards.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>

3517

<info>

3518

DESCRIPTION[doc] = "The package description used by package managers. If not set, DESCRIPTION takes the value of the SUMMARY variable."

</info>

The package description used by package managers.

3523

If not set, <filename>DESCRIPTION</filename> takes

the value of the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>

3532

<info>

3533

DISTRO[doc] = "The short name of the distribution. If the variable is blank, meta/conf/distro/defaultsetup.conf will be used."

</info>

The short name of the distribution.

3538

For information on the long name of the distribution, see

the

variable.

</para>

<para>

The <filename>DISTRO</filename> variable corresponds to a

3546

distribution configuration file whose root name is the

3547

same as the variable's argument and whose filename

3548

extension is <filename>.conf</filename>.

3549

For example, the distribution configuration file for the

3550

Poky distribution is named <filename>poky.conf</filename>

3551

and resides in the

3552

<filename>meta-poky/conf/distro</filename> directory of

the

</para>

<para>

Within that <filename>poky.conf</filename> file, the

3559

<filename>DISTRO</filename> variable is set as follows:

DISTRO = "poky"

</literallayout>

</para>

<para>

Distribution configuration files are located in a

3567

<filename>conf/distro</filename> directory within the

3568

3569

that contains the distribution configuration.

3570

The value for <filename>DISTRO</filename> must not contain

3571

spaces, and is typically all lower-case.

3572

<note>

3573

If the <filename>DISTRO</filename> variable is blank,

3574

a set of default configurations are used, which are

3575

specified within

3576

<filename>meta/conf/distro/defaultsetup.conf</filename>

3577

also in the Source Directory.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_CODENAME'><glossterm>DISTRO_CODENAME</glossterm>

3584

<info>

3585

DISTRO_CODENAME[doc] = "Specifies a codename for the distribution being built."

</info>

Specifies a codename for the distribution being built.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>

3595

<info>

3596

DISTRO_EXTRA_RDEPENDS[doc] = "Specifies a list of distro-specific packages to add to all images. The variable only applies to the images that include packagegroup-base."

</info>

Specifies a list of distro-specific packages to add to all images.

3601

This variable takes affect through

3602

<filename>packagegroup-base</filename> so the

3603

variable only really applies to the more full-featured

3604

images that include <filename>packagegroup-base</filename>.

3605

You can use this variable to keep distro policy out of

3606

generic images.

3607

As with all other distro variables, you set this variable

3608

in the distro <filename>.conf</filename> file.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>

3614

<info>

3615

DISTRO_EXTRA_RRECOMMENDS[doc] = "Specifies a list of distro-specific packages to add to all images if the packages exist. The list of packages are automatically installed but you can remove them."

</info>

Specifies a list of distro-specific packages to add to all images

3620

if the packages exist.

3621

The packages might not exist or be empty (e.g. kernel modules).

3622

The list of packages are automatically installed but you can

remove them.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>

3629

<info>

3630

DISTRO_FEATURES[doc] = "The features enabled for the distribution."

</info>

The software support you want in your distribution for

3635

various features.

3636

You define your distribution features in the distribution

configuration file.

</para>

<para>

In most cases, the presence or absence of a feature in

3642

<filename>DISTRO_FEATURES</filename> is translated to the

3643

appropriate option supplied to the configure script

3644

during the

3645

3646

task for recipes that optionally support the feature.

3647

For example, specifying "x11" in

3648

<filename>DISTRO_FEATURES</filename>, causes

3649

every piece of software built for the target that can

3650

optionally support X11 to have its X11 support enabled.

</para>

<para>

Two more examples are Bluetooth and NFS support.

3655

For a more complete list of features that ships with the

3656

Yocto Project and that you can provide with this variable,

3657

see the

3658

"<link linkend='ref-features-distro'>Distro Features</link>"

section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>

3665

<info>

3666

DISTRO_FEATURES_BACKFILL[doc] = "Features to be added to DISTRO_FEATURES if not also present in DISTRO_FEATURES_BACKFILL_CONSIDERED. This variable is set in the meta/conf/bitbake.conf file and it is not intended to be user-configurable."

</info>

Features to be added to

3671

<filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>

3672

if not also present in

3673

<filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.

</para>

<para>

This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.

3678

It is not intended to be user-configurable.

3679

It is best to just reference the variable to see which distro features are

3680

being backfilled for all distro configurations.

3681

See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for

more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>

3688

<info>

3689

DISTRO_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from DISTRO_FEATURES_BACKFILL that should not be backfilled (i.e. added to DISTRO_FEATURES) during the build."

</info>

Features from

<filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>

3695

that should not be backfilled (i.e. added to

3696

<filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)

3697

during the build.

3698

See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for

more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_FEATURES_DEFAULT'><glossterm>DISTRO_FEATURES_DEFAULT</glossterm>

3705

<info>

3706

DISTRO_FEATURES_DEFAULT[doc] = "Provides the default list of distro features with the exception of any libc-specific features."

</info>

A convenience variable that gives you the default

3711

list of distro features with the exception of any

3712

features specific to the C library

3713

(<filename>libc</filename>).

</para>

<para>

When creating a custom distribution, you might find it

3718

useful to be able to reuse the default

3719

3720

options without the need to write out the full set.

3721

Here is an example that uses

3722

<filename>DISTRO_FEATURES_DEFAULT</filename> from a

3723

custom distro configuration file:

3724

3725

DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_FEATURES_FILTER_NATIVE'><glossterm>DISTRO_FEATURES_FILTER_NATIVE</glossterm>

3732

<info>

3733

DISTRO_FEATURES_FILTER_NATIVE[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building native recipes."

</info>

Specifies a list of features that if present in

3738

the target

3739

3740

value should be included in

3741

<filename>DISTRO_FEATURES</filename> when building native

3742

recipes.

3743

This variable is used in addition to the features

filtered using the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_FEATURES_FILTER_NATIVESDK'><glossterm>DISTRO_FEATURES_FILTER_NATIVESDK</glossterm>

3752

<info>

3753

DISTRO_FEATURES_FILTER_NATIVESDK[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building nativesdk recipes."

</info>

Specifies a list of features that if present in the target

3758

3759

value should be included in

3760

<filename>DISTRO_FEATURES</filename> when building

3761

nativesdk recipes.

3762

This variable is used in addition to the features

filtered using the

variable.

</para>

</glossdef>

</glossentry>

<!--

<glossentry id='var-DISTRO_FEATURES_LIBC'><glossterm>DISTRO_FEATURES_LIBC</glossterm>

3772

<info>

3773

DISTRO_FEATURES_LIBC[doc] = "Specifies the list of distro features that are specific to the C library (libc)."

</info>

A convenience variable that specifies the list of distro

3778

features that are specific to the C library

3779

(<filename>libc</filename>).

3780

Typically, these features are prefixed with "libc-" and

3781

control which features are enabled at during the build

3782

within the C library itself.

</para>

</glossdef>

</glossentry>

-->

<glossentry id='var-DISTRO_FEATURES_NATIVE'><glossterm>DISTRO_FEATURES_NATIVE</glossterm>

3789

<info>

3790

DISTRO_FEATURES_NATIVE[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building native recipes."

</info>

Specifies a list of features that should be included in

3795

3796

when building native recipes.

3797

This variable is used in addition to the features

filtered using the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_FEATURES_NATIVESDK'><glossterm>DISTRO_FEATURES_NATIVESDK</glossterm>

3806

<info>

3807

DISTRO_FEATURES_NATIVESDK[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building nativesdk recipes."

</info>

Specifies a list of features that should be included in

3812

3813

when building nativesdk recipes.

3814

This variable is used in addition to the features

filtered using the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>

3823

<info>

3824

DISTRO_NAME[doc] = "The long name of the distribution."

</info>

The long name of the distribution.

3829

For information on the short name of the distribution, see

the

variable.

</para>

<para>

The <filename>DISTRO_NAME</filename> variable corresponds

3837

to a distribution configuration file whose root name is the

3838

same as the variable's argument and whose filename

3839

extension is <filename>.conf</filename>.

3840

For example, the distribution configuration file for the

3841

Poky distribution is named <filename>poky.conf</filename>

3842

and resides in the

3843

<filename>meta-poky/conf/distro</filename> directory of

the

</para>

<para>

Within that <filename>poky.conf</filename> file, the

3850

<filename>DISTRO_NAME</filename> variable is set as

3851

follows:

3852

3853

DISTRO_NAME = "Poky (Yocto Project Reference Distro)"

</literallayout>

</para>

<para>

Distribution configuration files are located in a

3859

<filename>conf/distro</filename> directory within the

3860

3861

that contains the distribution configuration.

3862

<note>

3863

If the <filename>DISTRO_NAME</filename> variable is

3864

blank, a set of default configurations are used, which

3865

are specified within

3866

<filename>meta/conf/distro/defaultsetup.conf</filename>

3867

also in the Source Directory.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>

3874

<info>

3875

DISTRO_VERSION[doc] = "The version of the distribution."

</info>

The version of the distribution.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>

3885

<info>

3886

DISTROOVERRIDES[doc] = "A colon-separated list of overrides specific to the current distribution."

</info>

A colon-separated list of overrides specific to the

3891

current distribution.

3892

By default, this list includes the value of

</para>

<para>

You can extend <filename>DISTROOVERRIDES</filename>

3898

to add extra overrides that should apply to

the distribution.

</para>

<para>

The underlying mechanism behind

3904

<filename>DISTROOVERRIDES</filename> is simply that it

3905

is included in the default value of

</para>

</glossdef>

</glossentry>

<info>

DL_DIR[doc] = "The central download directory used by the build process to store downloads. By default, the directory is 'downloads' in the Build Directory."

</info>

The central download directory used by the build process to

3918

store downloads.

3919

By default, <filename>DL_DIR</filename> gets files

3920

suitable for mirroring for everything except Git

3921

repositories.

3922

If you want tarballs of Git repositories, use the

variable.

</para>

<para>

You can set this directory by defining the

3929

<filename>DL_DIR</filename> variable in the

3930

<filename>conf/local.conf</filename> file.

3931

This directory is self-maintaining and you should not have

3932

to touch it.

3933

By default, the directory is <filename>downloads</filename>

in the

#DL_DIR ?= "${TOPDIR}/downloads"

3938

</literallayout>

3939

To specify a different download directory, simply remove

3940

the comment from the line and provide your directory.

</para>

<para>

During a first build, the system downloads many different

3945

source code tarballs from various upstream projects.

3946

Downloading can take a while, particularly if your network

3947

connection is slow.

3948

Tarballs are all stored in the directory defined by

3949

<filename>DL_DIR</filename> and the build system looks there

3950

first to find source tarballs.

3951

<note>

3952

When wiping and rebuilding, you can preserve this

3953

directory to speed up this part of subsequent

builds.

</note>

</para>

<para>

You can safely share this directory between multiple builds

3960

on the same development machine.

3961

For additional information on how the build process gets

3962

source files when working behind a firewall or proxy server,

3963

see this specific question in the

3964

"<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"

3965

chapter.

3966

You can also refer to the

3967

"<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"

Wiki page.

</para>

</glossdef>

</glossentry>

<glossentry id='var-DOC_COMPRESS'><glossterm>DOC_COMPRESS</glossterm>

3974

<info>

3975

DOC_COMPRESS[doc] = "When inheriting the compress_doc class, this variable sets the compression policy used when the OpenEmbedded build system compresses man pages and info pages."

</info>

When inheriting the

class, this variable sets the compression policy used when

3982

the OpenEmbedded build system compresses man pages and info

3983

pages.

3984

By default, the compression method used is gz (gzip).

3985

Other policies available are xz and bz2.

</para>

<para>

For information on policies and on how to use this

3990

variable, see the comments in the

3991

<filename>meta/classes/compress_doc.bbclass</filename> file.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-EFI_PROVIDER'><glossterm>EFI_PROVIDER</glossterm>

4001

<info>

4002

EFI_PROVIDER[doc] = "When building bootable images (i.e. where hddimg, iso, or wic.vmdk is in IMAGE_FSTYPES), the EFI_PROVIDER variable specifies the EFI bootloader to use."

</info>

When building bootable images (i.e. where

4007

<filename>hddimg</filename>, <filename>iso</filename>,

4008

or <filename>wic.vmdk</filename> is in

4009

4010

the <filename>EFI_PROVIDER</filename> variable specifies

4011

the EFI bootloader to use.

4012

The default is "grub-efi", but "systemd-boot" can be used

instead.

</para>

<para>

See the

and

classes for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>

4027

<info>

4028

ENABLE_BINARY_LOCALE_GENERATION[doc] = "Controls which locales for glibc are generated during the build. The variable is useful if the target device has 64Mbytes of RAM or less."

</info>

Variable that controls which locales for

4033

<filename>glibc</filename> are generated during the

4034

build (useful if the target device has 64Mbytes

of RAM or less).

</para>

</glossdef>

</glossentry>

<glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>

4041

<info>

4042

ERR_REPORT_DIR[doc] = "When used with the report-error class, specifies the path used for storing the debug files created by the error reporting tool, which allows you to submit build errors you encounter to a central database."

</info>

When used with the

class, specifies the path used for storing the debug files

4049

created by the

4050

<ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,

4051

which allows you to submit build errors you encounter to a

4052

central database.

4053

By default, the value of this variable is

4054

<filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.

</para>

<para>

You can set <filename>ERR_REPORT_DIR</filename> to the path

4059

you want the error reporting tool to store the debug files

4060

as follows in your <filename>local.conf</filename> file:

4061

4062

ERR_REPORT_DIR = "<replaceable>path</replaceable>"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>

4069

<info>

4070

ERROR_QA[doc] = "Specifies the quality assurance checks whose failures are reported as errors by the OpenEmbedded build system."

</info>

Specifies the quality assurance checks whose failures are

4075

reported as errors by the OpenEmbedded build system.

4076

You set this variable in your distribution configuration

4077

file.

4078

For a list of the checks you can control with this variable,

4079

see the

4080

"<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"

section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXCLUDE_FROM_SHLIBS'><glossterm>EXCLUDE_FROM_SHLIBS</glossterm>

4087

<info>

4088

EXCLUDE_FROM_SHLIBS[doc] = "Causes the OpenEmbedded build system's shared libraries resolver to exclude an entire package when scanning for shared libraries."

</info>

Triggers the OpenEmbedded build system's shared libraries

4093

resolver to exclude an entire package when scanning for

4094

shared libraries.

4095

<note>

4096

The shared libraries resolver's functionality results

4097

in part from the internal function

4098

<filename>package_do_shlibs</filename>, which is part of

the

task.

You should be aware that the shared libraries resolver

4103

might implicitly define some dependencies between

4104

packages.

4105

</note>

4106

The <filename>EXCLUDE_FROM_SHLIBS</filename> variable is

4107

similar to the

4108

4109

variable, which excludes a package's particular libraries

4110

only and not the whole package.

</para>

<para>

Use the

<filename>EXCLUDE_FROM_SHLIBS</filename> variable by

4116

setting it to "1" for a particular package:

4117

4118

EXCLUDE_FROM_SHLIBS = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>

4125

<info>

4126

EXCLUDE_FROM_WORLD[doc] = "Directs BitBake to exclude a recipe from world builds (i.e. bitbake world)."

</info>

Directs BitBake to exclude a recipe from world builds (i.e.

4131

<filename>bitbake world</filename>).

4132

During world builds, BitBake locates, parses and builds all

4133

recipes found in every layer exposed in the

4134

<filename>bblayers.conf</filename> configuration file.

</para>

<para>

To exclude a recipe from a world build using this variable,

4139

set the variable to "1" in the recipe.

</para>

<note>

Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>

4144

may still be built during a world build in order to satisfy

4145

dependencies of other recipes.

4146

Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>

4147

only ensures that the recipe is not explicitly added

4148

to the list of build targets in a world build.

</note>

</glossdef>

</glossentry>

<glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>

4154

<info>

4155

EXTENDPE[doc] = "Used with file and pathnames to create a prefix for a recipe's version based on the recipe's PE value. If PE is set and greater than zero for a recipe, EXTENDPE becomes that value."

</info>

Used with file and pathnames to create a prefix for a recipe's

4160

version based on the recipe's

4161

4162

If <filename>PE</filename> is set and greater than zero for a recipe,

4163

<filename>EXTENDPE</filename> becomes that value (e.g if

4164

<filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>

4165

becomes "1_").

4166

If a recipe's <filename>PE</filename> is not set (the default) or is equal to

4167

zero, <filename>EXTENDPE</filename> becomes "".</para>

4168

<para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>

4169

variable for an example.

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>

4175

<info>

4176

EXTENDPKGV[doc] = "The full package version specification as it appears on the final packages produced by a recipe."

</info>

The full package version specification as it appears on the

4181

final packages produced by a recipe.

4182

The variable's value is normally used to fix a runtime

4183

dependency to the exact same version of another package

4184

in the same recipe:

4185

4186

RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"

</literallayout>

</para>

<para>

The dependency relationships are intended to force the

4192

package manager to upgrade these types of packages in

lock-step.

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTERNAL_KERNEL_TOOLS'><glossterm>EXTERNAL_KERNEL_TOOLS</glossterm>

4199

<info>

4200

EXTERNAL_KERNEL_TOOLS[doc] = "Indicates kernel tools are external to the source tree."

</info>

When set, the <filename>EXTERNAL_KERNEL_TOOLS</filename>

4205

variable indicates that these tools are not in the

source tree.

</para>

<para>

When kernel tools are available in the tree, they are

4211

preferred over any externally installed tools.

4212

Setting the <filename>EXTERNAL_KERNEL_TOOLS</filename>

4213

variable tells the OpenEmbedded build system to prefer

4214

the installed external tools.

4215

See the

4216

4217

class in <filename>meta/classes</filename> to see how

4218

the variable is used.

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>

4224

<info>

4225

EXTERNALSRC[doc] = "If externalsrc.bbclass is inherited, this variable points to the source tree, which is outside of the OpenEmbedded build system."

</info>

When inheriting the

class, this variable points to the source tree, which is

4232

outside of the OpenEmbedded build system.

4233

When set, this variable sets the

4234

4235

variable, which is what the OpenEmbedded build system uses

4236

to locate unpacked recipe source code.

</para>

<para>

For more information on

4241

<filename>externalsrc.bbclass</filename>, see the

4242

"<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"

4243

section.

4244

You can also find information on how to use this variable

4245

in the

4246

"<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"

4247

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>

4253

<info>

4254

EXTERNALSRC_BUILD[doc] = "If externalsrc.bbclass is inherited, this variable points to the directory in which the recipe's source code is built, which is outside of the OpenEmbedded build system."

</info>

When inheriting the

class, this variable points to the directory in which the

4261

recipe's source code is built, which is outside of the

4262

OpenEmbedded build system.

4263

When set, this variable sets the

4264

4265

variable, which is what the OpenEmbedded build system uses

4266

to locate the Build Directory.

</para>

<para>

For more information on

4271

<filename>externalsrc.bbclass</filename>, see the

4272

"<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"

4273

section.

4274

You can also find information on how to use this variable

4275

in the

4276

"<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"

4277

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTRA_AUTORECONF'><glossterm>EXTRA_AUTORECONF</glossterm>

4283

<info>

4284

EXTRA_AUTORECONF[doc] = "Extra options passed to the autoreconf command, which is executed during do_configure."

</info>

For recipes inheriting the

4289

4290

class, you can use <filename>EXTRA_AUTORECONF</filename> to

4291

specify extra options to pass to the

4292

<filename>autoreconf</filename> command that is

executed during the

task.

</para>

<para>

The default value is "--exclude=autopoint".

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>

4305

<info>

4306

EXTRA_IMAGE_FEATURES[doc] = "The list of additional features to include in an image. Configure this variable in the conf/local.conf file in the Build Directory."

</info>

A list of additional features to include in an image.

4311

When listing more than one feature, separate them with

a space.

</para>

<para>

Typically, you configure this variable in your

4317

<filename>local.conf</filename> file, which is found in the

4318

4319

Although you can use this variable from within a recipe,

4320

best practices dictate that you do not.

4321

<note>

4322

To enable primary features from within the image

recipe, use the

variable.

</note>

</para>

<para>

Here are some examples of features you can add:

4331

4332

"dbg-pkgs" - Adds -dbg packages for all installed packages

4333

including symbol information for debugging and

4334

profiling.

4335

4336

"debug-tweaks" - Makes an image suitable for debugging.

4337

For example, allows root logins without

4338

passwords and enables post-installation

4339

logging. See the 'allow-empty-password'

4340

and 'post-install-logging' features in

4341

the "<link linkend='ref-features-image'>Image Features</link>" section for

4342

more information.

4343

4344

"dev-pkgs" - Adds -dev packages for all installed packages.

4345

This is useful if you want to develop against

4346

the libraries in the image.

4347

4348

"read-only-rootfs" - Creates an image whose root

4349

filesystem is read-only. See the

4350

"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"

4351

section in the Yocto Project

4352

Development Tasks Manual for

4353

more information

4354

4355

"tools-debug" - Adds debugging tools such as gdb and

4356

strace.

4357

4358

"tools-sdk" - Adds development tools such as gcc, make,

4359

pkgconfig and so forth.

4360

4361

"tools-testapps" - Adds useful testing tools such as

4362

ts_print, aplay, arecord and so

forth.

</literallayout>

</para>

<para>

For a complete list of image features that ships with the

4370

Yocto Project, see the

4371

"<link linkend="ref-features-image">Image Features</link>"

section.

</para>

<para>

For an example that shows how to customize your image by

4377

using this variable, see the

4378

"<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"

4379

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm>

4385

<info>

4386

EXTRA_IMAGECMD[doc] = "Specifies additional options for the image creation command that has been specified in IMAGE_CMD. When setting this variable, you should use an override for the associated image type."

</info>

Specifies additional options for the image

4391

creation command that has been specified in

4392

4393

When setting this variable, use an override for the

4394

associated image type.

4395

Here is an example:

4396

4397

EXTRA_IMAGECMD_ext3 ?= "-i 4096"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>

4404

<info>

4405

EXTRA_IMAGEDEPENDS[doc] = "A list of recipes to build that do not provide packages for installing into the root filesystem. Use this variable to list recipes that are required to build the final image, but not needed in the root filesystem."

</info>

A list of recipes to build that do not provide packages

4410

for installing into the root filesystem.

</para>

<para>

Sometimes a recipe is required to build the final image but is not

4415

needed in the root filesystem.

4416

You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to

4417

list these recipes and thus specify the dependencies.

4418

A typical example is a required bootloader in a machine configuration.

</para>

<note>

To add packages to the root filesystem, see the various

4423

<filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>

4424

and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>

variables.

</note>

</glossdef>

</glossentry>

<glossentry id='var-EXTRANATIVEPATH'><glossterm>EXTRANATIVEPATH</glossterm>

4431

<info>

4432

EXTRANATIVEPATH[doc] = "A list of subdirectories of ${STAGING_BINDIR_NATIVE} added to the beginning of the environment variable PATH."

</info>

A list of subdirectories of

4437

<filename>${</filename><link linkend='var-STAGING_BINDIR_NATIVE'><filename>STAGING_BINDIR_NATIVE</filename></link><filename>}</filename>

4438

added to the beginning of the environment variable

4439

<filename>PATH</filename>.

4440

As an example, the following prepends

4441

"${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:"

4442

to <filename>PATH</filename>:

4443

4444

EXTRANATIVEPATH = "foo bar"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>

4451

<info>

4452

EXTRA_OECMAKE[doc] = "Additional cmake options."

</info>

Additional

<ulink url='https://cmake.org/overview/'>CMake</ulink>

options.

See the

class for additional information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>

4467

<info>

4468

EXTRA_OECONF[doc] = "Additional configure script options."

</info>

Additional <filename>configure</filename> script options.

4473

See

4474

4475

for additional information on passing configure script

options.

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>

4482

<info>

4483

EXTRA_OEMAKE[doc] = "Additional GNU make options."

</info>

Additional GNU <filename>make</filename> options.

</para>

<para>

Because the <filename>EXTRA_OEMAKE</filename> defaults to

4492

"", you need to set the variable to specify any required

GNU options.

</para>

<para>

and

also make use of

<filename>EXTRA_OEMAKE</filename> to pass the required

flags.

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>

4508

<info>

4509

EXTRA_OESCONS[doc] = "When a recipe inherits the scons class, this variable specifies additional configuration options you want to pass to the scons command line."

</info>

When inheriting the

class, this variable specifies additional configuration

4516

options you want to pass to the

4517

<filename>scons</filename> command line.

</para>

</glossdef>

</glossentry>

<glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>

4523

<info>

4524

EXTRA_USERS_PARAMS[doc] = "When a recipe inherits the extrausers class, this variable provides image level user and group operations."

</info>

When inheriting the

class, this variable provides image level user and group

4531

operations.

4532

This is a more global method of providing user and group

4533

configuration as compared to using the

4534

4535

class, which ties user and group configurations to a

specific recipe.

</para>

<para>

The set list of commands you can configure using the

4541

<filename>EXTRA_USERS_PARAMS</filename> is shown in the

4542

<filename>extrausers</filename> class.

4543

These commands map to the normal Unix commands of the same

4544

names:

4545

4546

# EXTRA_USERS_PARAMS = "\

4547

# useradd -p '' tester; \

4548

# groupadd developers; \

4549

# userdel nobody; \

4550

# groupdel -g video; \

4551

# groupmod -g 1020 developers; \

4552

# usermod -s /bin/sh tester; \

# "

</literallayout>

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>

4564

<info>

4565

FEATURE_PACKAGES[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES. When setting the value, FEATURE_PACKAGES should have the name of the feature item as an override."

</info>

Defines one or more packages to include in an image when

4570

a specific item is included in

4571

4572

When setting the value, <filename>FEATURE_PACKAGES</filename>

4573

should have the name of the feature item as an override.

4574

Here is an example:

4575

4576

FEATURE_PACKAGES_widget = "<replaceable>package1</replaceable> <replaceable>package2</replaceable>"

</literallayout>

</para>

<para>

In this example, if "widget" were added to

4582

<filename>IMAGE_FEATURES</filename>, <replaceable>package1</replaceable> and

4583

<replaceable>package2</replaceable> would be included in the image.

4584

<note>

4585

Packages installed by features defined through

4586

<filename>FEATURE_PACKAGES</filename> are often package

4587

groups.

4588

While similarly named, you should not confuse the

4589

<filename>FEATURE_PACKAGES</filename> variable with

4590

package groups, which are discussed elsewhere in the

documentation.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>

4598

<info>

4599

FEED_DEPLOYDIR_BASE_URI[doc] = "Allow to serve ipk deploy directory as an ad hoc feed (bogofeed). Set to base URL of the directory as exported by HTTP. Set of ad hoc feed configs will be generated in the image."

</info>

Points to the base URL of the server and location within

4604

the document-root that provides the metadata and

4605

packages required by OPKG to support runtime package

4606

management of IPK packages.

4607

You set this variable in your

4608

<filename>local.conf</filename> file.

</para>

<para>

Consider the following example:

4613

4614

FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"

4615

</literallayout>

4616

This example assumes you are serving your packages over

4617

HTTP and your databases are located in a directory

4618

named <filename>BOARD-dir</filename>, which is underneath

4619

your HTTP server's document-root.

4620

In this case, the OpenEmbedded build system generates a set

4621

of configuration files for you in your target that work

with the feed.

</para>

</glossdef>

</glossentry>

<glossentry id='var-FILES'><glossterm>FILES</glossterm>

4628

<info>

4629

FILES[doc] = "The list of directories or files that are placed in a package."

</info>

The list of files and directories that are placed in a

package.

The

variable lists the packages generated by a recipe.

</para>

<para>

To use the <filename>FILES</filename> variable, provide a

4642

package name override that identifies the resulting package.

4643

Then, provide a space-separated list of files or paths

4644

that identify the files you want included as part of the

resulting package.

Here is an example:

FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"

4649

</literallayout>

4650

<note><title>Notes</title>

4651

4652

4653

When specifying files or paths, you can pattern

match using Python's

syntax.

For details on the syntax, see the

4658

documentation by following the previous link.

4659

</para></listitem>

4660

4661

When specifying paths as part of the

4662

<filename>FILES</filename> variable, it is

4663

good practice to use appropriate path

4664

variables.

4665

For example, use <filename>${sysconfdir}</filename>

4666

rather than <filename>/etc</filename>, or

4667

<filename>${bindir}</filename> rather than

4668

<filename>/usr/bin</filename>.

4669

You can find a list of these variables at the

4670

top of the

4671

<filename>meta/conf/bitbake.conf</filename>

4672

file in the

4673

4674

You will also find the default values of the

4675

various <filename>FILES_*</filename> variables

in this file.

</para></listitem>

</itemizedlist>

</note>

</para>

<para>

If some of the files you provide with the

4684

<filename>FILES</filename> variable are editable and you

4685

know they should not be overwritten during the package

4686

update process by the Package Management System (PMS), you

4687

can identify these files so that the PMS will not

overwrite them.

See the

variable for information on how to identify these files to

the PMS.

</para>

</glossdef>

</glossentry>

<glossentry id='var-FILES_SOLIBSDEV'><glossterm>FILES_SOLIBSDEV</glossterm>

4698

<info>

4699

FILES_SOLIBSDEV[doc] = "Defines the full path name of the development symbolic link (symlink) for shared libraries on the target platform."

</info>

Defines the file specification to match

4704

4705

In other words, <filename>FILES_SOLIBSDEV</filename>

4706

defines the full path name of the development symbolic link

4707

(symlink) for shared libraries on the target platform.

</para>

<para>

The following statement from the

4712

<filename>bitbake.conf</filename> shows how it is set:

4713

4714

FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>

4721

<info>

4722

FILESEXTRAPATHS[doc] = "Extends the search path the OpenEmbedded build system uses when looking for files and patches as it processes recipes and append files."

</info>

Extends the search path the OpenEmbedded build system uses

4727

when looking for files and patches as it processes recipes

4728

and append files.

4729

The default directories BitBake uses when it processes

4730

recipes are initially defined by the

4731

4732

variable.

4733

You can extend <filename>FILESPATH</filename> variable

4734

by using <filename>FILESEXTRAPATHS</filename>.

</para>

<para>

Best practices dictate that you accomplish this by using

4739

<filename>FILESEXTRAPATHS</filename> from within a

4740

<filename>.bbappend</filename> file and that you prepend

4741

paths as follows:

4742

4743

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"

4744

</literallayout>

4745

In the above example, the build system first looks for files

4746

in a directory that has the same name as the corresponding

append file.

<note>

<para>When extending

<filename>FILESEXTRAPATHS</filename>,

4751

be sure to use the immediate expansion

4752

(<filename>:=</filename>) operator.

4753

Immediate expansion makes sure that BitBake evaluates

4754

4755

at the time the directive is encountered rather than at

4756

some later time when expansion might result in a

4757

directory that does not contain the files you need.

4758

</para>

4759

4760

<para>Also, include the trailing separating colon

4761

character if you are prepending.

4762

The trailing colon character is necessary because you

4763

are directing BitBake to extend the path by prepending

4764

directories to the search path.</para>

4765

</note>

4766

Here is another common use:

4767

4768

FILESEXTRAPATHS_prepend := "${THISDIR}/files:"

4769

</literallayout>

4770

In this example, the build system extends the

4771

<filename>FILESPATH</filename> variable to include a

4772

directory named <filename>files</filename> that is in the

4773

same directory as the corresponding append file.

</para>

<para>

This next example specifically adds three paths:

4778

4779

FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"

</literallayout>

</para>

<para>

A final example shows how you can extend the search path

4785

and include a

4786

4787

override, which is useful in a BSP layer:

4788

4789

FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:"

4790

</literallayout>

4791

The previous statement appears in the

4792

<filename>linux-yocto-dev.bbappend</filename> file, which

4793

is found in the Yocto Project

4794

<ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>

4795

in

4796

<filename>meta-intel/common/recipes-kernel/linux</filename>.

4797

Here, the machine override is a special

4798

4799

definition for multiple <filename>meta-intel</filename>

4800

machines.

4801

<note>

4802

For a layer that supports a single BSP, the override

4803

could just be the value of <filename>MACHINE</filename>.

</note>

</para>

<para>

By prepending paths in <filename>.bbappend</filename>

4809

files, you allow multiple append files that reside in

4810

different layers but are used for the same recipe to

4811

correctly extend the path.

</para>

</glossdef>

</glossentry>

<glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>

4817

<info>

4818

FILESOVERRIDES[doc] = "A subset of OVERRIDES used by the OpenEmbedded build system for creating FILESPATH."

</info>

A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>

4823

used by the OpenEmbedded build system for creating

4824

4825

The <filename>FILESOVERRIDES</filename> variable uses

4826

overrides to automatically extend the

4827

4828

variable.

4829

For an example of how that works, see the

4830

4831

variable description.

4832

Additionally, you find more information on how overrides

4833

are handled in the

4834

"<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"

4835

section of the BitBake User Manual.

</para>

<para>

By default, the <filename>FILESOVERRIDES</filename>

4840

variable is defined as:

4841

4842

FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"

</literallayout>

<note>

Do not hand-edit the <filename>FILESOVERRIDES</filename>

4847

variable.

4848

The values match up with expected overrides and are

4849

used in an expected manner by the build system.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>

4856

<info>

4857

FILESPATH[doc] = "The default set of directories the OpenEmbedded build system uses when searching for patches and files. It is defined in the base.bbclass class found in meta/classes in the Source Directory. Do not hand-edit the FILESPATH variable."

</info>

The default set of directories the OpenEmbedded build

4862

system uses when searching for patches and files.

</para>

<para>

During the build process, BitBake searches each directory

4867

in <filename>FILESPATH</filename> in the specified order

4868

when looking for files and patches specified by each

4869

<filename>file://</filename> URI in a recipe's

statements.

</para>

<para>

The default value for the <filename>FILESPATH</filename>

4876

variable is defined in the <filename>base.bbclass</filename>

4877

class found in <filename>meta/classes</filename> in the

4878

4879

4880

FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \

4881

"${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"

4882

</literallayout>

4883

The <filename>FILESPATH</filename> variable is automatically

4884

extended using the overrides from the

4885

4886

variable.

4887

<note><title>Notes</title>

Do not hand-edit the

<filename>FILESPATH</filename> variable.

4892

If you want the build system to look in

4893

directories other than the defaults, extend the

4894

<filename>FILESPATH</filename> variable by

using the

variable.

</para></listitem>

Be aware that the default

4901

<filename>FILESPATH</filename> directories do

4902

not map to directories in custom layers

4903

where append files

4904

(<filename>.bbappend</filename>) are used.

4905

If you want the build system to find patches

4906

or files that reside with your append files,

4907

you need to extend the

4908

<filename>FILESPATH</filename> variable by

4909

using the <filename>FILESEXTRAPATHS</filename>

variable.

</para></listitem>

</itemizedlist>

</note>

</para>

<para>

You can take advantage of this searching behavior in

4918

useful ways.

4919

For example, consider a case where the following

4920

directory structure exists for general and machine-specific

configurations:

files/defconfig

files/MACHINEA/defconfig

4925

files/MACHINEB/defconfig

4926

</literallayout>

4927

Also in the example, the <filename>SRC_URI</filename>

4928

statement contains "file://defconfig".

4929

Given this scenario, you can set

4930

4931

to "MACHINEA" and cause the build system to use files

4932

from <filename>files/MACHINEA</filename>.

4933

Set <filename>MACHINE</filename> to "MACHINEB" and the

4934

build system uses files from

4935

<filename>files/MACHINEB</filename>.

4936

Finally, for any machine other than "MACHINEA" and

4937

"MACHINEB", the build system uses files from

4938

<filename>files/defconfig</filename>.

</para>

<para>

You can find out more about the patching process in the

4943

"<ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>Patching</ulink>"

4944

section in the Yocto Project Overview and Concepts Manual

4945

and the

4946

"<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code'>Patching Code</ulink>"

4947

section in the Yocto Project Development Tasks Manual.

See the

task as well.

</para>

</glossdef>

</glossentry>

<glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>

4956

<info>

4957

FILESYSTEM_PERMS_TABLES[doc] = "Allows you to define your own file permissions settings table as part of your configuration for the packaging process."

</info>

Allows you to define your own file permissions settings table as part of

4962

your configuration for the packaging process.

4963

For example, suppose you need a consistent set of custom permissions for

4964

a set of groups and users across an entire work project.

4965

It is best to do this in the packages themselves but this is not always

possible.

</para>

<para>

By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which

4971

is located in the <filename>meta/files</filename> folder in the

4972

4973

If you create your own file permissions setting table, you should place it in your

4974

layer or the distro's layer.

</para>

<para>

You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the

4979

<filename>conf/local.conf</filename> file, which is found in the

4980

4981

point to your custom <filename>fs-perms.txt</filename>.

4982

You can specify more than a single file permissions setting table.

4983

The paths you specify to these files must be defined within the

</para>

<para>

For guidance on how to create your own file permissions settings table file,

4989

examine the existing <filename>fs-perms.txt</filename>.

</para>

</glossdef>

</glossentry>

<info>

FIT_HASH_ALG[doc] = "Specifies the hash algorithm used in creating the FIT Image."

</info>

Specifies the hash algorithm used in creating the FIT Image.

For e.g. sha256.

</para>

</glossdef>

</glossentry>

<info>

FIT_SIGN_ALG[doc] = "Specifies the signature algorithm used in creating the FIT Image."

</info>

Specifies the signature algorithm used in creating the FIT Image.

For e.g. rsa2048.

</para>

</glossdef>

</glossentry>

<glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm>

5019

<info>

5020

FONT_EXTRA_RDEPENDS[doc] = "When a recipe inherits the fontcache class, this variable specifies runtime dependencies for font packages. This variable defaults to 'fontconfig-utils'."

</info>

When inheriting the

class, this variable specifies the runtime dependencies

5027

for font packages.

5028

By default, the <filename>FONT_EXTRA_RDEPENDS</filename>

5029

is set to "fontconfig-utils".

</para>

</glossdef>

</glossentry>

<glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>

5035

<info>

5036

FONT_PACKAGES[doc] = "When a recipe inherits the fontcache class, this variable identifies packages containing font files that need to be cached by Fontconfig."

</info>

When inheriting the

class, this variable identifies packages containing font

5043

files that need to be cached by Fontconfig.

5044

By default, the <filename>fontcache</filename> class assumes

5045

that fonts are in the recipe's main package

5046

(i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).

5047

Use this variable if fonts you need are in a package

5048

other than that main package.

</para>

</glossdef>

</glossentry>

<glossentry id='var-FORCE_RO_REMOVE'><glossterm>FORCE_RO_REMOVE</glossterm>

5054

<info>

5055

FORCE_RO_REMOVE[doc] = "Forces the removal of the packages listed in ROOTFS_RO_UNNEEDED during the generation of the root filesystem."

</info>

Forces the removal of the packages listed in

5060

<filename>ROOTFS_RO_UNNEEDED</filename> during the

5061

generation of the root filesystem.

</para>

<para>

Set the variable to "1" to force the removal of these

packages.

</para>

</glossdef>

</glossentry>

<glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>

5072

<info>

5073

FULL_OPTIMIZATION[doc]= "The options to pass in TARGET_CFLAGS and CFLAGS when compiling an optimized system. This variable defaults to '-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2'."

</info>

The options to pass in

5078

<filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>

5079

and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>

5080

when compiling an optimized system.

5081

This variable defaults to

5082

"-O2 -pipe ${DEBUG_FLAGS}".

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-GCCPIE'><glossterm>GCCPIE</glossterm>

5091

<info>

5092

GCCPIE[doc] = "Enables Position Independent Executables (PIE) within the GNU C Compiler (GCC)."

</info>

Enables Position Independent Executables (PIE) within the

5097

GNU C Compiler (GCC).

5098

Enabling PIE in the GCC makes Return Oriented Programming

5099

(ROP) attacks much more difficult to

execute.

</para>

<para>

By default the <filename>security_flags.inc</filename>

5105

file enables PIE by setting the variable as follows:

5106

5107

GCCPIE ?= "--enable-default-pie"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-GCCVERSION'><glossterm>GCCVERSION</glossterm>

5114

<info>

5115

GCCVERSION[doc] = "Specifies the default version of the GNU C Compiler (GCC) to use."

</info>

Specifies the default version of the GNU C Compiler (GCC)

5120

used for compilation.

5121

By default, <filename>GCCVERSION</filename> is set to

5122

"8.x" in the

5123

<filename>meta/conf/distro/include/tcmode-default.inc</filename>

include file:

GCCVERSION ?= "8.%"

</literallayout>

You can override this value by setting it in a configuration

5129

file such as the <filename>local.conf</filename>.

</para>

</glossdef>

</glossentry>

<info>

GDB[doc] = "The minimal command and arguments to run the GNU Debugger."

</info>

The minimal command and arguments to run the GNU Debugger.

</para>

</glossdef>

</glossentry>

<glossentry id='var-GITDIR'><glossterm>GITDIR</glossterm>

5146

<info>

5147

GITDIR[doc] = "The directory where Git clones will be stored."

</info>

The directory in which a local copy of a Git repository

5152

is stored when it is cloned.

</para>

</glossdef>

</glossentry>

<glossentry id='var-GLIBC_GENERATE_LOCALES'><glossterm>GLIBC_GENERATE_LOCALES</glossterm>

5158

<info>

5159

GLIBC_GENERATE_LOCALES[doc]= "Specifies the list of GLIBC locales to generate should you not wish to generate all LIBC locals, which can be time consuming."

</info>

Specifies the list of GLIBC locales to generate should you

5164

not wish to generate all LIBC locals, which can be time

5165

consuming.

5166

<note>

5167

If you specifically remove the locale

5168

<filename>en_US.UTF-8</filename>, you must set

appropriately.

</note>

</para>

<para>

You can set <filename>GLIBC_GENERATE_LOCALES</filename>

5176

in your <filename>local.conf</filename> file.

5177

By default, all locales are generated.

5178

5179

GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>

5186

<info>

5187

GROUPADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the groupadd command if you wish to add a group to the system when the package is installed."

</info>

When inheriting the

class, this variable

specifies for a package what parameters should be passed

5195

to the <filename>groupadd</filename> command

5196

if you wish to add a group to the system when the package

is installed.

</para>

<para>

Here is an example from the <filename>dbus</filename>

5202

recipe:

5203

5204

GROUPADD_PARAM_${PN} = "-r netdev"

5205

</literallayout>

5206

For information on the standard Linux shell command

5207

<filename>groupadd</filename>, see

5208

<ulink url='http://linux.die.net/man/8/groupadd'></ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>

5214

<info>

5215

GROUPMEMS_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the groupmems command if you wish to modify the members of a group when the package is installed."

</info>

When inheriting the

class, this variable

specifies for a package what parameters should be passed

5223

to the <filename>groupmems</filename> command

5224

if you wish to modify the members of a group when the

5225

package is installed.

</para>

<para>

For information on the standard Linux shell command

5230

<filename>groupmems</filename>, see

5231

<ulink url='http://linux.die.net/man/8/groupmems'></ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>

5237

<info>

5238

GRUB_GFXSERIAL[doc] = "Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu."

</info>

Configures the GNU GRand Unified Bootloader (GRUB) to have

5243

graphics and serial in the boot menu.

5244

Set this variable to "1" in your

5245

<filename>local.conf</filename> or distribution

5246

configuration file to enable graphics and serial

in the menu.

</para>

<para>

See the

class for more information on how this variable is used.

</para>

</glossdef>

</glossentry>

<info>

GRUB_OPTS[doc] = "Additional options to add to the GNU GRand Unified Bootloader (GRUB) configuration."

</info>

Additional options to add to the GNU GRand Unified

5265

Bootloader (GRUB) configuration.

5266

Use a semi-colon character (<filename>;</filename>) to

5267

separate multiple options.

</para>

<para>

The <filename>GRUB_OPTS</filename> variable is optional.

5272

See the

5273

5274

class for more information on how this variable is used.

</para>

</glossdef>

</glossentry>

<glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>

5280

<info>

5281

GRUB_TIMEOUT[doc] = "Specifies the timeout before executing the default LABEL in the GNU GRand Unified Bootloader (GRUB)."

</info>

Specifies the timeout before executing the default

5286

<filename>LABEL</filename> in the GNU GRand Unified

Bootloader (GRUB).

</para>

<para>

The <filename>GRUB_TIMEOUT</filename> variable is optional.

5292

See the

5293

5294

class for more information on how this variable is used.

</para>

</glossdef>

</glossentry>

<glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>

5300

<info>

5301

GTKIMMODULES_PACKAGES[doc] = "For recipes that inherit the gtk-immodules-cache class, this variable specifies the packages that contain the GTK+ input method modules being installed when the modules are in packages other than the main package."

</info>

When inheriting the

class, this variable specifies the packages that contain the

5308

GTK+ input method modules being installed when the modules

5309

are in packages other than the main package.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>

5319

<info>

5320

HOMEPAGE[doc] = "Website where more information about the software the recipe is building can be found."

</info>

Website where more information about the software the recipe is building

can be found.

</para>

</glossdef>

</glossentry>

<info>

HOST_ARCH[doc] = "The name of the target architecture. Normally same as the TARGET_ARCH."

</info>

The name of the target architecture, which is normally

5338

the same as

5339

5340

The OpenEmbedded build system supports many

5341

architectures.

5342

Here is an example list of architectures supported.

5343

This list is by no means complete as the architecture

is configurable:

arm

i586

x86_64

powerpc

powerpc64

mips

mipsel

</literallayout>

</para>

</glossdef>

</glossentry>

<info>

HOST_CC_ARCH[doc] = "The name of the host architecture. Normally same as the TARGET_CC_ARCH."

</info>

Specifies architecture-specific compiler flags that are

5365

passed to the C compiler.

</para>

<para>

Default initialization for <filename>HOST_CC_ARCH</filename>

5370

varies depending on what is being built:

when building for the target

5375

</para></listitem>

5376

5377

<filename>BUILD_CC_ARCH</filename>

5378

when building for the build host (i.e.

5379

<filename>-native</filename>)

5380

</para></listitem>

5381

5382

<filename>BUILDSDK_CC_ARCH</filename>

5383

when building for an SDK (i.e.

5384

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<info>

HOST_OS[doc] = "The name of the target operating system. Normally the same as the TARGET_OS."

</info>

Specifies the name of the target operating system, which

5398

is normally the same as the

5399

5400

The variable can be set to "linux" for <filename>glibc</filename>-based systems and

5401

to "linux-musl" for <filename>musl</filename>.

5402

For ARM/EABI targets, there are also "linux-gnueabi" and

5403

"linux-musleabi" values possible.

</para>

</glossdef>

</glossentry>

<glossentry id='var-HOST_PREFIX'><glossterm>HOST_PREFIX</glossterm>

5409

<info>

5410

HOST_PREFIX[doc] = "The prefix for the cross compile toolchain. Normally same as the TARGET_PREFIX."

</info>

Specifies the prefix for the cross-compile toolchain.

5415

<filename>HOST_PREFIX</filename> is normally the same as

</para>

</glossdef>

</glossentry>

<info>

HOST_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the build is occurring in the context of the current recipe."

</info>

Specifies the system, including the architecture and the

5428

operating system, for which the build is occurring

5429

in the context of the current recipe.

</para>

<para>

The OpenEmbedded build system automatically sets this

variable based on

and

variables.

<note>

You do not need to set the variable yourself.

</note>

</para>

<para>

Consider these two examples:

5447

5448

<listitem><para>Given a native recipe on a 32-bit

5449

x86 machine running Linux, the value is

5450

"i686-linux".

5451

</para></listitem>

5452

<listitem><para>Given a recipe being built for a

5453

little-endian MIPS target running Linux,

5454

the value might be "mipsel-linux".

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-HOSTTOOLS'><glossterm>HOSTTOOLS</glossterm>

5462

<info>

5463

HOSTTOOLS[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks."

</info>

A space-separated list (filter) of tools on the build host

5468

that should be allowed to be called from within build tasks.

5469

Using this filter helps reduce the possibility of host

5470

contamination.

5471

If a tool specified in the value of

5472

<filename>HOSTTOOLS</filename> is not found on the

5473

build host, the OpenEmbedded build system produces

5474

an error and the build is not started.

</para>

<para>

For additional information, see

</para>

</glossdef>

</glossentry>

<glossentry id='var-HOSTTOOLS_NONFATAL'><glossterm>HOSTTOOLS_NONFATAL</glossterm>

5485

<info>

5486

HOSTTOOLS_NONFATAL[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks."

</info>

A space-separated list (filter) of tools on the build host

5491

that should be allowed to be called from within build tasks.

5492

Using this filter helps reduce the possibility of host

contamination.

Unlike

the OpenEmbedded build system does not produce an error

5497

if a tool specified in the value of

5498

<filename>HOSTTOOLS_NONFATAL</filename> is not found on the

5499

build host.

5500

Thus, you can use <filename>HOSTTOOLS_NONFATAL</filename>

5501

to filter optional host tools.

</para>

</glossdef>

</glossentry>

<glossentry id='var-HOST_VENDOR'><glossterm>HOST_VENDOR</glossterm>

5507

<info>

5508

HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR."

</info>

Specifies the name of the vendor.

5513

<filename>HOST_VENDOR</filename> is normally the same as

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>

5524

<info>

5525

ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function."

</info>

Disables or enables the <filename>icecc</filename>

5530

(Icecream) function.

5531

For more information on this function and best practices

5532

for using this variable, see the

5533

"<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"

section.

</para>

<para>

Setting this variable to "1" in your

5539

<filename>local.conf</filename> disables the function:

5540

5541

ICECC_DISABLED ??= "1"

5542

</literallayout>

5543

To enable the function, set the variable as follows:

ICECC_DISABLED = ""

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>

5552

<info>

5553

ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide."

</info>

Points to the <filename>icecc-create-env</filename> script

5558

that you provide.

5559

This variable is used by the

5560

5561

class.

5562

You set this variable in your

5563

<filename>local.conf</filename> file.

</para>

<para>

If you do not point to a script that you provide, the

5568

OpenEmbedded build system uses the default script provided

5569

by the <filename>icecc-create-env.bb</filename> recipe,

5570

which is a modified version and not the one that comes with

5571

<filename>icecc</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>

5577

<info>

5578

ICECC_PARALLEL_MAKE[doc] = "Extra options passed to the make command during the do_compile task that specify parallel compilation."

</info>

Extra options passed to the <filename>make</filename>

5583

command during the

5584

5585

task that specify parallel compilation.

5586

This variable usually takes the form of

5587

"-j <replaceable>x</replaceable>", where

5588

<replaceable>x</replaceable> represents the maximum

5589

number of parallel threads <filename>make</filename> can

5590

run.

5591

<note>

5592

The options passed affect builds on all enabled

5593

machines on the network, which are machines running the

5594

<filename>iceccd</filename> daemon.

</note>

</para>

<para>

If your enabled machines support multiple cores,

5600

coming up with the maximum number of parallel threads

5601

that gives you the best performance could take some

5602

experimentation since machine speed, network lag,

5603

available memory, and existing machine loads can all

5604

affect build time.

5605

Consequently, unlike the

5606

5607

variable, there is no rule-of-thumb for setting

5608

<filename>ICECC_PARALLEL_MAKE</filename> to achieve

optimal performance.

</para>

<para>

If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,

5614

the build system does not use it (i.e. the system does

5615

not detect and assign the number of cores as is done with

5616

<filename>PARALLEL_MAKE</filename>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>

5622

<info>

5623

ICECC_PATH[doc] = "The location of the icecc binary."

</info>

The location of the <filename>icecc</filename> binary.

5628

You can set this variable in your

5629

<filename>local.conf</filename> file.

5630

If your <filename>local.conf</filename> file does not define

5631

this variable, the

5632

5633

class attempts to define it by locating

5634

<filename>icecc</filename> using <filename>which</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>

5640

<info>

5641

ICECC_USER_CLASS_BL[doc] = "Identifies user classes that you do not want the Icecream distributed compile support to consider."

</info>

Identifies user classes that you do not want the

5646

Icecream distributed compile support to consider.

5647

This variable is used by the

5648

5649

class.

5650

You set this variable in your

5651

<filename>local.conf</filename> file.

</para>

<para>

When you list classes using this variable, you are

5656

"blacklisting" them from distributed compilation across

5657

remote hosts.

5658

Any classes you list will be distributed and compiled

locally.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>

5665

<info>

5666

ICECC_USER_PACKAGE_BL[doc] = "Identifies user recipes that you do not want the Icecream distributed compile support to consider."

</info>

Identifies user recipes that you do not want the

5671

Icecream distributed compile support to consider.

5672

This variable is used by the

5673

5674

class.

5675

You set this variable in your

5676

<filename>local.conf</filename> file.

</para>

<para>

When you list packages using this variable, you are

5681

"blacklisting" them from distributed compilation across

5682

remote hosts.

5683

Any packages you list will be distributed and compiled

locally.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>

5690

<info>

5691

ICECC_USER_PACKAGE_WL[doc] = "Identifies user recipes that use an empty PARALLEL_MAKE variable that you want to force remote distributed compilation on using the Icecream distributed compile support."

</info>

Identifies user recipes that use an empty

5696

5697

variable that you want to force remote distributed

5698

compilation on using the Icecream distributed compile

5699

support.

5700

This variable is used by the

5701

5702

class.

5703

You set this variable in your

5704

<filename>local.conf</filename> file.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>

5710

<info>

5711

IMAGE_BASENAME[doc] = "The base name of image output files."

</info>

The base name of image output files.

5716

This variable defaults to the recipe name

5717

(<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_BOOT_FILES'><glossterm>IMAGE_BOOT_FILES</glossterm>

5723

<info>

5724

IMAGE_BOOT_FILES[doc] = "A space-separated list of files from ${DEPLOY_DIR_IMAGE} to place in boot partition."

</info>

A space-separated list of files installed into the

5729

boot partition when preparing an image using the Wic tool

5730

with the <filename>bootimg-partition</filename> or <filename>bootimg-efi</filename> source

5731

plugin.

5732

By default, the files are installed under the same name as

5733

the source files.

5734

To change the installed name, separate it from the

5735

original name with a semi-colon (;).

5736

Source files need to be located in

5737

5738

Here are two examples:

5739

5740

5741

IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"

5742

IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"

</literallayout>

</para>

<para>

Alternatively, source files can be picked up using

5748

a glob pattern.

5749

In this case, the destination file must have the same name

5750

as the base name of the source file path.

5751

To install files into a directory within the

5752

target location, pass its name after a semi-colon

5753

(;).

5754

Here are two examples:

5755

5756

IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"

5757

IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"

5758

</literallayout>

5759

The first example installs all files from

5760

<filename>${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles</filename>

5761

into the root of the target partition.

5762

The second example installs the same files into a

5763

<filename>boot</filename> directory within the

target partition.

</para>

<para>

You can find information on how to use the Wic tool in the

5769

"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"

5770

section of the Yocto Project Development Tasks Manual.

5771

Reference material for Wic is located in the

5772

"<ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>OpenEmbedded Kickstart (.wks) Reference</ulink>"

chapter.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>

5779

<info>

5780

IMAGE_CLASSES[doc] = "A list of classes that all images should inherit."

</info>

A list of classes that all images should inherit.

5785

You typically use this variable to specify the list of

5786

classes that register the different types of images

5787

the OpenEmbedded build system creates.

</para>

<para>

The default value for <filename>IMAGE_CLASSES</filename> is

5792

<filename>image_types</filename>.

5793

You can set this variable in your

5794

<filename>local.conf</filename> or in a distribution

configuration file.

</para>

<para>

For more information, see

5800

<filename>meta/classes/image_types.bbclass</filename> in the

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_CMD'><glossterm>IMAGE_CMD</glossterm>

5807

<info>

5808

IMAGE_CMD[doc] = "Specifies the command to create the image file for a specific image type, which corresponds to the value set set in IMAGE_FSTYPES, (e.g. ext3, btrfs, and so forth)."

</info>

Specifies the command to create the image file for a

5813

specific image type, which corresponds to the value set

5814

set in

5815

5816

(e.g. <filename>ext3</filename>,

5817

<filename>btrfs</filename>, and so forth).

5818

When setting this variable, you should use

5819

an override for the associated type.

5820

Here is an example:

5821

5822

IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \

5823

--faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \

${EXTRA_IMAGECMD}"

</literallayout>

</para>

<para>

You typically do not need to set this variable unless

5830

you are adding support for a new image type.

5831

For more examples on how to set this variable, see the

5832

5833

class file, which is

5834

<filename>meta/classes/image_types.bbclass</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>IMAGE_DEVICE_TABLES</glossterm>

5840

<info>

5841

IMAGE_DEVICE_TABLES[doc] = "Specifies one or more files that contain custom device tables that are passed to the makedevs command as part of creating an image."

</info>

Specifies one or more files that contain custom device

5846

tables that are passed to the

5847

<filename>makedevs</filename> command as part of creating

5848

an image.

5849

These files list basic device nodes that should be

5850

created under <filename>/dev</filename> within the image.

5851

If <filename>IMAGE_DEVICE_TABLES</filename> is not set,

5852

<filename>files/device_table-minimal.txt</filename> is

5853

used, which is located by

5854

5855

For details on how you should write device table files,

5856

see <filename>meta/files/device_table-minimal.txt</filename>

as an example.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>

5863

<info>

5864

IMAGE_FEATURES[doc] = "The primary list of features to include in an image. Configure this variable in an image recipe."

</info>

The primary list of features to include in an image.

5869

Typically, you configure this variable in an image recipe.

5870

Although you can use this variable from your

5871

<filename>local.conf</filename> file, which is found in the

5872

5873

best practices dictate that you do not.

5874

<note>

5875

To enable extra features from outside the image recipe,

5876

use the

5877

<filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.

</note>

</para>

<para>

For a list of image features that ships with the Yocto

5883

Project, see the

5884

"<link linkend="ref-features-image">Image Features</link>"

section.

</para>

<para>

For an example that shows how to customize your image by

5890

using this variable, see the

5891

"<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"

5892

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>

5898

<info>

5899

IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created."

</info>

Specifies the formats the OpenEmbedded build system uses

5904

during the build when creating the root filesystem.

5905

For example, setting <filename>IMAGE_FSTYPES</filename>

5906

as follows causes the build system to create root

5907

filesystems using two formats: <filename>.ext3</filename>

5908

and <filename>.tar.bz2</filename>:

5909

5910

IMAGE_FSTYPES = "ext3 tar.bz2"

</literallayout>

</para>

<para>

For the complete list of supported image formats from which

you can choose, see

</para>

<note><title>Notes</title>

5921

5922

5923

If an image recipe uses the "inherit image" line

5924

and you are setting

5925

<filename>IMAGE_FSTYPES</filename> inside the

5926

recipe, you must set

5927

<filename>IMAGE_FSTYPES</filename> prior to

5928

using the "inherit image" line.

5929

</para></listitem>

5930

5931

Due to the way the OpenEmbedded build system

5932

processes this variable, you cannot update its

5933

contents by using <filename>_append</filename> or

5934

<filename>_prepend</filename>.

5935

You must use the <filename>+=</filename>

5936

operator to add one or more options to the

5937

<filename>IMAGE_FSTYPES</filename> variable.

</para></listitem>

</itemizedlist>

</note>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>

5945

<info>

5946

IMAGE_INSTALL[doc] = "Used by recipes to specify the packages to install into an image through image.bbclass."

</info>

Used by recipes to specify the packages to install into an

image through the

class.

Use the <filename>IMAGE_INSTALL</filename> variable with

5955

care to avoid ordering issues.

</para>

<para>

Image recipes set <filename>IMAGE_INSTALL</filename>

5960

to specify the packages to install into an image through

5961

<filename>image.bbclass</filename>.

5962

Additionally, "helper" classes such as the

5963

5964

class exist that can take lists used with

5965

<filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>

5966

and turn them into auto-generated entries in

5967

<filename>IMAGE_INSTALL</filename> in addition to its

default contents.

</para>

<para>

When you use this variable, it is best to use it as follows:

5973

5974

IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"

5975

</literallayout>

5976

Be sure to include the space between the quotation character

5977

and the start of the package name or names.

5978

<note><title>Caution</title>

When working with a

image, do not use the

5984

<filename>IMAGE_INSTALL</filename> variable to

5985

specify packages for installation.

5986

Instead, use the

5987

5988

variable, which allows the initial RAM

5989

filesystem (initramfs) recipe to use a fixed

5990

set of packages and not be affected by

5991

<filename>IMAGE_INSTALL</filename>.

5992

For information on creating an initramfs, see

5993

the

5994

"<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"

5995

section in the Yocto Project Development Tasks

Manual.

</para></listitem>

Using <filename>IMAGE_INSTALL</filename> with

6000

the

6001

6002

BitBake operator within the

6003

<filename>/conf/local.conf</filename> file or

6004

from within an image recipe is not recommended.

6005

Use of this operator in these ways can cause

6006

ordering issues.

6007

Since <filename>core-image.bbclass</filename>

6008

sets <filename>IMAGE_INSTALL</filename> to a

6009

default value using the

6010

6011

operator, using a <filename>+=</filename>

6012

operation against

6013

<filename>IMAGE_INSTALL</filename> results in

6014

unexpected behavior when used within

6015

<filename>conf/local.conf</filename>.

6016

Furthermore, the same operation from within

6017

an image recipe may or may not succeed

6018

depending on the specific situation.

6019

In both these cases, the behavior is contrary

6020

to how most users expect the

6021

<filename>+=</filename> operator to work.

</para></listitem>

</itemizedlist>

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>

6030

<info>

6031

IMAGE_LINGUAS[doc] = "Specifies the list of locales to install into the image during the root filesystem construction process."

</info>

Specifies the list of locales to install into the image

6036

during the root filesystem construction process.

6037

The OpenEmbedded build system automatically splits locale

6038

files, which are used for localization, into separate

6039

packages.

6040

Setting the <filename>IMAGE_LINGUAS</filename> variable

6041

ensures that any locale packages that correspond to packages

6042

already selected for installation into the image are also

installed.

Here is an example:

IMAGE_LINGUAS = "pt-br de-de"

</literallayout>

</para>

<para>

In this example, the build system ensures any Brazilian

6052

Portuguese and German locale files that correspond to

6053

packages in the image are installed (i.e.

6054

<filename>*-locale-pt-br</filename>

6055

and <filename>*-locale-de-de</filename> as well as

6056

<filename>*-locale-pt</filename>

6057

and <filename>*-locale-de</filename>, since some software

6058

packages only provide locale files by language and not by

6059

country-specific language).

</para>

<para>

See the

variable for information on generating GLIBC locales.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>

6071

<info>

6072

IMAGE_MANIFEST[doc] = "The manifest file for the image. This file lists all the installed packages that make up the image."

</info>

The manifest file for the image.

6077

This file lists all the installed packages that make up

6078

the image.

6079

The file contains package information on a line-per-package

6080

basis as follows:

6081

6082

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

6090

6091

IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"

6092

</literallayout>

6093

The location is derived using the

and

variables.

You can find information on how the image

6099

is created in the

6100

"<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"

6101

section in the Yocto Project Overview and Concepts Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>

6107

<info>

6108

IMAGE_NAME[doc] = "The name of the output image files minus the extension."

</info>

The name of the output image files minus the extension.

6113

This variable is derived using the

and

variables:

IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>

6127

<info>

6128

IMAGE_OVERHEAD_FACTOR[doc] = "Defines a multiplier that the build system applies to the initial image size for cases when the multiplier times the returned disk usage value for the image is greater than the sum of IMAGE_ROOTFS_SIZE and IMAGE_ROOTFS_EXTRA_SPACE."

</info>

Defines a multiplier that the build system applies to the initial image

6133

size for cases when the multiplier times the returned disk usage value

6134

for the image is greater than the sum of

6135

<filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>

6136

and

6137

<filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.

6138

The result of the multiplier applied to the initial image size creates

6139

free disk space in the image as overhead.

6140

By default, the build process uses a multiplier of 1.3 for this variable.

6141

This default value results in 30% free disk space added to the image when this

6142

method is used to determine the final generated image size.

6143

You should be aware that post install scripts and the package management

6144

system uses disk space inside this overhead area.

6145

Consequently, the multiplier does not produce an image with

6146

all the theoretical free disk space.

6147

See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>

6148

for information on how the build system determines the overall image size.

</para>

<para>

The default 30% free disk space typically gives the image enough room to boot

6153

and allows for basic post installs while still leaving a small amount of

6154

free disk space.

6155

If 30% free space is inadequate, you can increase the default value.

6156

For example, the following setting gives you 50% free space added to the image:

6157

6158

IMAGE_OVERHEAD_FACTOR = "1.5"

</literallayout>

</para>

<para>

Alternatively, you can ensure a specific amount of free disk space is added

6164

to the image by using the

6165

<filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>

6172

<info>

6173

IMAGE_PKGTYPE[doc] = "Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system."

</info>

Defines the package type (i.e. DEB, RPM, IPK, or TAR) used

6178

by the OpenEmbedded build system.

6179

The variable is defined appropriately by the

or

class.

<note><title>Warning</title>

6187

The <filename>package_tar</filename> class is broken

6188

and is not supported.

6189

It is recommended that you do not use it.

</note>

</para>

<para>

The

and

classes use the <filename>IMAGE_PKGTYPE</filename> for

6199

packaging up images and SDKs.

</para>

<para>

You should not set the <filename>IMAGE_PKGTYPE</filename>

6204

manually.

6205

Rather, the variable is set indirectly through the

appropriate

class using the

variable.

The OpenEmbedded build system uses the first package type

6212

(e.g. DEB, RPM, or IPK) that appears with the variable

6213

<note>

6214

Files using the <filename>.tar</filename> format are

6215

never used as a substitute packaging format for DEB,

6216

RPM, and IPK formatted files for your image or SDK.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>

6223

<info>

6224

IMAGE_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the final image output files."

</info>

Specifies a list of functions to call once the

6229

OpenEmbedded build system creates the final image

6230

output files.

6231

You can specify functions separated by semicolons:

6232

6233

IMAGE_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

6239

within the function, you can use

6240

<filename>${IMAGE_ROOTFS}</filename>, which points to

6241

the directory that becomes the root filesystem image.

6242

See the

6243

6244

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_PREPROCESS_COMMAND'><glossterm>IMAGE_PREPROCESS_COMMAND</glossterm>

6250

<info>

6251

IMAGE_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system creates the final image output files."

</info>

Specifies a list of functions to call before the

6256

OpenEmbedded build system creates the final image

6257

output files.

6258

You can specify functions separated by semicolons:

6259

6260

IMAGE_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

6266

within the function, you can use

6267

<filename>${IMAGE_ROOTFS}</filename>, which points to

6268

the directory that becomes the root filesystem image.

6269

See the

6270

6271

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>

6277

<info>

6278

IMAGE_ROOTFS[doc] = "The location of the root filesystem while it is under construction (i.e. during do_rootfs)."

</info>

The location of the root filesystem while it is under

6283

construction (i.e. during the

6284

6285

task).

6286

This variable is not configurable.

Do not change it.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm>

6293

<info>

6294

IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes."

</info>

Specifies the alignment for the output image file in

6299

Kbytes.

6300

If the size of the image is not a multiple of

6301

this value, then the size is rounded up to the nearest

6302

multiple of the value.

6303

The default value is "1".

6304

See

6305

6306

for additional information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>

6312

<info>

6313

IMAGE_ROOTFS_EXTRA_SPACE[doc] = "Defines additional free disk space created in the image in Kbytes. By default, this variable is set to '0'."

</info>

Defines additional free disk space created in the image in Kbytes.

6318

By default, this variable is set to "0".

6319

This free disk space is added to the image after the build system determines

6320

the image size as described in

6321

<filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.

</para>

<para>

This variable is particularly useful when you want to ensure that a

6326

specific amount of free disk space is available on a device after an image

6327

is installed and running.

6328

For example, to be sure 5 Gbytes of free disk space is available, set the

6329

variable as follows:

6330

6331

IMAGE_ROOTFS_EXTRA_SPACE = "5242880"

</literallayout>

</para>

<para>

For example, the Yocto Project Build Appliance specifically requests 40 Gbytes

6337

of extra space with the line:

6338

6339

IMAGE_ROOTFS_EXTRA_SPACE = "41943040"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>

6346

<info>

6347

IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image."

</info>

Defines the size in Kbytes for the generated image.

6352

The OpenEmbedded build system determines the final size for the generated

6353

image using an algorithm that takes into account the initial disk space used

6354

for the generated image, a requested size for the image, and requested

6355

additional free disk space to be added to the image.

6356

Programatically, the build system determines the final size of the

6357

generated image as follows:

6358

6359

if (image-du * overhead) < rootfs-size:

6360

internal-rootfs-size = rootfs-size + xspace

6361

else:

6362

internal-rootfs-size = (image-du * overhead) + xspace

where:

image-du = Returned value of the du command on

6367

the image.

6368

6369

overhead = IMAGE_OVERHEAD_FACTOR

6370

6371

rootfs-size = IMAGE_ROOTFS_SIZE

6372

6373

internal-rootfs-size = Initial root filesystem

6374

size before any modifications.

6375

6376

xspace = IMAGE_ROOTFS_EXTRA_SPACE

</literallayout>

</para>

<para>

See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>

6382

and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>

6383

variables for related information.

6384

<!-- In the above example, <filename>overhead</filename> is defined by the

6385

<filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>

6386

variable, <filename>xspace</filename> is defined by the

6387

<filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>

6388

variable, and <filename>du</filename> is the results of the disk usage command

6389

on the initially generated image. -->

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>

6395

<info>

6396

IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another."

</info>

Specifies a dependency from one image type on another.

6401

Here is an example from the

class:

IMAGE_TYPEDEP_live = "ext3"

</literallayout>

</para>

<para>

In the previous example, the variable ensures that when

6411

"live" is listed with the

6412

6413

variable, the OpenEmbedded build system produces an

6414

<filename>ext3</filename> image first since one of the

6415

components of the live

6416

image is an <filename>ext3</filename>

6417

formatted partition containing the root

filesystem.

</para>

</glossdef>

</glossentry>

<glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>

6424

<info>

6425

IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default."

</info>

Specifies the complete list of supported image types

by default:

btrfs

container

cpio

cpio.gz

cpio.lz4

cpio.lzma

cpio.xz

cramfs

ext2

ext2.bz2

ext2.gz

ext2.lzma

ext3

ext3.gz

ext4

ext4.gz

f2fs

hddimg

iso

jffs2

jffs2.sum

multiubi

squashfs

squashfs-lz4

squashfs-lzo

squashfs-xz

tar

tar.bz2

tar.gz

tar.lz4

tar.xz

tar.zst

ubi

ubifs

wic

wic.bz2

wic.gz

wic.lzma

</literallayout>

</para>

<para>

For more information about these types of images, see

6475

<filename>meta/classes/image_types*.bbclass</filename>

in the

</para>

</glossdef>

</glossentry>

<info>

INC_PR[doc] = "Helps define the recipe revision for recipes that share a common include file."

</info>

Helps define the recipe revision for recipes that share

6489

a common <filename>include</filename> file.

6490

You can think of this variable as part of the recipe revision

6491

as set from within an include file.

</para>

<para>

Suppose, for example, you have a set of recipes that

6496

are used across several projects.

6497

And, within each of those recipes the revision

6498

(its <link linkend='var-PR'><filename>PR</filename></link>

6499

value) is set accordingly.

6500

In this case, when the revision of those recipes changes,

6501

the burden is on you to find all those recipes and

6502

be sure that they get changed to reflect the updated

6503

version of the recipe.

6504

In this scenario, it can get complicated when recipes

6505

that are used in many places and provide common functionality

6506

are upgraded to a new revision.

</para>

<para>

A more efficient way of dealing with this situation is

6511

to set the <filename>INC_PR</filename> variable inside

6512

the <filename>include</filename> files that the recipes

6513

share and then expand the <filename>INC_PR</filename>

6514

variable within the recipes to help

6515

define the recipe revision.

</para>

<para>

The following provides an example that shows how to use

6520

the <filename>INC_PR</filename> variable

6521

given a common <filename>include</filename> file that

6522

defines the variable.

6523

Once the variable is defined in the

6524

<filename>include</filename> file, you can use the

6525

variable to set the <filename>PR</filename> values in

6526

each recipe.

6527

You will notice that when you set a recipe's

6528

<filename>PR</filename> you can provide more granular

6529

revisioning by appending values to the

6530

<filename>INC_PR</filename> variable:

6531

6532

recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"

6533

recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"

6534

recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"

6535

recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"

6536

</literallayout>

6537

The first line of the example establishes the baseline

6538

revision to be used for all recipes that use the

6539

<filename>include</filename> file.

6540

The remaining lines in the example are from individual

6541

recipes and show how the <filename>PR</filename> value

is set.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>

6548

<info>

6549

INCOMPATIBLE_LICENSE[doc] = "Specifies a space-separated list of license names (as they would appear in LICENSE) that should be excluded from the build."

</info>

Specifies a space-separated list of license names

6554

(as they would appear in

6555

6556

that should be excluded from the build.

6557

Recipes that provide no alternatives to listed incompatible

6558

licenses are not built.

6559

Packages that are individually licensed with the specified

6560

incompatible licenses will be deleted.

</para>

<note>

This functionality is only regularly tested using

6565

the following setting:

6566

6567

INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"

6568

</literallayout>

6569

Although you can use other settings, you might be required

6570

to remove dependencies on or provide alternatives to

6571

components that are required to produce a functional system

image.

</note>

It is possible to define a list of licenses that are allowed

6577

to be used instead of the licenses that are excluded. To do

6578

this, define a

6579

variable <filename>COMPATIBLE_LICENSES</filename> with the

6580

names of the licences that are allowed. Then

6581

define <filename>INCOMPATIBLE_LICENSE</filename> as:

6582

6583

INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}"

6584

</literallayout>

6585

This will result

6586

in <filename>INCOMPATIBLE_LICENSE</filename> containing the

6587

names of all licences

6588

from <link linkend='var-AVAILABLE_LICENSES'><filename>AVAILABLE_LICENSES</filename></link>

6589

except the ones specified

6590

in <filename>COMPATIBLE_LICENSES</filename>, thus only

6591

allowing the latter licences to be used.

</note>

</glossdef>

</glossentry>

<glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>

6597

<info>

6598

INHERIT[doc] = "Causes the named class or classes to be inherited globally."

</info>

Causes the named class or classes to be inherited globally.

6603

Anonymous functions in the class or classes

6604

are not executed for the

6605

base configuration and in each individual recipe.

6606

The OpenEmbedded build system ignores changes to

6607

<filename>INHERIT</filename> in individual recipes.

</para>

<para>

For more information on <filename>INHERIT</filename>, see

6612

the

6613

"<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>"

6614

section in the Bitbake User Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>

6620

<info>

6621

INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable."

</info>

Lists classes that will be inherited at the

6626

distribution level.

6627

It is unlikely that you want to edit this variable.

</para>

<para>

The default value of the variable is set as follows in the

6632

<filename>meta/conf/distro/defaultsetup.conf</filename>

6633

file:

6634

6635

INHERIT_DISTRO ?= "debian devshell sstate license"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>

6642

<info>

6643

INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS."

</info>

Prevents the default dependencies, namely the C compiler

6648

and standard C library (libc), from being added to

6649

6650

This variable is usually used within recipes that do not

6651

require any compilation using the C compiler.

</para>

<para>

Set the variable to "1" to prevent the default dependencies

from being added.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm>

6662

<info>

6663

INHIBIT_PACKAGE_DEBUG_SPLIT[doc] = "If set to "1", prevents the OpenEmbedded build system from splitting out debug information during packaging"

</info>

Prevents the OpenEmbedded build system from splitting

6668

out debug information during packaging.

6669

By default, the build system splits out debugging

6670

information during the

6671

6672

task.

6673

For more information on how debug information is split out,

see the

variable.

</para>

<para>

To prevent the build system from splitting out

6681

debug information during packaging, set the

6682

<filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable

6683

as follows:

6684

6685

INHIBIT_PACKAGE_DEBUG_SPLIT = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>

6692

<info>

6693

INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages."

</info>

If set to "1", causes the build to not strip binaries in

6698

resulting packages and prevents the

6699

<filename>-dbg</filename> package from containing the

source files.

</para>

<para>

By default, the OpenEmbedded build system strips

6705

binaries and puts the debugging symbols into

6706

<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-dbg</filename>.

6707

Consequently, you should not set

6708

<filename>INHIBIT_PACKAGE_STRIP</filename> when you plan

to debug in general.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INHIBIT_SYSROOT_STRIP'><glossterm>INHIBIT_SYSROOT_STRIP</glossterm>

6715

<info>

6716

INHIBIT_SYSROOT_STRIP[doc] = "If set to "1", causes the build to not strip binaries in the resulting sysroot."

</info>

If set to "1", causes the build to not strip binaries in

6721

the resulting sysroot.

</para>

<para>

By default, the OpenEmbedded build system strips

6726

binaries in the resulting sysroot.

6727

When you specifically set the

6728

<filename>INHIBIT_SYSROOT_STRIP</filename> variable to

6729

"1" in your recipe, you inhibit this stripping.

</para>

<para>

If you want to use this variable, include the

6734

6735

class.

6736

This class uses a <filename>sys_strip()</filename>

6737

function to test for the variable and acts accordingly.

6738

<note>

6739

Use of the <filename>INHIBIT_SYSROOT_STRIP</filename>

6740

variable occurs in rare and special circumstances.

6741

For example, suppose you are building bare-metal

6742

firmware by using an external GCC toolchain.

6743

Furthermore, even if the toolchain's binaries are

6744

strippable, other files exist that are needed for the

6745

build that are not strippable.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>

6752

<info>

6753

INITRAMFS_FSTYPES[doc] = "Defines the format for the output image of an initial RAM filesystem (initramfs), which is used during boot."

</info>

Defines the format for the output image of an initial

6758

RAM filesystem (initramfs), which is used during boot.

6759

Supported formats are the same as those supported by the

variable.

</para>

<para>

The default value of this variable, which is set in the

6766

<filename>meta/conf/bitbake.conf</filename> configuration

file in the

is "cpio.gz".

The Linux kernel's initramfs mechanism, as opposed to the

6771

initial RAM filesystem

6772

<ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>

6773

mechanism, expects an optionally compressed cpio

archive.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>

6780

<info>

6781

INITRAMFS_IMAGE[doc] = "Specifies the PROVIDES name of an image recipe that is used to build an initial RAM filesystem (initramfs) image."

</info>

Specifies the

name of an image recipe that is used to build an initial

6788

RAM filesystem (initramfs) image.

6789

In other words, the <filename>INITRAMFS_IMAGE</filename>

6790

variable causes an additional recipe to be built as

6791

a dependency to whatever root filesystem recipe you

6792

might be using (e.g. <filename>core-image-sato</filename>).

6793

The initramfs image recipe you provide should set

to

</para>

<para>

An initramfs image provides a temporary root filesystem

6801

used for early system initialization (e.g. loading of

6802

modules needed to locate and mount the "real" root

6803

filesystem).

6804

<note>

6805

See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename>

6806

recipe in the

6807

6808

for an example initramfs recipe.

6809

To select this sample recipe as the one built

6810

to provide the initramfs image,

6811

set <filename>INITRAMFS_IMAGE</filename> to

6812

"core-image-minimal-initramfs".

</note>

</para>

<para>

You can also find more information by referencing the

6818

<filename>meta-poky/conf/local.conf.sample.extended</filename>

6819

configuration file in the Source Directory,

the

class, and the

class to see how to use the

6825

<filename>INITRAMFS_IMAGE</filename> variable.

</para>

<para>

If <filename>INITRAMFS_IMAGE</filename> is empty, which is

6830

the default, then no initramfs image is built.

</para>

<para>

For more information, you can also see the

6835

6836

variable, which allows the generated image to be bundled

6837

inside the kernel image.

6838

Additionally, for information on creating an initramfs

6839

image, see the

6840

"<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"

6841

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>

6847

<info>

6848

INITRAMFS_IMAGE_BUNDLE[doc] = "Controls whether or not the image recipe specified by INITRAMFS_IMAGE is run through an extra pass (do_bundle_initramfs) during kernel compilation in order to build a single binary that contains both the kernel image and the initial RAM filesystem (initramfs)."

</info>

Controls whether or not the image recipe specified by

6853

6854

is run through an extra pass

6855

(<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)

6856

during kernel compilation in order to build a single binary

6857

that contains both the kernel image and the initial RAM

6858

filesystem (initramfs) image.

6859

This makes use of the

kernel feature.

<note>

Using an extra compilation pass to bundle the initramfs

6864

avoids a circular dependency between the kernel recipe and

6865

the initramfs recipe should the initramfs include kernel

6866

modules.

6867

Should that be the case, the initramfs recipe depends on

6868

the kernel for the kernel modules, and the kernel depends

6869

on the initramfs recipe since the initramfs is bundled

6870

inside the kernel image.

</note>

</para>

<para>

The combined binary is deposited into the

6876

<filename>tmp/deploy</filename> directory, which is part

of the

</para>

<para>

Setting the variable to "1" in a configuration file causes the

6883

OpenEmbedded build system to generate a kernel image with the

6884

initramfs specified in <filename>INITRAMFS_IMAGE</filename>

6885

bundled within:

6886

6887

INITRAMFS_IMAGE_BUNDLE = "1"

</literallayout>

By default, the

class sets this variable to a null string as follows:

6892

6893

INITRAMFS_IMAGE_BUNDLE ?= ""

</literallayout>

<note>

You must set the

<filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in

6898

a configuration file.

6899

You cannot set the variable in a recipe file.

6900

</note>

6901

See the

6902

<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>

6903

file for additional information.

6904

Also, for information on creating an initramfs, see the

6905

"<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"

6906

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITRAMFS_LINK_NAME'><glossterm>INITRAMFS_LINK_NAME</glossterm>

6912

<info>

6913

INITRAMFS_LINK_NAME[doc] = "The link name of the initial RAM filesystem image."

</info>

The link name of the initial RAM filesystem image.

6918

This variable is set in the

6919

<filename>meta/classes/kernel-artifact-names.bbclass</filename>

6920

file as follows:

6921

6922

INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"

6923

</literallayout>

6924

The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>

6925

variable, which is set in the same file, has the following

6926

value:

6927

6928

KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"

</literallayout>

</para>

<para>

See the

variable for additional information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITRAMFS_NAME'><glossterm>INITRAMFS_NAME</glossterm>

6941

<info>

6942

INITRAMFS_NAME[doc] = "The base name of the initial RAM filesystem image."

</info>

The base name of the initial RAM filesystem image.

6947

This variable is set in the

6948

<filename>meta/classes/kernel-artifact-names.bbclass</filename>

6949

file as follows:

6950

6951

INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"

</literallayout>

The value of the

variable, which is set in the same file, has the following

6956

value:

6957

6958

KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITRD'><glossterm>INITRD</glossterm>

6965

<info>

6966

INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)."

</info>

Indicates list of filesystem images to concatenate and use

6971

as an initial RAM disk (<filename>initrd</filename>).

</para>

<para>

The <filename>INITRD</filename> variable is an optional

6976

variable used with the

class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITRD_IMAGE'><glossterm>INITRD_IMAGE</glossterm>

6984

<info>

6985

INITRD_IMAGE[doc] = "When building a "live" bootable image (i.e. when IMAGE_FSTYPES contains "live"), INITRD_IMAGE specifies the image recipe that should be built to provide the initial RAM disk image."

</info>

When building a "live" bootable image (i.e. when

6990

6991

contains "live"), <filename>INITRD_IMAGE</filename>

6992

specifies the image recipe that should be built

6993

to provide the initial RAM disk image.

6994

The default value is "core-image-minimal-initramfs".

</para>

<para>

See the

class for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>

7006

<info>

7007

INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d."

</info>

The filename of the initialization script as installed to

7012

<filename>${sysconfdir}/init.d</filename>.

</para>

<para>

This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.

7017

The variable is mandatory.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>

7023

<info>

7024

INITSCRIPT_PACKAGES[doc] = "A list of the packages that contain initscripts. This variable is used in recipes when using update-rc.d.bbclass. The variable is optional and defaults to the PN variable."

</info>

A list of the packages that contain initscripts.

7029

If multiple packages are specified, you need to append the package name

7030

to the other <filename>INITSCRIPT_*</filename> as an override.

</para>

<para>

This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.

7035

The variable is optional and defaults to the

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>

7042

<info>

7043

INITSCRIPT_PARAMS[doc] = "Specifies the options to pass to update-rc.d. The variable is mandatory and is used in recipes when using update-rc.d.bbclass."

</info>

Specifies the options to pass to <filename>update-rc.d</filename>.

7048

Here is an example:

7049

7050

INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."

</literallayout>

</para>

<para>

In this example, the script has a runlevel of 99,

7056

starts the script in initlevels 2 and 5, and

7057

stops the script in levels 0, 1 and 6.

</para>

<para>

The variable's default value is "defaults", which is

set in the

class.

</para>

<para>

The value in

<filename>INITSCRIPT_PARAMS</filename> is passed through

7070

to the <filename>update-rc.d</filename> command.

7071

For more information on valid parameters, please see the

7072

<filename>update-rc.d</filename> manual page at

7073

<ulink url='http://www.tin.org/bin/man.cgi?section=8&topic=update-rc.d'></ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>

7079

<info>

7080

INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe."

</info>

Specifies the QA checks to skip for a specific package

7085

within a recipe.

7086

For example, to skip the check for symbolic link

7087

<filename>.so</filename> files in the main package of a

7088

recipe, add the following to the recipe.

7089

The package name override must be used, which in this

7090

example is <filename>${PN}</filename>:

7091

7092

INSANE_SKIP_${PN} += "dev-so"

</literallayout>

</para>

<para>

See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"

7098

section for a list of the valid QA checks you can

7099

specify using this variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INSTALL_TIMEZONE_FILE'><glossterm>INSTALL_TIMEZONE_FILE</glossterm>

7105

<info>

7106

INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file."

</info>

By default, the <filename>tzdata</filename> recipe packages

7111

an <filename>/etc/timezone</filename> file.

7112

Set the <filename>INSTALL_TIMEZONE_FILE</filename>

7113

variable to "0" at the configuration level to disable this

behavior.

</para>

</glossdef>

</glossentry>

<info>

IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image."

</info>

When the IPK backend is in use and package management

7126

is enabled on the target, you can use this variable to

7127

set up <filename>opkg</filename> in the target image

7128

to point to package feeds on a nominated server.

7129

Once the feed is established, you can perform

7130

installations or upgrades using the package manager

at runtime.

</para>

</glossdef>

</glossentry>

<!--

<glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>

7138

7139

<para>

7140

An environment variable that defines the directory where

7141

post installation hooks are installed for the

7142

post install environment.

7143

This variable is fixed as follows:

7144

7145

${WORKDIR}/intercept_scripts

</literallayout>

</para>

<para>

After installation of a target's root filesystem,

7151

post installation scripts, which are essentially bash scripts,

7152

are all executed just a single time.

7153

Limiting execution of these scripts minimizes installation

7154

time that would be lengthened due to certain packages

7155

triggering redundant operations.

7156

For example, consider the installation of font packages

7157

as a common example.

7158

Without limiting the execution of post installation scripts,

7159

all font directories would be rescanned to create the

7160

cache after each individual font package was installed.

</para>

<para>

Do not edit the <filename>INTERCEPT_DIR</filename>

variable.

</para>

</glossdef>

</glossentry>

-->

</glossdiv>

<glossentry id='var-KARCH'><glossterm>KARCH</glossterm>

7179

<info>

7180

KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions."

</info>

Defines the kernel architecture used when assembling

7185

the configuration.

7186

Architectures supported for this release are:

powerpc

i386

x86_64

arm

qemu

mips

</literallayout>

</para>

<para>

You define the <filename>KARCH</filename> variable in the

7199

<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>

7205

<info>

7206

KBRANCH[doc] = "A regular expression used by the build process to explicitly identify the kernel branch that is validated, patched, and configured during a build."

</info>

A regular expression used by the build process to explicitly

7211

identify the kernel branch that is validated, patched,

7212

and configured during a build.

7213

You must set this variable to ensure the exact kernel

7214

branch you want is being used by the build process.

</para>

<para>

Values for this variable are set in the kernel's recipe

7219

file and the kernel's append file.

7220

For example, if you are using the

7221

<filename>linux-yocto_4.12</filename> kernel, the kernel

7222

recipe file is the

7223

<filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>

7224

file.

7225

<filename>KBRANCH</filename> is set as follows in that

7226

kernel recipe file:

7227

7228

KBRANCH ?= "standard/base"

</literallayout>

</para>

<para>

This variable is also used from the kernel's append file

7234

to identify the kernel branch specific to a particular

7235

machine or target hardware.

7236

Continuing with the previous kernel example, the kernel's

7237

append file (i.e.

7238

<filename>linux-yocto_4.12.bbappend</filename>) is located

7239

in the BSP layer for a given machine.

7240

For example, the append file for the Beaglebone,

7241

EdgeRouter, and generic versions of both 32 and 64-bit IA

7242

machines (<filename>meta-yocto-bsp</filename>) is named

7243

<filename>meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend</filename>.

7244

Here are the related statements from that append file:

7245

7246

KBRANCH_genericx86 = "standard/base"

7247

KBRANCH_genericx86-64 = "standard/base"

7248

KBRANCH_edgerouter = "standard/edgerouter"

7249

KBRANCH_beaglebone = "standard/beaglebone"

7250

</literallayout>

7251

The <filename>KBRANCH</filename> statements identify

7252

the kernel branch to use when building for each

supported BSP.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KBUILD_DEFCONFIG'><glossterm>KBUILD_DEFCONFIG</glossterm>

7259

<info>

7260

KBUILD_DEFCONFIG[doc] = "Specifies an "in-tree" kernel configuration file for use during a kernel build."

</info>

When used with the

class, specifies an "in-tree" kernel configuration file

7267

for use during a kernel build.

</para>

<para>

Typically, when using a <filename>defconfig</filename> to

7272

configure a kernel during a build, you place the

7273

file in your layer in the same manner as you would

7274

place patch files and configuration fragment files (i.e.

7275

"out-of-tree").

7276

However, if you want to use a <filename>defconfig</filename>

7277

file that is part of the kernel tree (i.e. "in-tree"),

7278

you can use the

7279

<filename>KBUILD_DEFCONFIG</filename> variable and append

7280

the

7281

7282

variable to point to the <filename>defconfig</filename>

file.

</para>

<para>

To use the variable, set it in the append file for your

7288

kernel recipe using the following form:

7289

7290

KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>

7291

</literallayout>

7292

Here is an example from a "raspberrypi2"

7293

<filename>KMACHINE</filename> build that uses a

7294

<filename>defconfig</filename> file named

7295

"bcm2709_defconfig":

7296

7297

KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"

7298

</literallayout>

7299

As an alternative, you can use the following within your

7300

append file:

7301

7302

KBUILD_DEFCONFIG_pn-linux-yocto ?= <replaceable>defconfig_file</replaceable>

7303

</literallayout>

7304

For more information on how to use the

7305

<filename>KBUILD_DEFCONFIG</filename> variable, see the

7306

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-an-in-tree-defconfig-file'>Using an "In-Tree" <filename>defconfig</filename> File</ulink>"

7307

section in the Yocto Project Linux Kernel Development

Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_ALT_IMAGETYPE'><glossterm>KERNEL_ALT_IMAGETYPE</glossterm>

7314

<info>

7315

KERNEL_ALT_IMAGETYPE[doc] = "Specifies an alternate kernel image type for creation."

</info>

Specifies an alternate kernel image type for creation in

7320

addition to the kernel image type specified using the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_ARTIFACT_NAME'><glossterm>KERNEL_ARTIFACT_NAME</glossterm>

7328

<info>

7329

KERNEL_ARTIFACT_NAME[doc] = "Specifies the name of all of the build artifacts."

</info>

Specifies the name of all of the build artifacts.

7334

You can change the name of the artifacts by changing the

7335

<filename>KERNEL_ARTIFACT_NAME</filename> variable.

</para>

<para>

The value of <filename>KERNEL_ARTIFACT_NAME</filename>,

7340

which is set in the

7341

<filename> meta/classes/kernel-artifact-names.bbclass</filename>

7342

file, has the following default value:

7343

7344

KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"

</literallayout>

</para>

<para>

See the

and

variables for additional information.

7356

<note>

7357

The <filename>IMAGE_VERSION_SUFFIX</filename> variable

is set to

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_CLASSES'><glossterm>KERNEL_CLASSES</glossterm>

7366

<info>

7367

KERNEL_CLASSES[doc] = "A list of classes defining kernel image types that kernel class should inherit."

</info>

A list of classes defining kernel image types that the

7372

7373

class should inherit.

7374

You typically append this variable to enable extended image

7375

types.

7376

An example is the "kernel-fitimage", which enables

7377

fitImage support and resides in

7378

<filename>meta/classes/kernel-fitimage.bbclass</filename>.

7379

You can register custom kernel image types with the

7380

<filename>kernel</filename> class using this variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_DEVICETREE'><glossterm>KERNEL_DEVICETREE</glossterm>

7386

<info>

7387

KERNEL_DEVICETREE[doc] = "Specifies the name of the generated Linux kernel device tree (i.e. the .dtb) file."

</info>

Specifies the name of the generated Linux kernel device tree

7392

(i.e. the <filename>.dtb</filename>) file.

7393

<note>

7394

Legacy support exists for specifying the full path

7395

to the device tree.

7396

However, providing just the <filename>.dtb</filename>

7397

file is preferred.

7398

</note>

7399

In order to use this variable, the

7400

7401

class must be inherited.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_DTB_LINK_NAME'><glossterm>KERNEL_DTB_LINK_NAME</glossterm>

7407

<info>

7408

KERNEL_DTB_LINK_NAME[doc] = "The link name of the kernel device tree binary (DTB)."

</info>

The link name of the kernel device tree binary (DTB).

7413

This variable is set in the

7414

<filename>meta/classes/kernel-artifact-names.bbclass</filename>

7415

file as follows:

7416

7417

KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"

7418

</literallayout>

7419

The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>

7420

variable, which is set in the same file, has the following

7421

value:

7422

7423

KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"

</literallayout>

</para>

<para>

See the

variable for additional information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_DTB_NAME'><glossterm>KERNEL_DTB_NAME</glossterm>

7436

<info>

7437

KERNEL_DTB_NAME[doc] = "The base name of the kernel device tree binary (DTB)."

</info>

The base name of the kernel device tree binary (DTB).

7442

This variable is set in the

7443

<filename>meta/classes/kernel-artifact-names.bbclass</filename>

7444

file as follows:

7445

7446

KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"

</literallayout>

The value of the

variable, which is set in the same file, has the following

7451

value:

7452

7453

KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>

7460

<info>

7461

KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel."

</info>

Specifies additional <filename>make</filename>

7466

command-line arguments the OpenEmbedded build system

7467

passes on when compiling the kernel.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>

7473

<info>

7474

KERNEL_FEATURES[doc] = "Includes additional kernel metadata. The metadata you add through this variable includes config fragments and features descriptions."

</info>

Includes additional kernel metadata.

7479

In the OpenEmbedded build system, the default Board Support

Packages (BSPs)

is provided through

the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>

and

variables.

You can use the <filename>KERNEL_FEATURES</filename>

7488

variable from within the kernel recipe or kernel append

7489

file to further add metadata for all BSPs or specific

BSPs.

</para>

<para>

The metadata you add through this variable includes config

7495

fragments and features descriptions,

7496

which usually includes patches as well as config fragments.

7497

You typically override the

7498

<filename>KERNEL_FEATURES</filename> variable for a

7499

specific machine.

7500

In this way, you can provide validated, but optional,

7501

sets of kernel configurations and features.

</para>

<para>

For example, the following example from the

7506

<filename>linux-yocto-rt_4.12</filename> kernel recipe

7507

adds "netfilter" and "taskstats" features to all BSPs

7508

as well as "virtio" configurations to all QEMU machines.

7509

The last two statements add specific configurations to

7510

targeted machine types:

7511

7512

KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"

7513

KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"

7514

KERNEL_FEATURES_append_qemuall = " cfg/virtio.scc"

7515

KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"

7516

KERNEL_FEATURES_append_qemux86-64 = " cfg/sound.scc" </literallayout></para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_FIT_LINK_NAME'><glossterm>KERNEL_FIT_LINK_NAME</glossterm>

7521

<info>

7522

KERNEL_FIT_LINK_NAME[doc] = "The link name of the kernel flattened image tree (FIT) image."

</info>

The link name of the kernel flattened image tree (FIT) image.

7527

This variable is set in the

7528

<filename>meta/classes/kernel-artifact-names.bbclass</filename>

7529

file as follows:

7530

7531

KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"

7532

</literallayout>

7533

The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>

7534

variable, which is set in the same file, has the following

7535

value:

7536

7537

KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"

</literallayout>

</para>

<para>

See the

variable for additional information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_FIT_NAME'><glossterm>KERNEL_FIT_NAME</glossterm>

7550

<info>

7551

KERNEL_FIT_NAME[doc] = "The base name of the kernel flattened image tree (FIT) image."

</info>

The base name of the kernel flattened image tree (FIT) image.

7556

This variable is set in the

7557

<filename>meta/classes/kernel-artifact-names.bbclass</filename>

7558

file as follows:

7559

7560

KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"

</literallayout>

The value of the

variable, which is set in the same file, has the following

7565

value:

7566

7567

KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_IMAGE_LINK_NAME'><glossterm>KERNEL_IMAGE_LINK_NAME</glossterm>

7574

<info>

7575

KERNEL_IMAGE_LINK_NAME[doc] = "The link name for the kernel image."

</info>

The link name for the kernel image.

7580

This variable is set in the

7581

<filename>meta/classes/kernel-artifact-names.bbclass</filename>

7582

file as follows:

7583

7584

KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"

7585

</literallayout>

7586

The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>

7587

variable, which is set in the same file, has the following

7588

value:

7589

7590

KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"

</literallayout>

</para>

<para>

See the

variable for additional information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_IMAGE_MAXSIZE'><glossterm>KERNEL_IMAGE_MAXSIZE</glossterm>

7603

<info>

7604

KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."

</info>

Specifies the maximum size of the kernel image file in

7609

kilobytes.

7610

If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,

7611

the size of the kernel image file is checked against

7612

the set value during the

7613

7614

task.

7615

The task fails if the kernel image file is larger than

the setting.

</para>

<para>

<filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for

7621

target devices that have a limited amount of space in

7622

which the kernel image must be stored.

</para>

<para>

By default, this variable is not set, which means the

7627

size of the kernel image is not checked.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_IMAGE_NAME'><glossterm>KERNEL_IMAGE_NAME</glossterm>

7633

<info>

7634

KERNEL_IMAGE_NAME[doc] = "The base name of the kernel image."

</info>

The base name of the kernel image.

7639

This variable is set in the

7640

<filename>meta/classes/kernel-artifact-names.bbclass</filename>

7641

file as follows:

7642

7643

KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"

</literallayout>

The value of the

variable, which is set in the same file, has the following

7648

value:

7649

7650

KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>

7657

<info>

7658

KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."

</info>

The type of kernel to build for a device, usually set by the

7663

machine configuration files and defaults to "zImage".

7664

This variable is used

7665

when building the kernel and is passed to <filename>make</filename> as the target to

build.

</para>

<para>

If you want to build an alternate kernel image type, use the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_MODULE_AUTOLOAD'><glossterm>KERNEL_MODULE_AUTOLOAD</glossterm>

7678

<info>

7679

KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot"

</info>

Lists kernel modules that need to be auto-loaded during

7684

boot.

7685

<note>

7686

This variable replaces the deprecated

variable.

</note>

</para>

<para>

You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename>

7694

variable anywhere that it can be

7695

recognized by the kernel recipe or by an out-of-tree kernel

7696

module recipe (e.g. a machine configuration file, a

7697

distribution configuration file, an append file for the

7698

recipe, or the recipe itself).

</para>

<para>

Specify it as follows:

7703

7704

KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name1</replaceable> <replaceable>module_name2</replaceable> <replaceable>module_name3</replaceable>"

</literallayout>

</para>

<para>

Including <filename>KERNEL_MODULE_AUTOLOAD</filename> causes

7710

the OpenEmbedded build system to populate the

7711

<filename>/etc/modules-load.d/modname.conf</filename>

7712

file with the list of modules to be auto-loaded on boot.

7713

The modules appear one-per-line in the file.

7714

Here is an example of the most common use case:

7715

7716

KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>"

</literallayout>

</para>

<para>

For information on how to populate the

7722

<filename>modname.conf</filename> file with

7723

<filename>modprobe.d</filename> syntax lines, see the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm>

7731

<info>

7732

KERNEL_MODULE_PROBECONF[doc] = "Lists kernel modules for which the build system expects to find module_conf_* values that specify configuration for each of the modules."

</info>

Provides a list of modules for which the OpenEmbedded

7737

build system expects to find

7738

<filename>module_conf_</filename><replaceable>modname</replaceable>

7739

values that specify configuration for each of the modules.

7740

For information on how to provide those module

7741

configurations, see the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>

7749

<info>

7750

KERNEL_PATH[doc] = "The location of the kernel sources. This variable is set to the value of the STAGING_KERNEL_DIR within the module class (module.bbclass)."

</info>

The location of the kernel sources.

7755

This variable is set to the value of the

within the

class.

For information on how this variable is used, see the

7761

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"

7762

section in the Yocto Project Linux Kernel Development

Manual.

</para>

<para>

To help maximize compatibility with out-of-tree drivers

7768

used to build modules, the OpenEmbedded build system also

7769

recognizes and uses the

7770

7771

variable, which is identical to the

7772

<filename>KERNEL_PATH</filename> variable.

7773

Both variables are common variables used by external

7774

Makefiles to point to the kernel source directory.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>

7780

<info>

7781

KERNEL_SRC[doc] = "The location of the kernel sources. This variable is set to the value of the STAGING_KERNEL_DIR within the module class (module.bbclass)."

</info>

The location of the kernel sources.

7786

This variable is set to the value of the

within the

class.

For information on how this variable is used, see the

7792

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"

7793

section in the Yocto Project Linux Kernel Development

Manual.

</para>

<para>

To help maximize compatibility with out-of-tree drivers

7799

used to build modules, the OpenEmbedded build system also

7800

recognizes and uses the

7801

7802

variable, which is identical to the

7803

<filename>KERNEL_SRC</filename> variable.

7804

Both variables are common variables used by external

7805

Makefiles to point to the kernel source directory.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_VERSION'><glossterm>KERNEL_VERSION</glossterm>

7811

<info>

7812

KERNEL_VERSION[doc] = "Specifies the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources."

</info>

Specifies the version of the kernel as extracted from

7817

<filename>version.h</filename> or

7818

<filename>utsrelease.h</filename> within the kernel sources.

7819

Effects of setting this variable do not take affect until

7820

the kernel has been configured.

7821

Consequently, attempting to refer to this variable in

7822

contexts prior to configuration will not work.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNELDEPMODDEPEND'><glossterm>KERNELDEPMODDEPEND</glossterm>

7828

<info>

7829

KERNELDEPMODDEPEND[doc] = "Specifies whether or not to use the data referenced through the PKGDATA_DIR directory."

</info>

Specifies whether the data referenced through

7834

7835

is needed or not.

7836

The <filename>KERNELDEPMODDEPEND</filename> does not

7837

control whether or not that data exists,

7838

but simply whether or not it is used.

7839

If you do not need to use the data, set the

7840

<filename>KERNELDEPMODDEPEND</filename> variable in your

7841

<filename>initramfs</filename> recipe.

7842

Setting the variable there when the data is not needed

7843

avoids a potential dependency loop.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>

7849

<info>

7850

KFEATURE_DESCRIPTION[doc] = "Provides a short description of a configuration fragment. You use this variable in the .scc file that describes a configuration fragment file."

</info>

Provides a short description of a configuration fragment.

7855

You use this variable in the <filename>.scc</filename>

7856

file that describes a configuration fragment file.

7857

Here is the variable used in a file named

7858

<filename>smp.scc</filename> to describe SMP being

7859

enabled:

7860

7861

define KFEATURE_DESCRIPTION "Enable SMP"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>

7868

<info>

7869

KMACHINE[doc] = "The machine as known by the kernel."

</info>

The machine as known by the kernel.

7874

Sometimes the machine name used by the kernel does not

7875

match the machine name used by the OpenEmbedded build

7876

system.

7877

For example, the machine name that the OpenEmbedded build

7878

system understands as

7879

<filename>core2-32-intel-common</filename> goes by a

7880

different name in the Linux Yocto kernel.

7881

The kernel understands that machine as

7882

<filename>intel-core2-32</filename>.

7883

For cases like these, the <filename>KMACHINE</filename>

7884

variable maps the kernel machine name to the OpenEmbedded

7885

build system machine name.

</para>

<para>

These mappings between different names occur in the

7890

Yocto Linux Kernel's <filename>meta</filename> branch.

7891

As an example take a look in the

7892

<filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename>

7893

file:

7894

7895

LINUX_VERSION_core2-32-intel-common = "3.19.0"

7896

COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"

7897

SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"

7898

SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"

7899

KMACHINE_core2-32-intel-common = "intel-core2-32"

7900

KBRANCH_core2-32-intel-common = "standard/base"

7901

KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"

7902

</literallayout>

7903

The <filename>KMACHINE</filename> statement says that

7904

the kernel understands the machine name as

7905

"intel-core2-32".

7906

However, the OpenEmbedded build system understands the

7907

machine as "core2-32-intel-common".

</para>

</glossdef>

</glossentry>

<glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>

7914

<info>

7915

KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration."

</info>

Defines the kernel type to be used in assembling the

7920

configuration.

7921

The linux-yocto recipes define "standard", "tiny",

7922

and "preempt-rt" kernel types.

7923

See the

7924

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"

7925

section in the Yocto Project Linux Kernel Development

7926

Manual for more information on kernel types.

</para>

<para>

You define the <filename>KTYPE</filename> variable in the

7931

<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.

7932

The value you use must match the value used for the

7933

7934

value used by the kernel recipe.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-LABELS'><glossterm>LABELS</glossterm>

7943

<info>

7944

LABELS[doc] = "Provides a list of targets for automatic configuration."

</info>

Provides a list of targets for automatic configuration.

</para>

<para>

See the

class for more information on how this variable is used.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>

7960

<info>

7961

LAYERDEPENDS[doc] = "Lists the layers, separated by spaces, on which this recipe depends. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer."

</info>

Lists the layers, separated by spaces, on which this

7966

recipe depends.

7967

Optionally, you can specify a specific layer version for a

7968

dependency by adding it to the end of the layer name.

7969

Here is an example:

7970

7971

LAYERDEPENDS_mylayer = "anotherlayer (=3)"

7972

</literallayout>

7973

In this previous example, version 3 of "anotherlayer"

is compared against

</para>

<para>

An error is produced if any dependency is missing or

7980

the version numbers (if specified) do not match exactly.

7981

This variable is used in the

7982

<filename>conf/layer.conf</filename> file and must be

7983

suffixed with the name of the specific layer (e.g.

7984

<filename>LAYERDEPENDS_mylayer</filename>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>

7990

<info>

7991

LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer."

</info>

When used inside the <filename>layer.conf</filename> configuration

7996

file, this variable provides the path of the current layer.

7997

This variable is not available outside of <filename>layer.conf</filename>

7998

and references are expanded immediately when parsing of the file completes.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LAYERRECOMMENDS'><glossterm>LAYERRECOMMENDS</glossterm>

8004

<info>

8005

LAYERRECOMMENDS[doc] = "Lists the layers, separated by spaces, recommended for use with this layer."

</info>

Lists the layers, separated by spaces, recommended for

use with this layer.

</para>

<para>

Optionally, you can specify a specific layer version for a

8015

recommendation by adding the version to the end of the

layer name.

Here is an example:

LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"

8020

</literallayout>

8021

In this previous example, version 3 of "anotherlayer" is

8022

compared against

8023

<filename>LAYERVERSION_anotherlayer</filename>.

</para>

<para>

This variable is used in the

8028

<filename>conf/layer.conf</filename> file and must be

8029

suffixed with the name of the specific layer (e.g.

8030

<filename>LAYERRECOMMENDS_mylayer</filename>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-LAYERSERIES_COMPAT'><glossterm>LAYERSERIES_COMPAT</glossterm>

8036

<info>

8037

LAYERSERIES_COMPAT[doc] = "Lists the OpenEmbedded-Core versions for which a layer is compatible."

</info>

Lists the versions of the

8042

8043

a layer is compatible.

8044

Using the <filename>LAYERSERIES_COMPAT</filename> variable

8045

allows the layer maintainer to indicate which combinations

8046

of the layer and OE-Core can be expected to work.

8047

The variable gives the system a way to detect when a layer

8048

has not been tested with new releases of OE-Core (e.g.

8049

the layer is not maintained).

</para>

<para>

To specify the OE-Core versions for which a layer is

8054

compatible, use this variable in your layer's

8055

<filename>conf/layer.conf</filename> configuration file.

8056

For the list, use the Yocto Project

8057

<ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Release Name</ulink>

8058

(e.g. &DISTRO_NAME_NO_CAP;).

8059

To specify multiple OE-Core versions for the layer,

8060

use a space-separated list:

8061

8062

LAYERSERIES_COMPAT_<replaceable>layer_root_name</replaceable> = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"

8063

</literallayout>

8064

<note>

8065

Setting <filename>LAYERSERIES_COMPAT</filename> is

8066

required by the Yocto Project Compatible version 2

8067

standard.

8068

The OpenEmbedded build system produces a warning if

8069

the variable is not set for any given layer.

</note>

</para>

<para>

See the

"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-layer'>Creating Your Own Layer</ulink>"

8076

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>

8082

<info>

8083

LAYERVERSION[doc] = "Optionally specifies the version of a layer as a single number. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer."

</info>

Optionally specifies the version of a layer as a single number.

8088

You can use this within

8089

8090

for another layer in order to depend on a specific version

8091

of the layer.

8092

This variable is used in the <filename>conf/layer.conf</filename> file

8093

and must be suffixed with the name of the specific layer (e.g.

8094

<filename>LAYERVERSION_mylayer</filename>).

</para>

</glossdef>

</glossentry>

<info>

LD[doc] = "Minimal command and arguments to run the linker."

</info>

The minimal command and arguments used to run the

linker.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm>

8112

<info>

8113

LDFLAGS[doc] = "Specifies the flags to pass to the linker."

</info>

Specifies the flags to pass to the linker.

8118

This variable is exported to an environment

8119

variable and thus made visible to the software being

8120

built during the compilation step.

</para>

<para>

Default initialization for <filename>LDFLAGS</filename>

8125

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

8134

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

8139

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>

8147

<info>

8148

LEAD_SONAME[doc] = "Specifies the lead (or primary) compiled library file (i.e. .so) that the debian class applies its naming policy to given a recipe that packages multiple libraries."

</info>

Specifies the lead (or primary) compiled library file

8153

(i.e. <filename>.so</filename>) that the

8154

8155

class applies its naming policy to given a recipe that

8156

packages multiple libraries.

</para>

<para>

This variable works in conjunction with the

8161

<filename>debian</filename> class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>

8167

<info>

8168

LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code."

</info>

Checksums of the license text in the recipe source code.

</para>

<para>

This variable tracks changes in license text of the source

8177

code files.

8178

If the license text is changed, it will trigger a build

8179

failure, which gives the developer an opportunity to review any

license change.

</para>

<para>

This variable must be defined for all recipes (unless

8185

8186

is set to "CLOSED").</para>

8187

<para>For more information, see the

8188

"<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"

8189

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>

8195

<info>

8196

LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &, '|', and parentheses can be used."

</info>

The list of source licenses for the recipe.

8201

Follow these rules:

8202

8203

<listitem><para>Do not use spaces within individual

8204

license names.</para></listitem>

8205

<listitem><para>Separate license names using

8206

| (pipe) when there is a choice between licenses.

8207

</para></listitem>

8208

<listitem><para>Separate license names using

8209

& (ampersand) when multiple licenses exist

8210

that cover different parts of the source.

8211

</para></listitem>

8212

<listitem><para>You can use spaces between license

8213

names.</para></listitem>

8214

<listitem><para>For standard licenses, use the names

8215

of the files in

8216

<filename>meta/files/common-licenses/</filename>

8217

or the

8218

8219

flag names defined in

8220

<filename>meta/conf/licenses.conf</filename>.

</para></listitem>

</itemizedlist>

</para>

<para>

Here are some examples:

8227

8228

LICENSE = "LGPLv2.1 | GPLv3"

8229

LICENSE = "MPL-1 & LGPLv2.1"

8230

LICENSE = "GPLv2+"

8231

</literallayout>

8232

The first example is from the recipes for Qt, which the user

8233

may choose to distribute under either the LGPL version

8234

2.1 or GPL version 3.

8235

The second example is from Cairo where two licenses cover

8236

different parts of the source code.

8237

The final example is from <filename>sysstat</filename>,

8238

which presents a single license.

</para>

<para>

You can also specify licenses on a per-package basis to

8243

handle situations where components of the output have

8244

different licenses.

8245

For example, a piece of software whose code is

8246

licensed under GPLv2 but has accompanying documentation

8247

licensed under the GNU Free Documentation License 1.2 could

8248

be specified as follows:

8249

8250

LICENSE = "GFDL-1.2 & GPLv2"

8251

LICENSE_${PN} = "GPLv2"

8252

LICENSE_${PN}-doc = "GFDL-1.2"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-LICENSE_CREATE_PACKAGE'><glossterm>LICENSE_CREATE_PACKAGE</glossterm>

8259

<info>

8260

LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."

</info>

Setting <filename>LICENSE_CREATE_PACKAGE</filename>

8265

to "1" causes the OpenEmbedded build system to create

8266

an extra package (i.e.

8267

<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)

8268

for each recipe and to add those packages to the

</para>

<para>

The <filename>${PN}-lic</filename> package installs a

8274

directory in <filename>/usr/share/licenses</filename>

8275

named <filename>${PN}</filename>, which is the recipe's

8276

base name, and installs files in that directory that

8277

contain license and copyright information (i.e. copies of

8278

the appropriate license files from

8279

<filename>meta/common-licenses</filename> that match the

8280

licenses specified in the

8281

8282

variable of the recipe metadata and copies of files marked

8283

in

8284

8285

as containing license text).

</para>

<para>

For related information on providing license text, see the

variable, the

variable, and the

"<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"

8295

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm>

8301

<info>

8302

LICENSE_FLAGS[doc] = "Specifies additional flags for a recipe you must whitelist through LICENSE_FLAGS_WHITELIST in order to allow the recipe to be built."

</info>

Specifies additional flags for a recipe you must

8307

whitelist through

8308

8309

in order to allow the recipe to be built.

8310

When providing multiple flags, separate them with

spaces.

</para>

<para>

This value is independent of

8316

8317

and is typically used to mark recipes that might

8318

require additional licenses in order to be used in a

8319

commercial product.

8320

For more information, see the

8321

"<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"

8322

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm>LICENSE_FLAGS_WHITELIST</glossterm>

8328

<info>

8329

LICENSE_FLAGS_WHITELIST[doc] = "Lists license flags that when specified in LICENSE_FLAGS within a recipe should not prevent that recipe from being built."

</info>

Lists license flags that when specified in

8334

8335

within a recipe should not prevent that recipe from being

8336

built.

8337

This practice is otherwise known as "whitelisting"

8338

license flags.

8339

For more information, see the

8340

"<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"

8341

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>

8347

<info>

8348

LICENSE_PATH[doc] = "Path to additional licenses used during the build."

</info>

Path to additional licenses used during the build.

8353

By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>

8354

to define the directory that holds common license text used during the build.

8355

The <filename>LICENSE_PATH</filename> variable allows you to extend that

8356

location to other areas that have additional licenses:

8357

8358

LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>

8365

<info>

8366

LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration."

</info>

Defines the kernel type to be used in assembling the

8371

configuration.

8372

The linux-yocto recipes define "standard", "tiny", and

8373

"preempt-rt" kernel types.

8374

See the

8375

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"

8376

section in the Yocto Project Linux Kernel Development

8377

Manual for more information on kernel types.

</para>

<para>

If you do not specify a

8382

<filename>LINUX_KERNEL_TYPE</filename>, it defaults to

"standard".

Together with

the <filename>LINUX_KERNEL_TYPE</filename> variable

8387

defines the search

8388

arguments used by the kernel tools to find the appropriate

8389

description within the kernel

8390

8391

with which to build out the sources and configuration.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>

8397

<info>

8398

LINUX_VERSION[doc] = "The Linux version from kernel.org on which the Linux kernel image being built using the OpenEmbedded build system is based. You define this variable in the kernel recipe."

</info>

The Linux version from <filename>kernel.org</filename>

8403

on which the Linux kernel image being built using the

8404

OpenEmbedded build system is based.

8405

You define this variable in the kernel recipe.

8406

For example, the <filename>linux-yocto-3.4.bb</filename>

8407

kernel recipe found in

8408

<filename>meta/recipes-kernel/linux</filename>

8409

defines the variables as follows:

8410

8411

LINUX_VERSION ?= "3.4.24"

</literallayout>

</para>

<para>

The <filename>LINUX_VERSION</filename> variable is used to

8417

define <link linkend='var-PV'><filename>PV</filename></link>

8418

for the recipe:

8419

8420

PV = "${LINUX_VERSION}+git${SRCPV}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>

8427

<info>

8428

LINUX_VERSION_EXTENSION[doc] = "A string extension compiled into the version string of the Linux kernel built with the OpenEmbedded build system. You define this variable in the kernel recipe."

</info>

A string extension compiled into the version

8433

string of the Linux kernel built with the OpenEmbedded

8434

build system.

8435

You define this variable in the kernel recipe.

8436

For example, the linux-yocto kernel recipes all define

8437

the variable as follows:

8438

8439

LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"

</literallayout>

</para>

<para>

Defining this variable essentially sets the

8445

Linux kernel configuration item

8446

<filename>CONFIG_LOCALVERSION</filename>, which is visible

8447

through the <filename>uname</filename> command.

8448

Here is an example that shows the extension assuming it

8449

was set as previously shown:

$ uname -r

3.7.0-rc8-custom

</literallayout>

</para>

</glossdef>

</glossentry>

<info>

LOG_DIR[doc] = "Specifies the directory to which the OpenEmbedded build system writes overall log files. The default directory is ${TMPDIR}/log"

</info>

Specifies the directory to which the OpenEmbedded build

8465

system writes overall log files.

8466

The default directory is <filename>${TMPDIR}/log</filename>.

</para>

<para>

For the directory containing logs specific to each task,

8471

see the <link linkend='var-T'><filename>T</filename></link>

variable.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>

8482

<info>

8483

MACHINE[doc] = "Specifies the target device for which the image is built. You define MACHINE in the conf/local.conf file in the Build Directory."

</info>

Specifies the target device for which the image is built.

8488

You define <filename>MACHINE</filename> in the

8489

<filename>local.conf</filename> file found in the

8490

8491

By default, <filename>MACHINE</filename> is set to

8492

"qemux86", which is an x86-based architecture machine to

8493

be emulated using QEMU:

MACHINE ?= "qemux86"

</literallayout>

</para>

<para>

The variable corresponds to a machine configuration file of the

8501

same name, through which machine-specific configurations are set.

8502

Thus, when <filename>MACHINE</filename> is set to "qemux86" there

8503

exists the corresponding <filename>qemux86.conf</filename> machine

8504

configuration file, which can be found in the

8505

8506

in <filename>meta/conf/machine</filename>.

</para>

<para>

The list of machines supported by the Yocto Project as

8511

shipped include the following:

8512

8513

MACHINE ?= "qemuarm"

8514

MACHINE ?= "qemuarm64"

8515

MACHINE ?= "qemumips"

8516

MACHINE ?= "qemumips64"

8517

MACHINE ?= "qemuppc"

8518

MACHINE ?= "qemux86"

8519

MACHINE ?= "qemux86-64"

8520

MACHINE ?= "genericx86"

8521

MACHINE ?= "genericx86-64"

8522

MACHINE ?= "beaglebone"

8523

MACHINE ?= "edgerouter"

8524

</literallayout>

8525

The last five are Yocto Project reference hardware boards, which

8526

are provided in the <filename>meta-yocto-bsp</filename> layer.

8527

<note>Adding additional Board Support Package (BSP) layers

8528

to your configuration adds new possible settings for

8529

<filename>MACHINE</filename>.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm>

8536

<info>

8537

MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH."

</info>

Specifies the name of the machine-specific architecture.

8542

This variable is set automatically from

or

You should not hand-edit the

8547

<filename>MACHINE_ARCH</filename> variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>

8553

<info>

8554

MACHINE_ESSENTIAL_EXTRA_RDEPENDS[doc] = "A list of required machine-specific packages to install as part of the image being built. Because this is a 'machine-essential' variable, the list of packages are essential for the machine to boot."

</info>

A list of required machine-specific packages to install as part of

8559

the image being built.

8560

The build process depends on these packages being present.

8561

Furthermore, because this is a "machine-essential" variable, the list of

8562

packages are essential for the machine to boot.

8563

The impact of this variable affects images based on

8564

<filename>packagegroup-core-boot</filename>,

8565

including the <filename>core-image-minimal</filename> image.

</para>

<para>

This variable is similar to the

8570

<filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>

8571

variable with the exception that the image being built has a build

8572

dependency on the variable's list of packages.

8573

In other words, the image will not build if a file in this list is not found.

</para>

<para>

As an example, suppose the machine for which you are building requires

8578

<filename>example-init</filename> to be run during boot to initialize the hardware.

8579

In this case, you would use the following in the machine's

8580

<filename>.conf</filename> configuration file:

8581

8582

MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>

8589

<info>

8590

MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS[doc] = "A list of recommended machine-specific packages to install as part of the image being built. Because this is a 'machine-essential' variable, the list of packages are essential for the machine to boot."

</info>

A list of recommended machine-specific packages to install as part of

8595

the image being built.

8596

The build process does not depend on these packages being present.

8597

However, because this is a "machine-essential" variable, the list of

8598

packages are essential for the machine to boot.

8599

The impact of this variable affects images based on

8600

<filename>packagegroup-core-boot</filename>,

8601

including the <filename>core-image-minimal</filename> image.

</para>

<para>

This variable is similar to the

8606

<filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>

8607

variable with the exception that the image being built does not have a build

8608

dependency on the variable's list of packages.

8609

In other words, the image will still build if a package in this list is not found.

8610

Typically, this variable is used to handle essential kernel modules, whose

8611

functionality may be selected to be built into the kernel rather than as a module,

8612

in which case a package will not be produced.

</para>

<para>

Consider an example where you have a custom kernel where a specific touchscreen

8617

driver is required for the machine to be usable.

8618

However, the driver can be built as a module or

8619

into the kernel depending on the kernel configuration.

8620

If the driver is built as a module, you want it to be installed.

8621

But, when the driver is built into the kernel, you still want the

8622

build to succeed.

8623

This variable sets up a "recommends" relationship so that in the latter case,

8624

the build will not fail due to the missing package.

8625

To accomplish this, assuming the package for the module was called

8626

<filename>kernel-module-ab123</filename>, you would use the

8627

following in the machine's <filename>.conf</filename> configuration

8628

file:

8629

8630

MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"

</literallayout>

<note>

In this example, the

<filename>kernel-module-ab123</filename> recipe

8635

needs to explicitly set its

8636

8637

variable to ensure that BitBake does not use the

8638

kernel recipe's

8639

8640

variable to satisfy the dependency.

</note>

</para>

<para>

Some examples of these machine essentials are flash, screen, keyboard, mouse,

8646

or touchscreen drivers (depending on the machine).

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>

8652

<info>

8653

MACHINE_EXTRA_RDEPENDS[doc] = "A list of machine-specific packages to install as part of the image being built that are not essential for the machine to boot. However, the build process for more fully-featured images depends on the packages being present."

</info>

A list of machine-specific packages to install as part of the

8658

image being built that are not essential for the machine to boot.

8659

However, the build process for more fully-featured images

8660

depends on the packages being present.

</para>

<para>

This variable affects all images based on

8665

<filename>packagegroup-base</filename>, which does not include the

8666

<filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>

images.

</para>

<para>

The variable is similar to the

8672

<filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>

8673

variable with the exception that the image being built has a build

8674

dependency on the variable's list of packages.

8675

In other words, the image will not build if a file in this list is not found.

</para>

<para>

An example is a machine that has WiFi capability but is not

8680

essential for the machine to boot the image.

8681

However, if you are building a more fully-featured image, you want to enable

8682

the WiFi.

8683

The package containing the firmware for the WiFi hardware is always

8684

expected to exist, so it is acceptable for the build process to depend upon

8685

finding the package.

8686

In this case, assuming the package for the firmware was called

8687

<filename>wifidriver-firmware</filename>, you would use the following in the

8688

<filename>.conf</filename> file for the machine:

8689

8690

MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>

8697

<info>

8698

MACHINE_EXTRA_RRECOMMENDS[doc] = "A list of machine-specific packages to install as part of the image being built that are not essential for booting the machine. The image being built has no build dependencies on the packages in this list."

</info>

A list of machine-specific packages to install as part of the

8703

image being built that are not essential for booting the machine.

8704

The image being built has no build dependency on this list of packages.

</para>

<para>

This variable affects only images based on

8709

<filename>packagegroup-base</filename>, which does not include the

8710

<filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>

images.

</para>

<para>

This variable is similar to the

8716

<filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>

8717

variable with the exception that the image being built does not have a build

8718

dependency on the variable's list of packages.

8719

In other words, the image will build if a file in this list is not found.

</para>

<para>

An example is a machine that has WiFi capability but is not essential

8724

For the machine to boot the image.

8725

However, if you are building a more fully-featured image, you want to enable

8726

WiFi.

8727

In this case, the package containing the WiFi kernel module will not be produced

8728

if the WiFi driver is built into the kernel, in which case you still want the

8729

build to succeed instead of failing as a result of the package not being found.

8730

To accomplish this, assuming the package for the module was called

8731

<filename>kernel-module-examplewifi</filename>, you would use the

8732

following in the <filename>.conf</filename> file for the machine:

8733

8734

MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>

8741

<info>

8742

MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports."

</info>

Specifies the list of hardware features the

8747

8748

of supporting.

8749

For related information on enabling features, see the

and

variables.

</para>

<para>

For a list of hardware features supported by the Yocto

8759

Project as shipped, see the

8760

"<link linkend='ref-features-machine'>Machine Features</link>"

section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>

8767

<info>

8768

MACHINE_FEATURES_BACKFILL[doc] = "Features to be added to MACHINE_FEATURES if not also present in MACHINE_FEATURES_BACKFILL_CONSIDERED. This variable is set in the meta/conf/bitbake.conf file and is not intended to be user-configurable."

</info>

Features to be added to

8773

<filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>

8774

if not also present in

8775

<filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.

</para>

<para>

This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.

8780

It is not intended to be user-configurable.

8781

It is best to just reference the variable to see which machine features are

8782

being backfilled for all machine configurations.

8783

See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for

more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>

8790

<info>

8791

MACHINE_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from MACHINE_FEATURES_BACKFILL that should not be backfilled (i.e. added to MACHINE_FEATURES) during the build."

</info>

Features from

<filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>

8797

that should not be backfilled (i.e. added to

8798

<filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)

8799

during the build.

8800

See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for

more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>

8807

<info>

8808

MACHINEOVERRIDES[doc] = "A colon-separated list of overrides that apply to the current machine."

</info>

A colon-separated list of overrides that apply to the

8813

current machine.

8814

By default, this list includes the value of

</para>

<para>

You can extend <filename>MACHINEOVERRIDES</filename>

8820

to add extra overrides that should apply to a machine.

8821

For example, all machines emulated in QEMU (e.g.

8822

<filename>qemuarm</filename>, <filename>qemux86</filename>,

8823

and so forth) include a file named

8824

<filename>meta/conf/machine/include/qemu.inc</filename>

8825

that prepends the following override to

8826

<filename>MACHINEOVERRIDES</filename>:

8827

8828

MACHINEOVERRIDES =. "qemuall:"

8829

</literallayout>

8830

This override allows variables to be overriden for all

8831

machines emulated in QEMU, like in the following example

8832

from the <filename>connman-conf</filename> recipe:

8833

8834

SRC_URI_append_qemuall = "file://wired.config \

file://wired-setup \

"

</literallayout>

The underlying mechanism behind

8839

<filename>MACHINEOVERRIDES</filename> is simply that it is

8840

included in the default value of

</para>

</glossdef>

</glossentry>

<glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>

8847

<info>

8848

MAINTAINER[doc] = "The email address of the distribution maintainer."

</info>

The email address of the distribution maintainer.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>

8858

<info>

8859

MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."

</info>

Specifies additional paths from which the OpenEmbedded

8864

build system gets source code.

8865

When the build system searches for source code, it first

8866

tries the local download directory.

8867

If that location fails, the build system tries locations

8868

defined by

8869

8870

the upstream source, and then locations specified by

8871

<filename>MIRRORS</filename> in that order.

</para>

<para>

Assuming your distribution

8876

(<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)

8877

is "poky", the default value for

8878

<filename>MIRRORS</filename> is defined in the

8879

<filename>conf/distro/poky.conf</filename> file in the

8880

<filename>meta-poky</filename> Git repository.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>

8886

<info>

8887

MLPREFIX[doc] = "Specifies a prefix has been added to PN to create a special version of a recipe or package (i.e. a Multilib version)."

</info>

Specifies a prefix has been added to

8892

8893

of a recipe or package (i.e. a Multilib version).

8894

The variable is used in places where the prefix needs to be

8895

added to or removed from a the name (e.g. the

8896

8897

<filename>MLPREFIX</filename> gets set when a prefix has been

8898

added to <filename>PN</filename>.

8899

<note>

8900

The "ML" in <filename>MLPREFIX</filename> stands for

8901

"MultiLib".

8902

This representation is historical and comes from

8903

a time when <filename>nativesdk</filename> was a suffix

8904

rather than a prefix on the recipe name.

8905

When <filename>nativesdk</filename> was turned into a

8906

prefix, it made sense to set

8907

<filename>MLPREFIX</filename> for it as well.

</note>

</para>

<para>

To help understand when <filename>MLPREFIX</filename>

8913

might be needed, consider when

8914

8915

is used to provide a <filename>nativesdk</filename> version

8916

of a recipe in addition to the target version.

8917

If that recipe declares build-time dependencies on tasks in

8918

other recipes by using

8919

8920

then a dependency on "foo" will automatically get rewritten

8921

to a dependency on "nativesdk-foo".

8922

However, dependencies like the following will not get

8923

rewritten automatically:

8924

8925

do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo"

8926

</literallayout>

8927

If you want such a dependency to also get transformed,

8928

you can do the following:

8929

8930

do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>

8937

<info>

8938

module_autoload[doc] = "This variable has been replaced by the KERNEL_MODULE_AUTOLOAD variable. You should replace all occurrences of module_autoload with additions to KERNEL_MODULE_AUTOLOAD."

</info>

This variable has been replaced by the

8943

<filename>KERNEL_MODULE_AUTOLOAD</filename> variable.

8944

You should replace all occurrences of

8945

<filename>module_autoload</filename> with additions to

8946

<filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:

8947

8948

module_autoload_rfcomm = "rfcomm"

</literallayout>

</para>

<para>

should now be replaced with:

8954

8955

KERNEL_MODULE_AUTOLOAD += "rfcomm"

</literallayout>

See the

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-module_conf'><glossterm>module_conf</glossterm>

8965

<info>

8966

module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file."

</info>

Specifies

<ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>

8972

syntax lines for inclusion in the

8973

<filename>/etc/modprobe.d/modname.conf</filename> file.

</para>

<para>

You can use this variable anywhere that it can be

8978

recognized by the kernel recipe or out-of-tree kernel

8979

module recipe (e.g. a machine configuration file, a

8980

distribution configuration file, an append file for the

8981

recipe, or the recipe itself).

8982

If you use this variable, you must also be sure to list

8983

the module name in the

variable.

</para>

<para>

Here is the general syntax:

8990

8991

module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>"

8992

</literallayout>

8993

You must use the kernel module name override.

</para>

<para>

Run <filename>man modprobe.d</filename> in the shell to

8998

find out more information on the exact syntax

8999

you want to provide with <filename>module_conf</filename>.

</para>

<para>

Including <filename>module_conf</filename> causes the

9004

OpenEmbedded build system to populate the

9005

<filename>/etc/modprobe.d/modname.conf</filename>

9006

file with <filename>modprobe.d</filename> syntax lines.

9007

Here is an example that adds the options

9008

9009

to a module named <filename>mymodule</filename>:

9010

9011

module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"

</literallayout>

</para>

<para>

For information on how to specify kernel modules to

9017

auto-load on boot, see the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>

9025

<info>

9026

MODULE_TARBALL_DEPLOY[doc] = "Controls creation of the modules-*.tgz file. Set this variable to "0" to disable creation of this file, which contains all of the kernel modules resulting from a kernel build."

</info>

Controls creation of the <filename>modules-*.tgz</filename>

9031

file.

9032

Set this variable to "0" to disable creation of this

9033

file, which contains all of the kernel modules resulting

from a kernel build.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MODULE_TARBALL_LINK_NAME'><glossterm>MODULE_TARBALL_LINK_NAME</glossterm>

9040

<info>

9041

MODULE_TARBALL_LINK_NAME[doc] = "The link name of the kernel module tarball."

</info>

The link name of the kernel module tarball.

9046

This variable is set in the

9047

<filename>meta/classes/kernel-artifact-names.bbclass</filename>

9048

file as follows:

9049

9050

MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"

9051

</literallayout>

9052

The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>

9053

variable, which is set in the same file, has the following

9054

value:

9055

9056

KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"

</literallayout>

</para>

<para>

See the

variable for additional information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MODULE_TARBALL_NAME'><glossterm>MODULE_TARBALL_NAME</glossterm>

9069

<info>

9070

MODULE_TARBALL_NAME[doc] = "The base name of the kernel module tarball."

</info>

The base name of the kernel module tarball.

9075

This variable is set in the

9076

<filename>meta/classes/kernel-artifact-names.bbclass</filename>

9077

file as follows:

9078

9079

MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"

</literallayout>

The value of the

variable, which is set in the same file, has the following

9084

value:

9085

9086

KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"

</literallayout>

</para>

</glossdef>

</glossentry>

<!--

<glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm>

9094

<info>

9095

MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories."

</info>

-->

<!--

Serves the same purpose as

9102

9103

but for the "HOST" system, in situations that involve a

9104

"HOST" and a "TARGET" system.

9105

See the

9106

9107

variable for more information.

</para>

<para>

The default value of this variable is:

9112

9113

${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS}

</literallayout>

</para>

</glossdef>

</glossentry>

-->

<glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>

9121

<info>

9122

MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories."

</info>

Uniquely identifies the type of the target system for

9127

which packages are being built.

9128

This variable allows output for different types of target

9129

systems to be put into different subdirectories of the same

output directory.

</para>

<para>

The default value of this variable is:

9135

9136

${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}

</literallayout>

Some classes (e.g.

modify the <filename>MULTIMACH_TARGET_SYS</filename> value.

</para>

<para>

See the

variable for an example.

9147

See the

9148

9149

variable for more information.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>

9159

<info>

9160

NATIVELSBSTRING[doc] = "A string identifying the host distribution."

</info>

A string identifying the host distribution.

9165

Strings consist of the host distributor ID

9166

followed by the release, as reported by the

9167

<filename>lsb_release</filename> tool

9168

or as read from <filename>/etc/lsb-release</filename>.

9169

For example, when running a build on Ubuntu 12.10, the value

9170

is "Ubuntu-12.10".

9171

If this information is unable to be determined, the value

9172

resolves to "Unknown".

</para>

<para>

This variable is used by default to isolate native shared

9177

state packages for different distributions (e.g. to avoid

9178

problems with <filename>glibc</filename> version

9179

incompatibilities).

9180

Additionally, the variable is checked against

9181

9182

if that variable is set.

</para>

</glossdef>

</glossentry>

<info>

NM[doc] = "Minimal command and arguments to run 'nm'."

</info>

The minimal command and arguments to run

9194

<filename>nm</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-NO_GENERIC_LICENSE'><glossterm>NO_GENERIC_LICENSE</glossterm>

9200

<info>

9201

NO_GENERIC_LICENSE[doc] = "Used to allow copying a license that does not exist in common licenses."

</info>

Avoids QA errors when you use a non-common, non-CLOSED

9206

license in a recipe.

9207

Packages exist, such as the linux-firmware package, with

9208

many licenses that are not in any way common.

9209

Also, new licenses are added occasionally to avoid

9210

introducing a lot of common license files, which are only

9211

applicable to a specific package.

9212

<filename>NO_GENERIC_LICENSE</filename> is used to allow

9213

copying a license that does not exist in common licenses.

</para>

<para>

The following example shows how to add

9218

<filename>NO_GENERIC_LICENSE</filename> to a recipe:

9219

9220

NO_GENERIC_LICENSE[<replaceable>license_name</replaceable>] = "<replaceable>license_file_in_fetched_source</replaceable>"

9221

</literallayout>

9222

The following is an example that uses the

9223

<filename>LICENSE.Abilis.txt</filename> file as the license

9224

from the fetched source:

9225

9226

NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>

9233

<info>

9234

NO_RECOMMENDATIONS[doc] = "When set to '1', no recommended packages will be installed. Some recommended packages might be required for certain system functionality, such as kernel-modules. It is up to the user to add packages to IMAGE_INSTALL as needed."

</info>

Prevents installation of all "recommended-only" packages.

9239

Recommended-only packages are packages installed only

through the

variable).

Setting the <filename>NO_RECOMMENDATIONS</filename> variable

9244

to "1" turns this feature on:

9245

9246

NO_RECOMMENDATIONS = "1"

</literallayout>

</para>

<para>

You can set this variable globally in your

9252

<filename>local.conf</filename> file or you can attach it to

9253

a specific image recipe by using the recipe name override:

9254

9255

NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "1"

</literallayout>

</para>

<para>

It is important to realize that if you choose to not install

9261

packages using this variable and some other packages are

9262

dependent on them (i.e. listed in a recipe's

9263

9264

variable), the OpenEmbedded build system ignores your

9265

request and will install the packages to avoid dependency

9266

errors.

9267

<note>

9268

Some recommended packages might be required for certain

9269

system functionality, such as kernel modules.

9270

It is up to you to add packages with the

variable.

</note>

</para>

<para>

Support for this variable exists only when using the

9278

IPK and RPM packaging backend.

9279

Support does not exist for DEB.

</para>

<para>

See the

and the

variables for related information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-NOAUTOPACKAGEDEBUG'><glossterm>NOAUTOPACKAGEDEBUG</glossterm>

9293

<info>

9294

NOAUTOPACKAGEDEBUG[doc] = "Disables auto package from splitting .debug files."

</info>

Disables auto package from splitting

9299

<filename>.debug</filename> files. If a recipe requires

9300

<filename>FILES_${PN}-dbg</filename> to be set manually,

9301

the <filename>NOAUTOPACKAGEDEBUG</filename> can be defined

9302

allowing you to define the content of the debug package.

9303

For example:

9304

9305

NOAUTOPACKAGEDEBUG = "1"

9306

FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"

9307

FILES_${PN}-dbg = "/usr/src/debug/"

9308

FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"

</literallayout>

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-OBJCOPY'><glossterm>OBJCOPY</glossterm>

9318

<info>

9319

OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'."

</info>

The minimal command and arguments to run

9324

<filename>objcopy</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-OBJDUMP'><glossterm>OBJDUMP</glossterm>

9330

<info>

9331

OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'."

</info>

The minimal command and arguments to run

9336

<filename>objdump</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>

9342

<info>

9343

OE_BINCONFIG_EXTRA_MANGLE[doc] = "When a recipe inherits the binconfig.bbclass class, this variable specifies additional arguments passed to the "sed" command."

</info>

When inheriting the

class, this variable

specifies additional arguments passed to the "sed" command.

9351

The sed command alters any paths in configuration scripts

9352

that have been set up during compilation.

9353

Inheriting this class results in all paths in these scripts

9354

being changed to point into the

9355

<filename>sysroots/</filename> directory so that all builds

9356

that use the script will use the correct directories

9357

for the cross compiling layout.

</para>

<para>

See the <filename>meta/classes/binconfig.bbclass</filename>

9362

in the

9363

9364

for details on how this class applies these additional

9365

sed command arguments.

9366

For general information on the

9367

<filename>binconfig</filename> class, see the

9368

"<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"

section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>

9375

<info>

9376

OE_IMPORTS[doc] = "An internal variable used to tell the OpenEmbedded build system what Python modules to import for every Python function run by the system."

</info>

An internal variable used to tell the OpenEmbedded build

9381

system what Python modules to import for every Python

9382

function run by the system.

</para>

<note>

Do not set this variable.

9387

It is for internal use only.

</note>

</glossdef>

</glossentry>

<glossentry id='var-OE_INIT_ENV_SCRIPT'><glossterm>OE_INIT_ENV_SCRIPT</glossterm>

9393

<info>

9394

OE_INIT_ENV_SCRIPT[doc] = "The name of the build environment setup script for the purposes of setting up the environment within the extensible SDK."

</info>

The name of the build environment setup script for the

9399

purposes of setting up the environment within the

9400

extensible SDK.

9401

The default value is "oe-init-build-env".

</para>

<para>

If you use a custom script to set up your build

9406

environment, set the

9407

<filename>OE_INIT_ENV_SCRIPT</filename> variable to its

name.

</para>

</glossdef>

</glossentry>

<glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>

9414

<info>

9415

OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system."

</info>

Controls how the OpenEmbedded build system spawns

9420

interactive terminals on the host development system

9421

(e.g. using the BitBake command with the

9422

<filename>-c devshell</filename> command-line option).

9423

For more information, see the

9424

"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section

9425

in the Yocto Project Development Tasks Manual.

</para>

<para>

You can use the following values for the

9430

<filename>OE_TERMINAL</filename> variable:

auto

gnome

xfce

rxvt

screen

konsole

none

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>

9445

<info>

9446

OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced."

</info>

The directory from which the top-level build environment

9451

setup script is sourced.

9452

The Yocto Project provides a top-level build environment

9453

setup script:

9454

9455

When you run this script, the

9456

<filename>OEROOT</filename> variable resolves to the

9457

directory that contains the script.

</para>

<para>

For additional information on how this variable is used,

9462

see the initialization script.

</para>

</glossdef>

</glossentry>

<glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>

9468

<info>

9469

OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support."

</info>

Declares the oldest version of the Linux kernel that the

9474

produced binaries must support.

9475

This variable is passed into the build of the Embedded

9476

GNU C Library (<filename>glibc</filename>).

</para>

<para>

The default for this variable comes from the

9481

<filename>meta/conf/bitbake.conf</filename> configuration

9482

file.

9483

You can override this default by setting the variable

9484

in a custom distribution configuration file.

</para>

</glossdef>

</glossentry>

<glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>

9490

<info>

9491

OVERRIDES[doc] = "A colon-separated list of overrides that currently apply."

</info>

A colon-separated list of overrides that currently apply.

9496

Overrides are a BitBake mechanism that allows variables to

9497

be selectively overridden at the end of parsing.

9498

The set of overrides in <filename>OVERRIDES</filename>

9499

represents the "state" during building, which includes

9500

the current recipe being built, the machine for which

9501

it is being built, and so forth.

</para>

<para>

As an example, if the string "an-override" appears as an

9506

element in the colon-separated list in

9507

<filename>OVERRIDES</filename>, then the following

9508

assignment will override <filename>FOO</filename> with the

9509

value "overridden" at the end of parsing:

9510

9511

FOO_an-override = "overridden"

9512

</literallayout>

9513

See the

9514

"<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"

9515

section in the BitBake User Manual for more information on

9516

the overrides mechanism.

</para>

<para>

The default value of <filename>OVERRIDES</filename>

9521

includes the values of the

and

variables.

Another important override included by default is

9528

<filename>pn-${PN}</filename>.

9529

This override allows variables to be set for a single

9530

recipe within configuration (<filename>.conf</filename>)

files.

Here is an example:

FOO_pn-myrecipe = "myrecipe-specific value"

9535

</literallayout>

9536

9537

An easy way to see what overrides apply is to search for

9538

<filename>OVERRIDES</filename> in the output of the

9539

<filename>bitbake -e</filename> command.

9540

See the

9541

"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-debugging-viewing-variable-values'>Viewing Variable Values</ulink>"

9542

section in the Yocto Project Development Tasks

9543

Manual for more information.

</note>

</para>

</glossdef>

</glossentry>

</glossdiv>

<info>

P[doc] = "The recipe name and version. P is comprised of ${PN}-${PV}."

</info>

The recipe name and version.

9559

<filename>P</filename> is comprised of the following:

${PN}-${PV}

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_ADD_METADATA'><glossterm>PACKAGE_ADD_METADATA</glossterm>

9568

<info>

9569

PACKAGE_ADD_METADATA[doc] = "This variable defines additional metadata to add to packages."

</info>

9574

This variable defines additional metdata to add to packages.

</para>

<para>

You may find you need to inject additional metadata into

9579

packages. This variable allows you to do that by setting

9580

the injected data as the value. Multiple fields can be

9581

added by splitting the content with the literal separator

"\n".

</para>

<para>

The suffixes '_IPK', '_DEB', or '_RPM' can be applied to

9587

the variable to do package type specific settings. It can

9588

also be made package specific by using the package name as

a suffix.

</para>

<para>

You can find out more about applying this variable in

9594

the

9595

"<ulink url='&YOCTO_DOCS_DEV_URL;#adding-custom-metadata-to-packages'>Adding custom metadata to packages</ulink>"

9596

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>

9602

<info>

9603

PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."

</info>

The architecture of the resulting package or packages.

</para>

<para>

By default, the value of this variable is set to

9612

9613

when building for the target,

9614

9615

when building for the

9616

build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building

for the SDK.

<note>

See

for more information.

9622

</note>

9623

However, if your recipe's output packages are built

9624

specific to the target machine rather than generally for

9625

the architecture of the machine, you should set

9626

<filename>PACKAGE_ARCH</filename> to the value of

9627

9628

in the recipe as follows:

9629

9630

PACKAGE_ARCH = "${MACHINE_ARCH}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm>

9637

<info>

9638

PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority."

</info>

Specifies a list of architectures compatible with

9643

the target machine.

9644

This variable is set automatically and should not

9645

normally be hand-edited.

9646

Entries are separated using spaces and listed in order

9647

of priority.

9648

The default value for

9649

<filename>PACKAGE_ARCHS</filename> is "all any noarch

9650

${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>

9656

<info>

9657

PACKAGE_BEFORE_PN[doc] = "Enables easily adding packages to PACKAGES before ${PN} so that the packages can pick up files that would normally be included in the default package."

</info>

Enables easily adding packages to

9662

<filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>

9663

before <filename>${<link linkend='var-PN'>PN</link>}</filename>

9664

so that those added packages can pick up files that would normally be

9665

included in the default package.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>

9671

<info>

9672

PACKAGE_CLASSES[doc] = "This variable specifies the package manager to use when packaging data. It is set in the conf/local.conf file in the Build Directory."

</info>

This variable, which is set in the

9677

<filename>local.conf</filename> configuration file found in

9678

the <filename>conf</filename> folder of the

9679

9680

specifies the package manager the OpenEmbedded build system

9681

uses when packaging data.

</para>

<para>

You can provide one or more of the following arguments for

9686

the variable:

9687

9688

PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"

9689

</literallayout>

9690

<note><title>Warning</title>

9691

While it is a legal option, the

9692

<filename>package_tar</filename> class has limited

9693

functionality due to no support for package

9694

dependencies by that backend.

9695

Therefore, it is recommended that you do not use it.

9696

</note>

9697

The build system uses only the first argument in the list

9698

as the package manager when creating your image or SDK.

9699

However, packages will be created using any additional

9700

packaging classes you specify.

9701

For example, if you use the following in your

9702

<filename>local.conf</filename> file:

9703

9704

PACKAGE_CLASSES ?= "package_ipk"

9705

</literallayout>

9706

The OpenEmbedded build system uses the IPK package manager

9707

to create your image or SDK.

</para>

<para>

For information on packaging and build performance effects

9712

as a result of the package manager in use, see the

9713

"<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"

section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm>PACKAGE_DEBUG_SPLIT_STYLE</glossterm>

9720

<info>

9721

PACKAGE_DEBUG_SPLIT_STYLE[doc] = "Determines how to split up the binary and debug information when creating *-dbg packages to be used with the GNU Project Debugger (GDB)."

</info>

Determines how to split up the binary and debug information

9726

when creating <filename>*-dbg</filename> packages to be

9727

used with the GNU Project Debugger (GDB).

</para>

<para>

With the

<filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,

9733

you can control where debug information, which can include

9734

or exclude source files, is stored:

9735

9736

9737

".debug": Debug symbol files are placed next

9738

to the binary in a <filename>.debug</filename>

9739

directory on the target.

9740

For example, if a binary is installed into

9741

<filename>/bin</filename>, the corresponding debug

9742

symbol files are installed in

9743

<filename>/bin/.debug</filename>.

9744

Source files are placed in

9745

<filename>/usr/src/debug</filename>.

9746

</para></listitem>

9747

9748

"debug-file-directory": Debug symbol files are

9749

placed under <filename>/usr/lib/debug</filename>

9750

on the target, and separated by the path from where

9751

the binary is installed.

9752

For example, if a binary is installed in

9753

<filename>/bin</filename>, the corresponding debug

9754

symbols are installed in

9755

<filename>/usr/lib/debug/bin</filename>.

9756

Source files are placed in

9757

<filename>/usr/src/debug</filename>.

9758

</para></listitem>

9759

9760

"debug-without-src": The same behavior as

9761

".debug" previously described with the exception

9762

that no source files are installed.

9763

</para></listitem>.

9764

9765

"debug-with-srcpkg": The same behavior as

9766

".debug" previously described with the exception

9767

that all source files are placed in a separate

9768

<filename>*-src</filename> pkg.

9769

This is the default behavior.

</para></listitem>

</itemizedlist>

</para>

<para>

You can find out more about debugging using GDB by reading

9776

the

9777

"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"

9778

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_EXCLUDE_COMPLEMENTARY'><glossterm>PACKAGE_EXCLUDE_COMPLEMENTARY</glossterm>

9784

<info>

9785

PACKAGE_EXCLUDE_COMPLEMENTARY[doc] = "Prevents specific packages from being installed when you are installing complementary packages."

</info>

Prevents specific packages from being installed when

9790

you are installing complementary packages.

</para>

<para>

You might find that you want to prevent installing certain

9795

packages when you are installing complementary packages.

9796

For example, if you are using

9797

9798

to install <filename>dev-pkgs</filename>, you might not want

9799

to install all packages from a particular multilib.

9800

If you find yourself in this situation, you can use the

9801

<filename>PACKAGE_EXCLUDE_COMPLEMENTARY</filename> variable

9802

to specify regular expressions to match the packages you

want to exclude.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>

9809

<info>

9810

PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated."

</info>

Lists packages that should not be installed into an image.

9815

For example:

9816

9817

PACKAGE_EXCLUDE = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."

</literallayout>

</para>

<para>

You can set this variable globally in your

9823

<filename>local.conf</filename> file or you can attach it to

9824

a specific image recipe by using the recipe name override:

9825

9826

PACKAGE_EXCLUDE_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"

</literallayout>

</para>

<para>

If you choose to not install

9832

a package using this variable and some other package is

9833

dependent on it (i.e. listed in a recipe's

9834

9835

variable), the OpenEmbedded build system generates a fatal

9836

installation error.

9837

Because the build system halts the process with a fatal

9838

error, you can use the variable with an iterative

9839

development process to remove specific components from a

system.

</para>

<para>

Support for this variable exists only when using the

9845

IPK and RPM packaging backend.

9846

Support does not exist for DEB.

</para>

<para>

See the

and the

variables for related information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>

9860

<info>

9861

PACKAGE_EXTRA_ARCHS[doc] = "Specifies the list of architectures compatible with the device CPU. This variable is useful when you build for several different devices that use miscellaneous processors."

</info>

Specifies the list of architectures compatible with the device CPU.

9866

This variable is useful when you build for several different devices that use

9867

miscellaneous processors such as XScale and ARM926-EJS.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_FEED_ARCHS'><glossterm>PACKAGE_FEED_ARCHS</glossterm>

9873

<info>

9874

PACKAGE_FEED_ARCHS[doc] = "Optionally specifies user-defined package architectures when constructing package feed URIs."

</info>

Optionally specifies the package architectures used as

9879

part of the package feed URIs during the build.

9880

When used, the <filename>PACKAGE_FEED_ARCHS</filename>

9881

variable is appended to the final package feed URI, which

9882

is constructed using the

and

variables.

You can use the <filename>PACKAGE_FEEDS_ARCHS</filename>

9889

variable to whitelist specific package architectures.

9890

If you do not need to whitelist specific architectures,

9891

which is a common case, you can omit this variable.

9892

Omitting the variable results in all available

9893

architectures for the current machine being included

9894

into remote package feeds.

</note>

</para>

<para>

Consider the following example where the

9900

<filename>PACKAGE_FEED_URIS</filename>,

9901

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

9902

<filename>PACKAGE_FEED_ARCHS</filename> variables are

9903

defined in your <filename>local.conf</filename> file:

9904

9905

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

9906

https://example.com/packagerepos/updates"

9907

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

9908

PACKAGE_FEED_ARCHS = "all core2-64"

9909

</literallayout>

9910

Given these settings, the resulting package feeds are

9911

as follows:

9912

9913

https://example.com/packagerepos/release/rpm/all

9914

https://example.com/packagerepos/release/rpm/core2-64

9915

https://example.com/packagerepos/release/rpm-dev/all

9916

https://example.com/packagerepos/release/rpm-dev/core2-64

9917

https://example.com/packagerepos/updates/rpm/all

9918

https://example.com/packagerepos/updates/rpm/core2-64

9919

https://example.com/packagerepos/updates/rpm-dev/all

9920

https://example.com/packagerepos/updates/rpm-dev/core2-64

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_FEED_BASE_PATHS'><glossterm>PACKAGE_FEED_BASE_PATHS</glossterm>

9927

<info>

9928

PACKAGE_FEED_BASE_PATHS[doc] = "Specifies base path used when constructing package feed URIs."

</info>

Specifies the base path used when constructing package feed

9933

URIs.

9934

The <filename>PACKAGE_FEED_BASE_PATHS</filename> variable

9935

makes up the middle portion of a package feed URI used

9936

by the OpenEmbedded build system.

9937

The base path lies between the

and

variables.

</para>

<para>

Consider the following example where the

9946

<filename>PACKAGE_FEED_URIS</filename>,

9947

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

9948

<filename>PACKAGE_FEED_ARCHS</filename> variables are

9949

defined in your <filename>local.conf</filename> file:

9950

9951

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

9952

https://example.com/packagerepos/updates"

9953

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

9954

PACKAGE_FEED_ARCHS = "all core2-64"

9955

</literallayout>

9956

Given these settings, the resulting package feeds are

9957

as follows:

9958

9959

https://example.com/packagerepos/release/rpm/all

9960

https://example.com/packagerepos/release/rpm/core2-64

9961

https://example.com/packagerepos/release/rpm-dev/all

9962

https://example.com/packagerepos/release/rpm-dev/core2-64

9963

https://example.com/packagerepos/updates/rpm/all

9964

https://example.com/packagerepos/updates/rpm/core2-64

9965

https://example.com/packagerepos/updates/rpm-dev/all

9966

https://example.com/packagerepos/updates/rpm-dev/core2-64

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_FEED_URIS'><glossterm>PACKAGE_FEED_URIS</glossterm>

9973

<info>

9974

PACKAGE_FEED_URIS[doc] = "Specifies the front portion of the package feed URI used by the OpenEmbedded build system."

</info>

Specifies the front portion of the package feed URI

9979

used by the OpenEmbedded build system.

9980

Each final package feed URI is comprised of

9981

<filename>PACKAGE_FEED_URIS</filename>,

and

variables.

</para>

<para>

Consider the following example where the

9990

<filename>PACKAGE_FEED_URIS</filename>,

9991

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

9992

<filename>PACKAGE_FEED_ARCHS</filename> variables are

9993

defined in your <filename>local.conf</filename> file:

9994

9995

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

9996

https://example.com/packagerepos/updates"

9997

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

9998

PACKAGE_FEED_ARCHS = "all core2-64"

9999

</literallayout>

10000

Given these settings, the resulting package feeds are

10001

as follows:

10002

10003

https://example.com/packagerepos/release/rpm/all

10004

https://example.com/packagerepos/release/rpm/core2-64

10005

https://example.com/packagerepos/release/rpm-dev/all

10006

https://example.com/packagerepos/release/rpm-dev/core2-64

10007

https://example.com/packagerepos/updates/rpm/all

10008

https://example.com/packagerepos/updates/rpm/core2-64

10009

https://example.com/packagerepos/updates/rpm-dev/all

10010

https://example.com/packagerepos/updates/rpm-dev/core2-64

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>

10017

<info>

10018

PACKAGE_INSTALL[doc] = "List of the packages to be installed into the image. The variable is generally not user-defined and uses IMAGE_INSTALL as part of the list."

</info>

The final list of packages passed to the package manager

10023

for installation into the image.

</para>

<para>

Because the package manager controls actual installation

10028

of all packages, the list of packages passed using

10029

<filename>PACKAGE_INSTALL</filename> is not the final list

10030

of packages that are actually installed.

10031

This variable is internal to the image construction

10032

code.

10033

Consequently, in general, you should use the

10034

10035

variable to specify packages for installation.

10036

The exception to this is when working with

the

image.

When working with an initial RAM filesystem (initramfs)

10041

image, use the <filename>PACKAGE_INSTALL</filename>

10042

variable.

10043

For information on creating an initramfs, see the

10044

"<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"

10045

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_INSTALL_ATTEMPTONLY'><glossterm>PACKAGE_INSTALL_ATTEMPTONLY</glossterm>

10051

<info>

10052

PACKAGE_INSTALL_ATTEMPTONLY[doc] = "List of packages attempted to be installed when creating an image. If a listed package fails to install, the build system does not generate an error. This variable is generally not user-defined."

</info>

Specifies a list of packages the OpenEmbedded build

10057

system attempts to install when creating an image.

10058

If a listed package fails to install, the build system

10059

does not generate an error.

10060

This variable is generally not user-defined.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm>

10066

<info>

10067

PACKAGE_PREPROCESS_FUNCS[doc] = "Specifies a list of functions run to pre-process the PKGD directory prior to splitting the files out to individual packages."

</info>

Specifies a list of functions run to pre-process the

10072

10073

directory prior to splitting the files out to individual

packages.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_WRITE_DEPS'><glossterm>PACKAGE_WRITE_DEPS</glossterm>

10080

<info>

10081

PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script dependencies on native/cross tools."

</info>

Specifies a list of dependencies for post-installation and

10086

pre-installation scripts on native/cross tools.

10087

If your post-installation or pre-installation script can

10088

execute at rootfs creation time rather than on the

10089

target but depends on a native tool in order to execute,

10090

you need to list the tools in

10091

<filename>PACKAGE_WRITE_DEPS</filename>.

</para>

<para>

For information on running post-installation scripts, see

10096

the

10097

"<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"

10098

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>

10104

<info>

10105

PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis."

</info>

This variable provides a means of enabling or disabling

10110

features of a recipe on a per-recipe basis.

10111

<filename>PACKAGECONFIG</filename> blocks are defined

10112

in recipes when you specify features and then arguments

10113

that define feature behaviors.

10114

Here is the basic block structure (broken over multiple

10115

lines for readability):

10116

10117

PACKAGECONFIG ??= "f1 f2 f3 ..."

10118

PACKAGECONFIG[f1] = "\

--with-f1, \

--without-f1, \

build-deps-for-f1, \

runtime-deps-for-f1, \

10123

runtime-recommends-for-f1, \

10124

packageconfig-conflicts-for-f1 \

10125

"

10126

PACKAGECONFIG[f2] = "\

10127

... and so on and so on ...

</literallayout>

</para>

<para>

The <filename>PACKAGECONFIG</filename>

10133

variable itself specifies a space-separated list of the

10134

features to enable.

10135

Following the features, you can determine the behavior of

10136

each feature by providing up to six order-dependent

10137

arguments, which are separated by commas.

10138

You can omit any argument you like but must retain the

10139

separating commas.

10140

The order is important and specifies the following:

10141

10142

<listitem><para>Extra arguments

10143

that should be added to the configure script

10144

argument list

10145

(<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>

10146

or

10147

10148

if the feature is enabled.</para></listitem>

10149

<listitem><para>Extra arguments

10150

that should be added to <filename>EXTRA_OECONF</filename>

10151

or <filename>PACKAGECONFIG_CONFARGS</filename>

10152

if the feature is disabled.

10153

</para></listitem>

10154

<listitem><para>Additional build dependencies

10155

(<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)

10156

that should be added if the feature is enabled.

10157

</para></listitem>

10158

<listitem><para>Additional runtime dependencies

10159

(<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)

10160

that should be added if the feature is enabled.

10161

</para></listitem>

10162

<listitem><para>Additional runtime recommendations

10163

(<link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)

10164

that should be added if the feature is enabled.

10165

</para></listitem>

10166

<listitem><para>Any conflicting (that is, mutually

10167

exclusive) <filename>PACKAGECONFIG</filename>

10168

settings for this feature.

</para></listitem>

</orderedlist>

</para>

<para>

Consider the following

10175

<filename>PACKAGECONFIG</filename> block taken from the

10176

<filename>librsvg</filename> recipe.

10177

In this example the feature is <filename>gtk</filename>,

10178

which has three arguments that determine the feature's

10179

behavior.

10180

10181

PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"

10182

</literallayout>

10183

The <filename>--with-gtk3</filename> and

10184

<filename>gtk+3</filename> arguments apply only if

10185

the feature is enabled.

10186

In this case, <filename>--with-gtk3</filename> is

10187

added to the configure script argument list and

10188

<filename>gtk+3</filename> is added to

10189

<filename>DEPENDS</filename>.

10190

On the other hand, if the feature is disabled say through

10191

a <filename>.bbappend</filename> file in another layer, then

10192

the second argument <filename>--without-gtk3</filename> is

10193

added to the configure script instead.

</para>

<para>

The basic <filename>PACKAGECONFIG</filename> structure

10198

previously described holds true regardless of whether you

10199

are creating a block or changing a block.

10200

When creating a block, use the structure inside your

recipe.

</para>

<para>

If you want to change an existing

10206

<filename>PACKAGECONFIG</filename> block, you can do so

10207

one of two ways:

10208

10209

<listitem><para><emphasis>Append file:</emphasis>

10210

Create an append file named

10211

<replaceable>recipename</replaceable><filename>.bbappend</filename>

10212

in your layer and override the value of

10213

<filename>PACKAGECONFIG</filename>.

10214

You can either completely override the variable:

10215

10216

PACKAGECONFIG = "f4 f5"

10217

</literallayout>

10218

Or, you can just append the variable:

10219

10220

PACKAGECONFIG_append = " f4"

10221

</literallayout></para></listitem>

10222

<listitem><para><emphasis>Configuration file:</emphasis>

10223

This method is identical to changing the block

10224

through an append file except you edit your

10225

<filename>local.conf</filename> or

10226

<filename><replaceable>mydistro</replaceable>.conf</filename> file.

10227

As with append files previously described,

10228

you can either completely override the variable:

10229

10230

PACKAGECONFIG_pn-<replaceable>recipename</replaceable> = "f4 f5"

10231

</literallayout>

10232

Or, you can just amend the variable:

10233

10234

PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4"

10235

</literallayout></para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGECONFIG_CONFARGS'><glossterm>PACKAGECONFIG_CONFARGS</glossterm>

10242

<info>

10243

PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from the PACKAGECONFIG setting."

</info>

A space-separated list of configuration options generated

from the

setting.

</para>

<para>

Classes such as

and

use <filename>PACKAGECONFIG_CONFARGS</filename> to pass

10259

<filename>PACKAGECONFIG</filename> options to

10260

<filename>configure</filename> and

10261

<filename>cmake</filename>, respectively.

10262

If you are using

10263

<filename>PACKAGECONFIG</filename> but not a class that

10264

handles the <filename>do_configure</filename> task, then

10265

you need to use

10266

<filename>PACKAGECONFIG_CONFARGS</filename> appropriately.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm>

10272

<info>

10273

PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe."

</info>

For recipes inheriting the

10278

10279

class, setting

10280

<filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to

10281

"1" specifies that the normal complementary packages

10282

(i.e. <filename>-dev</filename>,

10283

<filename>-dbg</filename>, and so forth) should not be

10284

automatically created by the

10285

<filename>packagegroup</filename> recipe, which is the

default behavior.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>

10292

<info>

10293

PACKAGES[doc] = "The list of packages the recipe creates."

</info>

The list of packages the recipe creates.

10298

The default value is the following:

10299

10300

${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}

</literallayout>

</para>

<para>

During packaging, the

10306

10307

task goes through <filename>PACKAGES</filename> and uses

10308

the

10309

10310

variable corresponding to each package to assign files to

10311

the package.

10312

If a file matches the <filename>FILES</filename> variable

10313

for more than one package in <filename>PACKAGES</filename>,

10314

it will be assigned to the earliest (leftmost) package.

</para>

<para>

Packages in the variable's list that are empty (i.e. where

10319

none of the patterns in

10320

<filename>FILES_</filename><replaceable>pkg</replaceable>

10321

match any files installed by the

10322

10323

task) are not generated, unless generation is forced through

the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>

10332

<info>

10333

PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes."

</info>

A promise that your recipe satisfies runtime dependencies

10338

for optional modules that are found in other recipes.

10339

<filename>PACKAGES_DYNAMIC</filename>

10340

does not actually satisfy the dependencies, it only states that

10341

they should be satisfied.

10342

For example, if a hard, runtime dependency

10343

(<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)

10344

of another package is satisfied

10345

at build time through the <filename>PACKAGES_DYNAMIC</filename>

10346

variable, but a package with the module name is never actually

10347

produced, then the other package will be broken.

10348

Thus, if you attempt to include that package in an image,

10349

you will get a dependency failure from the packaging system

during the

task.

</para>

<para>

Typically, if there is a chance that such a situation can

10357

occur and the package that is not created is valid

10358

without the dependency being satisfied, then you should use

10359

10360

(a soft runtime dependency) instead of

10361

<filename>RDEPENDS</filename>.

</para>

<para>

For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>

10366

variable when you are splitting packages, see the

10367

"<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section

10368

in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>

10374

<info>

10375

PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages."

</info>

Specifies a list of functions run to perform additional

10380

splitting of files into individual packages.

10381

Recipes can either prepend to this variable or prepend

10382

to the <filename>populate_packages</filename> function

10383

in order to perform additional package splitting.

10384

In either case, the function should set

and other packaging variables appropriately in order to

10389

perform the desired splitting.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>

10395

<info>

10396

PARALLEL_MAKE[doc] = "Specifies extra options that are passed to the make command during the compile tasks. This variable is usually in the form -j x, where x represents the maximum number of parallel threads make can run."

</info>

Extra options passed to the <filename>make</filename>

10401

command during the

10402

10403

task in order to specify parallel compilation on the local

10404

build host.

10405

This variable is usually in the form "-j <replaceable>x</replaceable>",

10406

where <replaceable>x</replaceable> represents the maximum

10407

number of parallel threads <filename>make</filename> can

10408

run.

10409

<note><title>Caution</title>

10410

In order for <filename>PARALLEL_MAKE</filename> to be

10411

effective, <filename>make</filename> must be called

10412

with

10413

<filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.

10414

An easy way to ensure this is to use the

10415

<filename>oe_runmake</filename> function.

</note>

</para>

<para>

By default, the OpenEmbedded build system automatically

10421

sets this variable to be equal to the number of cores the

10422

build system uses.

10423

<note>

10424

If the software being built experiences dependency

10425

issues during the <filename>do_compile</filename>

10426

task that result in race conditions, you can clear

10427

the <filename>PARALLEL_MAKE</filename> variable within

10428

the recipe as a workaround.

10429

For information on addressing race conditions, see the

10430

"<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"

10431

section in the Yocto Project Development Tasks Manual.

10432

</note>

10433

For single socket systems (i.e. one CPU), you should not

10434

have to override this variable to gain optimal parallelism

10435

during builds.

10436

However, if you have very large systems that employ

10437

multiple physical CPUs, you might want to make sure the

10438

<filename>PARALLEL_MAKE</filename> variable is not

10439

set higher than "-j 20".

</para>

<para>

For more information on speeding up builds, see the

10444

"<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"

10445

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>

10451

<info>

10452

PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation."

</info>

Extra options passed to the

10457

<filename>make install</filename> command during the

10458

10459

task in order to specify parallel installation.

10460

This variable defaults to the value of

10461

10462

<note><title>Notes and Cautions</title>

10463

<para>In order for <filename>PARALLEL_MAKEINST</filename>

10464

to be

10465

effective, <filename>make</filename> must be called

10466

with

10467

<filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.

10468

An easy way to ensure this is to use the

10469

<filename>oe_runmake</filename> function.</para>

10470

10471

<para>If the software being built experiences

10472

dependency issues during the

10473

<filename>do_install</filename> task that result in

10474

race conditions, you can clear the

10475

<filename>PARALLEL_MAKEINST</filename> variable within

10476

the recipe as a workaround.

10477

For information on addressing race conditions, see the

10478

"<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"

10479

section in the Yocto Project Development Tasks Manual.

</para>

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>

10487

<info>

10488

PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution."

</info>

Determines the action to take when a patch fails.

10493

You can set this variable to one of two values: "noop" and

"user".

</para>

<para>

The default value of "noop" causes the build to simply fail

10499

when the OpenEmbedded build system cannot successfully

10500

apply a patch.

10501

Setting the value to "user" causes the build system to

10502

launch a shell and places you in the right location so that

10503

you can manually resolve the conflicts.

</para>

<para>

Set this variable in your

10508

<filename>local.conf</filename> file.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>

10514

<info>

10515

PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch."

</info>

Specifies the utility used to apply patches for a recipe

during the

task.

You can specify one of three utilities: "patch", "quilt", or

10524

"git".

10525

The default utility used is "quilt" except for the

10526

quilt-native recipe itself.

10527

Because the quilt tool is not available at the

10528

time quilt-native is being patched, it uses "patch".

</para>

<para>

If you wish to use an alternative patching tool, set the

10533

variable in the recipe using one of the following:

PATCHTOOL = "patch"

PATCHTOOL = "quilt"

PATCHTOOL = "git"

</literallayout>

</para>

</glossdef>

</glossentry>

<info>

PE[doc] = "The epoch of the recipe. The default value is '0'. The field is used to make upgrades possible when the versioning scheme changes in some backwards incompatible way."

</info>

The epoch of the recipe.

10550

By default, this variable is unset.

10551

The variable is used to make upgrades possible when the

10552

versioning scheme changes in some backwards incompatible

way.

</para>

<para>

<filename>PE</filename> is the default value of the

variable.

</para>

</glossdef>

</glossentry>

<info>

PF[doc] = "Specifies the recipe or package name and includes all version and revision numbers. This variable is comprised of ${PN}-${EXTENDPE}${PV}-${PR}."

</info>

Specifies the recipe or package name and includes all version and revision

10571

numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and

10572

<filename>bash-4.2-r1/</filename>).

10573

This variable is comprised of the following:

10574

10575

${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>

10582

<info>

10583

PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf."

</info>

When inheriting the

class, this variable identifies packages that contain

10590

the pixbuf loaders used with

10591

<filename>gdk-pixbuf</filename>.

10592

By default, the <filename>pixbufcache</filename> class

10593

assumes that the loaders are in the recipe's main package

10594

(i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).

10595

Use this variable if the loaders you need are in a package

10596

other than that main package.

</para>

</glossdef>

</glossentry>

<info>

PKG[doc] = "The name of the resulting package created by the OpenEmbedded build system. When you use this variable, you must use a package name override."

</info>

The name of the resulting package created by the

10608

OpenEmbedded build system.

10609

<note>

10610

When using the <filename>PKG</filename> variable, you

10611

must use a package name override.

</note>

</para>

<para>

For example, when the

10617

10618

class renames the output package, it does so by setting

10619

<filename>PKG_<replaceable>packagename</replaceable></filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PKG_CONFIG_PATH'><glossterm>PKG_CONFIG_PATH</glossterm>

10625

<info>

10626

PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context."

</info>

The path to <filename>pkg-config</filename> files for the

10631

current build context.

10632

<filename>pkg-config</filename> reads this variable

10633

from the environment.

</para>

</glossdef>

</glossentry>

<info>

PKGD[doc] = "Points to the destination directory for files to be packaged before they are split into individual packages."

</info>

Points to the destination directory for files to be

10645

packaged before they are split into individual packages.

10646

This directory defaults to the following:

${WORKDIR}/package

</literallayout>

</para>

<para>

Do not change this default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>

10659

<info>

10660

PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process."

</info>

Points to a shared, global-state directory that holds data

10665

generated during the packaging process.

10666

During the packaging process, the

10667

10668

task packages data for each recipe and installs it into

10669

this temporary, shared area.

10670

This directory defaults to the following, which you should

10671

not change:

10672

10673

${STAGING_DIR_HOST}/pkgdata

10674

</literallayout>

10675

For examples of how this data is used, see the

10676

"<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"

10677

section in the Yocto Project Overview and Concepts Manual

10678

and the

10679

"<ulink url='&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></ulink>"

10680

section in the Yocto Project Development Tasks Manual.

10681

For more information on the shared, global-state directory,

see

</para>

</glossdef>

</glossentry>

<glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>

10689

<info>

10690

PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages."

</info>

Points to the parent directory for files to be packaged

10695

after they have been split into individual packages.

10696

This directory defaults to the following:

10697

10698

${WORKDIR}/packages-split

</literallayout>

</para>

<para>

Under this directory, the build system creates

10704

directories for each package specified in

10705

10706

Do not change this default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>

10712

<info>

10713

PKGDESTWORK[doc] = "Points to a temporary work area where the do_package task saves package metadata."

</info>

Points to a temporary work area where the

10718

10719

task saves package metadata.

10720

The <filename>PKGDESTWORK</filename> location defaults to

the following:

${WORKDIR}/pkgdata

</literallayout>

Do not change this default.

</para>

<para>

The

task copies the package metadata from

10732

<filename>PKGDESTWORK</filename> to

10733

10734

to make it available globally.

</para>

</glossdef>

</glossentry>

<info>

PKGE[doc] = "The epoch of the package(s) built by the recipe."

</info>

The epoch of the package(s) built by the recipe.

10746

By default, <filename>PKGE</filename> is set to

</para>

</glossdef>

</glossentry>

<info>

PKGR[doc] = "The revision of the package(s) built by the recipe."

</info>

The revision of the package(s) built by the recipe.

10759

By default, <filename>PKGR</filename> is set to

</para>

</glossdef>

</glossentry>

<info>

PKGV[doc] = "The version of the package(s) built by the recipe."

</info>

The version of the package(s) built by the

10772

recipe.

10773

By default, <filename>PKGV</filename> is set to

</para>

</glossdef>

</glossentry>

<info>

PN[doc] = "PN refers to a recipe name in the context of a file used by the OpenEmbedded build system as input to create a package."

</info>

This variable can have two separate functions depending on the context: a recipe

10786

name or a resulting package name.

</para>

<para>

<filename>PN</filename> refers to a recipe name in the context of a file used

10791

by the OpenEmbedded build system as input to create a package.

10792

The name is normally extracted from the recipe file name.

10793

For example, if the recipe is named

10794

<filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>

will be "expat".

</para>

<para>

The variable refers to a package name in the context of a file created or produced by the

10800

OpenEmbedded build system.

</para>

<para>

If applicable, the <filename>PN</filename> variable also contains any special

10805

suffix or prefix.

10806

For example, using <filename>bash</filename> to build packages for the native

10807

machine, <filename>PN</filename> is <filename>bash-native</filename>.

10808

Using <filename>bash</filename> to build packages for the target and for Multilib,

10809

<filename>PN</filename> would be <filename>bash</filename> and

10810

<filename>lib64-bash</filename>, respectively.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>

10816

<info>

10817

PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build."

</info>

Lists recipes you do not want the OpenEmbedded build system

10822

to build.

10823

This variable works in conjunction with the

10824

10825

class, which is inherited globally.

</para>

<para>

To prevent a recipe from being built, use the

10830

<filename>PNBLACKLIST</filename> variable in your

10831

<filename>local.conf</filename> file.

10832

Here is an example that prevents

10833

<filename>myrecipe</filename> from being built:

10834

10835

PNBLACKLIST[myrecipe] = "Not supported by our organization."

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-POPULATE_SDK_POST_HOST_COMMAND'><glossterm>POPULATE_SDK_POST_HOST_COMMAND</glossterm>

10842

<info>

10843

POPULATE_SDK_POST_HOST_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created host part of the SDK."

</info>

Specifies a list of functions to call once the

10848

OpenEmbedded build system has created the host part of

10849

the SDK.

10850

You can specify functions separated by semicolons:

10851

10852

POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the SDK path to a command

10858

within a function, you can use

10859

<filename>${SDK_DIR}</filename>, which points to

10860

the parent directory used by the OpenEmbedded build

10861

system when creating SDK output.

10862

See the

10863

10864

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-POPULATE_SDK_POST_TARGET_COMMAND'><glossterm>POPULATE_SDK_POST_TARGET_COMMAND</glossterm>

10870

<info>

10871

POPULATE_SDK_POST_TARGET_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created target part of the SDK."

</info>

Specifies a list of functions to call once the

10876

OpenEmbedded build system has created the target part of

10877

the SDK.

10878

You can specify functions separated by semicolons:

10879

10880

POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the SDK path to a command

10886

within a function, you can use

10887

<filename>${SDK_DIR}</filename>, which points to

10888

the parent directory used by the OpenEmbedded build

10889

system when creating SDK output.

10890

See the

10891

10892

variable for more information.

</para>

</glossdef>

</glossentry>

<info>

PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'."

</info>

The revision of the recipe. The default value for this

10904

variable is "r0".

10905

Subsequent revisions of the recipe conventionally have the

10906

values "r1", "r2", and so forth.

10907

When

10908

10909

increases, <filename>PR</filename> is conventionally reset

10910

to "r0".

10911

<note>

10912

The OpenEmbedded build system does not need the aid of

10913

<filename>PR</filename> to know when to rebuild a

10914

recipe.

10915

The build system uses the task

10916

<ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>input checksums</ulink>

along with the

and

<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state cache</ulink>

10921

mechanisms.

10922

</note>

10923

The <filename>PR</filename> variable primarily becomes

10924

significant when a package manager dynamically installs

10925

packages on an already built image.

10926

In this case, <filename>PR</filename>, which is the default

10927

value of

10928

10929

helps the package manager distinguish which package is the

10930

most recent one in cases where many packages have the same

10931

<filename>PV</filename> (i.e. <filename>PKGV</filename>).

10932

A component having many packages with the same

10933

<filename>PV</filename> usually means that the packages all

10934

install the same upstream version, but with later

10935

(<filename>PR</filename>) version packages including

10936

packaging fixes.

10937

<note>

10938

<filename>PR</filename> does not need to be increased

10939

for changes that do not change the package contents or

10940

metadata.

10941

</note>

10942

Because manually managing <filename>PR</filename> can be

10943

cumbersome and error-prone, an automated solution exists.

10944

See the

10945

"<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"

10946

section in the Yocto Project Development Tasks Manual

10947

for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>

10953

<info>

10954

PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference."

</info>

If multiple recipes provide the same item, this variable

10959

determines which recipe is preferred and thus provides

10960

the item (i.e. the preferred provider).

10961

You should always suffix this variable with the name of the

10962

provided item.

10963

And, you should define the variable using the preferred

10964

recipe's name

10965

(<link linkend='var-PN'><filename>PN</filename></link>).

10966

Here is a common example:

10967

10968

PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"

10969

</literallayout>

10970

In the previous example, multiple recipes are providing

10971

"virtual/kernel".

10972

The <filename>PREFERRED_PROVIDER</filename> variable is

10973

set with the name (<filename>PN</filename>) of the recipe

10974

you prefer to provide "virtual/kernel".

</para>

<para>

Following are more examples:

10979

10980

PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"

10981

PREFERRED_PROVIDER_virtual/libgl ?= "mesa"

10982

</literallayout>

10983

For more information, see the

10984

"<ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>Using Virtual Providers</ulink>"

10985

section in the Yocto Project Development Tasks Manual.

10986

<note>

10987

If you use a <filename>virtual/*</filename> item

10988

with <filename>PREFERRED_PROVIDER</filename>, then any

10989

recipe that

10990

10991

that item but is not selected (defined) by

10992

<filename>PREFERRED_PROVIDER</filename> is prevented

10993

from building, which is usually desirable since this

10994

mechanism is designed to select between mutually

10995

exclusive alternative providers.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>

11002

<info>

11003

PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference."

</info>

If multiple versions of recipes exist, this

11008

variable determines which version is given preference.

11009

You must always suffix the variable with the

11010

11011

you want to select, and you should set the

11012

11013

accordingly for precedence.

</para>

<para>

The <filename>PREFERRED_VERSION</filename> variable

11018

supports limited wildcard use through the

11019

"<filename>%</filename>" character.

11020

You can use the character to match any number of

11021

characters, which can be useful when specifying versions

11022

that contain long revision numbers that potentially change.

11023

Here are two examples:

11024

11025

PREFERRED_VERSION_python = "3.4.0"

11026

PREFERRED_VERSION_linux-yocto = "5.0%"

11027

</literallayout>

11028

<note><title>Important</title>

11029

The use of the "<filename>%</filename>" character

11030

is limited in that it only works at the end of the

11031

string.

11032

You cannot use the wildcard character in any other

11033

location of the string.

</note>

</para>

<para>

The specified version is matched against

11039

11040

which does not necessarily match the version part of

11041

the recipe's filename.

11042

For example, consider two recipes

11043

<filename>foo_1.2.bb</filename> and

11044

<filename>foo_git.bb</filename> where

11045

<filename>foo_git.bb</filename> contains the following

11046

assignment:

11047

11048

PV = "1.1+git${SRCPV}"

11049

</literallayout>

11050

In this case, the correct way to select

11051

<filename>foo_git.bb</filename> is by using an

11052

assignment such as the following:

11053

11054

PREFERRED_VERSION_foo = "1.1+git%"

11055

</literallayout>

11056

Compare that previous example against the following

11057

incorrect example, which does not work:

11058

11059

PREFERRED_VERSION_foo = "git"

</literallayout>

</para>

<para>

Sometimes the <filename>PREFERRED_VERSION</filename>

11065

variable can be set by configuration files in a way that

is hard to change.

You can use

to set a machine-specific override.

11070

Here is an example:

11071

11072

PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%"

11073

</literallayout>

11074

Although not recommended, worst case, you can also use the

11075

"forcevariable" override, which is the strongest override

possible.

Here is an example:

PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%"

11080

</literallayout>

11081

<note>

11082

The <filename>_forcevariable</filename> override is

11083

not handled specially.

11084

This override only works because the default value of

11085

<filename>OVERRIDES</filename> includes

"forcevariable".

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>

11093

<info>

11094

PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."

</info>

Specifies additional paths from which the OpenEmbedded

11099

build system gets source code.

11100

When the build system searches for source code, it first

11101

tries the local download directory.

11102

If that location fails, the build system tries locations

11103

defined by <filename>PREMIRRORS</filename>, the upstream

11104

source, and then locations specified by

in that order.

</para>

<para>

Assuming your distribution

11111

(<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)

11112

is "poky", the default value for

11113

<filename>PREMIRRORS</filename> is defined in the

11114

<filename>conf/distro/poky.conf</filename> file in the

11115

<filename>meta-poky</filename> Git repository.

</para>

<para>

Typically, you could add a specific server for the

11120

build system to attempt before any others by adding

11121

something like the following to the

11122

<filename>local.conf</filename> configuration file in the

11123

11124

11125

PREMIRRORS_prepend = "\

11126

git://.*/.* http://www.yoctoproject.org/sources/ \n \

11127

ftp://.*/.* http://www.yoctoproject.org/sources/ \n \

11128

http://.*/.* http://www.yoctoproject.org/sources/ \n \

11129

https://.*/.* http://www.yoctoproject.org/sources/ \n"

11130

</literallayout>

11131

These changes cause the build system to intercept

11132

Git, FTP, HTTP, and HTTPS requests and direct them to

11133

the <filename>http://</filename> sources mirror.

11134

You can use <filename>file://</filename> URLs to point

11135

to local directories or network shares as well.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PRIORITY'><glossterm>PRIORITY</glossterm>

11141

<info>

11142

PRIORITY[doc] = "Indicates the importance of a package. The default value is 'optional'. Other standard values are 'required', 'standard', and 'extra'."

</info>

Indicates the importance of a package.

</para>

<para>

<filename>PRIORITY</filename> is considered to be part of

11151

the distribution policy because the importance of any given

11152

recipe depends on the purpose for which the distribution

11153

is being produced.

11154

Thus, <filename>PRIORITY</filename> is not normally set

within recipes.

</para>

<para>

You can set <filename>PRIORITY</filename> to "required",

11160

"standard", "extra", and "optional", which is the default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>

11166

<info>

11167

PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver."

</info>

Specifies libraries installed within a recipe that

11172

should be ignored by the OpenEmbedded build system's

11173

shared library resolver.

11174

This variable is typically used when software being

11175

built by a recipe has its own private versions of a

11176

library normally provided by another recipe.

11177

In this case, you would not want the package containing

11178

the private libraries to be set as a dependency on other

11179

unrelated packages that should instead depend on the

11180

package providing the standard version of the library.

</para>

<para>

Libraries specified in this variable should be specified

11185

by their file name.

11186

For example, from the Firefox recipe in meta-browser:

11187

11188

PRIVATE_LIBS = "libmozjs.so \

libxpcom.so \

libnspr4.so \

libxul.so \

libmozalloc.so \

libplc4.so \

libplds4.so"

</literallayout>

</para>

<para>

For more information, see the

11200

"<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"

11201

section in the Yocto Project Overview and Concepts Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>

11207

<info>

11208

PROVIDES[doc] = "A list of aliases that a recipe also provides. These aliases are useful for satisfying dependencies of other recipes during the build as specified by DEPENDS."

</info>

A list of aliases by which a particular recipe can be

11213

known.

11214

By default, a recipe's own

11215

11216

is implicitly already in its <filename>PROVIDES</filename>

11217

list and therefore does not need to mention that it provides itself.

11218

If a recipe uses <filename>PROVIDES</filename>, the

11219

additional aliases are synonyms for the recipe and can

11220

be useful for satisfying dependencies of other recipes during

11221

the build as specified by

11222

<filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.

</para>

<para>

Consider the following example

11227

<filename>PROVIDES</filename> statement from the recipe

11228

file <filename>eudev_3.2.9.bb</filename>:

PROVIDES = "udev"

</literallayout>

The <filename>PROVIDES</filename> statement results in

11233

the "eudev" recipe also being available as simply "udev".

11234

11235

<note>

11236

Given that a recipe's own recipe name is already

11237

implicitly in its own <filename>PROVIDES</filename> list,

11238

it is unnecessary to add aliases with the "+=" operator;

11239

using a simple assignment will be sufficient. In other

11240

words, while you could write:

PROVIDES += "udev"

</literallayout>

in the above, the "+=" is overkill and unnecessary.

</note>

</para>

<para>

In addition to providing recipes under alternate names,

11250

the <filename>PROVIDES</filename> mechanism is also used

11251

to implement virtual targets.

11252

A virtual target is a name that corresponds to some

11253

particular functionality (e.g. a Linux kernel).

11254

Recipes that provide the functionality in question list the

11255

virtual target in <filename>PROVIDES</filename>.

11256

Recipes that depend on the functionality in question can

11257

include the virtual target in <filename>DEPENDS</filename>

11258

to leave the choice of provider open.

</para>

<para>

Conventionally, virtual targets have names on the form

11263

"virtual/function" (e.g. "virtual/kernel").

11264

The slash is simply part of the name and has no

11265

syntactical significance.

</para>

<para>

The

variable is used to select which particular recipe

11272

provides a virtual target.

11273

<note>

11274

<para>A corresponding mechanism for virtual runtime

11275

dependencies (packages) exists.

11276

However, the mechanism does not depend on any special

11277

functionality beyond ordinary variable assignments.

11278

For example,

11279

<filename>VIRTUAL-RUNTIME_dev_manager</filename>

11280

refers to the package of the component that manages

11281

the <filename>/dev</filename> directory.</para>

11282

11283

<para>Setting the "preferred provider" for runtime

11284

dependencies is as simple as using the following

11285

assignment in a configuration file:</para>

11286

11287

VIRTUAL-RUNTIME_dev_manager = "udev"

</literallayout>

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>

11295

<info>

11296

PRSERV_HOST[doc] = "The network based PR service host and port."

</info>

The network based

service host and port.

</para>

<para>

The <filename>conf/local.conf.sample.extended</filename>

11307

configuration file in the

11308

11309

shows how the <filename>PRSERV_HOST</filename> variable is

11310

set:

11311

11312

PRSERV_HOST = "localhost:0"

11313

</literallayout>

11314

You must set the variable if you want to automatically

11315

start a local

11316

<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.

11317

You can set <filename>PRSERV_HOST</filename> to other

11318

values to use a remote PR service.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm>

11324

<info>

11325

PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe."

</info>

Specifies whether or not

11330

<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink>

11331

(ptest) functionality is enabled when building a recipe.

11332

You should not set this variable directly.

11333

Enabling and disabling building Package Tests

11334

at build time should be done by adding "ptest" to (or

removing it from)

</para>

</glossdef>

</glossentry>

<info>

PV[doc] = "The version of the recipe. The version is normally extracted from the recipe filename."

</info>

The version of the recipe.

11348

The version is normally extracted from the recipe filename.

11349

For example, if the recipe is named

11350

<filename>expat_2.0.1.bb</filename>, then the default value

11351

of <filename>PV</filename> will be "2.0.1".

11352

<filename>PV</filename> is generally not overridden within

11353

a recipe unless it is building an unstable (i.e.

11354

development) version from a source code repository

11355

(e.g. Git or Subversion).

</para>

<para>

<filename>PV</filename> is the default value of the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>

11367

<info>

11368

PYTHON_ABI[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, denotes the Application Binary Interface (ABI) currently in use for Python."

</info>

When used by recipes that inherit the

or

classes, denotes the Application Binary Interface (ABI)

11379

currently in use for Python.

11380

By default, the ABI is "m".

11381

You do not have to set this variable as the OpenEmbedded

11382

build system sets it for you.

</para>

<para>

The OpenEmbedded build system uses the ABI to construct

11387

directory names used when installing the Python headers

11388

and libraries in sysroot

11389

(e.g. <filename>.../python3.3m/...</filename>).

</para>

<para>

Recipes that inherit the <filename>distutils</filename>

11394

class during cross-builds also use this variable to

11395

locate the headers and libraries of the appropriate Python

11396

that the extension is targeting.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>

11402

<info>

11403

PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built."

</info>

When used by recipes that inherit the

or

classes, specifies the major Python version being built.

11414

For Python 3.x, <filename>PYTHON_PN</filename> would be

11415

"python3".

11416

You do not have to set this variable as the

11417

OpenEmbedded build system automatically sets it for you.

</para>

<para>

The variable allows recipes to use common infrastructure

11422

such as the following:

11423

11424

DEPENDS += "${PYTHON_PN}-native"

11425

</literallayout>

11426

In the previous example, the version of the dependency

11427

is <filename>PYTHON_PN</filename>.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-RANLIB'><glossterm>RANLIB</glossterm>

11437

<info>

11438

RANLIB[doc] = "Minimal command and arguments to run 'ranlib'."

</info>

The minimal command and arguments to run

11443

<filename>ranlib</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>

11449

<info>

11450

RCONFLICTS[doc] = "The list of packages that conflict with another package. Note that the package will not be installed if the conflicting packages are not first removed."

</info>

The list of packages that conflict with packages.

11455

Note that packages will not be installed if conflicting

11456

packages are not first removed.

</para>

<para>

Like all package-controlling variables, you must always use

11461

them in conjunction with a package name override.

11462

Here is an example:

11463

11464

RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>"

</literallayout>

</para>

<para>

BitBake, which the OpenEmbedded build system uses, supports

11470

specifying versioned dependencies.

11471

Although the syntax varies depending on the packaging

11472

format, BitBake hides these differences from you.

11473

Here is the general syntax to specify versions with

11474

the <filename>RCONFLICTS</filename> variable:

11475

11476

RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

11477

</literallayout>

11478

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a dependency on version

11488

1.2 or greater of the package <filename>foo</filename>:

11489

11490

RCONFLICTS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>

11497

<info>

11498

RDEPENDS[doc] = "Lists runtime dependencies of a package."

</info>

Lists runtime dependencies of a package.

11503

These dependencies are other packages that must be

11504

installed in order for the package to function correctly.

11505

As an example, the following assignment declares that the

11506

package <filename>foo</filename> needs the packages

11507

<filename>bar</filename> and <filename>baz</filename> to

11508

be installed:

11509

11510

RDEPENDS_foo = "bar baz"

11511

</literallayout>

11512

The most common types of package runtime dependencies are

11513

automatically detected and added.

11514

Therefore, most recipes do not need to set

11515

<filename>RDEPENDS</filename>.

11516

For more information, see the

11517

"<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"

11518

section in the Yocto Project Overview and Concepts Manual.

</para>

<para>

The practical effect of the above

11523

<filename>RDEPENDS</filename> assignment is that

11524

11525

will be declared as dependencies inside the package

11526

<filename>foo</filename> when it is written out by one of

the

tasks.

Exactly how this is done depends on which package format

11531

is used, which is determined by

11532

11533

When the corresponding package manager installs the

11534

package, it will know to also install the packages on

which it depends.

</para>

<para>

To ensure that the packages <filename>bar</filename> and

11540

<filename>baz</filename> get built, the previous

11541

<filename>RDEPENDS</filename> assignment also causes a task

11542

dependency to be added.

11543

This dependency is from the recipe's

11544

11545

(not to be confused with

11546

11547

task to the <filename>do_package_write_*</filename>

11548

task of the recipes that build <filename>bar</filename> and

11549

<filename>baz</filename>.

</para>

<para>

The names of the packages you list within

11554

<filename>RDEPENDS</filename> must be the names of other

11555

packages - they cannot be recipe names.

11556

Although package names and recipe names usually match,

11557

the important point here is that you are

11558

providing package names within the

11559

<filename>RDEPENDS</filename> variable.

11560

For an example of the default list of packages created from

a recipe, see the

variable.

</para>

<para>

Because the <filename>RDEPENDS</filename> variable applies

11568

to packages being built, you should always use the variable

11569

in a form with an attached package name (remember that a

11570

single recipe can build multiple packages).

11571

For example, suppose you are building a development package

11572

that depends on the <filename>perl</filename> package.

11573

In this case, you would use the following

11574

<filename>RDEPENDS</filename> statement:

11575

11576

RDEPENDS_${PN}-dev += "perl"

11577

</literallayout>

11578

In the example, the development package depends on

11579

the <filename>perl</filename> package.

11580

Thus, the <filename>RDEPENDS</filename> variable has the

11581

<filename>${PN}-dev</filename> package name as part of the

11582

variable.

11583

<note>

11584

<title>Caution</title>

11585

<filename>RDEPENDS_${PN}-dev</filename> includes

11586

11587

by default.

11588

This default is set in the BitBake configuration file

11589

(<filename>meta/conf/bitbake.conf</filename>).

11590

Be careful not to accidentally remove

11591

<filename>${PN}</filename> when modifying

11592

<filename>RDEPENDS_${PN}-dev</filename>.

11593

Use the "+=" operator rather than the "=" operator.

</note>

</para>

<para>

The package names you use with

11599

<filename>RDEPENDS</filename> must appear as they would in

11600

the <filename>PACKAGES</filename> variable.

11601

The

11602

11603

variable allows a different name to be used for

11604

the final package (e.g. the

11605

11606

class uses this to rename packages), but this final package

11607

name cannot be used with <filename>RDEPENDS</filename>,

11608

which makes sense as <filename>RDEPENDS</filename> is meant

11609

to be independent of the package format used.

</para>

<para>

BitBake, which the OpenEmbedded build system uses, supports

11614

specifying versioned dependencies.

11615

Although the syntax varies depending on the packaging

11616

format, BitBake hides these differences from you.

11617

Here is the general syntax to specify versions with

11618

the <filename>RDEPENDS</filename> variable:

11619

11620

RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

11621

</literallayout>

11622

For <replaceable>operator</replaceable>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For <replaceable>version</replaceable>, provide the version

number.

You can use

to provide a full package version specification.

11637

</note>

11638

For example, the following sets up a dependency on version

11639

1.2 or greater of the package <filename>foo</filename>:

11640

11641

RDEPENDS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

<para>

For information on build-time dependencies, see the

variable.

You can also see the

"<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and

11651

"<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"

11652

sections in the BitBake User Manual for additional

11653

information on tasks and dependencies.

</para>

</glossdef>

</glossentry>

<glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>

11659

<info>

11660

REQUIRED_DISTRO_FEATURES[doc] = "When a recipe inherits the distro_features_check class, this variable identifies distribution features that must exist in the current configuration in order for the OpenEmbedded build system to build the recipe."

</info>

When inheriting the

class, this

variable identifies distribution features that must

11668

exist in the current configuration in order for the

11669

OpenEmbedded build system to build the recipe.

11670

In other words, if the

11671

<filename>REQUIRED_DISTRO_FEATURES</filename> variable

11672

lists a feature that does not appear in

11673

<filename>DISTRO_FEATURES</filename> within the

11674

current configuration, an error occurs and the

build stops.

</para>

</glossdef>

</glossentry>

<glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>

11681

<info>

11682

RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed."

</info>

With <filename>rm_work</filename> enabled, this

11687

variable specifies a list of recipes whose work directories

11688

should not be removed.

11689

See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"

11690

section for more details.

</para>

</glossdef>

</glossentry>

<info>

ROOT_HOME[doc] = "Defines the root home directory."

</info>

Defines the root home directory.

11702

By default, this directory is set as follows in the

11703

BitBake configuration file:

11704

11705

ROOT_HOME ??= "/home/root"

11706

</literallayout>

11707

<note>

11708

This default value is likely used because some

11709

embedded solutions prefer to have a read-only root

11710

filesystem and prefer to keep writeable data in one

place.

</note>

</para>

<para>

You can override the default by setting the variable

11717

in any layer or in the <filename>local.conf</filename> file.

11718

Because the default is set using a "weak" assignment

11719

(i.e. "??="), you can use either of the following forms

11720

to define your override:

ROOT_HOME = "/root"

ROOT_HOME ?= "/root"

</literallayout>

These override examples use <filename>/root</filename>,

11726

which is probably the most commonly used override.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>

11732

<info>

11733

ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem."

</info>

Indicates a filesystem image to include as the root

filesystem.

</para>

<para>

The <filename>ROOTFS</filename> variable is an optional

11743

variable used with the

class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_POSTINSTALL_COMMAND'><glossterm>ROOTFS_POSTINSTALL_COMMAND</glossterm>

11751

<info>

11752

ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."

</info>

Specifies a list of functions to call after the

11757

OpenEmbedded build system has installed packages.

11758

You can specify functions separated by semicolons:

11759

11760

ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

11766

within a function, you can use

11767

<filename>${IMAGE_ROOTFS}</filename>, which points to

11768

the directory that becomes the root filesystem image.

11769

See the

11770

11771

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>

11777

<info>

11778

ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."

</info>

Specifies a list of functions to call once the

11783

OpenEmbedded build system has created the root filesystem.

11784

You can specify functions separated by semicolons:

11785

11786

ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

11792

within a function, you can use

11793

<filename>${IMAGE_ROOTFS}</filename>, which points to

11794

the directory that becomes the root filesystem image.

11795

See the

11796

11797

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>

11803

<info>

11804

ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."

</info>

Specifies a list of functions to call after the

11809

OpenEmbedded build system has removed unnecessary

11810

packages.

11811

When runtime package management is disabled in the

11812

image, several packages are removed including

11813

<filename>base-passwd</filename>,

11814

<filename>shadow</filename>, and

11815

<filename>update-alternatives</filename>.

11816

You can specify functions separated by semicolons:

11817

11818

ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

11824

within a function, you can use

11825

<filename>${IMAGE_ROOTFS}</filename>, which points to

11826

the directory that becomes the root filesystem image.

11827

See the

11828

11829

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>

11835

<info>

11836

ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."

</info>

Specifies a list of functions to call before the

11841

OpenEmbedded build system has created the root filesystem.

11842

You can specify functions separated by semicolons:

11843

11844

ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

11850

within a function, you can use

11851

<filename>${IMAGE_ROOTFS}</filename>, which points to

11852

the directory that becomes the root filesystem image.

11853

See the

11854

11855

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>

11861

<info>

11862

RPROVIDES[doc] = "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."

</info>

A list of package name aliases that a package also provides.

11867

These aliases are useful for satisfying runtime dependencies

11868

of other packages both during the build and on the target

11869

(as specified by

11870

<filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).

11871

<note>

11872

A package's own name is implicitly already in its

11873

<filename>RPROVIDES</filename> list.

</note>

</para>

<para>

As with all package-controlling variables, you must always

11879

use the variable in conjunction with a package name override.

11880

Here is an example:

11881

11882

RPROVIDES_${PN} = "widget-abi-2"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>

11889

<info>

11890

RRECOMMENDS[doc] = "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."

</info>

A list of packages that extends the usability of a package

11895

being built.

11896

The package being built does not depend on this list of

11897

packages in order to successfully build, but rather

11898

uses them for extended usability.

11899

To specify runtime dependencies for packages, see the

11900

<filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>

variable.

</para>

<para>

The package manager will automatically install the

11906

<filename>RRECOMMENDS</filename> list of packages when

11907

installing the built package.

11908

However, you can prevent listed packages from being

11909

installed by using the

and

variables.

</para>

<para>

Packages specified in

11919

<filename>RRECOMMENDS</filename> need not actually be

11920

produced.

11921

However, a recipe must exist that provides each package,

either through the

or

variables or the

variable, or an error will occur during the build.

11929

If such a recipe does exist and the package is not produced,

11930

the build continues without error.

</para>

<para>

Because the <filename>RRECOMMENDS</filename> variable

11935

applies to packages being built, you should always attach

11936

an override to the variable to specify the particular

11937

package whose usability is being extended.

11938

For example, suppose you are building a development package

11939

that is extended to support wireless functionality.

11940

In this case, you would use the following:

11941

11942

RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>"

11943

</literallayout>

11944

In the example, the package name

11945

(<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)

11946

must appear as it would in the

11947

<filename>PACKAGES</filename> namespace before any renaming

11948

of the output package by classes such as

11949

<filename>debian.bbclass</filename>.

</para>

<para>

BitBake, which the OpenEmbedded build system uses, supports

11954

specifying versioned recommends.

11955

Although the syntax varies depending on the packaging

11956

format, BitBake hides these differences from you.

11957

Here is the general syntax to specify versions with

11958

the <filename>RRECOMMENDS</filename> variable:

11959

11960

RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

11961

</literallayout>

11962

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a recommend on version

11972

1.2 or greater of the package <filename>foo</filename>:

11973

11974

RRECOMMENDS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>

11981

<info>

11982

RREPLACES[doc] = "A list of packages replaced by a package. The package manager uses this variable to determine which package should be installed to replace other package(s) during an upgrade."

</info>

A list of packages replaced by a package.

11987

The package manager uses this variable to determine which

11988

package should be installed to replace other package(s)

11989

during an upgrade.

11990

In order to also have the other package(s) removed at the

11991

same time, you must add the name of the other

11992

package to the

11993

<filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.

</para>

<para>

As with all package-controlling variables, you must use

11998

this variable in conjunction with a package name

override.

Here is an example:

RREPLACES_${PN} = "<replaceable>other_package_being_replaced</replaceable>"

</literallayout>

</para>

<para>

BitBake, which the OpenEmbedded build system uses, supports

12008

specifying versioned replacements.

12009

Although the syntax varies depending on the packaging

12010

format, BitBake hides these differences from you.

12011

Here is the general syntax to specify versions with

12012

the <filename>RREPLACES</filename> variable:

12013

12014

RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

12015

</literallayout>

12016

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a replacement using

12026

version 1.2 or greater of the package

12027

<filename>foo</filename>:

12028

12029

RREPLACES_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>

12036

<info>

12037

RSUGGESTS[doc] = "A list of additional packages that you can suggest for installation by the package manager at the time a package is installed. Not all package managers support this functionality."

</info>

A list of additional packages that you can suggest for

12042

installation by the package manager at the time a package

12043

is installed.

12044

Not all package managers support this functionality.

</para>

<para>

As with all package-controlling variables, you must always

12049

use this variable in conjunction with a package name

override.

Here is an example:

RSUGGESTS_${PN} = "<replaceable>useful_package</replaceable> <replaceable>another_package</replaceable>"

</literallayout>

</para>

</glossdef>

</glossentry>

</glossdiv>

<info>

S[doc] = "The location in the Build Directory where unpacked package source code resides."

</info>

The location in the

where unpacked recipe source code resides.

12072

By default, this directory is

12073

<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/${</filename><link linkend='var-BPN'><filename>BPN</filename></link><filename>}-${</filename><link linkend='var-PV'><filename>PV</filename></link><filename>}</filename>,

12074

where <filename>${BPN}</filename> is the base recipe name

12075

and <filename>${PV}</filename> is the recipe version.

12076

If the source tarball extracts the code to a directory

12077

named anything other than <filename>${BPN}-${PV}</filename>,

12078

or if the source code is fetched from an SCM such as

12079

Git or Subversion, then you must set <filename>S</filename>

12080

in the recipe so that the OpenEmbedded build system

12081

knows where to find the unpacked source.

</para>

<para>

As an example, assume a

12086

12087

top-level folder named <filename>poky</filename> and a

12088

default Build Directory at <filename>poky/build</filename>.

12089

In this case, the work directory the build system uses

12090

to keep the unpacked recipe for <filename>db</filename>

12091

is the following:

12092

12093

poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19

12094

</literallayout>

12095

The unpacked source code resides in the

12096

<filename>db-5.1.19</filename> folder.

</para>

<para>

This next example assumes a Git repository.

12101

By default, Git repositories are cloned to

12102

<filename>${WORKDIR}/git</filename> during

12103

12104

Since this path is different from the default value of

12105

<filename>S</filename>, you must set it specifically

12106

so the source can be located:

12107

12108

SRC_URI = "git://path/to/repo.git"

S = "${WORKDIR}/git"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm>SANITY_REQUIRED_UTILITIES</glossterm>

12116

<info>

12117

SANITY_REQUIRED_UTILITIES[doc] = "Specifies a list of command-line utilities that should be checked for during the initial sanity checking process when running BitBake."

</info>

Specifies a list of command-line utilities that should be

12122

checked for during the initial sanity checking process when

12123

running BitBake.

12124

If any of the utilities are not installed on the build host,

12125

then BitBake immediately exits with an error.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>

12131

<info>

12132

SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against."

</info>

A list of the host distribution identifiers that the

12137

build system has been tested against.

12138

Identifiers consist of the host distributor ID

12139

followed by the release,

12140

as reported by the <filename>lsb_release</filename> tool

12141

or as read from <filename>/etc/lsb-release</filename>.

12142

Separate the list items with explicit newline

12143

characters (<filename>\n</filename>).

12144

If <filename>SANITY_TESTED_DISTROS</filename> is not empty

12145

and the current value of

12146

12147

does not appear in the list, then the build system reports

12148

a warning that indicates the current host distribution has

12149

not been tested as a build host.

</para>

</glossdef>

</glossentry>

<info>

SDK_ARCH[doc] = "The target architecture for the SDK."

</info>

The target architecture for the SDK.

12161

Typically, you do not directly set this variable.

Instead, use

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>

12169

<info>

12170

SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed."

</info>

The directory set up and used by the

12175

12176

class to which the SDK is deployed.

12177

The <filename>populate_sdk_base</filename> class defines

12178

<filename>SDK_DEPLOY</filename> as follows:

12179

12180

SDK_DEPLOY = "${TMPDIR}/deploy/sdk"

</literallayout>

</para>

</glossdef>

</glossentry>

<info>

SDK_DIR[doc] = "The parent directory used by the OpenEmbedded build system when creating SDK output."

</info>

The parent directory used by the OpenEmbedded build system

12193

when creating SDK output.

12194

The

12195

12196

class defines the variable as follows:

12197

12198

SDK_DIR = "${WORKDIR}/sdk"

12199

</literallayout>

12200

<note>

12201

The <filename>SDK_DIR</filename> directory is a

12202

temporary directory as it is part of

12203

<filename>WORKDIR</filename>.

12204

The final output directory is

</note>

</para>

</glossdef>

</glossentry>

<info>

SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK."

</info>

Controls whether or not shared state artifacts are copied

12218

into the extensible SDK.

12219

The default value of "full" copies all of the required

12220

shared state artifacts into the extensible SDK.

12221

The value "minimal" leaves these artifacts out of the

12222

SDK.

12223

<note>

12224

If you set the variable to "minimal", you need to

12225

ensure

12226

12227

is set in the SDK's configuration to enable the

12228

artifacts to be fetched as needed.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm>

12235

<info>

12236

SDK_HOST_MANIFEST[doc] = "The manifest file for the host part of the SDK. This file lists all the installed packages that make up the host part of the SDK."

</info>

The manifest file for the host part of the SDK.

12241

This file lists all the installed packages that make up

12242

the host part of the SDK.

12243

The file contains package information on a line-per-package

12244

basis as follows:

12245

12246

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

12254

12255

SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"

12256

</literallayout>

12257

The location is derived using the

and

variables.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm>

12267

<info>

12268

SDK_INCLUDE_PKGDATA[doc] = "When set to "1", specifies to include the packagedata for all recipes in the "world" target in the extensible SDK."

</info>

When set to "1", specifies to include the packagedata for

12273

all recipes in the "world" target in the extensible SDK.

12274

Including this data allows the

12275

<filename>devtool search</filename> command to find these

12276

recipes in search results, as well as allows the

12277

<filename>devtool add</filename> command to map

12278

dependencies more effectively.

12279

<note>

12280

Enabling the <filename>SDK_INCLUDE_PKGDATA</filename>

12281

variable significantly increases build time because

12282

all of world needs to be built.

12283

Enabling the variable also slightly increases the size

12284

of the extensible SDK.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm>

12291

<info>

12292

SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK."

</info>

When set to "1", specifies to include the toolchain in the

12297

extensible SDK.

12298

Including the toolchain is useful particularly when

12299

12300

is set to "minimal" to keep the SDK reasonably small

12301

but you still want to provide a usable toolchain.

12302

For example, suppose you want to use the toolchain from an

12303

IDE or from other tools and you do not

12304

want to perform additional steps to install the toolchain.

</para>

<para>

The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable

12309

defaults to "0" if <filename>SDK_EXT_TYPE</filename>

12310

is set to "minimal", and defaults to "1" if

12311

<filename>SDK_EXT_TYPE</filename> is set to "full".

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm>

12317

<info>

12318

SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration."

</info>

A list of classes to remove from the

12323

12324

value globally within the extensible SDK configuration.

12325

The

12326

12327

class sets the default value:

12328

12329

SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"

</literallayout>

</para>

<para>

Some classes are not generally applicable within

12335

the extensible SDK context.

12336

You can use this variable to disable those classes.

</para>

<para>

For additional information on how to customize the

12341

extensible SDK's configuration, see the

12342

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"

12343

section in the Yocto Project Application Development and

12344

the Extensible Software Development Kit (eSDK) manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_LOCAL_CONF_BLACKLIST'><glossterm>SDK_LOCAL_CONF_BLACKLIST</glossterm>

12350

<info>

12351

SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration."

</info>

A list of variables not allowed through from the

12356

OpenEmbedded build system configuration into the extensible

12357

SDK configuration.

12358

Usually, these are variables that are specific to the

12359

machine on which the build system is running and thus

12360

would be potentially problematic within the extensible SDK.

</para>

<para>By default,

<filename>SDK_LOCAL_CONF_BLACKLIST</filename> is set in the

12365

12366

class and excludes the following variables:

<ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'>BB_NUMBER_PARSE_THREADS</ulink>

</literallayout>

</para>

<para>

For additional information on how to customize the

12383

extensible SDK's configuration, see the

12384

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"

12385

section in the Yocto Project Application Development and

12386

the Extensible Software Development Kit (eSDK) manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm>

12393

<info>

12394

SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration."

</info>

A list of variables allowed through from the OpenEmbedded

12399

build system configuration into the extensible SDK

12400

configuration.

12401

By default, the list of variables is empty and is set in

the

class.

</para>

<para>

This list overrides the variables specified using the

12409

12410

variable as well as any variables identified by automatic

12411

blacklisting due to the "/" character being found at the

12412

start of the value, which is usually indicative of being a

12413

path and thus might not be valid on the system where the

SDK is installed.

</para>

<para>

For additional information on how to customize the

12419

extensible SDK's configuration, see the

12420

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"

12421

section in the Yocto Project Application Development and

12422

the Extensible Software Development Kit (eSDK) manual.

</para>

</glossdef>

</glossentry>

<info>

SDK_NAME[doc] = "The base name for SDK output files."

</info>

The base name for SDK output files.

12434

The name is derived from the

and

variables:

SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"

</literallayout>

</para>

</glossdef>

</glossentry>

<info>

SDK_OS[doc] = "The operating system for which the SDK will be built."

</info>

Specifies the operating system for which the SDK

12456

will be built.

12457

The default value is the value of

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>

12464

<info>

12465

SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output."

</info>

The location used by the OpenEmbedded build system when

creating SDK output.

The

class defines the variable as follows:

12474

12475

SDK_DIR = "${WORKDIR}/sdk"

12476

SDK_OUTPUT = "${SDK_DIR}/image"

12477

SDK_DEPLOY = "${DEPLOY_DIR}/sdk"

12478

</literallayout>

12479

<note>

12480

The <filename>SDK_OUTPUT</filename> directory is a

12481

temporary directory as it is part of

by way of

The final output directory is

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>

12493

<info>

12494

SDK_PACKAGE_ARCHS[doc] = "Specifies a list of architectures compatible with the SDK machine. This variable is set automatically and should not normally be hand-edited."

</info>

Specifies a list of architectures compatible with

12499

the SDK machine.

12500

This variable is set automatically and should not

12501

normally be hand-edited.

12502

Entries are separated using spaces and listed in order

12503

of priority.

12504

The default value for

12505

<filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch

12506

${SDK_ARCH}-${SDKPKGSUFFIX}".

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>

12512

<info>

12513

SDK_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the SDK."

</info>

Specifies a list of functions to call once the

12518

OpenEmbedded build system creates the SDK.

12519

You can specify functions separated by semicolons:

12520

12521

SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass an SDK path to a command within a

12527

function, you can use

12528

<filename>${SDK_DIR}</filename>, which points to

12529

the parent directory used by the OpenEmbedded build system

12530

when creating SDK output.

12531

See the

12532

12533

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>

12539

<info>

12540

SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."

</info>

The toolchain binary prefix used for

12545

<filename>nativesdk</filename> recipes.

12546

The OpenEmbedded build system uses the

12547

<filename>SDK_PREFIX</filename> value to set the

12548

12549

when building <filename>nativesdk</filename> recipes.

12550

The default value is "${SDK_SYS}-".

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm>

12556

<info>

12557

SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK."

</info>

A list of shared state tasks added to the extensible SDK.

12562

By default, the following tasks are added:

do_populate_lic

do_package_qa

do_populate_sysroot

do_deploy

</literallayout>

Despite the default value of "" for the

12570

<filename>SDK_RECRDEP_TASKS</filename> variable, the

12571

above four tasks are always added to the SDK.

12572

To specify tasks beyond these four, you need to use

12573

the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g.

12574

you are defining additional tasks that are needed in

order to build

</para>

</glossdef>

</glossentry>

<info>

SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built."

</info>

Specifies the system, including the architecture and the

12588

operating system, for which the SDK will be built.

</para>

<para>

The OpenEmbedded build system automatically sets this

variable based on

and

You do not need to set the <filename>SDK_SYS</filename>

variable yourself.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_TARGET_MANIFEST'><glossterm>SDK_TARGET_MANIFEST</glossterm>

12605

<info>

12606

SDK_TARGET_MANIFEST[doc] = "The manifest file for the target part of the SDK. This file lists all the installed packages that make up the target part of the SDK."

</info>

The manifest file for the target part of the SDK.

12611

This file lists all the installed packages that make up

12612

the target part of the SDK.

12613

The file contains package information on a line-per-package

12614

basis as follows:

12615

12616

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

12624

12625

SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"

12626

</literallayout>

12627

The location is derived using the

and

variables.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm>

12637

<info>

12638

SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation."

</info>

A list of targets to install from shared state as part of

12643

the standard or extensible SDK installation.

12644

The default value is "${PN}" (i.e. the image from which

the SDK is built).

</para>

<para>

The <filename>SDK_TARGETS</filename> variable is an

12650

internal variable and typically would not be changed.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm>

12656

<info>

12657

SDK_TITLE[doc] = "The title to be printed when running the SDK installer."

</info>

The title to be printed when running the SDK installer.

12662

By default, this title is based on the

or

variable and is set in the

class as follows:

SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"

12671

</literallayout>

12672

For the default distribution "poky",

12673

<filename>SDK_TITLE</filename> is set to

12674

"Poky (Yocto Project Reference Distro)".

</para>

<para>

For information on how to change this default title,

12679

see the

12680

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-sdk-installer-title'>Changing the Extensible SDK Installer Title</ulink>"

12681

section in the Yocto Project Application Development and

12682

the Extensible Software Development Kit (eSDK) manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_UPDATE_URL'><glossterm>SDK_UPDATE_URL</glossterm>

12688

<info>

12689

SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK."

</info>

An optional URL for an update server for the extensible

12694

SDK.

12695

If set, the value is used as the default update server when

12696

running <filename>devtool sdk-update</filename> within the

extensible SDK.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm>

12703

<info>

12704

SDK_VENDOR[doc] = "Specifies the name of the SDK vendor."

</info>

Specifies the name of the SDK vendor.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_VERSION'><glossterm>SDK_VERSION</glossterm>

12714

<info>

12715

SDK_VERSION[doc] = "Specifies the version for the SDK."

</info>

Specifies the version of the SDK.

12720

The distribution configuration file (e.g.

12721

<filename>/meta-poky/conf/distro/poky.conf</filename>)

12722

defines the <filename>SDK_VERSION</filename> as follows:

12723

12724

SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}"

</literallayout>

</para>

<para>

For additional information, see the

and

variables.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKEXTPATH'><glossterm>SDKEXTPATH</glossterm>

12739

<info>

12740

SDKEXTPATH[doc] = "The default installation directory for the extensible SDK."

</info>

The default installation directory for the Extensible SDK.

12745

By default, this directory is based on the

12746

12747

variable and is set in the

class as follows:

SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"

12752

</literallayout>

12753

For the default distribution "poky", the

12754

<filename>SDKEXTPATH</filename> is set to "poky_sdk".

</para>

<para>

For information on how to change this default directory,

12759

see the

12760

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-default-sdk-installation-directory'>Changing the Default SDK Installation Directory</ulink>"

12761

section in the Yocto Project Application Development and

12762

the Extensible Software Development Kit (eSDK) manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>

12768

<info>

12769

SDKIMAGE_FEATURES[doc] = "Equivalent to IMAGE_FEATURES. However, this variable applies to the SDK generated from an image using the command 'bitbake -c populate_sdk imagename'."

</info>

Equivalent to

<filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.

12775

However, this variable applies to the SDK generated from an

12776

image using the following command:

12777

12778

$ bitbake -c populate_sdk <replaceable>imagename</replaceable>

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>

12785

<info>

12786

SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK items."

</info>

The machine for which the SDK is built.

12791

In other words, the SDK is built such that it

12792

runs on the target you specify with the

12793

<filename>SDKMACHINE</filename> value.

12794

The value points to a corresponding

12795

<filename>.conf</filename> file under

12796

<filename>conf/machine-sdk/</filename>.

</para>

<para>

You can use "i686" and "x86_64" as possible values

12801

for this variable. The variable defaults to "i686"

12802

and is set in the local.conf file in the Build Directory.

SDKMACHINE ?= "i686"

</literallayout>

<note>

You cannot set the <filename>SDKMACHINE</filename>

12808

variable in your distribution configuration file.

12809

If you do, the configuration will not take affect.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>

12816

<info>

12817

SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system."

</info>

Defines the path offered to the user for installation

12822

of the SDK that is generated by the OpenEmbedded build

12823

system.

12824

The path appears as the default location for installing

12825

the SDK when you run the SDK's installation script.

12826

You can override the offered path when you run the

script.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm>

12833

<info>

12834

SDKTARGETSYSROOT[doc] = "Full path to the sysroot used for cross-compilation within an SDK as it will be when installed into the default SDKPATH."

</info>

The full path to the sysroot used for cross-compilation

12839

within an SDK as it will be when installed into the

default

</para>

</glossdef>

</glossentry>

<glossentry id='var-SECTION'><glossterm>SECTION</glossterm>

12847

<info>

12848

SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable."

</info>

The section in which packages should be categorized.

12853

Package management utilities can make use of this variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>

12859

<info>

12860

SELECTED_OPTIMIZATION[doc] = "The variable takes the value of FULL_OPTIMIZATION unless DEBUG_BUILD = '1'. In this case, the value of DEBUG_OPTIMIZATION is used."

</info>

Specifies the optimization flags passed to the C compiler

12865

when building for the target.

12866

The flags are passed through the default value of the

variable.

</para>

<para>

The <filename>SELECTED_OPTIMIZATION</filename> variable

12873

takes the value of

12874

<filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>

12875

unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".

12876

If that is the case, the value of

12877

<filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>

12883

<info>

12884

SERIAL_CONSOLE[doc] = "Defines the serial consoles (TTYs) to enable using getty."

</info>

Defines a serial console (TTY) to enable using

12889

<ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.

12890

Provide a value that specifies the baud rate followed by

12891

the TTY device name separated by a space.

12892

You cannot specify more than one TTY device:

12893

12894

SERIAL_CONSOLE = "115200 ttyS0"

12895

</literallayout>

12896

<note>

12897

The <filename>SERIAL_CONSOLE</filename> variable

is deprecated.

Please use the

variable.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>

12908

<info>

12909

SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty."

</info>

Defines a serial console (TTY) to enable using

12914

<ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.

12915

Provide a value that specifies the baud rate followed by

12916

the TTY device name separated by a semicolon.

12917

Use spaces to separate multiple devices:

12918

12919

SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>

12926

<info>

12927

SERIAL_CONSOLES_CHECK[doc] = "Selected SERIAL_CONSOLES to check against /proc/console before enabling using getty. Supported only by SysVinit."

</info>

Specifies serial consoles, which must be listed in

12932

12933

to check against <filename>/proc/console</filename>

12934

before enabling them using getty.

12935

This variable allows aliasing in the format:

12936

<device>:<alias>.

12937

If a device was listed as "sclp_line0"

12938

in <filename>/dev/</filename> and "ttyS0" was listed

12939

in <filename>/proc/console</filename>, you would do the

12940

following:

12941

12942

SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"

12943

</literallayout>

12944

This variable is currently only supported with SysVinit

12945

(i.e. not with systemd).

</para>

</glossdef>

</glossentry>

<glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>

12951

<info>

12952

SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS[doc] = "A list of recipe dependencies that should not be used to determine signatures of tasks from one recipe when they depend on tasks from another recipe."

</info>

A list of recipe dependencies that should not be used to

12957

determine signatures of tasks from one recipe when they

12958

depend on tasks from another recipe.

12959

For example:

12960

12961

SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"

</literallayout>

</para>

<para>

In the previous example, <filename>intone</filename>

12967

depends on <filename>mplayer2</filename>.

</para>

<para>

You can use the special token <filename>"*"</filename> on

12972

the left-hand side of the dependency to match all

12973

recipes except the one on the right-hand side.

12974

Here is an example:

12975

12976

SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"

</literallayout>

</para>

<para>

In the previous example, all recipes except

12982

<filename>quilt-native</filename> ignore task

12983

signatures from the <filename>quilt-native</filename>

12984

recipe when determining their task signatures.

</para>

<para>

Use of this variable is one mechanism to remove dependencies

12989

that affect task signatures and thus force rebuilds when a

12990

recipe changes.

12991

<note><title>Caution</title>

12992

If you add an inappropriate dependency for a recipe

12993

relationship, the software might break during

12994

runtime if the interface of the second recipe was

12995

changed after the first recipe had been built.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>

13002

<info>

13003

SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change."

</info>

A list of recipes that are completely stable and will

13008

never change.

13009

The ABI for the recipes in the list are presented by

13010

output from the tasks run to build the recipe.

13011

Use of this variable is one way to remove dependencies from

13012

one recipe on another that affect task signatures and

13013

thus force rebuilds when the recipe changes.

13014

<note><title>Caution</title>

13015

If you add an inappropriate variable to this list,

13016

the software might break at runtime if the

13017

interface of the recipe was changed after the other

had been built.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>

13025

<info>

13026

SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU."

</info>

Specifies the number of bits for the target system CPU.

13031

The value should be either "32" or "64".

</para>

</glossdef>

</glossentry>

<glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>

13037

<info>

13038

SITEINFO_ENDIANNESS[doc] = "Specifies the endian byte order of the target system. The value should be either 'le' for 'little-endian' or 'be' for 'big-endian'."

</info>

Specifies the endian byte order of the target system.

13043

The value should be either "le" for little-endian or "be" for big-endian.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SKIP_FILEDEPS'><glossterm>SKIP_FILEDEPS</glossterm>

13049

<info>

13050

SKIP_FILEDEPS[doc] = "Enables you to remove all files from the 'Provides' section of an RPM package."

</info>

Enables removal of all files from the "Provides" section of

13055

an RPM package.

13056

Removal of these files is required for packages containing

13057

prebuilt binaries and libraries such as

13058

<filename>libstdc++</filename> and

13059

<filename>glibc</filename>.

</para>

<para>

To enable file removal, set the variable to "1" in your

13064

<filename>conf/local.conf</filename> configuration file

in your:

SKIP_FILEDEPS = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>

13075

<info>

13076

SOC_FAMILY[doc] = "Groups together machines based upon the same family of SOC (System On Chip). You typically set this variable in a common .inc file that you include in the configuration files of all the machines."

</info>

Groups together machines based upon the same family

13081

of SOC (System On Chip).

13082

You typically set this variable in a common

13083

<filename>.inc</filename> file that you include in the

13084

configuration files of all the machines.

13085

<note>

13086

You must include

13087

<filename>conf/machine/include/soc-family.inc</filename>

13088

for this variable to appear in

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>

13096

<info>

13097

SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform."

</info>

Defines the suffix for shared libraries used on the

13102

target platform.

13103

By default, this suffix is ".so.*" for all Linux-based

13104

systems and is defined in the

13105

<filename>meta/conf/bitbake.conf</filename> configuration

file.

</para>

<para>

You will see this variable referenced in the default values

13111

of <filename>FILES_${PN}</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>

13117

<info>

13118

SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform."

</info>

Defines the suffix for the development symbolic link

13123

(symlink) for shared libraries on the target platform.

13124

By default, this suffix is ".so" for Linux-based

13125

systems and is defined in the

13126

<filename>meta/conf/bitbake.conf</filename> configuration

file.

</para>

<para>

You will see this variable referenced in the default values

13132

of <filename>FILES_${PN}-dev</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm>

13138

<info>

13139

SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks."

</info>

When you are fetching files to create a mirror of sources

13144

(i.e. creating a source mirror), setting

13145

<filename>SOURCE_MIRROR_FETCH</filename> to "1" in your

13146

<filename>local.conf</filename> configuration file ensures

13147

the source for all recipes are fetched regardless of

13148

whether or not a recipe is compatible with the

13149

configuration.

13150

A recipe is considered incompatible with the currently

13151

configured machine when either or both the

variable and

variables specify compatibility with a machine other

13156

than that of the current machine or host.

13157

<note><title>Warning</title>

13158

Do not set the

13159

<filename>SOURCE_MIRROR_FETCH</filename> variable

13160

unless you are creating a source mirror.

13161

In other words, do not set the variable during a

normal build.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>

13169

<info>

13170

SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI."

</info>

Defines your own

from which to first fetch source before attempting to fetch

13177

from the upstream specified in

</para>

<para>

To use this variable, you must globally inherit the

13183

13184

class and then provide the URL to your mirrors.

13185

Here is the general syntax:

13186

13187

INHERIT += "own-mirrors"

13188

SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>"

13189

</literallayout>

13190

<note>

13191

You can specify only a single URL in

13192

<filename>SOURCE_MIRROR_URL</filename>.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>

13199

<info>

13200

SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/."

</info>

Maps commonly used license names to their SPDX counterparts

13205

found in <filename>meta/files/common-licenses/</filename>.

13206

For the default <filename>SPDXLICENSEMAP</filename>

13207

mappings, see the

13208

<filename>meta/conf/licenses.conf</filename> file.

</para>

<para>

For additional information, see the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>

13220

<info>

13221

SPECIAL_PKGSUFFIX[doc] = "A list of prefixes for PN used by the OpenEmbedded build system to create variants of recipes or packages. The list specifies the prefixes to strip off during certain circumstances such as the generation of the BPN variable."

</info>

A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the

13226

OpenEmbedded build system to create variants of recipes or packages.

13227

The list specifies the prefixes to strip off during certain circumstances

13228

such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SPL_BINARY'><glossterm>SPL_BINARY</glossterm>

13234

<info>

13235

SPL_BINARY[doc] = "The file type of the Secondary Program Loader (SPL)."

</info>

The file type for the Secondary Program Loader (SPL).

13240

Some devices use an SPL from which to boot (e.g. the

13241

BeagleBone development board).

13242

For such cases, you can declare the file type of the

13243

SPL binary in the <filename>u-boot.inc</filename> include

13244

file, which is used in the U-Boot recipe.

</para>

<para>

The SPL file type is set to "null" by default in the

13249

<filename>u-boot.inc</filename> file as follows:

13250

13251

# Some versions of u-boot build an SPL (Second Program Loader) image that

13252

# should be packaged along with the u-boot binary as well as placed in the

13253

# deploy directory. For those versions they can set the following variables

13254

# to allow packaging the SPL.

13255

SPL_BINARY ?= ""

13256

SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"

13257

SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"

13258

SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"

13259

</literallayout>

13260

The <filename>SPL_BINARY</filename> variable helps form

13261

various <filename>SPL_*</filename> variables used by

13262

the OpenEmbedded build system.

</para>

<para>

See the BeagleBone machine configuration example in the

13267

"<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</ulink>"

13268

section in the Yocto Project Board Support Package

13269

Developer's Guide for additional information.

</para>

</glossdef>

</glossentry>

<info>

SRC_URI[doc] = "The list of source files - local or remote. This variable tells the OpenEmbedded build system what bits to pull in for the build and how to pull them in."

</info>

The list of source files - local or remote.

13281

This variable tells the OpenEmbedded build system which bits

13282

to pull in for the build and how to pull them in.

13283

For example, if the recipe or append file only needs to

13284

fetch a tarball from the Internet, the recipe or

13285

append file uses a single <filename>SRC_URI</filename>

13286

entry.

13287

On the other hand, if the recipe or append file needs to

13288

fetch a tarball, apply two patches, and include a custom

13289

file, the recipe or append file would include four

13290

instances of the variable.

</para>

<para>

The following list explains the available URI protocols.

13295

URI protocols are highly dependent on particular BitBake

13296

Fetcher submodules.

13297

Depending on the fetcher BitBake uses, various URL

13298

parameters are employed.

13299

For specifics on the supported Fetchers, see the

13300

"<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"

13301

section in the BitBake User Manual.

13302

13303

13304

Fetches files, which are usually files shipped with

13305

the

13306

13307

from the local machine (e.g.

13308

<ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>patch</ulink>

13309

files).

13310

The path is relative to the

13311

13312

variable.

13313

Thus, the build system searches, in order, from the

13314

following directories, which are assumed to be a

13315

subdirectories of the directory in which the

13316

recipe file (<filename>.bb</filename>) or

13317

append file (<filename>.bbappend</filename>)

resides:

The base recipe name without any special

13322

suffix or version numbers.

13323

</para></listitem>

13324

13325

<filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.

13326

The base recipe name and version but without

13327

any special package name suffix.

13328

</para></listitem>

13329

<listitem><para><emphasis>files -</emphasis>

13330

Files within a directory, which is named

13331

<filename>files</filename> and is also

13332

alongside the recipe or append file.

</para></listitem>

</itemizedlist>

<note>

If you want the build system to pick up files

13337

specified through a

13338

13339

statement from your append file, you need to be

13340

sure to extend the

13341

<filename>FILESPATH</filename>

13342

variable by also using the

13343

13344

variable from within your append file.

13345

</note>

13346

</para></listitem>

13347

<listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a

13348

Bazaar revision control repository.</para></listitem>

13349

<listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a

13350

Git revision control repository.</para></listitem>

13351

<listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from

13352

an OSC (OpenSUSE Build service) revision control repository.</para></listitem>

13353

<listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from

13354

a repo (Git) repository.</para></listitem>

13355

13356

Fetches files from a ClearCase repository.

13357

</para></listitem>

13358

<listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from

13359

the Internet using <filename>http</filename>.</para></listitem>

13360

<listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files

13361

from the Internet using <filename>https</filename>.</para></listitem>

13362

<listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files

13363

from the Internet using <filename>ftp</filename>.</para></listitem>

13364

<listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from

13365

a CVS revision control repository.</para></listitem>

13366

<listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from

13367

a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>

13368

<listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from

13369

a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>

13370

<listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from

13371

a secure shell.</para></listitem>

13372

<listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from

13373

a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>

13374

<listitem><para><emphasis><filename>npm://</filename> -</emphasis> Fetches JavaScript

13375

modules from a registry.

</para></listitem>

</itemizedlist>

</para>

<para>

Standard and recipe-specific options for <filename>SRC_URI</filename> exist.

13382

Here are standard options:

13383

13384

<listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply

13385

the patch or not.

13386

The default action is to apply the patch.</para></listitem>

13387

<listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which

13388

striplevel to use when applying the patch.

13389

The default level is 1.</para></listitem>

13390

<listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies

13391

the directory in which the patch should be applied.

13392

The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.

</para></listitem>

</itemizedlist>

</para>

<para>

Here are options specific to recipes building code from a revision control system:

13399

13400

<listitem><para><emphasis><filename>mindate</filename> -</emphasis>

13401

Apply the patch only if

13402

13403

is equal to or greater than <filename>mindate</filename>.

13404

</para></listitem>

13405

<listitem><para><emphasis><filename>maxdate</filename> -</emphasis>

13406

Apply the patch only if <filename>SRCDATE</filename>

13407

is not later than <filename>maxdate</filename>.

13408

</para></listitem>

13409

<listitem><para><emphasis><filename>minrev</filename> -</emphasis>

13410

Apply the patch only if <filename>SRCREV</filename>

13411

is equal to or greater than <filename>minrev</filename>.

13412

</para></listitem>

13413

<listitem><para><emphasis><filename>maxrev</filename> -</emphasis>

13414

Apply the patch only if <filename>SRCREV</filename>

13415

is not later than <filename>maxrev</filename>.

13416

</para></listitem>

13417

13418

Apply the patch only if <filename>SRCREV</filename>

13419

is equal to <filename>rev</filename>.

13420

</para></listitem>

13421

<listitem><para><emphasis><filename>notrev</filename> -</emphasis>

13422

Apply the patch only if <filename>SRCREV</filename>

13423

is not equal to <filename>rev</filename>.

</para></listitem>

</itemizedlist>

</para>

<para>

Here are some additional options worth mentioning:

13430

13431

<listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls

13432

whether or not to unpack the file if it is an archive.

13433

The default action is to unpack the file.</para></listitem>

13434

<listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file

13435

(or extracts its contents) into the specified

13436

subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

13437

when the Git fetcher is used.

13438

</para></listitem>

13439

<listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file

13440

(or extracts its contents) into the specified

13441

subdirectory of <filename>WORKDIR</filename>

13442

when the local (<filename>file://</filename>)

13443

fetcher is used.

13444

</para></listitem>

13445

<listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file

13446

(or extracts its contents) into the specified

13447

subdirectory of <filename>WORKDIR</filename> when

13448

the CVS fetcher is used.

13449

</para></listitem>

13450

<listitem><para><emphasis><filename>subpath</filename> -</emphasis>

13451

Limits the checkout to a specific subpath of the

13452

tree when using the Git fetcher is used.

13453

</para></listitem>

13454

<listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a

13455

name to be used for association with <filename>SRC_URI</filename> checksums

13456

when you have more than one file specified in <filename>SRC_URI</filename>.

13457

</para></listitem>

13458

<listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies

13459

the filename used when storing the downloaded file.</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>

13466

<info>

13467

SRC_URI_OVERRIDES_PACKAGE_ARCH[doc] = "By default, the OpenEmbedded build system automatically detects whether SRC_URI contains files that are machine-specific. If so, the build system automatically changes PACKAGE_ARCH. Setting this variable to '0' disables this behavior."

</info>

By default, the OpenEmbedded build system automatically detects whether

13472

13473

contains files that are machine-specific.

13474

If so, the build system automatically changes

13475

<filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.

13476

Setting this variable to "0" disables this behavior.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>

13482

<info>

13483

SRCDATE[doc] = "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)."

</info>

The date of the source code used to build the package.

13488

This variable applies only if the source was fetched from a Source Code Manager (SCM).

</para>

</glossdef>

</glossentry>

<glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>

13494

<info>

13495

SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV."

</info>

Returns the version string of the current package.

13500

This string is used to help define the value of

</para>

<para>

The <filename>SRCPV</filename> variable is defined in the

13506

<filename>meta/conf/bitbake.conf</filename> configuration

file in the

as follows:

SRCPV = "${@bb.fetch2.get_srcrev(d)}"

</literallayout>

</para>

<para>

Recipes that need to define <filename>PV</filename> do so

13517

with the help of the <filename>SRCPV</filename>.

13518

For example, the <filename>ofono</filename> recipe

13519

(<filename>ofono_git.bb</filename>) located in

13520

<filename>meta/recipes-connectivity</filename> in the

13521

Source Directory defines <filename>PV</filename> as

13522

follows:

13523

13524

PV = "0.12-git${SRCPV}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>

13531

<info>

13532

SRCREV[doc] = "The revision of the source code used to build the package. This variable applies to Subversion, Git, Mercurial, and Bazaar only."

</info>

The revision of the source code used to build the package.

13537

This variable applies to Subversion, Git, Mercurial, and

13538

Bazaar only.

13539

Note that if you want to build a fixed revision and you

13540

want to avoid performing a query on the remote repository

13541

every time BitBake parses your recipe, you should specify

13542

a <filename>SRCREV</filename> that is a

13543

full revision identifier and not just a tag.

13544

<note>

13545

For information on limitations when inheriting the

13546

latest revision of software using

13547

<filename>SRCREV</filename>, see the

13548

13549

variable description and the

13550

"<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"

13551

section, which is in the Yocto Project Development

Tasks Manual.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>

13560

<info>

13561

SSTATE_DIR[doc] = "The directory for the shared state cache."

</info>

The directory for the shared state cache.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>

13571

<info>

13572

SSTATE_MIRROR_ALLOW_NETWORK[doc] = "If set to "1", allows fetches from mirrors that are specified in SSTATE_MIRRORS to work even when fetching from the network is disabled by setting BB_NO_NETWORK to "1"."

</info>

If set to "1", allows fetches from

13577

mirrors that are specified in

13578

13579

to work even when fetching from the network is

13580

disabled by setting <filename>BB_NO_NETWORK</filename>

13581

to "1".

13582

Using the

13583

<filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>

13584

variable is useful if you have set

13585

<filename>SSTATE_MIRRORS</filename> to point to an

13586

internal server for your shared state cache, but

13587

you want to disable any other fetching from the network.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>

13593

<info>

13594

SSTATE_MIRRORS[doc] = "Configures the OpenEmbedded build system to search other mirror locations for prebuilt cache data objects before building out the data. You can specify a filesystem directory or a remote URL such as HTTP or FTP."

</info>

Configures the OpenEmbedded build system to search other

13599

mirror locations for prebuilt cache data objects before

13600

building out the data.

13601

This variable works like fetcher

13602

13603

and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>

13604

and points to the cache locations to check for the shared

13605

state (sstate) objects.

</para>

<para>

You can specify a filesystem directory or a remote URL such

13610

as HTTP or FTP.

13611

The locations you specify need to contain the shared state

13612

cache (sstate-cache) results from previous builds.

13613

The sstate-cache you point to can also be from builds on

other machines.

</para>

<para>

When pointing to sstate build artifacts on another machine

13619

that uses a different GCC version for native builds,

13620

you must configure <filename>SSTATE_MIRRORS</filename>

13621

with a regular expression that maps local search paths

13622

to server paths.

13623

The paths need to take into account

set by the

class.

For example, the following maps the local search path

13629

<filename>universal-4.9</filename> to the server-provided

13630

path <replaceable>server_url_sstate_path</replaceable>:

13631

13632

SSTATE_MIRRORS ?= file://universal-4.9/(.*) http://<replaceable>server_url_sstate_path</replaceable>/universal-4.8/\1 \n

</literallayout>

</para>

<para>

If a mirror uses the same structure as

13638

13639

you need to add

13640

"PATH" at the end as shown in the examples below.

13641

The build system substitutes the correct path within the

directory structure.

SSTATE_MIRRORS ?= "\

file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \

13646

file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_SCAN_FILES'><glossterm>SSTATE_SCAN_FILES</glossterm>

13653

<info>

13654

SSTATE_SCAN_FILES[doc] = "Controls the list of files the OpenEmbedded build system scans for hardcoded installation paths."

</info>

Controls the list of files the OpenEmbedded build system

13659

scans for hardcoded installation paths. The variable uses a

13660

space-separated list of filenames (not paths) with standard

13661

wildcard characters allowed.

</para>

<para>

During a build, the OpenEmbedded build system creates a

13666

shared state (sstate) object during the first stage of

13667

preparing the sysroots. That object is scanned for

13668

hardcoded paths for original installation locations.

13669

The list of files that are scanned for paths is controlled

13670

by the <filename>SSTATE_SCAN_FILES</filename> variable.

13671

Typically, recipes add files they want to be scanned to the

13672

value of <filename>SSTATE_SCAN_FILES</filename> rather than

13673

the variable being comprehensively set. The

13674

13675

class specifies the default list of files.

</para>

<para>

For details on the process, see the

class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>

13687

<info>

13688

STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host."

</info>

Specifies the path to the <filename>/lib</filename>

13693

subdirectory of the sysroot directory for the

build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>

13700

<info>

13701

STAGING_BASELIBDIR[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."

</info>

Specifies the path to the <filename>/lib</filename>

13706

subdirectory of the sysroot directory for the target

13707

for which the current recipe is being built

13708

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>

13714

<info>

13715

STAGING_BINDIR[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."

</info>

Specifies the path to the

13720

<filename>/usr/bin</filename> subdirectory of the

13721

sysroot directory for the target for which the current

13722

recipe is being built

13723

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm>

13729

<info>

13730

STAGING_BINDIR_CROSS[doc] = "Specifies the path to the directory containing binary configuration scripts. These scripts provide configuration information for other software that wants to make use of libraries or include files provided by the software associated with the script."

</info>

Specifies the path to the directory containing binary

13735

configuration scripts.

13736

These scripts provide configuration information for

13737

other software that wants to make use of libraries or

13738

include files provided by the software associated with

13739

the script.

13740

<note>

13741

This style of build configuration has been largely

13742

replaced by <filename>pkg-config</filename>.

13743

Consequently, if <filename>pkg-config</filename>

13744

is supported by the library to which you are linking,

13745

it is recommended you use

13746

<filename>pkg-config</filename> instead of a

13747

provided configuration script.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>

13754

<info>

13755

STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host."

</info>

Specifies the path to the

13760

<filename>/usr/bin</filename> subdirectory of the

13761

sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>

13767

<info>

13768

STAGING_DATADIR[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."

</info>

Specifies the path to the <filename>/usr/share</filename>

13773

subdirectory of the sysroot directory for the target

13774

for which the current recipe is being built

13775

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm>

13781

<info>

13782

STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host."

</info>

Specifies the path to the <filename>/usr/share</filename>

13787

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>

13793

<info>

13794

STAGING_DIR[doc] = "Helps construct the recipe-sysroots directory, which is used during packaging."

</info>

Helps construct the <filename>recipe-sysroots</filename>

13799

directory, which is used during packaging.

</para>

<para>

For information on how staging for recipe-specific

13804

sysroots occurs, see the

13805

13806

task, the

13807

"<ulink url='&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes'>Sharing Files Between Recipes</ulink>"

13808

section in the Yocto Project Development Tasks Manual, the

13809

"<ulink url='&YOCTO_DOCS_OM_URL;#configuration-compilation-and-staging-dev-environment'>Configuration, Compilation, and Staging</ulink>"

13810

section in the Yocto Project Overview and Concepts Manual,

and the

variable.

<note>

Recipes should never write files directly under

13816

the <filename>STAGING_DIR</filename> directory because

13817

the OpenEmbedded build system

13818

manages the directory automatically.

13819

Instead, files should be installed to

within your recipe's

task and then the OpenEmbedded build system will

13824

stage a subset of those files into the sysroot.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>

13831

<info>

13832

STAGING_DIR_HOST[doc] = "Specifies the path to the sysroot directory for the system that the component is built to run on."

</info>

Specifies the path to the sysroot directory for the system

13837

on which the component is built to run (the system that

13838

hosts the component).

13839

For most recipes, this sysroot is the one in which that

recipe's

task copies files.

Exceptions include <filename>-native</filename> recipes,

13844

where the <filename>do_populate_sysroot</filename> task

13845

instead uses

13846

13847

Depending on the type of recipe and the build target,

13848

<filename>STAGING_DIR_HOST</filename> can have the

following values:

For recipes building for the target machine, the

13853

value is

13854

"${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".

13855

</para></listitem>

13856

13857

For native recipes building for the build host, the

13858

value is empty given the assumption that when

13859

building for the build host, the build host's own

13860

directories should be used.

13861

<note>

13862

<para><filename>-native</filename> recipes are

13863

not installed into host paths like such as

13864

<filename>/usr</filename>.

13865

Rather, these recipes are installed into

13866

<filename>STAGING_DIR_NATIVE</filename>.

13867

When compiling <filename>-native</filename>

13868

recipes, standard build environment variables

such as

and

are set up so that both host paths and

13874

<filename>STAGING_DIR_NATIVE</filename> are

13875

searched for libraries and headers using, for

13876

example, GCC's <filename>-isystem</filename>

13877

option.</para>

13878

13879

<para>Thus, the emphasis is that the

13880

<filename>STAGING_DIR*</filename> variables

13881

should be viewed as input variables by tasks

such as

and

Having the real system root correspond to

13888

<filename>STAGING_DIR_HOST</filename> makes

13889

conceptual sense for

13890

<filename>-native</filename> recipes, as

13891

they make use of host headers and libraries.

</para>

</note>

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>

13901

<info>

13902

STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory used when building components that run on the build host itself."

</info>

Specifies the path to the sysroot directory used when

13907

building components that run on the build host itself.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm>

13913

<info>

13914

STAGING_DIR_TARGET[doc] = "Specifies the path to the sysroot used for the system for which the component generates code."

</info>

Specifies the path to the sysroot used for the system for

13919

which the component generates code.

13920

For components that do not generate code, which is the

13921

majority, <filename>STAGING_DIR_TARGET</filename> is set

to match

</para>

<para>

Some recipes build binaries that can run on the target

13928

system but those binaries in turn generate code for

13929

another different system (e.g. cross-canadian recipes).

13930

Using terminology from GNU, the primary system is referred

13931

to as the "HOST" and the secondary, or different, system is

13932

referred to as the "TARGET".

13933

Thus, the binaries run on the "HOST" system

13934

and generate binaries for the "TARGET" system.

13935

The <filename>STAGING_DIR_HOST</filename> variable points

13936

to the sysroot used for the "HOST" system, while

13937

<filename>STAGING_DIR_TARGET</filename>

13938

points to the sysroot used for the "TARGET" system.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm>

13944

<info>

13945

STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host."

</info>

Specifies the path to the <filename>/etc</filename>

13950

subdirectory of the sysroot directory for the

build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>

13957

<info>

13958

STAGING_EXECPREFIXDIR[doc] = "Specifies the path to the /usr subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."

</info>

Specifies the path to the <filename>/usr</filename>

13963

subdirectory of the sysroot directory for the target

13964

for which the current recipe is being built

13965

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>

13971

<info>

13972

STAGING_INCDIR[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the target for which the current recipe being built (STAGING_DIR_HOST)."

</info>

Specifies the path to the

13977

<filename>/usr/include</filename> subdirectory of the

13978

sysroot directory for the target for which the current

13979

recipe being built

13980

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm>

13986

<info>

13987

STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host."

</info>

Specifies the path to the <filename>/usr/include</filename>

13992

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_KERNEL_BUILDDIR'><glossterm>STAGING_KERNEL_BUILDDIR</glossterm>

13998

<info>

13999

STAGING_KERNEL_BUILDDIR[doc] = "Points to the directory containing the kernel build artifacts."

</info>

Points to the directory containing the kernel build

14004

artifacts.

14005

Recipes building software that needs to access kernel

14006

build artifacts

14007

(e.g. <filename>systemtap-uprobes</filename>) can look in

14008

the directory specified with the

14009

<filename>STAGING_KERNEL_BUILDDIR</filename> variable to

14010

find these artifacts after the kernel has been built.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>

14016

<info>

14017

STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules."

</info>

The directory with kernel headers that are required to build out-of-tree

modules.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm>

14028

<info>

14029

STAGING_LIBDIR[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."

</info>

Specifies the path to the <filename>/usr/lib</filename>

14034

subdirectory of the sysroot directory for the target for

14035

which the current recipe is being built

14036

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm>

14042

<info>

14043

STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host."

</info>

Specifies the path to the <filename>/usr/lib</filename>

14048

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAMP'><glossterm>STAMP</glossterm>

14054

<info>

14055

STAMP[doc] = "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."

</info>

Specifies the base path used to create recipe stamp files.

14060

The path to an actual stamp file is constructed by evaluating this

14061

string and then appending additional information.

14062

Currently, the default assignment for <filename>STAMP</filename>

14063

as set in the <filename>meta/conf/bitbake.conf</filename> file

14064

is:

14065

14066

STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"

</literallayout>

</para>

<para>

For information on how BitBake uses stamp files to determine

14072

if a task should be rerun, see the

14073

"<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"

14074

section in the Yocto Project Overview and Concepts Manual.

</para>

<para>

See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,

information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>

14090

<info>

14091

STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps."

</info>

Specifies the base directory in which the OpenEmbedded

14096

build system places stamps.

14097

The default directory is

14098

<filename>${TMPDIR}/stamps</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STRIP'><glossterm>STRIP</glossterm>

14104

<info>

14105

STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)."

</info>

The minimal command and arguments to run

14110

<filename>strip</filename>, which is used to strip

symbols.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>

14117

<info>

14118

SUMMARY[doc] = "The short (80 characters or less) summary of the binary package for packaging systems such as opkg, rpm, or dpkg. By default, SUMMARY is used to define the DESCRIPTION variable if DESCRIPTION is not set in the recipe."

</info>

The short (72 characters or less) summary of the binary package for packaging

14123

systems such as <filename>opkg</filename>, <filename>rpm</filename>, or

14124

<filename>dpkg</filename>.

14125

By default, <filename>SUMMARY</filename> is used to define

14126

the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>

14127

variable if <filename>DESCRIPTION</filename> is not set

in the recipe.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>

14134

<info>

14135

SVNDIR[doc] = "The directory where Subversion checkouts are stored."

</info>

The directory in which files checked out of a Subversion

system are stored.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>

14146

<info>

14147

SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console."

</info>

Specifies the kernel boot default console.

14152

If you want to use a console other than the default,

14153

set this variable in your recipe as follows where "X" is

14154

the console number you want to use:

14155

14156

SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"

</literallayout>

</para>

<para>

The

class initially sets this variable to null but then checks

for a value later.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>

14170

<info>

14171

SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file."

</info>

Lists additional options to add to the syslinux file.

14176

You need to set this variable in your recipe.

14177

If you want to list multiple options, separate the options

14178

with a semicolon character (<filename>;</filename>).

</para>

<para>

The

class uses this variable to create a set of options.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>

14190

<info>

14191

SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off."

</info>

Specifies the alternate serial port or turns it off.

14196

To turn off serial, set this variable to an empty string

14197

in your recipe.

14198

The variable's default value is set in the

class as follows:

SYSLINUX_SERIAL ?= "0 115200"

</literallayout>

</para>

<para>

The class checks for and uses the variable as needed.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>

14213

<info>

14214

SYSLINUX_SPLASH[doc] = "An .LSS file used as the background for the VGA boot menu when you use the boot menu."

</info>

An <filename>.LSS</filename> file used as the background

14219

for the VGA boot menu when you use the boot menu.

14220

You need to set this variable in your recipe.

</para>

<para>

The

class checks for this variable and if found, the

14227

OpenEmbedded build system installs the splash screen.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>

14233

<info>

14234

SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument."

</info>

Specifies the alternate console=tty... kernel boot argument.

14239

The variable's default value is set in the

class as follows:

SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"

</literallayout>

</para>

<para>

The class checks for and uses the variable as needed.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm>

14254

<info>

14255

SYSROOT_DESTDIR[doc] = "Points to the temporary work directory (default ${WORKDIR}/sysroot-destdir) where the files populated into the sysroot are assembled during the do_populate_sysroot task."

</info>

Points to the temporary directory under the work directory

14260

(default

14261

"<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destdir</filename>")

14262

where the files populated into the sysroot are assembled

during the

task.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>

14271

<info>

14272

SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task."

</info>

Directories that are staged into the sysroot by the

14277

14278

task.

14279

By default, the following directories are staged:

SYSROOT_DIRS = " \

${includedir} \

${libdir} \

${base_libdir} \

${nonarch_base_libdir} \

${datadir} \

"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm>

14294

<info>

14295

SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task."

</info>

Directories that are not staged into the sysroot by the

14300

14301

task.

14302

You can use this variable to exclude certain subdirectories

14303

of directories listed in

14304

14305

from staging.

14306

By default, the following directories are not staged:

14307

14308

SYSROOT_DIRS_BLACKLIST = " \

${mandir} \

${docdir} \

${infodir} \

${datadir}/locale \

${datadir}/applications \

${datadir}/fonts \

${datadir}/pixmaps \

"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm>

14323

<info>

14324

SYSROOT_DIRS_NATIVE[doc] = "Extra directories staged into the sysroot by the do_populate_sysroot task for -native recipes, in addition to those specified in SYSROOT_DIRS."

</info>

Extra directories staged into the sysroot by the

14329

14330

task for <filename>-native</filename> recipes, in addition

14331

to those specified in

14332

14333

By default, the following extra directories are staged:

14334

14335

SYSROOT_DIRS_NATIVE = " \

${bindir} \

${sbindir} \

${base_bindir} \

${base_sbindir} \

${libexecdir} \

${sysconfdir} \

${localstatedir} \

"

</literallayout>

<note>

Programs built by <filename>-native</filename> recipes

14347

run directly from the sysroot

14348

(<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>),

14349

which is why additional directories containing program

14350

executables and supporting files need to be staged.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>

14357

<info>

14358

SYSROOT_PREPROCESS_FUNCS[doc] = "A list of functions to execute after files are staged into the sysroot. These functions are usually used to apply additional processing on the staged files, or to stage additional files."

</info>

A list of functions to execute after files are staged into

14363

the sysroot.

14364

These functions are usually used to apply additional

14365

processing on the staged files, or to stage additional

files.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>

14372

<info>

14373

SYSTEMD_AUTO_ENABLE[doc] = "For recipes that inherit the systemd class, this variable specifies whether the specified service in SYSTEMD_SERVICE should start automatically or not."

</info>

When inheriting the

class, this variable specifies whether the specified service

14380

in

14381

14382

should start automatically or not.

14383

By default, the service is enabled to automatically start

14384

at boot time.

14385

The default setting is in the

class as follows:

SYSTEMD_AUTO_ENABLE ??= "enable"

</literallayout>

</para>

<para>

You can disable the service by setting the variable to

"disable".

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm>

14401

<info>

14402

SYSTEMD_BOOT_CFG[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_CFG variable specifies the configuration file that should be used."

</info>

When

is set to "systemd-boot", the

14409

<filename>SYSTEMD_BOOT_CFG</filename> variable specifies the

14410

configuration file that should be used.

14411

By default, the

14412

14413

class sets the <filename>SYSTEMD_BOOT_CFG</filename> as

14414

follows:

14415

14416

SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf"

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

14422

<ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSTEMD_BOOT_ENTRIES'><glossterm>SYSTEMD_BOOT_ENTRIES</glossterm>

14428

<info>

14429

SYSTEMD_BOOT_ENTRIES[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_ENTRIES variable specifies a list of entry files (*.conf) to install that contain one boot entry per file."

</info>

When

is set to "systemd-boot", the

14436

<filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies

14437

a list of entry files

14438

(<filename>*.conf</filename>) to install that contain

14439

one boot entry per file.

14440

By default, the

14441

14442

class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as

14443

follows:

14444

14445

SYSTEMD_BOOT_ENTRIES ?= ""

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

14451

<ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSTEMD_BOOT_TIMEOUT'><glossterm>SYSTEMD_BOOT_TIMEOUT</glossterm>

14457

<info>

14458

SYSTEMD_BOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_TIMEOUT variable specifies the boot menu timeout in seconds."

</info>

When

is set to "systemd-boot", the

14465

<filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies

14466

the boot menu timeout in seconds.

14467

By default, the

14468

14469

class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as

14470

follows:

14471

14472

SYSTEMD_BOOT_TIMEOUT ?= "10"

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

14478

<ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>

14484

<info>

14485

SYSTEMD_PACKAGES[doc] = "For recipes that inherit the systemd class, this variable locates the systemd unit files when they are not found in the main recipe's package."

</info>

When inheriting the

class, this variable locates the systemd unit files when

14492

they are not found in the main recipe's package.

14493

By default, the

14494

<filename>SYSTEMD_PACKAGES</filename> variable is set

14495

such that the systemd unit files are assumed to reside in

14496

the recipes main package:

14497

14498

SYSTEMD_PACKAGES ?= "${PN}"

</literallayout>

</para>

<para>

If these unit files are not in this recipe's main

14504

package, you need to use

14505

<filename>SYSTEMD_PACKAGES</filename> to list the package

14506

or packages in which the build system can find the systemd

unit files.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>

14513

<info>

14514

SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package."

</info>

When inheriting the

class, this variable specifies the systemd service name for

a package.

</para>

<para>

When you specify this file in your recipe, use a package

14526

name override to indicate the package to which the value

14527

applies.

14528

Here is an example from the connman recipe:

14529

14530

SYSTEMD_SERVICE_${PN} = "connman.service"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>

14537

<info>

14538

SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should run a getty, the default is '1'."

</info>

When using

<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,

14544

specifies a space-separated list of the virtual terminals

14545

that should run a

14546

<ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>

14547

(allowing login), assuming

is not set to "0".

</para>

<para>

The default value for

14554

<filename>SYSVINIT_ENABLED_GETTYS</filename> is "1"

14555

(i.e. only run a getty on the first virtual terminal).

</para>

</glossdef>

</glossentry>

</glossdiv>

<info>

T[doc] = "This variable points to a directory were BitBake places temporary files, which consist mostly of task logs and scripts, when building a particular recipe."

</info>

This variable points to a directory were BitBake places

14571

temporary files, which consist mostly of task logs and

14572

scripts, when building a particular recipe.

14573

The variable is typically set as follows:

14574

14575

T = "${WORKDIR}/temp"

</literallayout>

</para>

<para>

The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

14581

is the directory into which BitBake unpacks and builds the

14582

recipe.

14583

The default <filename>bitbake.conf</filename> file sets this variable.</para>

14584

<para>The <filename>T</filename> variable is not to be confused with

14585

the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,

14586

which points to the root of the directory tree where BitBake

14587

places the output of an entire build.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>

14593

<info>

14594

TARGET_ARCH[doc] = "The architecture of the device being built. The OpenEmbedded build system supports the following architectures: arm, mips, ppc, x86, x86-64."

</info>

The target machine's architecture.

14599

The OpenEmbedded build system supports many

14600

architectures.

14601

Here is an example list of architectures supported.

14602

This list is by no means complete as the architecture

is configurable:

arm

i586

x86_64

powerpc

powerpc64

mips

mipsel

</literallayout>

</para>

<para>

For additional information on machine architectures, see

the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm>

14625

<info>

14626

TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system."

</info>

Specifies architecture-specific assembler flags for the

14631

target system.

14632

<filename>TARGET_AS_ARCH</filename> is initialized from

14633

14634

by default in the BitBake configuration file

14635

(<filename>meta/conf/bitbake.conf</filename>):

14636

14637

TARGET_AS_ARCH = "${TUNE_ASARGS}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>

14644

<info>

14645

TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system."

</info>

Specifies architecture-specific C compiler flags for the

14650

target system.

14651

<filename>TARGET_CC_ARCH</filename> is initialized from

by default.

<note>

It is a common workaround to append

14656

14657

to <filename>TARGET_CC_ARCH</filename>

14658

in recipes that build software for the target that

14659

would not otherwise respect the exported

14660

<filename>LDFLAGS</filename> variable.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>

14667

<info>

14668

TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune."

</info>

This is a specific kernel compiler flag for a CPU or

14673

Application Binary Interface (ABI) tune.

14674

The flag is used rarely and only for cases where a

14675

userspace

14676

14677

is not compatible with the kernel compilation.

14678

The <filename>TARGET_CC_KERNEL_ARCH</filename> variable

14679

allows the kernel (and associated modules) to use a

14680

different configuration.

14681

See the

14682

<filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>

file in the

for an example.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>

14691

<info>

14692

TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS."

</info>

Specifies the flags to pass to the C compiler when building

14697

for the target.

14698

When building in the target context,

14699

14700

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

14705

the <filename>CFLAGS</filename> variable in the environment

14706

to the <filename>TARGET_CFLAGS</filename> value so that

14707

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>

14714

<info>

14715

TARGET_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the target."

</info>

Specifies the flags to pass to the C pre-processor

14720

(i.e. to both the C and the C++ compilers) when building

14721

for the target.

14722

When building in the target context,

14723

14724

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

14729

the <filename>CPPFLAGS</filename> variable in the

14730

environment to the <filename>TARGET_CPPFLAGS</filename>

14731

value so that executables built using the SDK also have

the flags applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>

14738

<info>

14739

TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target."

</info>

Specifies the flags to pass to the C++ compiler when

14744

building for the target.

14745

When building in the target context,

14746

14747

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

14752

the <filename>CXXFLAGS</filename> variable in the

14753

environment to the <filename>TARGET_CXXFLAGS</filename>

14754

value so that executables built using the SDK also have

the flags applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>

14761

<info>

14762

TARGET_FPU[doc] = "Specifies the method for handling FPU code. For FPU-less targets, which include most ARM CPUs, the variable must be set to 'soft'. If not, the kernel emulation gets used, which results in a performance penalty."

</info>

Specifies the method for handling FPU code.

14767

For FPU-less targets, which include most ARM CPUs, the variable must be

14768

set to "soft".

14769

If not, the kernel emulation gets used, which results in a performance penalty.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm>

14775

<info>

14776

TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system."

</info>

Specifies architecture-specific linker flags for the

14781

target system.

14782

<filename>TARGET_LD_ARCH</filename> is initialized from

14783

14784

by default in the BitBake configuration file

14785

(<filename>meta/conf/bitbake.conf</filename>):

14786

14787

TARGET_LD_ARCH = "${TUNE_LDARGS}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>

14794

<info>

14795

TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target."

</info>

Specifies the flags to pass to the linker when building

14800

for the target.

14801

When building in the target context,

14802

14803

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

14808

the

14809

14810

variable in the environment to the

14811

<filename>TARGET_LDFLAGS</filename> value so that

14812

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>

14819

<info>

14820

TARGET_OS[doc] = "Specifies the target's operating system."

</info>

Specifies the target's operating system.

14825

The variable can be set to "linux" for glibc-based systems

14826

(GNU C Library) and to "linux-musl" for musl libc.

14827

For ARM/EABI targets, "linux-gnueabi" and "linux-musleabi"

14828

possible values exist.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_PREFIX'><glossterm>TARGET_PREFIX</glossterm>

14834

<info>

14835

TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools."

</info>

Specifies the prefix used for the toolchain binary target

tools.

</para>

<para>

Depending on the type of recipe and the build target,

14845

<filename>TARGET_PREFIX</filename> is set as follows:

14846

14847

14848

For recipes building for the target machine,

14849

the value is

14850

"${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".

14851

</para></listitem>

14852

14853

For native recipes, the build system sets the

14854

variable to the value of

14855

<filename>BUILD_PREFIX</filename>.

14856

</para></listitem>

14857

14858

For native SDK recipes

14859

(<filename>nativesdk</filename>), the

14860

build system sets the variable to the value of

14861

<filename>SDK_PREFIX</filename>.

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm>

14869

<info>

14870

TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."

</info>

Specifies the system, including the architecture and the

14875

operating system, for which the build is occurring in

14876

the context of the current recipe.

</para>

<para>

The OpenEmbedded build system automatically sets this

variable based on

and

variables.

<note>

You do not need to set the

14889

<filename>TARGET_SYS</filename> variable yourself.

</note>

</para>

<para>

Consider these two examples:

14895

14896

14897

Given a native recipe on a 32-bit, x86 machine

14898

running Linux, the value is "i686-linux".

14899

</para></listitem>

14900

14901

Given a recipe being built for a little-endian,

14902

MIPS target running Linux, the value might be

"mipsel-linux".

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_VENDOR'><glossterm>TARGET_VENDOR</glossterm>

14911

<info>

14912

TARGET_VENDOR[doc] = "The name of the target vendor."

</info>

Specifies the name of the target vendor.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>

14922

<info>

14923

TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc', 'musl' or 'newlib'."

</info>

Specifies the GNU standard C library

14928

(<filename>libc</filename>) variant to use during the

14929

build process.

14930

This variable replaces <filename>POKYLIBC</filename>,

14931

which is no longer supported.

</para>

<para>

You can select "glibc", "musl", "newlib", or "baremetal"

</para>

</glossdef>

</glossentry>

<glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm>

14941

<info>

14942

TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."

</info>

Specifies a suffix to be appended onto the

14947

14948

value.

14949

The suffix identifies the <filename>libc</filename> variant

14950

for building.

14951

When you are building for multiple variants with the same

14952

14953

this mechanism ensures that output for different

14954

<filename>libc</filename> variants is kept separate to

14955

avoid potential conflicts.

</para>

<para>

In the <filename>defaultsetup.conf</filename> file, the

14960

default value of <filename>TCLIBCAPPEND</filename> is

14961

"-${TCLIBC}".

14962

However, distros such as poky, which normally only support

14963

one <filename>libc</filename> variant, set

14964

<filename>TCLIBCAPPEND</filename> to "" in their distro

14965

configuration file resulting in no suffix being applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>

14971

<info>

14972

TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'."

</info>

Specifies the toolchain selector.

14977

<filename>TCMODE</filename> controls the characteristics

14978

of the generated packages and images by telling the

14979

OpenEmbedded build system which toolchain profile to use.

14980

By default, the OpenEmbedded build system builds its own

14981

internal toolchain.

14982

The variable's default value is "default", which uses

14983

that internal toolchain.

14984

<note>

14985

If <filename>TCMODE</filename> is set to a value

14986

other than "default", then it is your responsibility

14987

to ensure that the toolchain is compatible with the

14988

default toolchain.

14989

Using older or newer versions of these components

14990

might cause build problems.

14991

See the Release Notes for the Yocto Project release

14992

for the specific components with which the toolchain

14993

must be compatible.

14994

To access the Release Notes, go to the

14995

<ulink url='&YOCTO_HOME_URL;/software-overview/downloads/'>Downloads</ulink>

14996

page on the Yocto Project website and click on the

14997

"RELEASE INFORMATION" link for the appropriate

release.

</note>

</para>

<para>

The <filename>TCMODE</filename> variable is similar to

15004

15005

which controls the variant of the GNU standard C library

15006

(<filename>libc</filename>) used during the build process:

15007

<filename>glibc</filename> or <filename>musl</filename>.

</para>

<para>

With additional layers, it is possible to use a pre-compiled

15012

external toolchain.

15013

One example is the Sourcery G++ Toolchain.

15014

The support for this toolchain resides in the separate

15015

<trademark class='registered'>Mentor Graphics</trademark>

15016

<filename>meta-sourcery</filename> layer at

15017

<ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.

</para>

<para>

The layer's <filename>README</filename> file contains

15022

information on how to use the Sourcery G++ Toolchain as

15023

an external toolchain.

15024

In summary, you must be sure to add the layer to your

15025

<filename>bblayers.conf</filename> file in front of the

15026

<filename>meta</filename> layer and then set the

15027

<filename>EXTERNAL_TOOLCHAIN</filename>

15028

variable in your <filename>local.conf</filename> file

15029

to the location in which you installed the toolchain.

</para>

<para>

The fundamentals used for this example apply to any

15034

external toolchain.

15035

You can use <filename>meta-sourcery</filename> as a

15036

template for adding support for other external toolchains.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>

15042

<info>

15043

TEST_EXPORT_DIR[doc] = "The location the OpenEmbedded build system uses to export tests when the TEST_EXPORT_ONLY variable is set to "1"."

</info>

The location the OpenEmbedded build system uses to export

15048

tests when the

15049

15050

variable is set to "1".

</para>

<para>

The <filename>TEST_EXPORT_DIR</filename> variable defaults

15055

to <filename>"${TMPDIR}/testimage/${PN}"</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>

15061

<info>

15062

TEST_EXPORT_ONLY[doc] = "Specifies to export the tests only. Set this variable to "1" if you do not want to run the tests but you want them to be exported in a manner that you to run them outside of the build system."

</info>

Specifies to export the tests only.

15067

Set this variable to "1" if you do not want to run the

15068

tests but you want them to be exported in a manner that

15069

you to run them outside of the build system.

</para>

</glossdef>

</glossentry>

<info>

TEST_LOG_DIR[doc] = "Holds the SSH log and the boot log for QEMU machines. The TEST_LOG_DIR variable defaults to "${WORKDIR}/testimage"."

</info>

Holds the SSH log and the boot log for QEMU machines.

15081

The <filename>TEST_LOG_DIR</filename> variable defaults

15082

to <filename>"${WORKDIR}/testimage"</filename>.

15083

<note>

15084

Actual test results reside in the task log

15085

(<filename>log.do_testimage</filename>), which is in

15086

the <filename>${WORKDIR}/temp/</filename> directory.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>

15093

<info>

15094

TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test"

</info>

For automated hardware testing, specifies the command to

15099

use to control the power of the target machine under test.

15100

Typically, this command would point to a script that

15101

performs the appropriate action (e.g. interacting

15102

with a web-enabled power strip).

15103

The specified command should expect to receive as the last

15104

argument "off", "on" or "cycle" specifying to power off,

15105

on, or cycle (power off and then power on) the device,

respectively.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm>TEST_POWERCONTROL_EXTRA_ARGS</glossterm>

15112

<info>

15113

TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD"

</info>

For automated hardware testing, specifies additional

15118

arguments to pass through to the command specified in

15119

15120

Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>

15121

is optional.

15122

You can use it if you wish, for example, to separate the

15123

machine-specific and non-machine-specific parts of the

arguments.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>

15130

<info>

15131

TEST_QEMUBOOT_TIMEOUT[doc] = "The time in seconds allowed for an image to boot before automated runtime tests begin to run against an image."

</info>

The time in seconds allowed for an image to boot before

15136

automated runtime tests begin to run against an

15137

image.

15138

The default timeout period to allow the boot process to

15139

reach the login prompt is 500 seconds.

15140

You can specify a different value in the

15141

<filename>local.conf</filename> file.

</para>

<para>

For more information on testing images, see the

15146

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

15147

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>

15153

<info>

15154

TEST_SERIALCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to connect to the serial console of the target machine under test."

</info>

For automated hardware testing, specifies the command

15159

to use to connect to the serial console of the target

15160

machine under test.

15161

This command simply needs to connect to the serial console

15162

and forward that connection to standard input and output

15163

as any normal terminal program does.

</para>

<para>

For example, to use the Picocom terminal program on

15168

serial device <filename>/dev/ttyUSB0</filename> at

15169

115200bps, you would set the variable as follows:

15170

15171

TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm>TEST_SERIALCONTROL_EXTRA_ARGS</glossterm>

15178

<info>

15179

TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD."

</info>

For automated hardware testing, specifies additional

15184

arguments to pass through to the command specified in

15185

15186

Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>

15187

is optional.

15188

You can use it if you wish, for example, to separate the

15189

machine-specific and non-machine-specific parts of the

command.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>

15196

<info>

15197

TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected."

</info>

The IP address of the build machine (host machine).

15202

This IP address is usually automatically detected.

15203

However, if detection fails, this variable needs to be set

15204

to the IP address of the build machine (i.e. where

15205

the build is taking place).

15206

<note>

15207

The <filename>TEST_SERVER_IP</filename> variable

15208

is only used for a small number of tests such as

15209

the "dnf" test suite, which needs to download

15210

packages from

15211

<filename>WORKDIR/oe-rootfs-repo</filename>.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>

15218

<info>

15219

TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine."

</info>

Specifies the target controller to use when running tests

15224

against a test image.

15225

The default controller to use is "qemu":

TEST_TARGET = "qemu"

</literallayout>

</para>

<para>

A target controller is a class that defines how an

15233

image gets deployed on a target and how a target is started.

15234

A layer can extend the controllers by adding a module

15235

in the layer's <filename>/lib/oeqa/controllers</filename>

15236

directory and by inheriting the

15237

<filename>BaseTarget</filename> class, which is an abstract

15238

class that cannot be used as a value of

15239

<filename>TEST_TARGET</filename>.

</para>

<para>

You can provide the following arguments with

15244

<filename>TEST_TARGET</filename>:

15245

15246

15247

Boots a QEMU image and runs the tests.

15248

See the

15249

"<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"

15250

section in the Yocto Project Development Tasks

15251

Manual for more information.

15252

</para></listitem>

15253

<listitem><para><emphasis>"simpleremote":</emphasis>

15254

Runs the tests on target hardware that is already

15255

up and running.

15256

The hardware can be on the network or it can be

15257

a device running an image on QEMU.

15258

You must also set

15259

15260

when you use "simpleremote".

15261

<note>

15262

This argument is defined in

15263

<filename>meta/lib/oeqa/controllers/simpleremote.py</filename>.

</note>

</para></listitem>

</itemizedlist>

</para>

<para>

For information on running tests on hardware, see the

15271

"<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"

15272

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>

15278

<info>

15279

TEST_TARGET_IP[doc] = "The IP address of your hardware under test."

</info>

The IP address of your hardware under test.

15284

The <filename>TEST_TARGET_IP</filename> variable has no

effect when

is set to "qemu".

</para>

<para>

When you specify the IP address, you can also include a

port.

Here is an example:

TEST_TARGET_IP = "192.168.1.4:2201"

15296

</literallayout>

15297

Specifying a port is useful when SSH is started on a

15298

non-standard port or in cases when your hardware under test

15299

is behind a firewall or network that is not directly

15300

accessible from your host and you need to do port address

translation.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>

15307

<info>

15308

TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing."

</info>

An ordered list of tests (modules) to run against

15313

an image when performing automated runtime testing.

</para>

<para>

The OpenEmbedded build system provides a core set of tests

15318

that can be used against images.

15319

<note>

15320

Currently, there is only support for running these tests

15321

under QEMU.

15322

</note>

15323

Tests include <filename>ping</filename>,

15324

<filename>ssh</filename>, <filename>df</filename> among

15325

others.

15326

You can add your own tests to the list of tests by

15327

appending <filename>TEST_SUITES</filename> as follows:

15328

15329

TEST_SUITES_append = " <replaceable>mytest</replaceable>"

15330

</literallayout>

15331

Alternatively, you can provide the "auto" option to

15332

have all applicable tests run against the image.

15333

15334

TEST_SUITES_append = " auto"

15335

</literallayout>

15336

Using this option causes the build system to automatically

15337

run tests that are applicable to the image.

15338

Tests that are not applicable are skipped.

</para>

<para>

The order in which tests are run is important.

15343

Tests that depend on another test must appear later in the

15344

list than the test on which they depend.

15345

For example, if you append the list of tests with two

15346

tests (<filename>test_A</filename> and

15347

<filename>test_B</filename>) where

15348

<filename>test_B</filename> is dependent on

15349

<filename>test_A</filename>, then you must order the tests

15350

as follows:

15351

15352

TEST_SUITES = " test_A test_B"

</literallayout>

</para>

<para>

For more information on testing images, see the

15358

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

15359

section in the Yocto Project Development Tasks Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TESTIMAGE_AUTO'><glossterm>TESTIMAGE_AUTO</glossterm>

15365

<info>

15366

TESTIMAGE_AUTO[doc] = "Enables automatic testing of an image once it is built."

</info>

Automatically runs the series of automated tests for

15371

images when an image is successfully built.

15372

Setting <filename>TESTIMAGE_AUTO</filename> to "1"

15373

causes any image that successfully builds to automatically

15374

boot under QEMU.

15375

Using the variable also adds in dependencies so that any

15376

SDK for which testing is requested is automatically built

first.

</para>

<para>

These tests are written in Python making use of the

15382

<filename>unittest</filename> module, and the majority of

15383

them run commands on the target system over

15384

<filename>ssh</filename>.

15385

You can set this variable to "1" in your

15386

<filename>local.conf</filename> file in the

15387

15388

to have the OpenEmbedded build system automatically run

15389

these tests after an image successfully builds:

TESTIMAGE_AUTO = "1"

</literallayout>

For more information on enabling, running, and writing

15394

these tests, see the

15395

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

15396

section in the Yocto Project Development Tasks Manual and

15397

the

15398

"<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"

section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>

15405

<info>

15406

THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located."

</info>

The directory in which the file BitBake is currently

15411

parsing is located.

15412

Do not manually set this variable.

</para>

</glossdef>

</glossentry>

<info>

TIME[doc] = "The time the build was started using HMS format."

</info>

The time the build was started.

15424

Times appear using the hour, minute, and second (HMS)

15425

format (e.g. "140159" for one minute and fifty-nine

15426

seconds past 1400 hours).

</para>

</glossdef>

</glossentry>

<glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>

15432

<info>

15433

TMPDIR[doc] = "The temporary directory the OpenEmbedded build system uses when it does its work building images. By default, the TMPDIR variable is named tmp within the Build Directory."

</info>

This variable is the base directory the OpenEmbedded

15438

build system uses for all build output and intermediate

15439

files (other than the shared state cache).

15440

By default, the <filename>TMPDIR</filename> variable points

15441

to <filename>tmp</filename> within the

</para>

<para>

If you want to establish this directory in a location other

15447

than the default, you can uncomment and edit the following

15448

statement in the

15449

<filename>conf/local.conf</filename> file in the

15450

15451

15452

#TMPDIR = "${TOPDIR}/tmp"

15453

</literallayout>

15454

An example use for this scenario is to set

15455

<filename>TMPDIR</filename> to a local disk, which does

15456

not use NFS, while having the Build Directory use NFS.

</para>

<para>

The filesystem used by <filename>TMPDIR</filename> must

15461

have standard filesystem semantics (i.e. mixed-case files

15462

are unique, POSIX file locking, and persistent inodes).

15463

Due to various issues with NFS and bugs in some

15464

implementations, NFS does not meet this minimum

15465

requirement.

15466

Consequently, <filename>TMPDIR</filename> cannot be on

NFS.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>

15473

<info>

15474

TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment."

</info>

This variable lists packages the OpenEmbedded build system

15479

uses when building an SDK, which contains a

15480

cross-development environment.

15481

The packages specified by this variable are part of the

15482

toolchain set that runs on the

15483

15484

and each package should usually have the prefix

15485

<filename>nativesdk-</filename>.

15486

For example, consider the following command when

15487

building an SDK:

15488

15489

$ bitbake -c populate_sdk <replaceable>imagename</replaceable>

15490

</literallayout>

15491

In this case, a default list of packages is set in this

15492

variable, but you can add additional packages to the list.

15493

See the

15494

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"

15495

section in the Yocto Project Application Development and

15496

the Extensible Software Development Kit (eSDK) manual

15497

for more information.

</para>

<para>

For background information on cross-development toolchains

15502

in the Yocto Project development environment, see the

15503

"<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"

15504

section in the Yocto Project Overview and Concepts Manual.

15505

For information on setting up a cross-development

15506

environment, see the

15507

<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>

manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TOOLCHAIN_OUTPUTNAME'><glossterm>TOOLCHAIN_OUTPUTNAME</glossterm>

15514

<info>

15515

TOOLCHAIN_OUTPUTNAME[doc] = "Defines the name used for the toolchain output."

</info>

This variable defines the name used for the toolchain

output.

The

class sets the

<filename>TOOLCHAIN_OUTPUTNAME</filename> variable as

15525

follows:

15526

15527

TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"

</literallayout>

See the

and

variables for additional information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>

15539

<info>

15540

TOOLCHAIN_TARGET_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when it creates the target part of an SDK, which includes libraries and headers."

</info>

This variable lists packages the OpenEmbedded build system

15545

uses when it creates the target part of an SDK

15546

(i.e. the part built for the target hardware), which

15547

includes libraries and headers.

15548

Use this variable to add individual packages to the

15549

part of the SDK that runs on the target.

15550

See the

15551

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"

15552

section in the Yocto Project Application Development and

15553

the Extensible Software Development Kit (eSDK) manual for

more information.

</para>

<para>

For background information on cross-development toolchains

15559

in the Yocto Project development environment, see the

15560

"<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"

15561

section in the Yocto Project Overview and Concepts Manual.

15562

For information on setting up a cross-development

15563

environment, see the

15564

<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>

manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>

15571

<info>

15572

TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images."

</info>

The top-level

BitBake automatically sets this variable when you

15579

initialize your build environment using

</para>

</glossdef>

</glossentry>

<glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>

15586

<info>

15587

TRANSLATED_TARGET_ARCH[doc] = "A sanitized version of TARGET_ARCH. This variable is used where the architecture is needed in a value where underscores are not allowed."

</info>

A sanitized version of

15592

15593

This variable is used where the architecture is needed in

15594

a value where underscores are not allowed, for example

15595

within package filenames.

15596

In this case, dash characters replace any underscore

15597

characters used in <filename>TARGET_ARCH</filename>.

</para>

<para>

Do not edit this variable.

</para>

</glossdef>

</glossentry>

<info>

TUNE_ARCH[doc] = "The GNU canonical architecture for a specific architecture (i.e. arm, armeb, mips, mips64, and so forth)."

</info>

The GNU canonical architecture for a specific architecture

15613

(i.e. <filename>arm</filename>,

15614

<filename>armeb</filename>,

15615

<filename>mips</filename>,

15616

<filename>mips64</filename>, and so forth).

15617

BitBake uses this value to setup configuration.

</para>

<para>

<filename>TUNE_ARCH</filename> definitions are specific to

15622

a given architecture.

15623

The definitions can be a single static definition, or

15624

can be dynamically adjusted.

15625

You can see details for a given CPU family by looking at

15626

the architecture's <filename>README</filename> file.

15627

For example, the

15628

<filename>meta/conf/machine/include/mips/README</filename>

15629

file in the

15630

15631

provides information for <filename>TUNE_ARCH</filename>

15632

specific to the <filename>mips</filename> architecture.

</para>

<para>

<filename>TUNE_ARCH</filename> is tied closely to

15637

15638

which defines the target machine's architecture.

15639

The BitBake configuration file

15640

(<filename>meta/conf/bitbake.conf</filename>) sets

15641

<filename>TARGET_ARCH</filename> as follows:

15642

15643

TARGET_ARCH = "${TUNE_ARCH}"

</literallayout>

</para>

<para>

The following list, which is by no means complete since

15649

architectures are configurable, shows supported machine

architectures:

arm

i586

x86_64

powerpc

powerpc64

mips

mipsel

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm>

15665

<info>

15666

TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system."

</info>

Specifies architecture-specific assembler flags for

15671

the target system.

15672

The set of flags is based on the selected tune features.

15673

<filename>TUNE_ASARGS</filename> is set using

15674

the tune include files, which are typically under

15675

<filename>meta/conf/machine/include/</filename> and are

influenced through

For example, the

<filename>meta/conf/machine/include/x86/arch-x86.inc</filename>

15680

file defines the flags for the x86 architecture as follows:

15681

15682

TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"

15683

</literallayout>

15684

<note>

15685

Board Support Packages (BSPs) select the tune.

15686

The selected tune, in turn, affects the tune variables

15687

themselves (i.e. the tune can supply its own

set of flags).

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm>

15695

<info>

15696

TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system."

</info>

Specifies architecture-specific C compiler flags for

15701

the target system.

15702

The set of flags is based on the selected tune features.

15703

<filename>TUNE_CCARGS</filename> is set using

15704

the tune include files, which are typically under

15705

<filename>meta/conf/machine/include/</filename> and are

influenced through

<note>

Board Support Packages (BSPs) select the tune.

15710

The selected tune, in turn, affects the tune variables

15711

themselves (i.e. the tune can supply its own

set of flags).

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm>

15719

<info>

15720

TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system."

</info>

Specifies architecture-specific linker flags for

15725

the target system.

15726

The set of flags is based on the selected tune features.

15727

<filename>TUNE_LDARGS</filename> is set using

15728

the tune include files, which are typically under

15729

<filename>meta/conf/machine/include/</filename> and are

influenced through

For example, the

<filename>meta/conf/machine/include/x86/arch-x86.inc</filename>

15734

file defines the flags for the x86 architecture as follows:

15735

15736

TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"

15737

</literallayout>

15738

<note>

15739

Board Support Packages (BSPs) select the tune.

15740

The selected tune, in turn, affects the tune variables

15741

themselves (i.e. the tune can supply its own

set of flags).

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm>

15749

<info>

15750

TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor."

</info>

Features used to "tune" a compiler for optimal use

15755

given a specific processor.

15756

The features are defined within the tune files and allow

15757

arguments (i.e. <filename>TUNE_*ARGS</filename>) to be

15758

dynamically generated based on the features.

</para>

<para>

The OpenEmbedded build system verifies the features

15763

to be sure they are not conflicting and that they are

supported.

</para>

<para>

The BitBake configuration file

15769

(<filename>meta/conf/bitbake.conf</filename>) defines

15770

<filename>TUNE_FEATURES</filename> as follows:

15771

15772

TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}"

</literallayout>

See the

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>

15782

<info>

15783

TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages."

</info>

The package architecture understood by the packaging

15788

system to define the architecture, ABI, and tuning of

15789

output packages.

15790

The specific tune is defined using the "_tune" override

15791

as follows:

15792

15793

TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>"

</literallayout>

</para>

<para>

These tune-specific package architectures are defined in

15799

the machine include files.

15800

Here is an example of the "core2-32" tuning as used

15801

in the

15802

<filename>meta/conf/machine/include/tune-core2.inc</filename>

15803

file:

15804

15805

TUNE_PKGARCH_tune-core2-32 = "core2-32"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>

15812

<info>

15813

TUNEABI[doc] = "An underlying ABI used by a particular tuning in a given toolchain layer. This feature allows providers using prebuilt libraries to check compatibility of a tuning against their selection of libraries."

</info>

An underlying Application Binary Interface (ABI) used by

15818

a particular tuning in a given toolchain layer.

15819

Providers that use prebuilt libraries can use the

15820

<filename>TUNEABI</filename>,

and

variables to check compatibility of tunings against their

15825

selection of libraries.

</para>

<para>

If <filename>TUNEABI</filename> is undefined, then every

tuning is allowed.

See the

class to see how the variable is used.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm>

15839

<info>

15840

TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST."

</info>

If set, the OpenEmbedded system ignores the

15845

15846

variable.

15847

Providers that use prebuilt libraries can use the

15848

<filename>TUNEABI_OVERRIDE</filename>,

15849

<filename>TUNEABI_WHITELIST</filename>,

15850

and

15851

15852

variables to check compatibility of a tuning against their

15853

selection of libraries.

</para>

<para>

See the

class to see how the variable is used.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm>

15865

<info>

15866

TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed."

</info>

A whitelist of permissible

15871

15872

values.

15873

If <filename>TUNEABI_WHITELIST</filename> is not set,

15874

all tunes are allowed.

15875

Providers that use prebuilt libraries can use the

15876

<filename>TUNEABI_WHITELIST</filename>,

15877

15878

and <filename>TUNEABI</filename> variables to check

15879

compatibility of a tuning against their selection of

libraries.

</para>

<para>

See the

class to see how the variable is used.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNECONFLICTS'><glossterm>TUNECONFLICTS[<replaceable>feature</replaceable>]</glossterm>

15892

<info>

15893

TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature."

</info>

Specifies CPU or Application Binary Interface (ABI)

15898

tuning features that conflict with <replaceable>feature</replaceable>.

</para>

<para>

Known tuning conflicts are specified in the machine include

15903

files in the

15904

15905

Here is an example from the

15906

<filename>meta/conf/machine/include/mips/arch-mips.inc</filename>

15907

include file that lists the "o32" and "n64" features as

15908

conflicting with the "n32" feature:

15909

15910

TUNECONFLICTS[n32] = "o32 n64"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm>

15917

<info>

15918

TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features."

</info>

Specifies a valid CPU or Application Binary Interface (ABI)

15923

tuning feature.

15924

The specified feature is stored as a flag.

15925

Valid features are specified in the machine include files

15926

(e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).

15927

Here is an example from that file:

15928

15929

TUNEVALID[bigendian] = "Enable big-endian mode."

</literallayout>

</para>

<para>

See the machine include files in the

for these features.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>

15946

<info>

15947

UBOOT_CONFIG[doc] = "Configures the UBOOT_MACHINE and can also define IMAGE_FSTYPES for individual cases."

</info>

Configures the

and can also define

for individual cases.

</para>

<para>

Following is an example from the

15960

<filename>meta-fsl-arm</filename> layer.

15961

15962

UBOOT_CONFIG ??= "sd"

15963

UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"

15964

UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"

15965

UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"

15966

UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"

15967

</literallayout>

15968

In this example, "sd" is selected as the configuration

15969

of the possible four for the

15970

<filename>UBOOT_MACHINE</filename>.

15971

The "sd" configuration defines "mx6qsabreauto_config"

15972

as the value for <filename>UBOOT_MACHINE</filename>, while

15973

the "sdcard" specifies the

15974

<filename>IMAGE_FSTYPES</filename> to use for the U-boot

image.

</para>

<para>

For more information on how the

15980

<filename>UBOOT_CONFIG</filename> is handled, see the

15981

<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>

class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_DTB_LOADADDRESS'><glossterm>UBOOT_DTB_LOADADDRESS</glossterm>

15988

<info>

15989

UBOOT_DTB_LOADADDRESS[doc] = "Specifies the load address for the dtb."

</info>

Specifies the load address for the dtb image used by U-boot.

15994

During FIT image creation, the

15995

<filename>UBOOT_DTB_LOADADDRESS</filename> variable is used

15996

in <filename>kernel-fitimage</filename> class to specify the

15997

load address to be used in creating the dtb sections of

15998

Image Tree Source for the FIT image.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_DTBO_LOADADDRESS'><glossterm>UBOOT_DTBO_LOADADDRESS</glossterm>

16004

<info>

16005

UBOOT_DTBO_LOADADDRESS[doc] = "Specifies the load address for the dtbo."

</info>

Specifies the load address for the dtbo image used by U-boot.

16010

During FIT image creation, the

16011

<filename>UBOOT_DTBO_LOADADDRESS</filename> variable is used

16012

in <filename>kernel-fitimage</filename> class to specify the

16013

load address to be used in creating the dtbo sections of

16014

Image Tree Source for the FIT image.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>

16020

<info>

16021

UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."

</info>

Specifies the entry point for the U-Boot image.

16026

During U-Boot image creation, the

16027

<filename>UBOOT_ENTRYPOINT</filename> variable is passed

16028

as a command-line parameter to the

16029

<filename>uboot-mkimage</filename> utility.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>

16035

<info>

16036

UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image."

</info>

Specifies the load address for the U-Boot image.

16041

During U-Boot image creation, the

16042

<filename>UBOOT_LOADADDRESS</filename> variable is passed

16043

as a command-line parameter to the

16044

<filename>uboot-mkimage</filename> utility.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>

16050

<info>

16051

UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image."

</info>

Appends a string to the name of the local version of the

16056

U-Boot image.

16057

For example, assuming the version of the U-Boot image

16058

built was "2013.10", the full version string reported by

16059

U-Boot would be "2013.10-yocto" given the following

16060

statement:

16061

16062

UBOOT_LOCALVERSION = "-yocto"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>

16069

<info>

16070

UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image."

</info>

Specifies the value passed on the

16075

<filename>make</filename> command line when building

16076

a U-Boot image.

16077

The value indicates the target platform configuration.

16078

You typically set this variable from the machine

16079

configuration file (i.e.

16080

<filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>).

</para>

<para>

Please see the "Selection of Processor Architecture and

16085

Board Type" section in the U-Boot README for valid values

for this variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>

16092

<info>

16093

UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile."

</info>

Specifies the target called in the

16098

<filename>Makefile</filename>.

16099

The default target is "all".

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_MKIMAGE_DTCOPTS'><glossterm>UBOOT_MKIMAGE_DTCOPTS</glossterm>

16105

<info>

16106

UBOOT_MKIMAGE_DTCOPTS[doc] = "Options for the device tree compiler passed to mkimage '-D' feature."

</info>

Options for the device tree compiler passed to mkimage '-D'

16111

feature while creating FIT image in

16112

<filename>kernel-fitimage</filename> class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_RD_LOADADDRESS'><glossterm>UBOOT_RD_LOADADDRESS</glossterm>

16118

<info>

16119

UBOOT_RD_LOADADDRESS[doc] = "Specifies the load address for the ramdisk image."

</info>

Specifies the load address for the RAM disk image.

16124

During FIT image creation, the

16125

<filename>UBOOT_RD_LOADADDRESS</filename> variable is used

16126

in <filename>kernel-fitimage</filename> class to specify the

16127

load address to be used in creating the Image Tree Source for

the FIT image.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_RD_ENTRYPOINT'><glossterm>UBOOT_RD_ENTRYPOINT</glossterm>

16134

<info>

16135

UBOOT_RD_ENTRYPOINT[doc] = "Specifies the entrypoint for the ramdisk image."

</info>

Specifies the entrypoint for the RAM disk image.

16140

During FIT image creation, the

16141

<filename>UBOOT_RD_ENTRYPOINT</filename> variable is used

16142

in <filename>kernel-fitimage</filename> class to specify the

16143

entrypoint to be used in creating the Image Tree Source for

the FIT image.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>

16150

<info>

16151

UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."

</info>

Points to the generated U-Boot extension.

16156

For example, <filename>u-boot.sb</filename> has a

16157

<filename>.sb</filename> extension.

</para>

<para>

The default U-Boot extension is

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_SIGN_ENABLE'><glossterm>UBOOT_SIGN_ENABLE</glossterm>

16168

<info>

16169

UBOOT_SIGN_KEYDIR[doc] = "Enable signing of FIT image."

</info>

Enable signing of FIT image. The default value is "0".

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_SIGN_KEYDIR'><glossterm>UBOOT_SIGN_KEYDIR</glossterm>

16179

<info>

16180

UBOOT_SIGN_KEYDIR[doc] = "Location of the directory containing the RSA key and certificate used for signing FIT image."

</info>

Location of the directory containing the RSA key and

16185

certificate used for signing FIT image.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_SIGN_KEYNAME'><glossterm>UBOOT_SIGN_KEYNAME</glossterm>

16191

<info>

16192

UBOOT_SIGN_KEYNAME[doc] = "The name of keys used for signing U-boot FIT image"

</info>

The name of keys used for signing U-boot FIT image stored in

16197

<filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename>

16198

directory. For e.g. dev.key key and dev.crt certificate

16199

stored in

16200

<filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename>

16201

directory will have

16202

<filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename>

set to "dev".

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>

16209

<info>

16210

UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."

</info>

Specifies the target used for building U-Boot.

16215

The target is passed directly as part of the "make" command

16216

(e.g. SPL and AIS).

16217

If you do not specifically set this variable, the

16218

OpenEmbedded build process passes and uses "all" for the

16219

target during the U-Boot building process.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UNKNOWN_CONFIGURE_WHITELIST'><glossterm>UNKNOWN_CONFIGURE_WHITELIST</glossterm>

16225

<info>

16226

UNKNOWN_CONFIGURE_WHITELIST[doc] = "Specifies a list of options that, if reported by the configure script as being invalid, should not generate a warning during the do_configure task."

</info>

Specifies a list of options that, if reported by the

16231

configure script as being invalid, should not generate a

warning during the

task.

Normally, invalid configure options are simply not passed

16236

to the configure script (e.g. should be removed from

or

However, common options, for example, exist that are passed

16241

to all configure scripts at a class level that might not

16242

be valid for some configure scripts.

16243

It follows that no benefit exists in seeing a warning about

16244

these options.

16245

For these cases, the options are added to

16246

<filename>UNKNOWN_CONFIGURE_WHITELIST</filename>.

</para>

<para>

The configure arguments check that uses

16251

<filename>UNKNOWN_CONFIGURE_WHITELIST</filename> is part

16252

of the

16253

16254

class and is only enabled if the recipe inherits the

class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>

16262

<info>

16263

UPDATERCPN[doc] = "Specifies the package that contains the initscript that is enabled."

</info>

For recipes inheriting the

16268

16269

class, <filename>UPDATERCPN</filename> specifies

16270

the package that contains the initscript that is

enabled.

</para>

<para>

The default value is "${PN}".

16276

Given that almost all recipes that install initscripts

16277

package them in the main package for the recipe, you

16278

rarely need to set this variable in individual recipes.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm>

16284

<info>

16285

UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository."

</info>

You can perform a per-recipe check for what the latest

16290

upstream source code version is by calling

16291

<filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.

16292

If the recipe source code is provided from Git

16293

repositories, the OpenEmbedded build system determines the

16294

latest upstream version by picking the latest tag from the

16295

list of all repository tags.

</para>

<para>

You can use the

<filename>UPSTREAM_CHECK_GITTAGREGEX</filename>

16301

variable to provide a regular expression to filter only the

16302

relevant tags should the default filter not work

16303

correctly.

16304

16305

UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm>

16312

<info>

16313

UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI."

</info>

Use the <filename>UPSTREAM_CHECK_REGEX</filename> variable

16318

to specify a different regular expression instead of the

16319

default one when the package checking system is parsing

the page found using

UPSTREAM_CHECK_REGEX = "package_regex"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-UPSTREAM_CHECK_URI'><glossterm>UPSTREAM_CHECK_URI</glossterm>

16330

<info>

16331

UPSTREAM_CHECK_URI[doc] = "The URL used by the package checking system to get the latest version of the package when source files are fetched from an upstream Git repository."

</info>

You can perform a per-recipe check for what the latest

16336

upstream source code version is by calling

16337

<filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.

16338

If the source code is provided from tarballs, the latest

16339

version is determined by fetching the directory listing

16340

where the tarball is and attempting to find a later tarball.

16341

When this approach does not work, you can use

16342

<filename>UPSTREAM_CHECK_URI</filename> to

16343

provide a different URI that contains the link to the

16344

latest tarball.

16345

16346

UPSTREAM_CHECK_URI = "recipe_url"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm>

16353

<info>

16354

USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population."

</info>

Determines if <filename>devtmpfs</filename> is used for

16359

<filename>/dev</filename> population.

16360

The default value used for <filename>USE_DEVFS</filename>

16361

is "1" when no value is specifically set.

16362

Typically, you would set <filename>USE_DEVFS</filename>

16363

to "0" for a statically populated <filename>/dev</filename>

directory.

</para>

<para>

See the

"<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-dev-manager'>Selecting a Device Manager</ulink>"

16370

section in the Yocto Project Development Tasks Manual for

16371

information on how to use this variable.

</para>

</glossdef>

</glossentry>

<info>

USE_VT[doc] = "When using SysVinit, determines whether or not to run a getty on any virtual terminals in order to enable logging in through those terminals."

</info>

When using

<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,

16384

determines whether or not to run a

16385

<ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>

16386

on any virtual terminals in order to enable logging in

16387

through those terminals.

</para>

<para>

The default value used for <filename>USE_VT</filename>

16392

is "1" when no default value is specifically set.

16393

Typically, you would set <filename>USE_VT</filename>

16394

to "0" in the machine configuration file for machines

16395

that do not have a graphical display attached and

16396

therefore do not need virtual terminal functionality.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>

16402

<info>

16403

USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features."

</info>

A list of classes to globally inherit.

16408

These classes are used by the OpenEmbedded build system

16409

to enable extra features (e.g.

16410

<filename>buildstats</filename>,

16411

<filename>image-mklibs</filename>, and so forth).

</para>

<para>

The default list is set in your

16416

<filename>local.conf</filename> file:

16417

16418

USER_CLASSES ?= "buildstats image-mklibs image-prelink"

16419

</literallayout>

16420

For more information, see

16421

<filename>meta-poky/conf/local.conf.sample</filename> in

the

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>

16429

<info>

16430

USERADD_ERROR_DYNAMIC[doc] = "If set to 'error', forces the OpenEmbedded build system to produce an error if the user identification (uid) and group identification (gid) values are not defined in any of the files listed in USERADD_UID_TABLES and USERADD_GID_TABLES. If set to 'warn', a warning will be issued instead."

</info>

If set to <filename>error</filename>, forces the

16436

OpenEmbedded build system to produce an error if the user

16437

identification (<filename>uid</filename>) and group

16438

identification (<filename>gid</filename>) values are not

16439

defined in any of the files listed

16440

in <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>

16441

and <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>. If

16442

set to <filename>warn</filename>, a warning will be issued

instead.

</para>

<para>

The default behavior for the build system is to dynamically

16448

apply <filename>uid</filename> and

16449

<filename>gid</filename> values.

16450

Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>

16451

variable is by default not set.

16452

If you plan on using statically assigned

16453

16454

values, you should set

16455

the <filename>USERADD_ERROR_DYNAMIC</filename> variable in

16456

your <filename>local.conf</filename> file as

16457

follows:

16458

16459

USERADD_ERROR_DYNAMIC = "error"

16460

</literallayout>

16461

Overriding the default behavior implies you are going to

16462

also take steps to set static <filename>uid</filename> and

16463

<filename>gid</filename> values through use of the

and

variables.

</para>

<note>

There is a difference in behavior between

16473

setting <filename>USERADD_ERROR_DYNAMIC</filename>

16474

to <filename>error</filename> and setting it

16475

to <filename>warn</filename>. When it is set

16476

to <filename>warn</filename>, the build system will report a

16477

warning for every undefined <filename>uid</filename> and

16478

<filename>gid</filename> in any recipe. But when it is set

16479

to <filename>error</filename>, it will only report errors

16480

for recipes that are actually built. This saves you from

16481

having to add static IDs for recipes that you know will

never be built.

</note>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>

16488

<info>

16489

USERADD_GID_TABLES[doc] = "Specifies a password file to use for obtaining static group identification (gid) values when the OpenEmbedded build system adds a group to the system during package installation."

</info>

Specifies a password file to use for obtaining static

16494

group identification (<filename>gid</filename>) values

16495

when the OpenEmbedded build system adds a group to the

16496

system during package installation.

</para>

<para>

When applying static group identification

16501

(<filename>gid</filename>) values, the OpenEmbedded build

16502

system looks in

16503

16504

for a <filename>files/group</filename> file and then applies

16505

those <filename>uid</filename> values.

16506

Set the variable as follows in your

16507

<filename>local.conf</filename> file:

16508

16509

USERADD_GID_TABLES = "files/group"

</literallayout>

</para>

<note>

Setting the

variable to "useradd-staticids" causes the build system

16517

to use static <filename>gid</filename> values.

</note>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>

16523

<info>

16524

USERADD_PACKAGES[doc] = "When a recipe inherits the useradd class, this variable specifies the individual packages within the recipe that require users and/or groups to be added."

</info>

When inheriting the

class, this variable

specifies the individual packages within the recipe that

16532

require users and/or groups to be added.

</para>

<para>

You must set this variable if the recipe inherits the

16537

class.

16538

For example, the following enables adding a user for the

16539

main package in a recipe:

16540

16541

USERADD_PACKAGES = "${PN}"

16542

</literallayout>

16543

<note>

16544

It follows that if you are going to use the

16545

<filename>USERADD_PACKAGES</filename> variable,

16546

you need to set one or more of the

or

variables.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>

16559

<info>

16560

USERADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should pass to the useradd command if you add a user to the system when the package is installed."

</info>

When inheriting the

class, this variable

specifies for a package what parameters should pass

16568

to the <filename>useradd</filename> command

16569

if you add a user to the system when the package

is installed.

</para>

<para>

Here is an example from the <filename>dbus</filename>

16575

recipe:

16576

16577

USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \

16578

--no-create-home --shell /bin/false \

16579

--user-group messagebus"

16580

</literallayout>

16581

For information on the standard Linux shell command

16582

<filename>useradd</filename>, see

16583

<ulink url='http://linux.die.net/man/8/useradd'></ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>

16589

<info>

16590

USERADD_UID_TABLES[doc] = "Specifies a password file to use for obtaining static user identification (uid) values when the OpenEmbedded build system adds a user to the system during package installation."

</info>

Specifies a password file to use for obtaining static

16595

user identification (<filename>uid</filename>) values

16596

when the OpenEmbedded build system adds a user to the

16597

system during package installation.

</para>

<para>

When applying static user identification

16602

(<filename>uid</filename>) values, the OpenEmbedded build

16603

system looks in

16604

16605

for a <filename>files/passwd</filename> file and then applies

16606

those <filename>uid</filename> values.

16607

Set the variable as follows in your

16608

<filename>local.conf</filename> file:

16609

16610

USERADD_UID_TABLES = "files/passwd"

</literallayout>

</para>

<note>

Setting the

variable to "useradd-staticids" causes the build system

16618

to use static <filename>uid</filename> values.

</note>

</glossdef>

</glossentry>

<glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>

16624

<info>

16625

USERADDEXTENSION[doc] = "When set to 'useradd-staticids', causes the OpenEmbedded build system to base all user and group additions on a static passwd and group files found in BBPATH."

</info>

When set to "useradd-staticids", causes the

16630

OpenEmbedded build system to base all user and group

16631

additions on a static

16632

<filename>passwd</filename> and

16633

<filename>group</filename> files found in

</para>

<para>

To use static user identification (<filename>uid</filename>)

16639

and group identification (<filename>gid</filename>)

16640

values, set the variable

16641

as follows in your <filename>local.conf</filename> file:

16642

16643

USERADDEXTENSION = "useradd-staticids"

16644

</literallayout>

16645

<note>

16646

Setting this variable to use static

16647

16648

values causes the OpenEmbedded build system to employ

the

class.

</note>

</para>

<para>

If you use static <filename>uid</filename> and

16657

<filename>gid</filename> information, you must also

16658

specify the <filename>files/passwd</filename> and

16659

<filename>files/group</filename> files by setting the

and

variables.

Additionally, you should also set the

variable.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-VOLATILE_LOG_DIR'><glossterm>VOLATILE_LOG_DIR</glossterm>

16676

<info>

16677

VOLATILE_LOG_DIR[doc] = "Specifies the persistence of the target's /var/log directory, which is used to house postinstall target log files."

</info>

Specifies the persistence of the target's

16682

<filename>/var/log</filename> directory, which is used to

16683

house postinstall target log files.

</para>

<para>

By default, <filename>VOLATILE_LOG_DIR</filename> is set

16688

to "yes", which means the file is not persistent.

16689

You can override this setting by setting the

16690

variable to "no" to make the log directory persistent.

</para>

</glossdef>

</glossentry>

</glossdiv>

<info>

WARN_QA[doc] = "Specifies the quality assurance checks whose failures are reported as warnings by the OpenEmbedded build system."

</info>

Specifies the quality assurance checks whose failures are

16706

reported as warnings by the OpenEmbedded build system.

16707

You set this variable in your distribution configuration

16708

file.

16709

For a list of the checks you can control with this variable,

16710

see the

16711

"<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"

section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-WKS_FILE_DEPENDS'><glossterm>WKS_FILE_DEPENDS</glossterm>

16718

<info>

16719

WKS_FILE_DEPENDS[doc] = "Lists a recipe's build-time dependencies specific to Wic."

</info>

When placed in the recipe that builds your image, this

16724

variable lists build-time dependencies.

16725

The <filename>WKS_FILE_DEPENDS</filename> variable is only

16726

applicable when Wic images are active (i.e. when

16727

16728

contains entries related to Wic).

16729

If your recipe does not create Wic images, the variable

has no effect.

</para>

<para>

The <filename>WKS_FILE_DEPENDS</filename> variable is

similar to the

variable.

When you use the variable in your recipe that builds the

16739

Wic image, dependencies you list in the

16740

<filename>WIC_FILE_DEPENDS</filename> variable are added to

16741

the <filename>DEPENDS</filename> variable.

</para>

<para>

With the <filename>WKS_FILE_DEPENDS</filename> variable,

16746

you have the possibility to specify a list of additional

16747

dependencies (e.g. native tools, bootloaders, and so forth),

16748

that are required to build Wic images.

16749

Following is an example:

16750

16751

WKS_FILE_DEPENDS = "<replaceable>some-native-tool</replaceable>"

16752

</literallayout>

16753

In the previous example,

16754

<replaceable>some-native-tool</replaceable> would be

16755

replaced with an actual native tool on which the build

would depend.

</para>

</glossdef>

</glossentry>

<info>

WKS_FILE[doc] = "Specifies the name of the wic kickstart file."

</info>

Specifies the location of the Wic

16768

kickstart file that is used by the OpenEmbedded build

16769

system to create a partitioned image

16770

(<replaceable>image</replaceable><filename>.wic</filename>).

16771

For information on how to create a partitioned image, see

16772

the

16773

"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"

16774

section in the Yocto Project Development Tasks Manual.

16775

For details on the kickstart file format, see the

16776

"<link linkend='ref-kickstart'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</link>"

Chapter.

</para>

</glossdef>

</glossentry>

<glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>

16783

<info>

16784

WORKDIR[doc] = "The pathname of the working directory in which the OpenEmbedded build system builds a recipe. This directory is located within the TMPDIR directory structure and changes as different packages are built."

</info>

The pathname of the work directory in which the OpenEmbedded

16789

build system builds a recipe.

16790

This directory is located within the

16791

16792

directory structure and is specific to the recipe being

16793

built and the system for which it is being built.

</para>

<para>

The <filename>WORKDIR</filename> directory is defined as

16798

follows:

16799

16800

${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}

16801

</literallayout>

16802

The actual directory depends on several things:

16803

16804

<listitem><filename>TMPDIR</filename>:

16805

The top-level build output directory</listitem>

16806

<listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:

16807

The target system identifier</listitem>

16808

<listitem><link linkend='var-PN'><filename>PN</filename></link>:

16809

The recipe name</listitem>

16810

<listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:

16811

The epoch - (if

16812

16813

is not specified, which is usually the case for most

16814

recipes, then <filename>EXTENDPE</filename> is blank)</listitem>

16815

<listitem><link linkend='var-PV'><filename>PV</filename></link>:

16816

The recipe version</listitem>

16817

<listitem><link linkend='var-PR'><filename>PR</filename></link>:

16818

The recipe revision</listitem>

</itemizedlist>

</para>

<para>

As an example, assume a Source Directory top-level folder

16824

name <filename>poky</filename>, a default Build Directory at

16825

<filename>poky/build</filename>, and a

16826

<filename>qemux86-poky-linux</filename> machine target

16827

system.

16828

Furthermore, suppose your recipe is named

16829

<filename>foo_1.3.0-r0.bb</filename>.

16830

In this case, the work directory the build system uses to

16831

build the package would be as follows:

16832

16833

poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0

</literallayout>

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-XSERVER'><glossterm>XSERVER</glossterm>

16844

<info>

16845

XSERVER[doc] = "Specifies the packages that should be installed to provide an X server and drivers for the current machine."

</info>

Specifies the packages that should be installed to

16850

provide an X server and drivers for the current machine,

16851

assuming your image directly includes

16852

<filename>packagegroup-core-x11-xserver</filename> or,

16853

perhaps indirectly, includes "x11-base" in

</para>

<para>

The default value of <filename>XSERVER</filename>, if not

16859

specified in the machine configuration, is

16860

"xserver-xorg xf86-video-fbdev xf86-input-evdev".

</para>

</glossdef>

</glossentry>

</glossdiv>

16868

16869

16870

</glossary>

</chapter>

<!--

vim: expandtab tw=80 ts=4

16877

-->