Blame - import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml - openbmc/openbmc

2018-02-01 10:27:11 -0500

[diff] [blame^]

487

488

<para>

489

For more information see the

490

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

491

section in the Yocto Project Development Manual.

492

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

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

497

<info>

498

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>

503

The list of defined CPU and Application Binary Interface

504

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

505

OpenEmbedded build system.

</para>

<para>

The list simply presents the tunes that are available.

510

Not all tunes may be compatible with a particular

511

machine configuration, or with each other in a

512

<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

518

spaces using the "+=" BitBake operator.

519

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

520

See the

521

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

522

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>

538

The directory within the

539

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>

540

in which the OpenEmbedded build system places generated

541

objects during a recipe's build process.

542

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

543

directory, which is defined as:

544

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

545

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</literallayout>

</para>

<para>

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

551

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

552

variable.

553

Most Autotools-based recipes support separating these

554

directories.

555

The build system defaults to using separate directories for

556

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

</para>

</glossdef>

</glossentry>

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

562

<info>

563

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>

568

Lists "recommended-only" packages to not install.

569

Recommended-only packages are packages installed only

through the

variable.

You can prevent any of these "recommended" packages from

574

being installed by listing them with the

575

<filename>BAD_RECOMMENDATIONS</filename> variable:

576

577

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

583

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

584

a specific image recipe by using the recipe name override:

585

586

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

592

packages using this variable and some other packages are

593

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

594

595

variable), the OpenEmbedded build system ignores your

596

request and will install the packages to avoid dependency

errors.

</para>

<para>

Support for this variable exists only when using the

602

IPK and RPM packaging backend.

603

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>

623

The library directory name for the CPU or Application

624

Binary Interface (ABI) tune.

625

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

626

Multilib context.

627

See the

628

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

629

section in the Yocto Project Development Manual for

630

information on Multilib.

</para>

<para>

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

635

the machine include files in the

636

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

637

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

</para>

</glossdef>

</glossentry>

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

643

<info>

644

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

</info>

649

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

650

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

</para>

</glossdef>

</glossentry>

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

656

<info>

657

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

662

is allowed to use to obtain the required source code.

663

Following are considerations surrounding this variable:

664

665

666

This host list is only used if

667

<filename>BB_NO_NETWORK</filename> is either not

set or set to "0".

</para></listitem>

Limited support for wildcard matching against the

672

beginning of host names exists.

673

For example, the following setting matches

674

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

675

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

676

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

677

678

BB_ALLOWED_NETWORKS = "*.gnu.org"

</literallayout>

</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

695

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

696

being fetched from an allowed location and avoids raising

697

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

698

699

statement.

700

This is because the fetcher does not attempt to use the

701

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

702

successful fetch from the

703

<filename>PREMIRRORS</filename> occurs.

</para>

</glossdef>

</glossentry>

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

709

<info>

710

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

</info>

715

Defines how BitBake handles situations where an append

716

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

717

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

718

This condition often occurs when layers get out of sync

719

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

720

recipe version and the old recipe no longer exists and the

721

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

727

the sane reaction given something is out of sync.

728

It is important to realize when your changes are no longer

being applied.

</para>

<para>

You can change the default behavior by setting this

734

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

735

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

736

located in the

737

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:

738

Here is an example:

739

740

BB_DANGLINGAPPENDS_WARNONLY = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

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

747

<info>

748

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>

753

Monitors disk space and available inodes during the build

754

and allows you to control the build based on these

parameters.

</para>

<para>

Disk space monitoring is disabled by default.

760

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

761

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

762

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

763

Use the following form:

764

765

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

where:

<replaceable>action</replaceable> is:

770

ABORT: Immediately abort the build when

771

a threshold is broken.

772

STOPTASKS: Stop the build after the currently

773

executing tasks have finished when

774

a threshold is broken.

775

WARN: Issue a warning but continue the

776

build when a threshold is broken.

777

Subsequent warnings are issued as

778

defined by the

779

780

which must be defined in the

781

conf/local.conf file.

782

783

<replaceable>dir</replaceable> is:

784

Any directory you choose. You can specify one or

785

more directories to monitor by separating the

786

groupings with a space. If two directories are

787

on the same device, only the first directory

788

is monitored.

789

790

<replaceable>threshold</replaceable> is:

791

Either the minimum available disk space,

792

the minimum number of free inodes, or

793

both. You must specify at least one. To

794

omit one or the other, simply omit the value.

795

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

796

Mbytes, and Kbytes, respectively. If you do

797

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

798

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

</literallayout>

</para>

<para>

Here are some examples:

804

805

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

806

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

807

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

808

</literallayout>

809

The first example works only if you also provide

810

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

811

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

812

This example causes the build system to immediately

813

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

814

below 1 Gbyte or the available free inodes drops below

815

100 Kbytes.

816

Because two directories are provided with the variable, the

817

build system also issue a

818

warning when the disk space in the

819

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

820

below 1 Gbyte or the number of free inodes drops

821

below 100 Kbytes.

822

Subsequent warnings are issued during intervals as

823

defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>

variable.

</para>

<para>

The second example stops the build after all currently

829

executing tasks complete when the minimum disk space

830

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

831

directory drops below 1 Gbyte.

832

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

</para>

<para>

The final example immediately aborts the build when the

837

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

838

drops below 100 Kbytes.

839

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>

846

<info>

847

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>

852

Defines the disk space and free inode warning intervals.

853

To set these intervals, define the variable in your

854

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

855

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

</para>

<para>

If you are going to use the

860

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

861

also use the

862

863

and define its action as "WARN".

864

During the build, subsequent warnings are issued each time

865

disk space or number of free inodes further reduces by

866

the respective interval.

</para>

<para>

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

871

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

872

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

873

the following:

874

875

BB_DISKMON_WARNINTERVAL = "50M,5K"

</literallayout>

</para>

<para>

When specifying the variable in your configuration file,

881

use the following form:

882

883

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

where:

<replaceable>disk_space_interval</replaceable> is:

888

An interval of memory expressed in either

889

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

890

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

891

892

<replaceable>disk_inode_interval</replaceable> is:

893

An interval of free inodes expressed in either

894

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

895

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

</literallayout>

</para>

<para>

Here is an example:

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

903

BB_DISKMON_WARNINTERVAL = "50M,5K"

904

</literallayout>

905

These variables cause the OpenEmbedded build system to

906

issue subsequent warnings each time the available

907

disk space further reduces by 50 Mbytes or the number

908

of free inodes further reduces by 5 Kbytes in the

909

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

910

Subsequent warnings based on the interval occur each time

911

a respective interval is reached beyond the initial warning

912

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

</para>

</glossdef>

</glossentry>

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

918

<info>

919

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

</info>

924

Causes tarballs of the Git repositories, including the

925

Git metadata, to be placed in the

directory.

</para>

<para>

For performance reasons, creating and placing tarballs of

932

the Git repositories is not the default action by the

933

OpenEmbedded build system.

934

935

BB_GENERATE_MIRROR_TARBALLS = "1"

936

</literallayout>

937

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

938

file in the

939

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

</para>

</glossdef>

</glossentry>

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

945

<info>

946

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>

951

The maximum number of tasks BitBake should run in parallel

952

at any one time.

953

The OpenEmbedded build system automatically configures

954

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

955

build system.

956

For example, a system with a dual core processor that

957

also uses hyper-threading causes the

958

<filename>BB_NUMBER_THREADS</filename> variable to default

to "4".

</para>

<para>

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

964

have to override this variable to gain optimal parallelism

965

during builds.

966

However, if you have very large systems that employ

967

multiple physical CPUs, you might want to make sure the

968

<filename>BB_NUMBER_THREADS</filename> variable is not

969

set higher than "20".

</para>

<para>

For more information on speeding up builds, see the

974

"<link linkend='speeding-up-the-build'>Speeding Up the Build</link>"

section.

</para>

</glossdef>

</glossentry>

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

981

<info>

982

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>

987

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

988

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

989

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

990

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

991

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

992

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

993

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

994

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

999

is as simple as adding the following to your recipe:

1000

1001

BBCLASSEXTEND =+ "native nativesdk"

1002

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

1003

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

1004

<note>

1005

<para>

1006

Internally, the <filename>BBCLASSEXTEND</filename>

1007

mechanism generates recipe variants by rewriting

1008

variable values and applying overrides such as

1009

<filename>_class-native</filename>.

1010

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

1011

a

1012

1013

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

on "foo-native".

</para>

<para>

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

1019

recipe is only parsed once.

1020

Parsing once adds some limitations.

1021

For example, it is not possible to

1022

include a different file depending on the variant,

1023

since <filename>include</filename> statements are

1024

processed when the recipe is parsed.

1025

</para>

1026

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

1032

<info>

1033

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

</info>

1038

Lists the names of configured layers.

1039

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

1040

variables.

1041

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

1042

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

</para>

</glossdef>

</glossentry>

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

1048

<info>

1049

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>

1054

Variable that expands to match files from

1055

1056

in a particular layer.

1057

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

1058

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

1059

<filename>BBFILE_PATTERN_emenlow</filename>).

</para>

</glossdef>

</glossentry>

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

1065

<info>

1066

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>

1071

Assigns the priority for recipe files in each layer.

</para>

<para>

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

1076

more than one layer.

1077

Setting this variable allows you to prioritize a

1078

layer against other layers that contain the same recipe - effectively

1079

letting you control the precedence for the multiple layers.

1080

The precedence established through this variable stands regardless of a

1081

recipe's version

1082

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

1083

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

1084

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

1090

precedence.

1091

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

1092

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

1093

dependencies (see the

1094

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

1095

more information.

1096

The default priority, if unspecified

1097

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

1098

(or 1 if no priorities are defined).

1099

</para>

1100

<tip>

1101

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

1102

all configured layers along with their priorities.

</tip>

</glossdef>

</glossentry>

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

1108

<info>

1109

BBFILES[doc] = "List of recipe files used by BitBake to build software."

</info>

1114

List of recipe files used by BitBake to build software.

</para>

</glossdef>

</glossentry>

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

1120

<info>

1121

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

</info>

1126

Variable that controls how BitBake displays logs on build failure.

</para>

</glossdef>

</glossentry>

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

1132

<info>

1133

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

</info>

1138

If

1139

1140

is set, specifies the maximum number of lines from the

1141

task log file to print when reporting a failed task.

1142

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

1143

the entire log is printed.

</para>

</glossdef>

</glossentry>

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

1149

<info>

1150

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

</info>

1155

Lists the layers to enable during the build.

1156

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

1157

file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

Here is an example:

BBLAYERS = " \

/home/scottrif/poky/meta \

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1162

/home/scottrif/poky/meta-poky \

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1163

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

1164

/home/scottrif/poky/meta-mykernel \

1165

"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1166

</literallayout>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

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

1171

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

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1176

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

1177

<info>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1178

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

1183

Prevents BitBake from processing recipes and recipe

1184

append files.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

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

1189

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

1190

<filename>.bbappend</filename> files.

1191

BitBake ignores any recipe or recipe append files that

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1192

match any of the expressions.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1193

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

1194

Consequently, matching files are not parsed or otherwise

1195

used by BitBake.</para>

1196

<para>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1197

The values you provide are passed to Python's regular

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1198

expression compiler.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1199

The expressions are compared against the full paths to

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1200

the files.

1201

For complete syntax information, see Python's

1202

documentation at

1203

<ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.

</para>

<para>

The following example uses a complete regular expression

1208

to tell BitBake to ignore all recipe and recipe append

1209

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

1210

directory:

1211

1212

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

1213

</literallayout>

1214

If you want to mask out multiple directories or recipes,

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1215

you can specify multiple regular expression fragments.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1216

This next example masks out multiple directories and

1217

individual recipes:

1218

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1219

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

1220

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

1221

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

1222

BBMASK += "opencv.*\.bbappend"

1223

BBMASK += "lzma"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1224

</literallayout>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1225

<note>

1226

When specifying a directory name, use the trailing

1227

slash character to ensure you match just that directory

name.

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

1234

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

1235

<info>

1236

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

</info>

1241

Specifies each separate configuration when you are

1242

building targets with multiple configurations.

1243

Use this variable in your

1244

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

1245

Specify a <replaceable>multiconfigname</replaceable> for

1246

each configuration file you are using.

1247

For example, the following line specifies three

1248

configuration files:

1249

1250

BBMULTIFONFIG = "configA configB configC"

1251

</literallayout>

1252

Each configuration file you use must reside in the

1253

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory's</ulink>

1254

<filename>conf/multiconfig</filename> directory

1255

(e.g.

1256

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

</para>

<para>

For information on how to use

1261

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

1262

supports building targets with multiple configurations,

1263

see the

1264

"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-building-targets-with-multiple-configurations'>Building Targets with Multiple Configurations</ulink>"

1265

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1270

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

1271

<info>

1272

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

</info>

1277

Used by BitBake to locate

1278

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

1279

This variable is analogous to the

1280

<filename>PATH</filename> variable.

1281

<note>

1282

If you run BitBake from a directory outside of the

1283

<ulink url='&YOCTO_DOCS_DEV_URL;build-directory'>Build Directory</ulink>,

1284

you must be sure to set

1285

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

1286

Build Directory.

1287

Set the variable as you would any environment variable

1288

and then run BitBake:

1289

1290

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

1291

$ export BBPATH

1292

$ bitbake <replaceable>target</replaceable>

</literallayout>

</note>

</para>

</glossdef>

</glossentry>

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

1300

<info>

1301

BBSERVER[doc] = "Points to the server that runs memory-resident BitBake."

</info>

1306

Points to the server that runs memory-resident BitBake.

1307

This variable is set by the

1308

1309

setup script and should not be hand-edited.

1310

The variable is only used when you employ memory-resident

1311

BitBake.

1312

The setup script exports the value as follows:

1313

1314

export BBSERVER=localhost:$port

</literallayout>

</para>

<para>

For more information on how the

1320

<filename>BBSERVER</filename> is used, see the

1321

<filename>oe-init-build-env-memres</filename> script, which

1322

is located in the

1323

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

</para>

</glossdef>

</glossentry>

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

1329

<info>

1330

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>

1335

When inheriting the

1336

1337

class, this variable specifies binary configuration

1338

scripts to disable in favor of using

1339

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

1340

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

1341

modify the specified scripts to return an error so that

1342

calls to them can be easily found and replaced.

</para>

<para>

To add multiple scripts, separate them by spaces.

1347

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

1348

recipe:

1349

1350

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

1357

<info>

1358

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

</info>

1363

When inheriting the

1364

1365

class, this variable specifies a wildcard for

1366

configuration scripts that need editing.

1367

The scripts are edited to correct any paths that have been

1368

set up during compilation so that they are correct for

1369

use when installed into the sysroot and called by the

1370

build processes of other recipes.

</para>

<para>

For more information on how this variable works, see

1375

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

1376

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

1377

You can also find general information on the class in the

1378

"<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>

1391

The base recipe name and version but without any special

1392

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

1393

and so forth).

1394

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

${BPN}-${PV}

</literallayout>

</para>

</glossdef>

</glossentry>

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

1404

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1409

This variable is a version of the

1410

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

1411

variable with common prefixes and suffixes

1412

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

1413

<filename>-cross</filename>,

1414

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

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1415

<filename>lib64-</filename> and

1416

<filename>lib32-</filename>.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

1417

The exact lists of prefixes and suffixes removed are

1418

specified by the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1419

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

1420

and

1421

1422

variables, respectively.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

1428

<info>

1429

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

</info>

1434

Specifies a URL for an upstream bug tracking website for

1435

a recipe.

1436

The OpenEmbedded build system does not use this variable.

1437

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

1438

in the software being built needs to be manually reported.

</para>

</glossdef>

</glossentry>

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

1444

<info>

1445

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

</info>

1450

Specifies the architecture of the build host

1451

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

1452

The OpenEmbedded build system sets the value of

1453

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

1454

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

</para>

</glossdef>

</glossentry>

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

1460

<info>

1461

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

</info>

1466

Specifies the flags to pass to the C compiler when building

1467

for the build host.

1468

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

1469

1470

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1476

<info>

1477

BUILD_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 build host."

</info>

1482

Specifies the flags to pass to the C pre-processor

1483

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

1484

for the build host.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1485

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1486

1487

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1493

<info>

1494

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

</info>

1499

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

1500

building for the build host.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1501

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1502

1503

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1509

<info>

1510

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

</info>

1515

Specifies the flags to pass to the linker when building

1516

for the build host.

1517

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

1518

1519

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1525

<info>

1526

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

</info>

1531

Specifies the optimization flags passed to the C compiler

1532

when building for the build host or the SDK.

1533

The flags are passed through the

and

default values.

</para>

<para>

The default value of the

1542

<filename>BUILD_OPTIMIZATION</filename> variable is

"-O2 -pipe".

</para>

</glossdef>

</glossentry>

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

1549

<info>

1550

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

</info>

1555

Specifies the operating system in use on the build

1556

host (e.g. "linux").

1557

The OpenEmbedded build system sets the value of

1558

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

1559

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

1560

converted to lower-case characters.

</para>

</glossdef>

</glossentry>

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

1566

<info>

1567

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

</info>

1572

The toolchain binary prefix used for native recipes.

1573

The OpenEmbedded build system uses the

1574

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

1575

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1576

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

1582

<info>

1583

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

</info>

1588

Specifies the system, including the architecture and

1589

the operating system, to use when building for the build

1590

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>

1608

<info>

1609

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

</info>

1614

Specifies the vendor name to use when building for the

1615

build host.

1616

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

</para>

</glossdef>

</glossentry>

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

1622

<info>

1623

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

</info>

1628

Points to the location of the

1629

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

1630

You can define this directory indirectly through the

and

scripts by passing in a Build Directory path when you run

1635

the scripts.

1636

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

1637

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

1638

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

</para>

</glossdef>

</glossentry>

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

1644

<info>

1645

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>

1650

When inheriting the

1651

1652

class, this variable specifies whether or not to commit the

1653

build history output in a local Git repository.

1654

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

1655

automatically by the

1656

<filename>buildhistory</filename>

1657

class and a commit will be created on every

1658

build for changes to each top-level subdirectory of the

1659

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

1660

If you want to track changes to build history over

1661

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

</para>

<para>

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

1666

does not commit the build history output in a local

1667

Git repository:

1668

1669

BUILDHISTORY_COMMIT ?= "0"

</literallayout>

</para>

</glossdef>

</glossentry>

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

1676

<info>

1677

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

</info>

1682

When inheriting the

1683

1684

class, this variable specifies the author to use for each

1685

Git commit.

1686

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

1687

variable to work, the

1688

1689

variable must be set to "1".

</para>

<para>

Git requires that the value you provide for the

1694

<filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable

1695

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

1696

Providing an email address or host that is not valid does

1697

not produce an error.

</para>

<para>

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

1702

sets the variable as follows:

1703

1704

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

1711

<info>

1712

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

</info>

1717

When inheriting the

1718

1719

class, this variable specifies the directory in which

1720

build history information is kept.

1721

For more information on how the variable works, see the

1722

<filename>buildhistory.class</filename>.

</para>

<para>

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

1727

sets the directory as follows:

1728

1729

BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"

</literallayout>

</para>

</glossdef>

</glossentry>

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

1736

<info>

1737

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

</info>

1742

When inheriting the

1743

1744

class, this variable specifies the build history features

1745

to be enabled.

1746

For more information on how build history works, see the

1747

"<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"

section.

</para>

<para>

You can specify three features in the form of a

1753

space-separated list:

1754

1755

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

1756

Analysis of the contents of images, which

1757

includes the list of installed packages among other

1758

things.

1759

</para></listitem>

1760

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

1761

Analysis of the contents of individual packages.

1762

</para></listitem>

1763

1764

Analysis of the contents of the software

1765

development kit (SDK).

</para></listitem>

</itemizedlist>

</para>

<para>

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

1772

enables all three features:

1773

1774

BUILDHISTORY_FEATURES ?= "image package sdk"

</literallayout>

</para>

</glossdef>

</glossentry>

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

1781

<info>

1782

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>

1787

When inheriting the

1788

1789

class, this variable specifies a list of paths to files

1790

copied from the

1791

image contents into the build history directory under

1792

an "image-files" directory in the directory for

1793

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

1794

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

1795

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

1796

monitor for changes in user and group entries.

1797

You can modify the list to include any file.

1798

Specifying an invalid path does not produce an error.

1799

Consequently, you can include files that might

1800

not always be present.

</para>

<para>

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

1805

provides paths to the following files:

1806

1807

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

1814

<info>

1815

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

</info>

1820

When inheriting the

1821

1822

class, this variable optionally specifies a remote

1823

repository to which build history pushes Git changes.

1824

In order for <filename>BUILDHISTORY_PUSH_REPO</filename>

to work,

must be set to "1".

</para>

<para>

The repository should correspond to a remote

1832

address that specifies a repository as understood by

1833

Git, or alternatively to a remote name that you have

1834

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

1835

within the local repository.

</para>

<para>

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

1840

sets the variable as follows:

1841

1842

BUILDHISTORY_PUSH_REPO ?= ""

</literallayout>

</para>

</glossdef>

</glossentry>

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

1849

<info>

1850

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

</info>

1855

Specifies the flags to pass to the C compiler when building

1856

for the SDK.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1857

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1858

context,

1859

1860

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1866

<info>

1867

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>

1872

Specifies the flags to pass to the C pre-processor

1873

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

1874

for the SDK.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1875

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1876

context,

1877

1878

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1884

<info>

1885

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

</info>

1890

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

1891

building for the SDK.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

1892

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

1893

context,

1894

1895

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1901

<info>

1902

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

</info>

1907

Specifies the flags to pass to the linker when building

1908

for the SDK.

1909

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

1910

context,

1911

1912

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1918

<info>

1919

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

</info>

1924

Points to the location of the directory that holds build

1925

statistics when you use and enable the

1926

1927

class.

1928

The <filename>BUILDSTATS_BASE</filename> directory defaults

1929

to

1930

<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>

1936

<info>

1937

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>

1942

For the BusyBox recipe, specifies whether to split the

1943

output executable file into two parts: one for features

1944

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

1945

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

1946

<filename>setuid root</filename>).

</para>

<para>

The <filename>BUSYBOX_SPLIT_SUID</filename> variable

1951

defaults to "1", which results in a single output

1952

executable file.

1953

Set the variable to "0" to split the output file.

</para>

</glossdef>

</glossentry>

</glossdiv>

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

1963

<info>

1964

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

</info>

1969

Specifies the directory BitBake uses to store a cache

1970

of the

1971

<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>

1972

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>

1985

The minimal command and arguments used to run the C

compiler.

</para>

</glossdef>

</glossentry>

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

1992

<info>

1993

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

</info>

1998

Specifies the flags to pass to the C compiler.

1999

This variable is exported to an environment

2000

variable and thus made visible to the software being

2001

built during the compilation step.

</para>

<para>

Default initialization for <filename>CFLAGS</filename>

2006

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

2015

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

2020

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

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

2028

<info>

2029

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

</info>

2034

An internal variable specifying the special class override

2035

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

2036

"class-native", and so forth).

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

2037

The classes that use this variable (e.g.

2038

2039

2040

and so forth) set the variable to appropriate values.

2041

<note>

2042

<filename>CLASSOVERRIDE</filename> gets its default

2043

"class-target" value from the

2044

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

2045

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

2046

</para>

2047

2048

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

2049

As an example, the following override allows you to install

2050

extra files, but only when building for the target:

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

2051

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

2052

do_install_append_class-target() {

2053

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

2054

}

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

2055

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

2056

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

2057

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

2058

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

2059

2060

FOO_class-native = "native"

2061

FOO = "other"

2062

</literallayout>

2063

The underlying mechanism behind

2064

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

2065

included in the default value of

2066

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

2072

<info>

2073

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

</info>

2078

If set to "1" within a recipe,

2079

<filename>CLEANBROKEN</filename> specifies that

2080

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

2081

not work for the software being built.

2082

Consequently, the OpenEmbedded build system will not try

2083

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

2084

2085

task, which is the default behavior.

</para>

</glossdef>

</glossentry>

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

2091

<info>

2092

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

</info>

2097

Provides a list of hardware features that are enabled in

both

and

This select list of features contains features that make

2103

sense to be controlled both at the machine and distribution

2104

configuration level.

2105

For example, the "bluetooth" feature requires hardware

2106

support but should also be optional at the distribution

2107

level, in case the hardware supports Bluetooth but you

2108

do not ever intend to use it.

</para>

<para>

For more information, see the

2113

2114

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

variables.

</para>

</glossdef>

</glossentry>

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

2121

<info>

2122

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

</info>

2127

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

2128

in the

2129

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,

2130

which is where generic license files reside.

</para>

</glossdef>

</glossentry>

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

2136

<info>

2137

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>

2142

A regular expression that resolves to one or more hosts

2143

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

2144

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

2145

The regular expression is matched against

2146

2147

You can use the variable to stop recipes from being built

2148

for classes of systems with which the recipes are not

2149

compatible.

2150

Stopping these builds is particularly useful with kernels.

2151

The variable also helps to increase parsing speed

2152

since the build system skips parsing recipes not

2153

compatible with the current system.

</para>

</glossdef>

</glossentry>

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

2159

<info>

2160

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

</info>

2165

A regular expression that resolves to one or more

2166

target machines with which a recipe is compatible.

2167

The regular expression is matched against

2168

2169

You can use the variable to stop recipes from being built

2170

for machines with which the recipes are not compatible.

2171

Stopping these builds is particularly useful with kernels.

2172

The variable also helps to increase parsing speed

2173

since the build system skips parsing recipes not

2174

compatible with the current machine.

</para>

</glossdef>

</glossentry>

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

2180

<info>

2181

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

</info>

2186

Defines wildcards to match when installing a list of

2187

complementary packages for all the packages explicitly

2188

(or implicitly) installed in an image.

2189

The resulting list of complementary packages is associated

2190

with an item that can be added to

2191

2192

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

2193

added to <filename>IMAGE_FEATURES</filename> will

2194

install -dev packages (containing headers and other

2195

development files) for every package in the image.

</para>

<para>

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

2200

variable flag to specify the feature item name and

2201

use the value to specify the wildcard.

2202

Here is an example:

2203

2204

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

2211

<info>

2212

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

</info>

2217

Tracks the version of the local configuration file

2218

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

2219

The value for <filename>CONF_VERSION</filename>

2220

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

2221

compatibility changes.

</para>

</glossdef>

</glossentry>

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

2227

<info>

2228

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

</info>

2233

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

2234

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

2235

packages on the target system, it is possible that

2236

configuration files you have changed after the original installation

2237

and that you now want to remain unchanged are overwritten.

2238

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

2239

want reset as part of the package update process.

2240

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

2241

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

2246

override that identifies the resulting package.

2247

Then, provide a space-separated list of files.

2248

Here is an example:

2249

2250

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

2251

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

</literallayout>

</para>

<para>

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

2257

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

2258

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

2259

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

2260

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

2261

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

2262

it makes sense that

2263

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

2264

<filename>FILES</filename> variable.

</para>

<note>

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

2269

it is good practice to use appropriate path variables.

2270

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

2271

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

2272

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

2273

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

2274

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

2275

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

</note>

</glossdef>

</glossentry>

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

2281

<info>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

2282

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."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

2287

Identifies the initial RAM filesystem (initramfs) source

2288

files.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

2289

The OpenEmbedded build system receives and uses

2290

this kernel Kconfig variable as an environment variable.

2291

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

</para>

<para>

The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be

2296

either a single cpio archive with a

2297

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

2298

space-separated list of directories and files for building

2299

the initramfs image.

2300

A cpio archive should contain a filesystem archive

2301

to be used as an initramfs image.

2302

Directories should contain a filesystem layout to be

2303

included in the initramfs image.

2304

Files should contain entries according to the format

2305

described by the

2306

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

kernel tree.

</para>

<para>

If you specify multiple directories and files, the

2312

initramfs image will be the aggregate of all of them.

2313

</para>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

2314

2315

<para>

2316

For information on creating an initramfs, see the

2317

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

2318

section in the Yocto Project Development Manual.

2319

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

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

2324

<info>

2325

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>

2330

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

2331

to the current build.

2332

This variable is used by the Autotools utilities when running

2333

<filename>configure</filename>.

</para>

</glossdef>

</glossentry>

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

2339

<info>

2340

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

</info>

2345

The minimal arguments for GNU configure.

</para>

</glossdef>

</glossentry>

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

2351

<info>

2352

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

2361

be in conflict should the recipe

2362

be built.

2363

In other words, if the

2364

<filename>CONFLICT_DISTRO_FEATURES</filename> variable

2365

lists a feature that also appears in

2366

<filename>DISTRO_FEATURES</filename> within the

2367

current configuration, an error occurs and the

build stops.

</para>

</glossdef>

</glossentry>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

2373

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

2374

<info>

2375

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

</info>

2380

A space-separated list of licenses to exclude from the

2381

source archived by the

2382

2383

class.

2384

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

2385

2386

value is in the value of

2387

<filename>COPYLEFT_LICENSE_EXCLUDE</filename>, then its

2388

source is not archived by the class.

2389

<note>

2390

The <filename>COPYLEFT_LICENSE_EXCLUDE</filename>

2391

variable takes precedence over the

variable.

</note>

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

2396

<filename>COPYLEFT_LICENSE_EXCLUDE</filename> is set

2397

by the

2398

2399

class, which is inherited by the

2400

<filename>archiver</filename> class.

</para>

</glossdef>

</glossentry>

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

2406

<info>

2407

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

</info>

2412

A space-separated list of licenses to include in the

2413

source archived by the

2414

2415

class.

2416

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

2417

2418

value is in the value of

2419

<filename>COPYLEFT_LICENSE_INCLUDE</filename>, then its

2420

source is archived by the class.

</para>

<para>

The default value is set by the

2425

2426

class, which is inherited by the

2427

<filename>archiver</filename> class.

2428

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

</para>

</glossdef>

</glossentry>

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

2434

<info>

2435

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

</info>

2440

A list of recipes to exclude in the source archived

by the

class.

The <filename>COPYLEFT_PN_EXCLUDE</filename> variable

2445

overrides the license inclusion and exclusion caused

through the

and

variables, respectively.

</para>

<para>

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

2455

exclude any recipes by name, for

2456

<filename>COPYLEFT_PN_EXCLUDE</filename> is set

2457

by the

2458

2459

class, which is inherited by the

2460

<filename>archiver</filename> class.

</para>

</glossdef>

</glossentry>

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

2466

<info>

2467

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

</info>

2472

A list of recipes to include in the source archived

by the

class.

The <filename>COPYLEFT_PN_INCLUDE</filename> variable

2477

overrides the license inclusion and exclusion caused

through the

and

variables, respectively.

</para>

<para>

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

2487

include any recipes by name, for

2488

<filename>COPYLEFT_PN_INCLUDE</filename> is set

2489

by the

2490

2491

class, which is inherited by the

2492

<filename>archiver</filename> class.

</para>

</glossdef>

</glossentry>

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

2498

<info>

2499

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

</info>

2504

A space-separated list of recipe types to include

2505

in the source archived by the

2506

2507

class.

2508

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

2509

<filename>native</filename>,

2510

<filename>nativesdk</filename>,

2511

<filename>cross</filename>,

2512

<filename>crosssdk</filename>, and

2513

<filename>cross-canadian</filename>.

</para>

<para>

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

2518

<filename>COPYLEFT_RECIPE_TYPES</filename> is set

2519

by the

2520

2521

class, which is inherited by the

2522

<filename>archiver</filename> class.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

2527

2528

<info>

2529

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>

2534

If set to "1" along with the

2535

2536

variable, the OpenEmbedded build system copies

2537

into the image the license files, which are located in

2538

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

2539

for each package.

2540

The license files are placed

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

2541

in directories within the image itself during build time.

2542

<note>

2543

The <filename>COPY_LIC_DIRS</filename> does not

2544

offer a path for adding licenses for newly installed

2545

packages to an image, which might be most suitable

2546

for read-only filesystems that cannot be upgraded.

2547

See the

2548

2549

variable for additional information.

2550

You can also reference the

2551

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

2552

section in the Yocto Project Development Manual for

2553

information on providing license text.

2554

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

2560

<info>

2561

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>

2566

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

2567

the license manifest for the image to

2568

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

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

2569

within the image itself during build time.

2570

<note>

2571

The <filename>COPY_LIC_MANIFEST</filename> does not

2572

offer a path for adding licenses for newly installed

2573

packages to an image, which might be most suitable

2574

for read-only filesystems that cannot be upgraded.

2575

See the

2576

2577

variable for additional information.

2578

You can also reference the

2579

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

2580

section in the Yocto Project Development Manual for

2581

information on providing license text.

2582

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

2588

<info>

2589

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>

2594

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

2595

You should only set this variable in the

2596

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

2597

in the

2598

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

</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>

2608

<info>

2609

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

</info>

2614

Specifies the parent directory of the OpenEmbedded

2615

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

</para>

<para>

It is an important distinction that

2620

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

2621

layer and not the layer itself.

2622

Consider an example where you have cloned the Poky Git

2623

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

2624

name for your local copy of the repository.

2625

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

2626

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

2627

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

layer.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

2633

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

2634

<info>

2635

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

</info>

2640

Lists files from the

2641

2642

directory that should be copied other than the layers

2643

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

2644

The <filename>COREBASE_FILES</filename> variable exists

2645

for the purpose of copying metadata from the

2646

OpenEmbedded build system into the extensible

SDK.

</para>

<para>

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

2652

is needed because it typically contains build

2653

directories and other files that should not normally

2654

be copied into the extensible SDK.

2655

Consequently, the value of

2656

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

2657

only copy the files that are actually needed.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

2662

2663

<info>

2664

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

</info>

2669

The minimal command and arguments used to run the C

preprocessor.

</para>

</glossdef>

</glossentry>

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

2676

<info>

2677

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

</info>

2682

Specifies the flags to pass to the C pre-processor

2683

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

2684

This variable is exported to an environment

2685

variable and thus made visible to the software being

2686

built during the compilation step.

</para>

<para>

Default initialization for <filename>CPPFLAGS</filename>

2691

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

2700

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

2705

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

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

2713

<info>

2714

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

</info>

2719

The toolchain binary prefix for the target tools.

2720

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

same as the

variable.

<note>

The OpenEmbedded build system sets the

2726

<filename>CROSS_COMPILE</filename> variable only in

2727

certain contexts (e.g. when building for kernel

2728

and kernel module recipes).

</note>

</para>

</glossdef>

</glossentry>

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

2735

<info>

2736

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

</info>

2741

The directory in which files checked out under the

2742

CVS system are stored.

</para>

</glossdef>

</glossentry>

<info>

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

</info>

2754

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

compiler.

</para>

</glossdef>

</glossentry>

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

2761

<info>

2762

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

</info>

2767

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

2768

This variable is exported to an environment

2769

variable and thus made visible to the software being

2770

built during the compilation step.

</para>

<para>

Default initialization for <filename>CXXFLAGS</filename>

2775

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

2784

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

2789

<filename>nativesdk-</filename>)

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

</glossdiv>

<info>

D[doc] = "The destination directory."

</info>

2807

The destination directory.

2808

The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>

2809

where components are installed by the

2810

2811

task.

2812

This location defaults to:

2813

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

2814

${<link linkend='var-WORKDIR'>WORKDIR</link>}/image

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

2815

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

2816

<note><title>Caution</title>

2817

Tasks that read from or write to this directory should

2818

run under

2819

2820

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<info>

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

</info>

2832

The date the build was started.

2833

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

2834

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

</para>

</glossdef>

</glossentry>

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

2840

<info>

2841

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

</info>

2846

The date and time on which the current build started.

2847

The format is suitable for timestamps.

</para>

</glossdef>

</glossentry>

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

2853

<info>

2854

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

</info>

2859

When the

2860

2861

class is inherited, which is the default behavior,

2862

<filename>DEBIAN_NOAUTONAME</filename> specifies a

2863

particular package should not be renamed according to

2864

Debian library package naming.

2865

You must use the package name as an override when you

2866

set this variable.

2867

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

2868

recipe:

2869

2870

DEBIAN_NOAUTONAME_fontconfig-utils = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

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

2877

<info>

2878

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

</info>

2883

When the

2884

2885

class is inherited, which is the default behavior,

2886

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

2887

library name for an individual package.

2888

Overriding the library name in these cases is rare.

2889

You must use the package name as an override when you

2890

set this variable.

2891

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

2892

recipe:

2893

2894

DEBIANNAME_${PN} = "dbus-1"

</literallayout>

</para>

</glossdef>

</glossentry>

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

2901

<info>

2902

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

</info>

2907

Specifies to build packages with debugging information.

2908

This influences the value of the

2909

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

variable.

</para>

</glossdef>

</glossentry>

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

2916

<info>

2917

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>

2922

The options to pass in

2923

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

2924

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

2925

a system for debugging.

2926

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

</para>

</glossdef>

</glossentry>

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

2932

<info>

2933

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

</info>

2938

Specifies a weak bias for recipe selection priority.

</para>

<para>

The most common usage of this is variable is to set

2943

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

2944

piece of software.

2945

Using the variable in this way causes the stable version

2946

of the recipe to build by default in the absence of

2947

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

2948

being used to build the development version.

</para>

<note>

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

2953

is weak and is overridden by

2954

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

2955

if that variable is different between two layers

2956

that contain different versions of the same recipe.

</note>

</glossdef>

</glossentry>

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

2962

<info>

2963

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

</info>

2968

The default CPU and Application Binary Interface (ABI)

2969

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

2970

system.

2971

The <filename>DEFAULTTUNE</filename> helps define

</para>

<para>

The default tune is either implicitly or explicitly set

2977

by the machine

2978

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

2979

However, you can override the setting using available tunes

as defined with

</para>

</glossdef>

</glossentry>

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

2987

<info>

2988

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

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

2993

Lists a recipe's build-time dependencies.

2994

These are dependencies on other recipes whose

2995

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

2996

by the recipe at build time.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

2997

</para>

2998

2999

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3000

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

3001

that contains the following assignment:

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

3002

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3003

DEPENDS = "bar"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

3004

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3005

The practical effect of the previous assignment is that

3006

all files installed by bar will be available in the

3007

appropriate staging sysroot, given by the

3008

3009

variables, by the time the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

3010

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3011

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

3012

This mechanism is implemented by having

3013

<filename>do_configure</filename> depend on the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

3014

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3015

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

3016

through a

3017

<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,

3023

<filename>STAGING_DIR_HOST</filename> explicitly.

3024

The standard classes and build-related variables are

3025

configured to automatically use the appropriate staging

3026

sysroots.

3027

</note>

3028

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

3029

be used to add utilities that run on the build machine

3030

during the build.

3031

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

3032

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

3033

the following:

3034

3035

DEPENDS = "codegen-native"

3036

</literallayout>

3037

For more information, see the

class and the

variable.

<note>

<title>Notes</title>

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

3047

recipe names.

3048

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

3049

3050

names, which usually match recipe names.

3051

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

3052

<filename>DEPENDS</filename> does not make

3053

sense.

3054

Use "foo" instead, as this will put files

3055

from all the packages that make up

3056

<filename>foo</filename>, which includes

3057

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

the sysroot.

</para></listitem>

One recipe having another recipe in

3062

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

3063

add any runtime dependencies between the

3064

packages produced by the two recipes.

3065

However, as explained in the

3066

"<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"

3067

section, runtime dependencies will often be

3068

added automatically, meaning

3069

<filename>DEPENDS</filename> alone is

3070

sufficient for most recipes.

</para></listitem>

Counterintuitively,

<filename>DEPENDS</filename> is often necessary

3075

even for recipes that install precompiled

3076

components.

3077

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

3078

is a precompiled library that links against

3079

<filename>libbar</filename>, then

3080

linking against <filename>libfoo</filename>

3081

requires both <filename>libfoo</filename>

3082

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

3083

in the sysroot.

3084

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

3085

recipe that installs <filename>libfoo</filename>

3086

to the recipe that installs

3087

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

3088

fail to link against

3089

<filename>libfoo</filename>.

3090

</para></listitem>

3091

</itemizedlist>

3092

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

For information on runtime dependencies, see the

3097

3098

variable.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3099

You can also see the

3100

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

3101

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

3102

sections in the BitBake User Manual for additional

3103

information on tasks and dependencies.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

3109

<info>

3110

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>

3115

Points to the general area that the OpenEmbedded build

3116

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

3117

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

3118

By default, this directory resides within the

3119

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>

3120

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

</para>

<para>

For more information on the structure of the Build

3125

Directory, see

3126

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

3127

section.

3128

For more detail on the contents of the

3129

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

3130

"<link linkend='images-dev-environment'>Images</link>",

3131

"<link linkend='package-feeds-dev-environment'>Package Feeds</link>",

3132

and

3133

"<link linkend='sdk-dev-environment'>Application Development SDK</link>"

sections.

</para>

</glossdef>

</glossentry>

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

3140

<info>

3141

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>

3146

Points to the area that the OpenEmbedded build system uses

3147

to place Debian packages that are ready to be used outside

3148

of the build system.

3149

This variable applies only when

3150

3151

contains "package_deb".

</para>

<para>

The BitBake configuration file initially defines the

3156

<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

3169

the

3170

3171

task writes Debian packages into the appropriate folder.

3172

For more information on how packaging works, see the

3173

"<link linkend='package-feeds-dev-environment'>Package Feeds</link>"

section.

</para>

</glossdef>

</glossentry>

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

3180

<info>

3181

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>

3186

Points to the area that the OpenEmbedded build system uses

3187

to place images and other associated output files that are

3188

ready to be deployed onto the target machine.

3189

The directory is machine-specific as it contains the

3190

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

3191

By default, this directory resides within the

3192

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>

3193

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

</para>

<para>

For more information on the structure of the Build

3198

Directory, see

3199

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

3200

section.

3201

For more detail on the contents of the

3202

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

3203

"<link linkend='images-dev-environment'>Images</link>" and

3204

"<link linkend='sdk-dev-environment'>Application Development SDK</link>"

sections.

</para>

</glossdef>

</glossentry>

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

3211

<info>

3212

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>

3217

Points to the area that the OpenEmbedded build system uses

3218

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

3219

the build system.

3220

This variable applies only when

3221

3222

contains "package_ipk".

</para>

<para>

The BitBake configuration file initially defines this

3227

variable as a sub-folder of

3228

3229

3230

DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"

</literallayout>

</para>

<para>

The

class uses the

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

3239

the

3240

3241

task writes IPK packages into the appropriate folder.

3242

For more information on how packaging works, see the

3243

"<link linkend='package-feeds-dev-environment'>Package Feeds</link>"

section.

</para>

</glossdef>

</glossentry>

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

3250

<info>

3251

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>

3256

Points to the area that the OpenEmbedded build system uses

3257

to place RPM packages that are ready to be used outside

3258

of the build system.

3259

This variable applies only when

3260

3261

contains "package_rpm".

</para>

<para>

The BitBake configuration file initially defines this

3266

variable as a sub-folder of

3267

3268

3269

DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"

</literallayout>

</para>

<para>

The

class uses the

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

3278

the

3279

3280

task writes RPM packages into the appropriate folder.

3281

For more information on how packaging works, see the

3282

"<link linkend='package-feeds-dev-environment'>Package Feeds</link>"

section.

</para>

</glossdef>

</glossentry>

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

3289

<info>

3290

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>

3295

Points to the area that the OpenEmbedded build system uses

3296

to place tarballs that are ready to be used outside of

3297

the build system.

3298

This variable applies only when

3299

3300

contains "package_tar".

</para>

<para>

The BitBake configuration file initially defines this

3305

variable as a sub-folder of

3306

3307

3308

DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"

</literallayout>

</para>

<para>

The

class uses the

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

3317

the

3318

3319

task writes TAR packages into the appropriate folder.

3320

For more information on how packaging works, see the

3321

"<link linkend='package-feeds-dev-environment'>Package Feeds</link>"

section.

</para>

</glossdef>

</glossentry>

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

3328

<info>

3329

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

</info>

3334

When inheriting the

3335

3336

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

3337

temporary work area for deployed files that is set in the

3338

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

3339

3340

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

</literallayout>

</para>

<para>

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

3346

should copy files to be deployed into

3347

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

3348

care of copying them into

afterwards.

</para>

</glossdef>

</glossentry>

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

3356

<info>

3357

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

</info>

3362

The package description used by package managers.

3363

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

the value of the

variable.

</para>

</glossdef>

</glossentry>

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

3372

<info>

3373

DISK_SIGNATURE[doc] = "A 32-bit MBR disk signature used by directdisk images."

</info>

3378

A 32-bit MBR disk signature used by

3379

<filename>directdisk</filename> images.

</para>

<para>

By default, the signature is set to an automatically

3384

generated random value that allows the OpenEmbedded

3385

build system to create a boot loader.

3386

You can override the signature in the image recipe

3387

by setting <filename>DISK_SIGNATURE</filename> to an

3388

8-digit hex string.

3389

You might want to override

3390

<filename>DISK_SIGNATURE</filename> if you want the disk

3391

signature to remain constant between image builds.

</para>

<para>

When using Linux 3.8 or later, you can use

3396

<filename>DISK_SIGNATURE</filename> to specify the root

3397

by UUID to allow the kernel to locate the root device

3398

even if the device name changes due to differences in

3399

hardware configuration.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3400

By default, <filename>ROOT_VM</filename> is set

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

3401

as follows:

3402

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3403

ROOT_VM ?= "root=/dev/sda2"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

3404

</literallayout>

3405

However, you can change this to locate the root device

3406

using the disk signature instead:

3407

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3408

ROOT_VM = "root=PARTUUID=${DISK_SIGNATURE}-02"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</literallayout>

</para>

<para>

As previously mentioned, it is possible to set the

3414

<filename>DISK_SIGNATURE</filename> variable in your

3415

<filename>local.conf</filename> file to a fixed

3416

value if you do not want <filename>syslinux.cfg</filename>

3417

changing for each build.

3418

You might find this useful when you want to upgrade the

3419

root filesystem on a device without having to recreate or

3420

modify the master boot record.

</para>

</glossdef>

</glossentry>

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

3426

<info>

3427

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

</info>

3432

The short name of the distribution.

3433

This variable corresponds to a distribution

3434

configuration file whose root name is the same as the

3435

variable's argument and whose filename extension is

3436

<filename>.conf</filename>.

3437

For example, the distribution configuration file for the

3438

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

3439

and resides in the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

3440

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

3441

the

3442

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

</para>

<para>

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

3447

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

DISTRO = "poky"

</literallayout>

</para>

<para>

Distribution configuration files are located in a

3455

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

3456

<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>

3457

that contains the distribution configuration.

3458

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

3459

spaces, and is typically all lower-case.

3460

<note>

3461

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

3462

of default configurations are used, which are specified

3463

within

3464

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

3465

also in the Source Directory.

</note>

</para>

</glossdef>

</glossentry>

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

3472

<info>

3473

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

</info>

3478

Specifies a codename for the distribution being built.

</para>

</glossdef>

</glossentry>

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

3484

<info>

3485

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>

3490

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

3491

This variable takes affect through

3492

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

3493

variable only really applies to the more full-featured

3494

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

3495

You can use this variable to keep distro policy out of

3496

generic images.

3497

As with all other distro variables, you set this variable

3498

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

</para>

</glossdef>

</glossentry>

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

3504

<info>

3505

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>

3510

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

3511

if the packages exist.

3512

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

3513

The list of packages are automatically installed but you can

remove them.

</para>

</glossdef>

</glossentry>

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

3520

<info>

3521

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

</info>

3526

The software support you want in your distribution for

3527

various features.

3528

You define your distribution features in the distribution

configuration file.

</para>

<para>

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

3534

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

3535

appropriate option supplied to the configure script

3536

during the

3537

3538

task for recipes that optionally support the feature.

3539

For example, specifying "x11" in

3540

<filename>DISTRO_FEATURES</filename>, causes

3541

every piece of software built for the target that can

3542

optionally support X11 to have its X11 support enabled.

</para>

<para>

Two more examples are Bluetooth and NFS support.

3547

For a more complete list of features that ships with the

3548

Yocto Project and that you can provide with this variable,

3549

see the

3550

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

section.

</para>

</glossdef>

</glossentry>

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

3557

<info>

3558

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>

3563

Features to be added to

3564

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

3565

if not also present in

3566

<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.

3571

It is not intended to be user-configurable.

3572

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

3573

being backfilled for all distro configurations.

3574

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>

3581

<info>

3582

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>

3587

Features from

3588

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

3589

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

3590

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

3591

during the build.

3592

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>

3599

<info>

3600

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

</info>

3605

A convenience variable that gives you the default

3606

list of distro features with the exception of any

3607

features specific to the C library

3608

(<filename>libc</filename>).

</para>

<para>

When creating a custom distribution, you might find it

3613

useful to be able to reuse the default

3614

3615

options without the need to write out the full set.

3616

Here is an example that uses

3617

<filename>DISTRO_FEATURES_DEFAULT</filename> from a

3618

custom distro configuration file:

3619

3620

DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} ${DISTRO_FEATURES_LIBC} myfeature"

</literallayout>

</para>

</glossdef>

</glossentry>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

3626

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

3627

<info>

3628

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>

3633

Specifies a list of features that if present in

3634

the target

3635

3636

value should be included in

3637

<filename>DISTRO_FEATURES</filename> when building native

3638

recipes.

3639

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>

3648

<info>

3649

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>

3654

Specifies a list of features that if present in the target

3655

3656

value should be included in

3657

<filename>DISTRO_FEATURES</filename> when building

3658

nativesdk recipes.

3659

This variable is used in addition to the features

filtered using the

variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

3667

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

3668

<info>

3669

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

</info>

3674

A convenience variable that specifies the list of distro

3675

features that are specific to the C library

3676

(<filename>libc</filename>).

3677

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

3678

control which features are enabled at during the build

3679

within the C library itself.

</para>

</glossdef>

</glossentry>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

3684

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

3685

<info>

3686

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

</info>

3691

Specifies a list of features that should be included in

3692

3693

when building native recipes.

3694

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>

3703

<info>

3704

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

</info>

3709

Specifies a list of features that should be included in

3710

3711

when building nativesdk recipes.

3712

This variable is used in addition to the features

filtered using the

variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

3720

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

3721

<info>

3722

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

</info>

3727

The long name of the distribution.

</para>

</glossdef>

</glossentry>

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

3733

<info>

3734

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

</info>

3739

The version of the distribution.

</para>

</glossdef>

</glossentry>

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

3745

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3746

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3751

A colon-separated list of overrides specific to the

3752

current distribution.

3753

By default, this list includes the value of

</para>

<para>

You can extend <filename>DISTROOVERRIDES</filename>

3759

to add extra overrides that should apply to

the distribution.

</para>

<para>

The underlying mechanism behind

3765

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

3766

is included in the default value of

3767

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</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>

3779

The central download directory used by the build process to

3780

store downloads.

3781

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

3782

suitable for mirroring for everything except Git

3783

repositories.

3784

If you want tarballs of Git repositories, use the

variable.

</para>

<para>

You can set this directory by defining the

3791

<filename>DL_DIR</filename> variable in the

3792

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

3793

This directory is self-maintaining and you should not have

3794

to touch it.

3795

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

3796

in the

3797

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

3798

3799

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

3800

</literallayout>

3801

To specify a different download directory, simply remove

3802

the comment from the line and provide your directory.

</para>

<para>

During a first build, the system downloads many different

3807

source code tarballs from various upstream projects.

3808

Downloading can take a while, particularly if your network

3809

connection is slow.

3810

Tarballs are all stored in the directory defined by

3811

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

3812

first to find source tarballs.

3813

<note>

3814

When wiping and rebuilding, you can preserve this

3815

directory to speed up this part of subsequent

builds.

</note>

</para>

<para>

You can safely share this directory between multiple builds

3822

on the same development machine.

3823

For additional information on how the build process gets

3824

source files when working behind a firewall or proxy server,

3825

see this specific question in the

3826

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

3827

chapter.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

3828

You can also refer to the

3829

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

3830

Wiki page.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

3836

<info>

3837

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>

3842

When inheriting the

3843

3844

class, this variable sets the compression policy used when

3845

the OpenEmbedded build system compresses man pages and info

3846

pages.

3847

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

3848

Other policies available are xz and bz2.

</para>

<para>

For information on policies and on how to use this

3853

variable, see the comments in the

3854

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

</para>

</glossdef>

</glossentry>

</glossdiv>

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

3864

<info>

3865

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

</info>

3870

When building bootable images (i.e. where

3871

<filename>hddimg</filename> or <filename>vmdk</filename>

3872

is in

3873

3874

the <filename>EFI_PROVIDER</filename> variable specifies

3875

the EFI bootloader to use.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3876

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

instead.

</para>

<para>

See the

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

3882

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

3883

and

3884

3885

classes for more information.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

3891

<info>

3892

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>

3897

Variable that controls which locales for

3898

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

3899

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>

3906

<info>

3907

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>

3912

When used with the

3913

3914

class, specifies the path used for storing the debug files

3915

created by the

3916

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

3917

which allows you to submit build errors you encounter to a

3918

central database.

3919

By default, the value of this variable is

3920

<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

3925

you want the error reporting tool to store the debug files

3926

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

3927

3928

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

3935

<info>

3936

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

</info>

3941

Specifies the quality assurance checks whose failures are

3942

reported as errors by the OpenEmbedded build system.

3943

You set this variable in your distribution configuration

3944

file.

3945

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

3946

see the

3947

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

section.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

3953

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

3954

<info>

3955

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

</info>

3960

Triggers the OpenEmbedded build system's shared libraries

3961

resolver to exclude an entire package when scanning for

3962

shared libraries.

3963

<note>

3964

The shared libraries resolver's functionality results

3965

in part from the internal function

3966

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

the

task.

You should be aware that the shared libraries resolver

3971

might implicitly define some dependencies between

3972

packages.

3973

</note>

3974

The <filename>EXCLUDE_FROM_SHLIBS</filename> variable is

3975

similar to the

3976

3977

variable, which excludes a package's particular libraries

3978

only and not the whole package.

</para>

<para>

Use the

<filename>EXCLUDE_FROM_SHLIBS</filename> variable by

3984

setting it to "1" for a particular package:

3985

3986

EXCLUDE_FROM_SHLIBS = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

3992

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

3993

<info>

3994

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

</info>

3999

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

4000

<filename>bitbake world</filename>).

4001

During world builds, BitBake locates, parses and builds all

4002

recipes found in every layer exposed in the

4003

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

</para>

<para>

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

4008

set the variable to "1" in the recipe.

</para>

<note>

Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>

4013

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

4014

dependencies of other recipes.

4015

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

4016

only ensures that the recipe is not explicitly added

4017

to the list of build targets in a world build.

</note>

</glossdef>

</glossentry>

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

4023

<info>

4024

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>

4029

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

4030

version based on the recipe's

4031

4032

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

4033

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

4034

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

4035

becomes "1_").

4036

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

4037

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

4038

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

4039

variable for an example.

</para>

</glossdef>

</glossentry>

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

4045

<info>

4046

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

</info>

4051

The full package version specification as it appears on the

4052

final packages produced by a recipe.

4053

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

4054

dependency to the exact same version of another package

4055

in the same recipe:

4056

4057

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

</literallayout>

</para>

<para>

The dependency relationships are intended to force the

4063

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>

4070

<info>

4071

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

</info>

4076

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

4077

variable indicates that these tools are not in the

source tree.

</para>

<para>

When kernel tools are available in the tree, they are

4083

preferred over any externally installed tools.

4084

Setting the <filename>EXTERNAL_KERNEL_TOOLS</filename>

4085

variable tells the OpenEmbedded build system to prefer

4086

the installed external tools.

4087

See the

4088

4089

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

4090

the variable is used.

</para>

</glossdef>

</glossentry>

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

4096

<info>

4097

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

</info>

4102

When inheriting the

4103

4104

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

4105

outside of the OpenEmbedded build system.

4106

When set, this variable sets the

4107

4108

variable, which is what the OpenEmbedded build system uses

4109

to locate unpacked recipe source code.

</para>

<para>

For more information on

4114

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

4115

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

4116

section.

4117

You can also find information on how to use this variable

4118

in the

4119

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

4120

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

4126

<info>

4127

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>

4132

When inheriting the

4133

4134

class, this variable points to the directory in which the

4135

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

4136

OpenEmbedded build system.

4137

When set, this variable sets the

4138

4139

variable, which is what the OpenEmbedded build system uses

4140

to locate the Build Directory.

</para>

<para>

For more information on

4145

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

4146

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

4147

section.

4148

You can also find information on how to use this variable

4149

in the

4150

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

4151

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

4157

<info>

4158

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

</info>

4163

For recipes inheriting the

4164

4165

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

4166

specify extra options to pass to the

4167

<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>

4180

<info>

4181

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>

4186

A list of additional features to include in an image.

4187

When listing more than one feature, separate them with

a space.

</para>

<para>

Typically, you configure this variable in your

4193

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

4194

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

4195

Although you can use this variable from within a recipe,

4196

best practices dictate that you do not.

4197

<note>

4198

To enable primary features from within the image

recipe, use the

variable.

</note>

</para>

<para>

Here are some examples of features you can add:

4207

4208

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

4209

including symbol information for debugging and

4210

profiling.

4211

4212

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

4213

For example, allows root logins without

4214

passwords and enables post-installation

4215

logging. See the 'allow-empty-password'

4216

and 'post-install-logging' features in

4217

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

4218

more information.

4219

4220

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

4221

This is useful if you want to develop against

4222

the libraries in the image.

4223

4224

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

4225

filesystem is read-only. See the

4226

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

4227

section in the Yocto Project

4228

Development Manual for more

4229

information

4230

4231

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

4232

strace.

4233

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

4234

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

4235

pkgconfig and so forth.

4236

4237

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

4238

ts_print, aplay, arecord and so

forth.

</literallayout>

</para>

<para>

For a complete list of image features that ships with the

4246

Yocto Project, see the

4247

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

section.

</para>

<para>

For an example that shows how to customize your image by

4253

using this variable, see the

4254

"<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>"

4255

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

4261

<info>

4262

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 type."

</info>

4267

Specifies additional options for the image

4268

creation command that has been specified in

4269

4270

When setting this variable, you should

4271

use an override for the associated type.

4272

Here is an example:

4273

4274

EXTRA_IMAGECMD_ext3 ?= "-i 4096"

</literallayout>

</para>

</glossdef>

</glossentry>

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

4281

<info>

4282

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>

4287

A list of recipes to build that do not provide packages

4288

for installing into the root filesystem.

</para>

<para>

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

4293

needed in the root filesystem.

4294

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

4295

list these recipes and thus specify the dependencies.

4296

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

</para>

<note>

To add packages to the root filesystem, see the various

4301

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

4302

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

variables.

</note>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

4308

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

4309

<info>

4310

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

</info>

4315

A list of subdirectories of

4316

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

4317

added to the beginning of the environment variable

4318

<filename>PATH</filename>.

4319

As an example, the following prepends

4320

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

4321

to <filename>PATH</filename>:

4322

4323

EXTRANATIVEPATH = "foo bar"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

4329

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

4330

<info>

4331

EXTRA_OECMAKE[doc] = "Additional cmake options."

</info>

4336

Additional <filename>cmake</filename> options.

</para>

</glossdef>

</glossentry>

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

4342

<info>

4343

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

</info>

4348

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

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

4349

See

4350

4351

for additional information on passing configure script

4352

options.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

4358

<info>

4359

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

</info>

4364

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

4365

</para>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

4366

4367

<para>

4368

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

4369

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

4370

GNU options.

4371

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

<para>

and

also make use of

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

4379

flags.

4380

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

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

4385

<info>

4386

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>

4391

When inheriting the

4392

4393

class, this variable specifies additional configuration

4394

options you want to pass to the

4395

<filename>scons</filename> command line.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

4400

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

4401

<info>

4402

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

</info>

4407

When inheriting the

4408

4409

class, this variable provides image level user and group

4410

operations.

4411

This is a more global method of providing user and group

4412

configuration as compared to using the

4413

4414

class, which ties user and group configurations to a

specific recipe.

</para>

<para>

The set list of commands you can configure using the

4420

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

4421

<filename>extrausers</filename> class.

4422

These commands map to the normal Unix commands of the same

4423

names:

4424

4425

# EXTRA_USERS_PARAMS = "\

4426

# useradd -p '' tester; \

4427

# groupadd developers; \

4428

# userdel nobody; \

4429

# groupdel -g video; \

4430

# groupmod -g 1020 developers; \

4431

# usermod -s /bin/sh tester; \

# "

</literallayout>

</para>

</glossdef>

</glossentry>

</glossdiv>

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

4443

<info>

4444

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>

4449

Defines one or more packages to include in an image when

4450

a specific item is included in

4451

4452

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

4453

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

4454

Here is an example:

4455

4456

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

</literallayout>

</para>

<para>

In this example, if "widget" were added to

4462

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

4463

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

4464

<note>

4465

Packages installed by features defined through

4466

<filename>FEATURE_PACKAGES</filename> are often package

4467

groups.

4468

While similarly named, you should not confuse the

4469

<filename>FEATURE_PACKAGES</filename> variable with

4470

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>

4478

<info>

4479

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>

4484

Points to the base URL of the server and location within

4485

the document-root that provides the metadata and

4486

packages required by OPKG to support runtime package

4487

management of IPK packages.

4488

You set this variable in your

4489

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

</para>

<para>

Consider the following example:

4494

4495

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

4496

</literallayout>

4497

This example assumes you are serving your packages over

4498

HTTP and your databases are located in a directory

4499

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

4500

your HTTP server's document-root.

4501

In this case, the OpenEmbedded build system generates a set

4502

of configuration files for you in your target that work

with the feed.

</para>

</glossdef>

</glossentry>

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

4509

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

4510

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

4515

The list of files and directories that are placed in a

package.

The

variable lists the packages generated by a recipe.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

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

4524

package name override that identifies the resulting package.

4525

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

4526

that identify the files you want included as part of the

resulting package.

Here is an example:

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

4530

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</literallayout>

</para>

<note>

When specifying paths as part of the

4536

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

4537

to use appropriate path variables.

4538

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

4539

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

4540

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

4541

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

4542

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

4543

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

4544

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

4545

You will also find the default values of the various

4546

<filename>FILES_*</filename> variables in this file.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</note>

<para>

If some of the files you provide with the

4551

<filename>FILES</filename> variable are editable and you

4552

know they should not be overwritten during the package

4553

update process by the Package Management System (PMS), you

4554

can identify these files so that the PMS will not

overwrite them.

See the

variable for information on how to identify these files to

4559

the PMS.

4560

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

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

4565

<info>

4566

FILES_SOLIBSDEV[doc] = "Defines the full path name of the development symbolic link (symlink) for shared libraries on the target platform."

</info>

4571

Defines the file specification to match

4572

4573

In other words, <filename>FILES_SOLIBSDEV</filename>

4574

defines the full path name of the development symbolic link

4575

(symlink) for shared libraries on the target platform.

</para>

<para>

The following statement from the

4580

<filename>bitbake.conf</filename> shows how it is set:

4581

4582

FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"

</literallayout>

</para>

</glossdef>

</glossentry>

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

4589

<info>

4590

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>

4595

Extends the search path the OpenEmbedded build system uses

4596

when looking for files and patches as it processes recipes

4597

and append files.

4598

The default directories BitBake uses when it processes

4599

recipes are initially defined by the

4600

4601

variable.

4602

You can extend <filename>FILESPATH</filename> variable

4603

by using <filename>FILESEXTRAPATHS</filename>.

</para>

<para>

Best practices dictate that you accomplish this by using

4608

<filename>FILESEXTRAPATHS</filename> from within a

4609

<filename>.bbappend</filename> file and that you prepend

4610

paths as follows:

4611

4612

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"

4613

</literallayout>

4614

In the above example, the build system first looks for files

4615

in a directory that has the same name as the corresponding

4616

append file.

4617

<note>

4618

<para>When extending <filename>FILESEXTRAPATHS</filename>,

4619

be sure to use the immediate expansion

4620

(<filename>:=</filename>) operator.

4621

Immediate expansion makes sure that BitBake evaluates

4622

4623

at the time the directive is encountered rather than at

4624

some later time when expansion might result in a

4625

directory that does not contain the files you need.

4626

</para>

4627

<para>Also, include the trailing separating colon

4628

character if you are prepending.

4629

The trailing colon character is necessary because you

4630

are directing BitBake to extend the path by prepending

4631

directories to the search path.</para>

4632

</note>

4633

Here is another common use:

4634

4635

FILESEXTRAPATHS_prepend := "${THISDIR}/files:"

4636

</literallayout>

4637

In this example, the build system extends the

4638

<filename>FILESPATH</filename> variable to include a

4639

directory named <filename>files</filename> that is in the

4640

same directory as the corresponding append file.

</para>

<para>

Here is a final example that specifically adds three paths:

4645

4646

FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"

</literallayout>

</para>

<para>

By prepending paths in <filename>.bbappend</filename>

4652

files, you allow multiple append files that reside in

4653

different layers but are used for the same recipe to

4654

correctly extend the path.

</para>

</glossdef>

</glossentry>

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

4660

<info>

4661

FILESOVERRIDES[doc] = "A subset of OVERRIDES used by the OpenEmbedded build system for creating FILESPATH."

</info>

4666

A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>

4667

used by the OpenEmbedded build system for creating

4668

4669

You can find more information on how overrides are handled

4670

in the

4671

<ulink url='&YOCTO_DOCS_BB_URL;'>BitBake Manual</ulink>.

</para>

<para>

By default, the <filename>FILESOVERRIDES</filename>

4676

variable is defined as:

4677

4678

FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"

</literallayout>

<note>

Do not hand-edit the <filename>FILESOVERRIDES</filename>

4683

variable.

4684

The values match up with expected overrides and are

4685

used in an expected manner by the build system.

</note>

</para>

</glossdef>

</glossentry>

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

4692

<info>

4693

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>

4698

The default set of directories the OpenEmbedded build system

4699

uses when searching for patches and files.

4700

During the build process, BitBake searches each directory in

4701

<filename>FILESPATH</filename> in the specified order when

4702

looking for files and patches specified by each

4703

<filename>file://</filename> URI in a recipe.

</para>

<para>

The default value for the <filename>FILESPATH</filename>

4708

variable is defined in the <filename>base.bbclass</filename>

4709

class found in <filename>meta/classes</filename> in the

4710

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:

4711

4712

FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \

4713

"${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"

4714

</literallayout>

4715

<note>

4716

Do not hand-edit the <filename>FILESPATH</filename>

4717

variable.

4718

If you want the build system to look in directories

4719

other than the defaults, extend the

4720

<filename>FILESPATH</filename> variable by using the

variable.

</note>

Be aware that the default <filename>FILESPATH</filename>

4725

directories do not map to directories in custom layers

4726

where append files (<filename>.bbappend</filename>)

4727

are used.

4728

If you want the build system to find patches or files

4729

that reside with your append files, you need to extend

4730

the <filename>FILESPATH</filename> variable by using

the

variable.

</para>

</glossdef>

</glossentry>

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

4739

<info>

4740

FILESYSTEM_PERMS_TABLES[doc] = "Allows you to define your own file permissions settings table as part of your configuration for the packaging process."

</info>

4745

Allows you to define your own file permissions settings table as part of

4746

your configuration for the packaging process.

4747

For example, suppose you need a consistent set of custom permissions for

4748

a set of groups and users across an entire work project.

4749

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

4755

is located in the <filename>meta/files</filename> folder in the

4756

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

4757

If you create your own file permissions setting table, you should place it in your

4758

layer or the distro's layer.

</para>

<para>

You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the

4763

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

4764

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to

4765

point to your custom <filename>fs-perms.txt</filename>.

4766

You can specify more than a single file permissions setting table.

4767

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,

4773

examine the existing <filename>fs-perms.txt</filename>.

</para>

</glossdef>

</glossentry>

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

4779

<info>

4780

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>

4785

When inheriting the

4786

4787

class, this variable specifies the runtime dependencies

4788

for font packages.

4789

By default, the <filename>FONT_EXTRA_RDEPENDS</filename>

4790

is set to "fontconfig-utils".

</para>

</glossdef>

</glossentry>

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

4796

<info>

4797

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>

4802

When inheriting the

4803

4804

class, this variable identifies packages containing font

4805

files that need to be cached by Fontconfig.

4806

By default, the <filename>fontcache</filename> class assumes

4807

that fonts are in the recipe's main package

4808

(i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).

4809

Use this variable if fonts you need are in a package

4810

other than that main package.

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

4815

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

4816

<info>

4817

FORCE_RO_REMOVE[doc] = "Forces the removal of the packages listed in ROOTFS_RO_UNNEEDED during the generation of the root filesystem."

</info>

4822

Forces the removal of the packages listed in

4823

<filename>ROOTFS_RO_UNNEEDED</filename> during the

4824

generation of the root filesystem.

</para>

<para>

Set the variable to "1" to force the removal of these

packages.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

4834

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

4835

<info>

4836

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>

4841

The options to pass in

4842

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

4843

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

4844

when compiling an optimized system.

4845

This variable defaults to

4846

"-O2 -pipe ${DEBUG_FLAGS}".

</para>

</glossdef>

</glossentry>

</glossdiv>

<info>

GDB[doc] = "The minimal command and arguments to run the GNU Debugger."

</info>

4861

The minimal command and arguments to run the GNU Debugger.

</para>

</glossdef>

</glossentry>

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

4867

<info>

4868

GITDIR[doc] = "The directory where Git clones will be stored."

</info>

4873

The directory in which a local copy of a Git repository

4874

is stored when it is cloned.

</para>

</glossdef>

</glossentry>

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

4880

<info>

4881

GLIBC_GENERATE_LOCALES[doc]= "Specifies the list of GLIBC locales to generate should you not wish generate all LIBC locals, which can be time consuming."

</info>

4886

Specifies the list of GLIBC locales to generate should you

4887

not wish generate all LIBC locals, which can be time

4888

consuming.

4889

<note>

4890

If you specifically remove the locale

4891

<filename>en_US.UTF-8</filename>, you must set

appropriately.

</note>

</para>

<para>

You can set <filename>GLIBC_GENERATE_LOCALES</filename>

4899

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

4900

By default, all locales are generated.

4901

4902

GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"

</literallayout>

</para>

</glossdef>

</glossentry>

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

4909

<info>

4910

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

4919

to the <filename>groupadd</filename> command

4920

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>

4926

recipe:

4927

4928

GROUPADD_PARAM_${PN} = "-r netdev"

4929

</literallayout>

4930

For information on the standard Linux shell command

4931

<filename>groupadd</filename>, see

4932

<ulink url='http://linux.die.net/man/8/groupadd'></ulink>.

</para>

</glossdef>

</glossentry>

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

4938

<info>

4939

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

4948

to the <filename>groupmems</filename> command

4949

if you wish to modify the members of a group when the

4950

package is installed.

</para>

<para>

For information on the standard Linux shell command

4955

<filename>groupmems</filename>, see

4956

<ulink url='http://linux.die.net/man/8/groupmems'></ulink>.

</para>

</glossdef>

</glossentry>

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

4962

<info>

4963

GRUB_GFXSERIAL[doc] = "Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu."

</info>

4968

Configures the GNU GRand Unified Bootloader (GRUB) to have

4969

graphics and serial in the boot menu.

4970

Set this variable to "1" in your

4971

<filename>local.conf</filename> or distribution

4972

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>

4991

Additional options to add to the GNU GRand Unified

4992

Bootloader (GRUB) configuration.

4993

Use a semi-colon character (<filename>;</filename>) to

4994

separate multiple options.

</para>

<para>

The <filename>GRUB_OPTS</filename> variable is optional.

4999

See the

5000

5001

class for more information on how this variable is used.

</para>

</glossdef>

</glossentry>

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

5007

<info>

5008

GRUB_TIMEOUT[doc] = "Specifies the timeout before executing the default LABEL in the GNU GRand Unified Bootloader (GRUB)."

</info>

5013

Specifies the timeout before executing the default

5014

<filename>LABEL</filename> in the GNU GRand Unified

Bootloader (GRUB).

</para>

<para>

The <filename>GRUB_TIMEOUT</filename> variable is optional.

5020

See the

5021

5022

class for more information on how this variable is used.

</para>

</glossdef>

</glossentry>

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

5028

<info>

5029

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>

5034

When inheriting the

5035

5036

class, this variable specifies the packages that contain the

5037

GTK+ input method modules being installed when the modules

5038

are in packages other than the main package.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdiv>

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

5048

<info>

5049

HOMEPAGE[doc] = "Website where more information about the software the recipe is building can be found."

</info>

5054

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>

5068

The name of the target architecture, which is normally

5069

the same as

5070

5071

The OpenEmbedded build system supports many

5072

architectures.

5073

Here is an example list of architectures supported.

5074

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>

5096

Specifies architecture-specific compiler flags that are

5097

passed to the C compiler.

</para>

<para>

Default initialization for <filename>HOST_CC_ARCH</filename>

5102

varies depending on what is being built:

when building for the target

5107

</para></listitem>

5108

5109

<filename>BUILD_CC_ARCH</filename>

5110

when building for the build host (i.e.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

5111

<filename>-native</filename>)

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

5112

</para></listitem>

5113

5114

<filename>BUILDSDK_CC_ARCH</filename>

5115

when building for an SDK (i.e.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

5116

<filename>nativesdk-</filename>)

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</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>

5130

Specifies the name of the target operating system, which

5131

is normally the same as the

5132

5133

The variable can be set to "linux" for <filename>glibc</filename>-based systems and

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

5134

to "linux-musl" for <filename>musl</filename>.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

5135

For ARM/EABI targets, there are also "linux-gnueabi" and

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

5136

"linux-musleabi" values possible.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

5142

<info>

5143

HOST_PREFIX[doc] = "The prefix for the cross compile toolchain. Normally same as the TARGET_PREFIX."

</info>

5148

Specifies the prefix for the cross-compile toolchain.

5149

<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 with the build is occurring in the context of the current recipe."

</info>

5162

Specifies the system, including the architecture and the

5163

operating system, for which the build is occurring

5164

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:

5182

5183

<listitem><para>Given a native recipe on a 32-bit

5184

x86 machine running Linux, the value is

5185

"i686-linux".

5186

</para></listitem>

5187

<listitem><para>Given a recipe being built for a

5188

little-endian MIPS target running Linux,

5189

the value might be "mipsel-linux".

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

5196

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

5197

<info>

5198

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>

5203

A space-separated list (filter) of tools on the build host

5204

that should be allowed to be called from within build tasks.

5205

Using this filter helps reduce the possibility of host

5206

contamination.

5207

If a tool specified in the value of

5208

<filename>HOSTTOOLS</filename> is not found on the

5209

build host, the OpenEmbedded build system produces

5210

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>

5221

<info>

5222

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>

5227

A space-separated list (filter) of tools on the build host

5228

that should be allowed to be called from within build tasks.

5229

Using this filter helps reduce the possibility of host

contamination.

Unlike

the OpenEmbedded build system does not produce and error

5234

if a tool specified in the value of

5235

<filename>HOSTTOOLS_NONFATAL</filename> is not found on the

5236

build host.

5237

Thus, you can use <filename>HOSTTOOLS_NONFATAL</filename>

5238

to filter optional host tools.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

5243

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

5244

<info>

5245

HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR."

</info>

5250

Specifies the name of the vendor.

5251

<filename>HOST_VENDOR</filename> is normally the same as

</para>

</glossdef>

</glossentry>

</glossdiv>

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

5262

<info>

5263

ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function."

</info>

5268

Disables or enables the <filename>icecc</filename>

5269

(Icecream) function.

5270

For more information on this function and best practices

5271

for using this variable, see the

5272

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

section.

</para>

<para>

Setting this variable to "1" in your

5278

<filename>local.conf</filename> disables the function:

5279

5280

ICECC_DISABLED ??= "1"

5281

</literallayout>

5282

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>

5291

<info>

5292

ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide."

</info>

5297

Points to the <filename>icecc-create-env</filename> script

5298

that you provide.

5299

This variable is used by the

5300

5301

class.

5302

You set this variable in your

5303

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

</para>

<para>

If you do not point to a script that you provide, the

5308

OpenEmbedded build system uses the default script provided

5309

by the <filename>icecc-create-env.bb</filename> recipe,

5310

which is a modified version and not the one that comes with

5311

<filename>icecc</filename>.

</para>

</glossdef>

</glossentry>

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

5317

<info>

5318

ICECC_PARALLEL_MAKE[doc] = "Extra options passed to the make command during the do_compile task that specify parallel compilation."

</info>

5323

Extra options passed to the <filename>make</filename>

5324

command during the

5325

5326

task that specify parallel compilation.

5327

This variable usually takes the form of

5328

"-j <replaceable>x</replaceable>", where

5329

<replaceable>x</replaceable> represents the maximum

5330

number of parallel threads <filename>make</filename> can

5331

run.

5332

<note>

5333

The options passed affect builds on all enabled

5334

machines on the network, which are machines running the

5335

<filename>iceccd</filename> daemon.

</note>

</para>

<para>

If your enabled machines support multiple cores,

5341

coming up with the maximum number of parallel threads

5342

that gives you the best performance could take some

5343

experimentation since machine speed, network lag,

5344

available memory, and existing machine loads can all

5345

affect build time.

5346

Consequently, unlike the

5347

5348

variable, there is no rule-of-thumb for setting

5349

<filename>ICECC_PARALLEL_MAKE</filename> to achieve

optimal performance.

</para>

<para>

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

5355

the build system does not use it (i.e. the system does

5356

not detect and assign the number of cores as is done with

5357

<filename>PARALLEL_MAKE</filename>).

</para>

</glossdef>

</glossentry>

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

5363

<info>

5364

ICECC_PATH[doc] = "The location of the icecc binary."

</info>

5369

The location of the <filename>icecc</filename> binary.

5370

You can set this variable in your

5371

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

5372

If your <filename>local.conf</filename> file does not define

5373

this variable, the

5374

5375

class attempts to define it by locating

5376

<filename>icecc</filename> using <filename>which</filename>.

</para>

</glossdef>

</glossentry>

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

5382

<info>

5383

ICECC_USER_CLASS_BL[doc] = "Identifies user classes that you do not want the Icecream distributed compile support to consider."

</info>

5388

Identifies user classes that you do not want the

5389

Icecream distributed compile support to consider.

5390

This variable is used by the

5391

5392

class.

5393

You set this variable in your

5394

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

</para>

<para>

When you list classes using this variable, you are

5399

"blacklisting" them from distributed compilation across

5400

remote hosts.

5401

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>

5408

<info>

5409

ICECC_USER_PACKAGE_BL[doc] = "Identifies user recipes that you do not want the Icecream distributed compile support to consider."

</info>

5414

Identifies user recipes that you do not want the

5415

Icecream distributed compile support to consider.

5416

This variable is used by the

5417

5418

class.

5419

You set this variable in your

5420

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

</para>

<para>

When you list packages using this variable, you are

5425

"blacklisting" them from distributed compilation across

5426

remote hosts.

5427

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>

5434

<info>

5435

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>

5440

Identifies user recipes that use an empty

5441

5442

variable that you want to force remote distributed

5443

compilation on using the Icecream distributed compile

5444

support.

5445

This variable is used by the

5446

5447

class.

5448

You set this variable in your

5449

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

</para>

</glossdef>

</glossentry>

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

5455

<info>

5456

IMAGE_BASENAME[doc] = "The base name of image output files."

</info>

5461

The base name of image output files.

5462

This variable defaults to the recipe name

5463

(<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>

5469

<info>

5470

IMAGE_BOOT_FILES[doc] = "Whitespace separated list of files from ${DEPLOY_DIR_IMAGE} to place in boot partition. Entries will be installed under a same name as the source file. To change the destination file name, pass a desired name after a semicolon (eg. u-boot.img;uboot)."

</info>

5475

A space-separated list of files installed into the

5476

boot partition when preparing an image using the

5477

<filename>wic</filename> tool with the

5478

<filename>bootimg-partition</filename> source

5479

plugin.

5480

By default, the files are installed under

5481

the same name as the source files.

5482

To change the installed name, separate it from the

5483

original name with a semi-colon (;).

5484

Source files need to be located in

5485

5486

Here are two examples:

5487

5488

5489

IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"

5490

IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"

</literallayout>

</para>

<para>

Alternatively, source files can be picked up using

5496

a glob pattern.

5497

In this case, the destination file

5498

will have the same name as the base name of the source file

5499

path.

5500

To install files into a directory within the

5501

target location, pass its name after a semi-colon

5502

(;).

5503

Here are two examples:

5504

5505

IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"

5506

IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"

5507

</literallayout>

5508

The first example installs all files from

5509

<filename>${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles</filename>

5510

into the root of the target partition.

5511

The second example installs the same files into a

5512

<filename>boot</filename> directory within the

target partition.

</para>

</glossdef>

</glossentry>

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

5519

<info>

5520

IMAGE_CLASSES[doc] = "A list of classes that all images should inherit."

</info>

5525

A list of classes that all images should inherit.

5526

You typically use this variable to specify the list of

5527

classes that register the different types of images

5528

the OpenEmbedded build system creates.

</para>

<para>

The default value for <filename>IMAGE_CLASSES</filename> is

5533

<filename>image_types</filename>.

5534

You can set this variable in your

5535

<filename>local.conf</filename> or in a distribution

configuration file.

</para>

<para>

For more information, see

5541

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

5542

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

</para>

</glossdef>

</glossentry>

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

5548

<info>

5549

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>

5554

Specifies the command to create the image file for a

5555

specific image type, which corresponds to the value set

5556

set in

5557

5558

(e.g. <filename>ext3</filename>,

5559

<filename>btrfs</filename>, and so forth).

5560

When setting this variable, you should use

5561

an override for the associated type.

5562

Here is an example:

5563

5564

IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \

5565

--faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \

${EXTRA_IMAGECMD}"

</literallayout>

</para>

<para>

You typically do not need to set this variable unless

5572

you are adding support for a new image type.

5573

For more examples on how to set this variable, see the

5574

5575

class file, which is

5576

<filename>meta/classes/image_types.bbclass</filename>.

</para>

</glossdef>

</glossentry>

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

5582

<info>

5583

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>

5588

Specifies one or more files that contain custom device

5589

tables that are passed to the

5590

<filename>makedevs</filename> command as part of creating

5591

an image.

5592

These files list basic device nodes that should be

5593

created under <filename>/dev</filename> within the image.

5594

If <filename>IMAGE_DEVICE_TABLES</filename> is not set,

5595

<filename>files/device_table-minimal.txt</filename> is

5596

used, which is located by

5597

5598

For details on how you should write device table files,

5599

see <filename>meta/files/device_table-minimal.txt</filename>

as an example.

</para>

</glossdef>

</glossentry>

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

5606

<info>

5607

IMAGE_FEATURES[doc] = "The primary list of features to include in an image. Configure this variable in an image recipe."

</info>

5612

The primary list of features to include in an image.

5613

Typically, you configure this variable in an image recipe.

5614

Although you can use this variable from your

5615

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

5616

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,

5617

best practices dictate that you do not.

5618

<note>

5619

To enable extra features from outside the image recipe,

5620

use the

5621

<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

5627

Project, see the

5628

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

section.

</para>

<para>

For an example that shows how to customize your image by

5634

using this variable, see the

5635

"<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>"

5636

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

5642

<info>

5643

IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created."

</info>

5648

Specifies the formats the OpenEmbedded build system uses

5649

during the build when creating the root filesystem.

5650

For example, setting <filename>IMAGE_FSTYPES</filename>

5651

as follows causes the build system to create root

5652

filesystems using two formats: <filename>.ext3</filename>

5653

and <filename>.tar.bz2</filename>:

5654

5655

IMAGE_FSTYPES = "ext3 tar.bz2"

</literallayout>

</para>

<para>

For the complete list of supported image formats from which

you can choose, see

</para>

<note>

If you add "live" to <filename>IMAGE_FSTYPES</filename>

5667

inside an image recipe, be sure that you do so prior to the

5668

"inherit image" line of the recipe or the live image will

not build.

</note>

<note>

Due to the way this variable is processed, it is not

5674

possible to update its contents using

5675

<filename>_append</filename> or

5676

<filename>_prepend</filename>. To add one or more

5677

additional options to this variable the

5678

<filename>+=</filename> operator must be used.

</note>

</glossdef>

</glossentry>

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

5684

<info>

5685

IMAGE_INSTALL[doc] = "Specifies the packages to install into an image. Image recipes set IMAGE_INSTALL to specify the packages to install into an image through image.bbclass."

</info>

5690

Specifies the packages to install into an image.

5691

The <filename>IMAGE_INSTALL</filename> variable is a

5692

mechanism for an image recipe and you should use it

5693

with care to avoid ordering issues.

<note>

When working with an

image, do not use the <filename>IMAGE_INSTALL</filename>

5698

variable to specify packages for installation.

5699

Instead, use the

5700

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

5701

variable, which allows the initial RAM filesystem

5702

(initramfs) recipe to use a fixed set of packages and

5703

not be affected by <filename>IMAGE_INSTALL</filename>.

5704

For information on creating an initramfs, see the

5705

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

5706

section in the Yocto Project Development Manual.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</note>

</para>

<para>

Image recipes set <filename>IMAGE_INSTALL</filename>

5712

to specify the packages to install into an image through

5713

<filename>image.bbclass</filename>.

5714

Additionally, "helper" classes exist, such as

5715

<filename>core-image.bbclass</filename>, that can take

5716

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

5717

lists and turn these into auto-generated entries in

5718

<filename>IMAGE_INSTALL</filename> in addition to its

default contents.

</para>

<para>

Using <filename>IMAGE_INSTALL</filename> with the

5724

<filename>+=</filename> operator from the

5725

<filename>/conf/local.conf</filename> file or from within

5726

an image recipe is not recommended as it can cause ordering

5727

issues.

5728

Since <filename>core-image.bbclass</filename> sets

5729

<filename>IMAGE_INSTALL</filename> to a default value using

5730

the <filename>?=</filename> operator, using a

5731

<filename>+=</filename> operation against

5732

<filename>IMAGE_INSTALL</filename> will result in

5733

unexpected behavior when used in

5734

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

5735

Furthermore, the same operation from within an image

5736

recipe may or may not succeed depending on the specific

5737

situation.

5738

In both these cases, the behavior is contrary to how most

5739

users expect the <filename>+=</filename> operator to work.

</para>

<para>

When you use this variable, it is best to use it as follows:

5744

5745

IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"

5746

</literallayout>

5747

Be sure to include the space between the quotation character

5748

and the start of the package name or names.

</para>

</glossdef>

</glossentry>

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

5754

<info>

5755

IMAGE_LINGUAS[doc] = "Specifies the list of locales to install into the image during the root filesystem construction process."

</info>

5760

Specifies the list of locales to install into the image

5761

during the root filesystem construction process.

5762

The OpenEmbedded build system automatically splits locale

5763

files, which are used for localization, into separate

5764

packages.

5765

Setting the <filename>IMAGE_LINGUAS</filename> variable

5766

ensures that any locale packages that correspond to packages

5767

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

5777

Portuguese and German locale files that correspond to

5778

packages in the image are installed (i.e.

5779

<filename>*-locale-pt-br</filename>

5780

and <filename>*-locale-de-de</filename> as well as

5781

<filename>*-locale-pt</filename>

5782

and <filename>*-locale-de</filename>, since some software

5783

packages only provide locale files by language and not by

5784

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>

5796

<info>

5797

IMAGE_MANIFEST[doc] = "The manifest file for the image. This file lists all the installed packages that make up the image."

</info>

5802

The manifest file for the image.

5803

This file lists all the installed packages that make up

5804

the image.

5805

The file contains package information on a line-per-package

5806

basis as follows:

5807

5808

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

5816

5817

IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"

5818

</literallayout>

5819

The location is derived using the

and

variables.

You can find information on how the image

5825

is created in the

5826

"<link linkend='image-generation-dev-environment'>Image Generation</link>"

section.

</para>

</glossdef>

</glossentry>

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

5833

<info>

5834

IMAGE_NAME[doc] = "The name of the output image files minus the extension."

</info>

5839

The name of the output image files minus the extension.

5840

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>

5854

<info>

5855

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>

5860

Defines a multiplier that the build system applies to the initial image

5861

size for cases when the multiplier times the returned disk usage value

5862

for the image is greater than the sum of

5863

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

5864

and

5865

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

5866

The result of the multiplier applied to the initial image size creates

5867

free disk space in the image as overhead.

5868

By default, the build process uses a multiplier of 1.3 for this variable.

5869

This default value results in 30% free disk space added to the image when this

5870

method is used to determine the final generated image size.

5871

You should be aware that post install scripts and the package management

5872

system uses disk space inside this overhead area.

5873

Consequently, the multiplier does not produce an image with

5874

all the theoretical free disk space.

5875

See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>

5876

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

5881

and allows for basic post installs while still leaving a small amount of

5882

free disk space.

5883

If 30% free space is inadequate, you can increase the default value.

5884

For example, the following setting gives you 50% free space added to the image:

5885

5886

IMAGE_OVERHEAD_FACTOR = "1.5"

</literallayout>

</para>

<para>

Alternatively, you can ensure a specific amount of free disk space is added

5892

to the image by using the

5893

<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>

5900

<info>

5901

IMAGE_PKGTYPE[doc] = "Defines the package type (DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system."

</info>

5906

Defines the package type (DEB, RPM, IPK, or TAR) used

5907

by the OpenEmbedded build system.

5908

The variable is defined appropriately by the

or

class.

<note><title>Warning</title>

5916

The <filename>package_tar</filename> class is broken

5917

and is not supported.

5918

It is recommended that you do not use it.

</note>

</para>

<para>

The

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

5924

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

5925

and

5926

5927

classes use the <filename>IMAGE_PKGTYPE</filename> for

5928

packaging up images and SDKs.

</para>

<para>

You should not set the <filename>IMAGE_PKGTYPE</filename>

5933

manually.

5934

Rather, the variable is set indirectly through the

appropriate

class using the

variable.

The OpenEmbedded build system uses the first package type

5941

(e.g. DEB, RPM, or IPK) that appears with the variable

5942

<note>

5943

Files using the <filename>.tar</filename> format are

5944

never used as a substitute packaging format for DEB,

5945

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>

5952

<info>

5953

IMAGE_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the final image output files."

</info>

5958

Specifies a list of functions to call once the

5959

OpenEmbedded build system has created the final image

5960

output files.

5961

You can specify functions separated by semicolons:

5962

5963

IMAGE_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

5969

within the function, you can use

5970

<filename>${IMAGE_ROOTFS}</filename>, which points to

5971

the directory that becomes the root filesystem image.

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

5972

See the

5973

5974

variable for more information.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

5980

<info>

5981

IMAGE_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the final image output files."

</info>

5986

Specifies a list of functions to call before the

5987

OpenEmbedded build system has created the final image

5988

output files.

5989

You can specify functions separated by semicolons:

5990

5991

IMAGE_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

5997

within the function, you can use

5998

<filename>${IMAGE_ROOTFS}</filename>, which points to

5999

the directory that becomes the root filesystem image.

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

6000

See the

6001

6002

variable for more information.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

6008

<info>

6009

IMAGE_ROOTFS[doc] = "The location of the root filesystem while it is under construction (i.e. during do_rootfs)."

</info>

6014

The location of the root filesystem while it is under

6015

construction (i.e. during the

6016

6017

task).

6018

This variable is not configurable.

Do not change it.

</para>

</glossdef>

</glossentry>

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

6025

<info>

6026

IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes."

</info>

6031

Specifies the alignment for the output image file in

6032

Kbytes.

6033

If the size of the image is not a multiple of

6034

this value, then the size is rounded up to the nearest

6035

multiple of the value.

6036

The default value is "1".

6037

See

6038

6039

for additional information.

</para>

</glossdef>

</glossentry>

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

6045

<info>

6046

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>

6051

Defines additional free disk space created in the image in Kbytes.

6052

By default, this variable is set to "0".

6053

This free disk space is added to the image after the build system determines

6054

the image size as described in

6055

<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

6060

specific amount of free disk space is available on a device after an image

6061

is installed and running.

6062

For example, to be sure 5 Gbytes of free disk space is available, set the

6063

variable as follows:

6064

6065

IMAGE_ROOTFS_EXTRA_SPACE = "5242880"

</literallayout>

</para>

<para>

For example, the Yocto Project Build Appliance specifically requests 40 Gbytes

6071

of extra space with the line:

6072

6073

IMAGE_ROOTFS_EXTRA_SPACE = "41943040"

</literallayout>

</para>

</glossdef>

</glossentry>

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

6080

<info>

6081

IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image."

</info>

6086

Defines the size in Kbytes for the generated image.

6087

The OpenEmbedded build system determines the final size for the generated

6088

image using an algorithm that takes into account the initial disk space used

6089

for the generated image, a requested size for the image, and requested

6090

additional free disk space to be added to the image.

6091

Programatically, the build system determines the final size of the

6092

generated image as follows:

6093

6094

if (image-du * overhead) < rootfs-size:

6095

internal-rootfs-size = rootfs-size + xspace

6096

else:

6097

internal-rootfs-size = (image-du * overhead) + xspace

where:

image-du = Returned value of the du command on

6102

the image.

6103

6104

overhead = IMAGE_OVERHEAD_FACTOR

6105

6106

rootfs-size = IMAGE_ROOTFS_SIZE

6107

6108

internal-rootfs-size = Initial root filesystem

6109

size before any modifications.

6110

6111

xspace = IMAGE_ROOTFS_EXTRA_SPACE

</literallayout>

</para>

<para>

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

6117

and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>

6118

variables for related information.

6119

<!-- In the above example, <filename>overhead</filename> is defined by the

6120

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

6121

variable, <filename>xspace</filename> is defined by the

6122

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

6123

variable, and <filename>du</filename> is the results of the disk usage command

6124

on the initially generated image. -->

</para>

</glossdef>

</glossentry>

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

6130

<info>

6131

IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another."

</info>

6136

Specifies a dependency from one image type on another.

6137

Here is an example from the

class:

IMAGE_TYPEDEP_live = "ext3"

</literallayout>

</para>

<para>

In the previous example, the variable ensures that when

6147

"live" is listed with the

6148

6149

variable, the OpenEmbedded build system produces an

6150

<filename>ext3</filename> image first since one of the

6151

components of the live

6152

image is an <filename>ext3</filename>

6153

formatted partition containing the root

filesystem.

</para>

</glossdef>

</glossentry>

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

6160

<info>

6161

IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default."

</info>

6166

Specifies the complete list of supported image types

6167

by default:

6168

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6169

btrfs

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6170

cpio

6171

cpio.gz

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

6172

cpio.lz4

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6173

cpio.lzma

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

cpio.xz

cramfs

elf

ext2

ext2.bz2

ext2.gz

ext2.lzma

ext3

ext3.gz

ext4

ext4.gz

hdddirect

hddimg

iso

jffs2

jffs2.sum

multiubi

qcow2

squashfs

squashfs-lzo

squashfs-xz

tar

tar.bz2

tar.gz

tar.lz4

tar.xz

ubi

ubifs

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6202

vdi

6203

vmdk

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

wic

wic.bz2

wic.gz

wic.lzma

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</literallayout>

</para>

<para>

For more information about these types of images, see

6213

<filename>meta/classes/image_types*.bbclass</filename>

6214

in the

6215

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

</para>

</glossdef>

</glossentry>

<info>

INC_PR[doc] = "Helps define the recipe revision for recipes that share a common include file."

</info>

6227

Helps define the recipe revision for recipes that share

6228

a common <filename>include</filename> file.

6229

You can think of this variable as part of the recipe revision

6230

as set from within an include file.

</para>

<para>

Suppose, for example, you have a set of recipes that

6235

are used across several projects.

6236

And, within each of those recipes the revision

6237

(its <link linkend='var-PR'><filename>PR</filename></link>

6238

value) is set accordingly.

6239

In this case, when the revision of those recipes changes,

6240

the burden is on you to find all those recipes and

6241

be sure that they get changed to reflect the updated

6242

version of the recipe.

6243

In this scenario, it can get complicated when recipes

6244

that are used in many places and provide common functionality

6245

are upgraded to a new revision.

</para>

<para>

A more efficient way of dealing with this situation is

6250

to set the <filename>INC_PR</filename> variable inside

6251

the <filename>include</filename> files that the recipes

6252

share and then expand the <filename>INC_PR</filename>

6253

variable within the recipes to help

6254

define the recipe revision.

</para>

<para>

The following provides an example that shows how to use

6259

the <filename>INC_PR</filename> variable

6260

given a common <filename>include</filename> file that

6261

defines the variable.

6262

Once the variable is defined in the

6263

<filename>include</filename> file, you can use the

6264

variable to set the <filename>PR</filename> values in

6265

each recipe.

6266

You will notice that when you set a recipe's

6267

<filename>PR</filename> you can provide more granular

6268

revisioning by appending values to the

6269

<filename>INC_PR</filename> variable:

6270

6271

recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"

6272

recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"

6273

recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"

6274

recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"

6275

</literallayout>

6276

The first line of the example establishes the baseline

6277

revision to be used for all recipes that use the

6278

<filename>include</filename> file.

6279

The remaining lines in the example are from individual

6280

recipes and show how the <filename>PR</filename> value

is set.

</para>

</glossdef>

</glossentry>

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

6287

<info>

6288

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>

6293

Specifies a space-separated list of license names

6294

(as they would appear in

6295

6296

that should be excluded from the build.

6297

Recipes that provide no alternatives to listed incompatible

6298

licenses are not built.

6299

Packages that are individually licensed with the specified

6300

incompatible licenses will be deleted.

</para>

<note>

This functionality is only regularly tested using

6305

the following setting:

6306

6307

INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"

6308

</literallayout>

6309

Although you can use other settings, you might be required

6310

to remove dependencies on or provide alternatives to

6311

components that are required to produce a functional system

image.

</note>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

6317

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

6318

<info>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

6319

INHERIT[doc] = "Causes the named class or classes to be inherited globally."

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

</info>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

6324

Causes the named class or classes to be inherited globally.

6325

Anonymous functions in the class or classes

6326

are not executed for the

6327

base configuration and in each individual recipe.

6328

The OpenEmbedded build system ignores changes to

6329

<filename>INHERIT</filename> in individual recipes.

</para>

<para>

For more information on <filename>INHERIT</filename>, see

6334

the

6335

"<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>"

6336

section in the Yocto Project Bitbake User Manual.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

6342

<info>

6343

INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable."

</info>

6348

Lists classes that will be inherited at the

6349

distribution level.

6350

It is unlikely that you want to edit this variable.

</para>

<para>

The default value of the variable is set as follows in the

6355

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

6356

file:

6357

6358

INHERIT_DISTRO ?= "debian devshell sstate license"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6364

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

6365

<info>

6366

INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS."

</info>

6371

Prevents the default dependencies, namely the C compiler

6372

and standard C library (libc), from being added to

6373

6374

This variable is usually used within recipes that do not

6375

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>

6386

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6387

INHIBIT_PACKAGE_DEBUG_SPLIT[doc] = "If set to "1", prevents the OpenEmbedded build system from splitting out debug information during packaging"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

6392

Prevents the OpenEmbedded build system from splitting

6393

out debug information during packaging.

6394

By default, the build system splits out debugging

6395

information during the

6396

6397

task.

6398

For more information on how debug information is split out,

see the

variable.

</para>

<para>

To prevent the build system from splitting out

6406

debug information during packaging, set the

6407

<filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable

6408

as follows:

6409

6410

INHIBIT_PACKAGE_DEBUG_SPLIT = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

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

6417

<info>

6418

INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages."

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6423

If set to "1", causes the build to not strip binaries in

6424

resulting packages and prevents the

6425

<filename>-dbg</filename> package from containing the

source files.

</para>

<para>

By default, the OpenEmbedded build system strips

6431

binaries and puts the debugging symbols into

6432

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

6433

Consequently, you should not set

6434

<filename>INHIBIT_PACKAGE_STRIP</filename> when you plan

6435

to debug in general.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6440

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

6441

<info>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

6442

INITRAMFS_FSTYPES[doc] = "Defines the format for the output image of an initial RAM filesystem (initramfs), which is used during boot."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

6447

Defines the format for the output image of an initial

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

6448

RAM filesystem (initramfs), which is used during boot.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6449

Supported formats are the same as those supported by the

6450

6451

variable.

6452

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6453

6454

<para>

6455

The default value of this variable, which is set in the

6456

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

6457

file in the

6458

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,

6459

is "cpio.gz".

6460

The Linux kernel's initramfs mechanism, as opposed to the

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

6461

initial RAM filesystem

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6462

<ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>

6463

mechanism, expects an optionally compressed cpio

6464

archive.

6465

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

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

6470

<info>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

6471

INITRAMFS_IMAGE[doc] = "Specifies the PROVIDES name of an image recipe that is used to build an initial RAM filesystem (initramfs) image."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6476

Specifies the

6477

6478

name of an image recipe that is used to build an initial

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

6479

RAM filesystem (initramfs) image.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6480

An initramfs provides a temporary root filesystem used for

6481

early system initialization (e.g. loading of modules

6482

needed to locate and mount the "real" root filesystem).

6483

The specified recipe is added as a dependency of the root

6484

filesystem recipe (e.g.

6485

<filename>core-image-sato</filename>).

6486

See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename>

6487

recipe in the

6488

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

6489

for an example initramfs recipe.

6490

To select this recipe to provide the initramfs,

6491

set <filename>INITRAMFS_IMAGE</filename> to

6492

"core-image-minimal-initramfs".

6493

<note>

6494

The initramfs image recipe should set

to

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6499

</para>

6500

6501

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6502

You can also find more information by referencing the

6503

<filename>meta/poky/conf/local.conf.sample.extended</filename>

6504

configuration file in the

6505

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,

6506

the

6507

6508

class, and the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6509

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6510

class to see how to use the

6511

<filename>INITRAMFS_IMAGE</filename> variable.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6512

</para>

6513

6514

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6515

If <filename>INITRAMFS_IMAGE</filename> is empty, which is

6516

the default, then no initramfs is built.

6517

</para>

6518

6519

<para>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

6520

For more information, you can also see the

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6521

6522

variable, which allows the generated image to be bundled

6523

inside the kernel image.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

6524

Additionally, for information on creating an initramfs, see

6525

the

6526

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

6527

section in the Yocto Project Development Manual.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

6533

<info>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

6534

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)."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

6539

Controls whether or not the image recipe specified by

6540

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6541

is run through an extra pass

6542

(<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)

6543

during kernel compilation in order to build a single binary

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

6544

that contains both the kernel image and the initial RAM

6545

filesystem (initramfs) image.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6546

This makes use of the

kernel feature.

<note>

Using an extra compilation pass to bundle the initramfs

6551

avoids a circular dependency between the kernel recipe and

6552

the initramfs recipe should the initramfs include kernel

6553

modules.

6554

Should that be the case, the initramfs recipe depends on

6555

the kernel for the kernel modules, and the kernel depends

6556

on the initramfs recipe since the initramfs is bundled

6557

inside the kernel image.

6558

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

The combined binary is deposited into the

6563

<filename>tmp/deploy</filename> directory, which is part

6564

of the

6565

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

6566

</para>

6567

6568

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6569

Setting the variable to "1" in a configuration file causes the

6570

OpenEmbedded build system to generate a kernel image with the

6571

initramfs specified in

6572

6573

bundled within:

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6574

6575

INITRAMFS_IMAGE_BUNDLE = "1"

</literallayout>

By default, the

class sets this variable to a null string as follows:

6580

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6581

INITRAMFS_IMAGE_BUNDLE ?= ""

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</literallayout>

<note>

You must set the

<filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in

6586

a configuration file.

6587

You cannot set the variable in a recipe file.

6588

</note>

6589

See the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

6590

<ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6591

file for additional information.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

6592

Also, for information on creating an initramfs, see the

6593

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

6594

section in the Yocto Project Development Manual.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

6600

<info>

6601

INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)."

</info>

6606

Indicates list of filesystem images to concatenate and use

6607

as an initial RAM disk (<filename>initrd</filename>).

</para>

<para>

The <filename>INITRD</filename> variable is an optional

6612

variable used with the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

6613

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

class.

</para>

</glossdef>

</glossentry>

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

6620

<info>

6621

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>

6626

When building a "live" bootable image (i.e. when

6627

6628

contains "live"), <filename>INITRD_IMAGE</filename>

6629

specifies the image recipe that should be built

6630

to provide the initial RAM disk image.

6631

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>

6643

<info>

6644

INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d."

</info>

6649

The filename of the initialization script as installed to

6650

<filename>${sysconfdir}/init.d</filename>.

</para>

<para>

This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.

6655

The variable is mandatory.

</para>

</glossdef>

</glossentry>

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

6661

<info>

6662

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>

6667

A list of the packages that contain initscripts.

6668

If multiple packages are specified, you need to append the package name

6669

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>.

6674

The variable is optional and defaults to the

</para>

</glossdef>

</glossentry>

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

6681

<info>

6682

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>

6687

Specifies the options to pass to <filename>update-rc.d</filename>.

6688

Here is an example:

6689

6690

INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."

</literallayout>

</para>

<para>

In this example, the script has a runlevel of 99,

6696

starts the script in initlevels 2 and 5, and

6697

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

6710

to the <filename>update-rc.d</filename> command.

6711

For more information on valid parameters, please see the

6712

<filename>update-rc.d</filename> manual page at

6713

<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>

6719

<info>

6720

INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe."

</info>

6725

Specifies the QA checks to skip for a specific package

6726

within a recipe.

6727

For example, to skip the check for symbolic link

6728

<filename>.so</filename> files in the main package of a

6729

recipe, add the following to the recipe.

6730

The package name override must be used, which in this

6731

example is <filename>${PN}</filename>:

6732

6733

INSANE_SKIP_${PN} += "dev-so"

</literallayout>

</para>

<para>

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

6739

section for a list of the valid QA checks you can

6740

specify using this variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

6745

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

6746

<info>

6747

INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file."

</info>

6752

By default, the <filename>tzdata</filename> recipe packages

6753

an <filename>/etc/timezone</filename> file.

6754

Set the <filename>INSTALL_TIMEZONE_FILE</filename>

6755

variable to "0" at the configuration level to disable this

behavior.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6761

6762

<info>

6763

IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image."

</info>

6768

When the IPK backend is in use and package management

6769

is enabled on the target, you can use this variable to

6770

set up <filename>opkg</filename> in the target image

6771

to point to package feeds on a nominated server.

6772

Once the feed is established, you can perform

6773

installations or upgrades using the package manager

at runtime.

</para>

</glossdef>

</glossentry>

<!--

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

6781

6782

<para>

6783

An environment variable that defines the directory where

6784

post installation hooks are installed for the

6785

post install environment.

6786

This variable is fixed as follows:

6787

6788

${WORKDIR}/intercept_scripts

</literallayout>

</para>

<para>

After installation of a target's root filesystem,

6794

post installation scripts, which are essentially bash scripts,

6795

are all executed just a single time.

6796

Limiting execution of these scripts minimizes installation

6797

time that would be lengthened due to certain packages

6798

triggering redundant operations.

6799

For example, consider the installation of font packages

6800

as a common example.

6801

Without limiting the execution of post installation scripts,

6802

all font directories would be rescanned to create the

6803

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>

6822

<info>

6823

KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions."

</info>

6828

Defines the kernel architecture used when assembling

6829

the configuration.

6830

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

6843

<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.

</para>

</glossdef>

</glossentry>

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

6849

<info>

6850

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>

6855

A regular expression used by the build process to explicitly

6856

identify the kernel branch that is validated, patched,

6857

and configured during a build.

6858

You must set this variable to ensure the exact kernel

6859

branch you want is being used by the build process.

</para>

<para>

Values for this variable are set in the kernel's recipe

6864

file and the kernel's append file.

6865

For example, if you are using the Yocto Project kernel that

6866

is based on the Linux 3.14 kernel, the kernel recipe file

6867

is the

6868

<filename>meta/recipes-kernel/linux/linux-yocto_3.14.bb</filename>

6869

file.

6870

Following is an example for a kernel recipe file:

6871

6872

KBRANCH ?= "standard/base"

</literallayout>

</para>

<para>

This variable is also used from the kernel's append file

6878

to identify the kernel branch specific to a particular

6879

machine or target hardware.

6880

The kernel's append file is located in the BSP layer for

6881

a given machine.

6882

For example, the kernel append file for the Emenlow BSP is in the

6883

<filename>meta-intel</filename> Git repository and is named

6884

<filename>meta-emenlow/recipes-kernel/linux/linux-yocto_3.14.bbappend</filename>.

6885

Here are the related statements from the append file:

6886

6887

COMPATIBLE_MACHINE_emenlow-noemgd = "emenlow-noemgd"

6888

KMACHINE_emenlow-noemgd = "emenlow"

6889

KBRANCH_emenlow-noemgd = "standard/base"

6890

KERNEL_FEATURES_append_emenlow-noemgd = " features/drm-gma500/drm-gma500.scc"

6891

</literallayout>

6892

The <filename>KBRANCH</filename> statement identifies

6893

the kernel branch to use when building for the Emenlow

BSP.

</para>

</glossdef>

</glossentry>

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

6900

<info>

6901

KBUILD_DEFCONFIG[doc] = "Specifies an "in-tree" kernel configuration file for use during a kernel build."

</info>

6906

When used with the

6907

6908

class, specifies an "in-tree" kernel configuration file

6909

for use during a kernel build.

</para>

<para>

Typically, when using a <filename>defconfig</filename> to

6914

configure a kernel during a build, you place the

6915

file in your layer in the same manner as you would

6916

patch files and configuration fragment files (i.e.

6917

"out-of-tree").

6918

However, if you want to use a <filename>defconfig</filename>

6919

file that is part of the kernel tree (i.e. "in-tree"),

6920

you can use the

6921

<filename>KBUILD_DEFCONFIG</filename> variable to point

6922

to the <filename>defconfig</filename> file.

</para>

<para>

To use the variable, set it in the append file for your

6927

kernel recipe using the following form:

6928

6929

KBUILD_DEFCONFIG_<link linkend='var-KMACHINE'>KMACHINE</link> ?= <replaceable>defconfig_file</replaceable>

6930

</literallayout>

6931

Here is an example from a "raspberrypi2"

6932

<filename>KMACHINE</filename> build that uses a

6933

<filename>defconfig</filename> file named

6934

"bcm2709_defconfig":

6935

6936

KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"

6937

</literallayout>

6938

As an alternative, you can use the following within your

6939

append file:

6940

6941

KBUILD_DEFCONFIG_pn-linux-yocto ?= <replaceable>defconfig_file</replaceable>

6942

</literallayout>

6943

For more information on how to use the

6944

<filename>KBUILD_DEFCONFIG</filename> variable, see the

6945

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-an-in-tree-defconfig-file'>Using an "In-Tree" <filename>defconfig</filename> File</ulink>"

section.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

6951

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

6952

<info>

6953

KERNEL_ALT_IMAGETYPE[doc] = "Specifies an alternate kernel image type for creation."

</info>

6958

Specifies an alternate kernel image type for creation in

6959

addition to the kernel image type specified using the

variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6966

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

6967

<info>

6968

KERNEL_CLASSES[doc] = "A list of classes defining kernel image types that kernel class should inherit."

</info>

6973

A list of classes defining kernel image types that the

6974

6975

class should inherit.

6976

You typically append this variable to enable extended image

6977

types.

6978

An example is the "kernel-fitimage", which enables

6979

fitImage support and resides in

6980

<filename>meta/classes/kernel-fitimage.bbclass</filename>.

6981

You can register custom kernel image types with the

6982

<filename>kernel</filename> class using this variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

6987

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

6988

<info>

6989

KERNEL_DEVICETREE[doc] = "Specifies the name of the generated Linux kernel device tree (i.e. the <filename>.dtb</filename>) file."

</info>

6994

Specifies the name of the generated Linux kernel device tree

6995

(i.e. the <filename>.dtb</filename>) file.

6996

<note>

6997

Legacy support exists for specifying the full path

6998

to the device tree.

6999

However, providing just the <filename>.dtb</filename>

7000

file is preferred.

7001

</note>

7002

In order to use this variable, you must have the include

7003

files in your kernel recipe:

7004

7005

require recipes-kernel/linux/linux-dtb.inc

</literallayout>

or

require recipes-kernel/linux/linux-yocto.inc

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

7015

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

7016

<info>

7017

KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel."

</info>

7022

Specifies additional <filename>make</filename>

7023

command-line arguments the OpenEmbedded build system

7024

passes on when compiling the kernel.

</para>

</glossdef>

</glossentry>

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

7030

<info>

7031

KERNEL_FEATURES[doc] = "Includes additional metadata from the Yocto Project kernel Git repository. The metadata you add through this variable includes config fragments and features descriptions."

</info>

7036

Includes additional metadata from the Yocto Project kernel Git repository.

7037

In the OpenEmbedded build system, the default Board Support Packages (BSPs)

7038

<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>

7039

is provided through

7040

the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>

7041

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

7042

You can use the <filename>KERNEL_FEATURES</filename> variable to further

7043

add metadata for all BSPs.

</para>

<para>

The metadata you add through this variable includes config fragments and

7048

features descriptions,

7049

which usually includes patches as well as config fragments.

7050

You typically override the <filename>KERNEL_FEATURES</filename> variable

7051

for a specific machine.

7052

In this way, you can provide validated, but optional, sets of kernel

7053

configurations and features.

</para>

<para>

For example, the following adds <filename>netfilter</filename> to all

7058

the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>

7059

machine:

7060

7061

# Add netfilter to all linux-yocto kernels

7062

KERNEL_FEATURES="features/netfilter/netfilter.scc"

7063

7064

# Add sound support to the qemux86 machine

7065

KERNEL_FEATURES_append_qemux86=" cfg/sound.scc"

7066

</literallayout></para>

</glossdef>

</glossentry>

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

7071

<info>

7072

KERNEL_IMAGE_BASE_NAME[doc] = "The base name of the kernel image."

</info>

7077

The base name of the kernel image.

7078

This variable is set in the

as follows:

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

7082

KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</literallayout>

</para>

<para>

See the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

and

variables for additional information.

</para>

</glossdef>

</glossentry>

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

7100

<info>

7101

KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."

</info>

7106

Specifies the maximum size of the kernel image file in

7107

kilobytes.

7108

If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,

7109

the size of the kernel image file is checked against

7110

the set value during the

7111

7112

task.

7113

The task fails if the kernel image file is larger than

the setting.

</para>

<para>

<filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for

7119

target devices that have a limited amount of space in

7120

which the kernel image must be stored.

</para>

<para>

By default, this variable is not set, which means the

7125

size of the kernel image is not checked.

</para>

</glossdef>

</glossentry>

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

7131

<info>

7132

KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."

</info>

7137

The type of kernel to build for a device, usually set by the

7138

machine configuration files and defaults to "zImage".

7139

This variable is used

7140

when building the kernel and is passed to <filename>make</filename> as the target to

7141

build.

7142

</para>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

7143

7144

<para>

7145

If you want to build an alternate kernel image type, use the

7146

7147

variable.

7148

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

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

7153

<info>

7154

KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot"

</info>

7159

Lists kernel modules that need to be auto-loaded during

7160

boot.

7161

<note>

7162

This variable replaces the deprecated

variable.

</note>

</para>

<para>

You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename>

7170

variable anywhere that it can be

7171

recognized by the kernel recipe or by an out-of-tree kernel

7172

module recipe (e.g. a machine configuration file, a

7173

distribution configuration file, an append file for the

7174

recipe, or the recipe itself).

</para>

<para>

Specify it as follows:

7179

7180

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

7186

the OpenEmbedded build system to populate the

7187

<filename>/etc/modules-load.d/modname.conf</filename>

7188

file with the list of modules to be auto-loaded on boot.

7189

The modules appear one-per-line in the file.

7190

Here is an example of the most common use case:

7191

7192

KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>"

</literallayout>

</para>

<para>

For information on how to populate the

7198

<filename>modname.conf</filename> file with

7199

<filename>modprobe.d</filename> syntax lines, see the

variable.

</para>

</glossdef>

</glossentry>

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

7207

<info>

7208

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>

7213

Provides a list of modules for which the OpenEmbedded

7214

build system expects to find

7215

<filename>module_conf_</filename><replaceable>modname</replaceable>

7216

values that specify configuration for each of the modules.

7217

For information on how to provide those module

7218

configurations, see the

variable.

</para>

</glossdef>

</glossentry>

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

7226

<info>

7227

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>

7232

The location of the kernel sources.

7233

This variable is set to the value of the

within the

class.

For information on how this variable is used, see the

7239

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"

section.

</para>

<para>

To help maximize compatibility with out-of-tree drivers

7245

used to build modules, the OpenEmbedded build system also

7246

recognizes and uses the

7247

7248

variable, which is identical to the

7249

<filename>KERNEL_PATH</filename> variable.

7250

Both variables are common variables used by external

7251

Makefiles to point to the kernel source directory.

</para>

</glossdef>

</glossentry>

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

7257

<info>

7258

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>

7263

The location of the kernel sources.

7264

This variable is set to the value of the

within the

class.

For information on how this variable is used, see the

7270

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"

section.

</para>

<para>

To help maximize compatibility with out-of-tree drivers

7276

used to build modules, the OpenEmbedded build system also

7277

recognizes and uses the

7278

7279

variable, which is identical to the

7280

<filename>KERNEL_SRC</filename> variable.

7281

Both variables are common variables used by external

7282

Makefiles to point to the kernel source directory.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

7287

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

7288

<info>

7289

KERNEL_VERSION[doc] = "Specifies the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources."

</info>

7294

Specifies the version of the kernel as extracted from

7295

<filename>version.h</filename> or

7296

<filename>utsrelease.h</filename> within the kernel sources.

7297

Effects of setting this variable do not take affect until

7298

the kernel has been configured.

7299

Consequently, attempting to refer to this variable in

7300

contexts prior to configuration will not work.

</para>

</glossdef>

</glossentry>

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

7306

<info>

7307

KERNELDEPMODDEPEND[doc] = "Specifies whether or not to use the data referenced through the PKGDATA_DIR directory."

</info>

7312

Specifies whether the data referenced through

7313

7314

is needed or not.

7315

The <filename>KERNELDEPMODDEPEND</filename> does not

7316

control whether or not that data exists,

7317

but simply whether or not it is used.

7318

If you do not need to use the data, set the

7319

<filename>KERNELDEPMODDEPEND</filename> variable in your

7320

<filename>initramfs</filename> recipe.

7321

Setting the variable there when the data is not needed

7322

avoids a potential dependency loop.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

7327

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

7328

<info>

7329

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>

7334

Provides a short description of a configuration fragment.

7335

You use this variable in the <filename>.scc</filename>

7336

file that describes a configuration fragment file.

7337

Here is the variable used in a file named

7338

<filename>smp.scc</filename> to describe SMP being

7339

enabled:

7340

7341

define KFEATURE_DESCRIPTION "Enable SMP"

</literallayout>

</para>

</glossdef>

</glossentry>

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

7348

<info>

7349

KMACHINE[doc] = "The machine as known by the kernel."

</info>

7354

The machine as known by the kernel.

7355

Sometimes the machine name used by the kernel does not

7356

match the machine name used by the OpenEmbedded build

7357

system.

7358

For example, the machine name that the OpenEmbedded build

7359

system understands as

7360

<filename>core2-32-intel-common</filename> goes by a

7361

different name in the Linux Yocto kernel.

7362

The kernel understands that machine as

7363

<filename>intel-core2-32</filename>.

7364

For cases like these, the <filename>KMACHINE</filename>

7365

variable maps the kernel machine name to the OpenEmbedded

7366

build system machine name.

</para>

<para>

These mappings between different names occur in the

7371

Yocto Linux Kernel's <filename>meta</filename> branch.

7372

As an example take a look in the

7373

<filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename>

7374

file:

7375

7376

LINUX_VERSION_core2-32-intel-common = "3.19.0"

7377

COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"

7378

SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"

7379

SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"

7380

KMACHINE_core2-32-intel-common = "intel-core2-32"

7381

KBRANCH_core2-32-intel-common = "standard/base"

7382

KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"

7383

</literallayout>

7384

The <filename>KMACHINE</filename> statement says that

7385

the kernel understands the machine name as

7386

"intel-core2-32".

7387

However, the OpenEmbedded build system understands the

7388

machine as "core2-32-intel-common".

</para>

</glossdef>

</glossentry>

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

7395

<info>

7396

KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration."

</info>

7401

Defines the kernel type to be used in assembling the

7402

configuration.

7403

The linux-yocto recipes define "standard", "tiny",

7404

and "preempt-rt" kernel types.

7405

See the

7406

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"

7407

section in the Yocto Project Linux Kernel Development

7408

Manual for more information on kernel types.

</para>

<para>

You define the <filename>KTYPE</filename> variable in the

7413

<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.

7414

The value you use must match the value used for the

7415

7416

value used by the kernel recipe.

</para>

</glossdef>

</glossentry>

</glossdiv>

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

7425

<info>

7426

LABELS[doc] = "Provides a list of targets for automatic configuration."

</info>

7431

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>

7443

<info>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

7444

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."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

7449

Lists the layers, separated by spaces, on which this

7450

recipe depends.

7451

Optionally, you can specify a specific layer version for a

7452

dependency by adding it to the end of the layer name.

7453

Here is an example:

7454

7455

LAYERDEPENDS_mylayer = "anotherlayer (=3)"

7456

</literallayout>

7457

In this previous example, version 3 of "anotherlayer"

is compared against

</para>

<para>

An error is produced if any dependency is missing or

7464

the version numbers (if specified) do not match exactly.

7465

This variable is used in the

7466

<filename>conf/layer.conf</filename> file and must be

7467

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

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

7468

<filename>LAYERDEPENDS_mylayer</filename>).

</para>

</glossdef>

</glossentry>

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

7474

<info>

7475

LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer."

</info>

7480

When used inside the <filename>layer.conf</filename> configuration

7481

file, this variable provides the path of the current layer.

7482

This variable is not available outside of <filename>layer.conf</filename>

7483

and references are expanded immediately when parsing of the file completes.

</para>

</glossdef>

</glossentry>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

7488

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

7489

<info>

7490

LAYERRECOMMENDS[doc] = "Lists the layers, separated by spaces, recommended for use with this layer."

</info>

7495

Lists the layers, separated by spaces, recommended for

use with this layer.

</para>

<para>

Optionally, you can specify a specific layer version for a

7501

recommendation by adding the version to the end of the

layer name.

Here is an example:

LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"

7506

</literallayout>

7507

In this previous example, version 3 of "anotherlayer" is

7508

compared against

7509

<filename>LAYERVERSION_anotherlayer</filename>.

</para>

<para>

This variable is used in the

7514

<filename>conf/layer.conf</filename> file and must be

7515

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

7516

<filename>LAYERRECOMMENDS_mylayer</filename>).

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

7521

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

7522

<info>

7523

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>

7528

Optionally specifies the version of a layer as a single number.

7529

You can use this within

7530

7531

for another layer in order to depend on a specific version

7532

of the layer.

7533

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

7534

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

7535

<filename>LAYERVERSION_mylayer</filename>).

</para>

</glossdef>

</glossentry>

<info>

LD[doc] = "Minimal command and arguments to run the linker."

</info>

7547

The minimal command and arguments used to run the

linker.

</para>

</glossdef>

</glossentry>

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

7554

<info>

7555

LDFLAGS[doc] = "Specifies the flags to pass to the linker."

</info>

7560

Specifies the flags to pass to the linker.

7561

This variable is exported to an environment

7562

variable and thus made visible to the software being

7563

built during the compilation step.

</para>

<para>

Default initialization for <filename>LDFLAGS</filename>

7568

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

7577

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

7582

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

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

7590

<info>

7591

LEAD_SONAME[doc] = "Specifies the lead (or primary) compiled library file (.so) that the debian class applies its naming policy to given a recipe that packages multiple libraries."

</info>

7596

Specifies the lead (or primary) compiled library file

7597

(<filename>.so</filename>) that the

7598

7599

class applies its naming policy to given a recipe that

7600

packages multiple libraries.

</para>

<para>

This variable works in conjunction with the

7605

<filename>debian</filename> class.

</para>

</glossdef>

</glossentry>

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

7611

<info>

7612

LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code."

</info>

7617

Checksums of the license text in the recipe source code.

</para>

<para>

This variable tracks changes in license text of the source

7622

code files.

7623

If the license text is changed, it will trigger a build

7624

failure, which gives the developer an opportunity to review any

license change.

</para>

<para>

This variable must be defined for all recipes (unless

7630

7631

is set to "CLOSED").</para>

7632

<para>For more information, see the

7633

"<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>

7634

Tracking License Changes</link>" section.

</para>

</glossdef>

</glossentry>

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

7640

<info>

7641

LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &, '|', and parentheses can be used."

</info>

7646

The list of source licenses for the recipe.

7647

Follow these rules:

7648

7649

<listitem><para>Do not use spaces within individual

7650

license names.</para></listitem>

7651

<listitem><para>Separate license names using

7652

| (pipe) when there is a choice between licenses.

7653

</para></listitem>

7654

<listitem><para>Separate license names using

7655

& (ampersand) when multiple licenses exist

7656

that cover different parts of the source.

7657

</para></listitem>

7658

<listitem><para>You can use spaces between license

7659

names.</para></listitem>

7660

<listitem><para>For standard licenses, use the names

7661

of the files in

7662

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

7663

or the

7664

7665

flag names defined in

7666

<filename>meta/conf/licenses.conf</filename>.

</para></listitem>

</itemizedlist>

</para>

<para>

Here are some examples:

7673

7674

LICENSE = "LGPLv2.1 | GPLv3"

7675

LICENSE = "MPL-1 & LGPLv2.1"

7676

LICENSE = "GPLv2+"

7677

</literallayout>

7678

The first example is from the recipes for Qt, which the user

7679

may choose to distribute under either the LGPL version

7680

2.1 or GPL version 3.

7681

The second example is from Cairo where two licenses cover

7682

different parts of the source code.

7683

The final example is from <filename>sysstat</filename>,

7684

which presents a single license.

</para>

<para>

You can also specify licenses on a per-package basis to

7689

handle situations where components of the output have

7690

different licenses.

7691

For example, a piece of software whose code is

7692

licensed under GPLv2 but has accompanying documentation

7693

licensed under the GNU Free Documentation License 1.2 could

7694

be specified as follows:

7695

7696

LICENSE = "GFDL-1.2 & GPLv2"

7697

LICENSE_${PN} = "GPLv2"

7698

LICENSE_${PN}-doc = "GFDL-1.2"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

7704

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

7705

<info>

7706

LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."

</info>

7711

Setting <filename>LICENSE_CREATE_PACKAGE</filename>

7712

to "1" causes the OpenEmbedded build system to create

7713

an extra package (i.e.

7714

<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)

7715

for each recipe and to add those packages to the

</para>

<para>

The <filename>${PN}-lic</filename> package installs a

7721

directory in <filename>/usr/share/licenses</filename>

7722

named <filename>${PN}</filename>, which is the recipe's

7723

base name, and installs files in that directory that

7724

contain license and copyright information (i.e. copies of

7725

the appropriate license files from

7726

<filename>meta/common-licenses</filename> that match the

7727

licenses specified in the

7728

7729

variable of the recipe metadata and copies of files marked

7730

in

7731

7732

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>"

7742

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

7747

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

7748

<info>

7749

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>

7754

Specifies additional flags for a recipe you must

7755

whitelist through

7756

7757

in order to allow the recipe to be built.

7758

When providing multiple flags, separate them with

spaces.

</para>

<para>

This value is independent of

7764

7765

and is typically used to mark recipes that might

7766

require additional licenses in order to be used in a

7767

commercial product.

7768

For more information, see the

7769

"<link linkend='enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</link>"

section.

</para>

</glossdef>

</glossentry>

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

7776

<info>

7777

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>

7782

Lists license flags that when specified in

7783

7784

within a recipe should not prevent that recipe from being

7785

built.

7786

This practice is otherwise known as "whitelisting"

7787

license flags.

7788

For more information, see the

section.

</para>

</glossdef>

</glossentry>

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

7796

<info>

7797

LICENSE_PATH[doc] = "Path to additional licenses used during the build."

</info>

7802

Path to additional licenses used during the build.

7803

By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>

7804

to define the directory that holds common license text used during the build.

7805

The <filename>LICENSE_PATH</filename> variable allows you to extend that

7806

location to other areas that have additional licenses:

7807

7808

LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>"

</literallayout>

</para>

</glossdef>

</glossentry>

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

7815

<info>

7816

LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration."

</info>

7821

Defines the kernel type to be used in assembling the

7822

configuration.

7823

The linux-yocto recipes define "standard", "tiny", and

7824

"preempt-rt" kernel types.

7825

See the

7826

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"

7827

section in the Yocto Project Linux Kernel Development

7828

Manual for more information on kernel types.

</para>

<para>

If you do not specify a

7833

<filename>LINUX_KERNEL_TYPE</filename>, it defaults to

"standard".

Together with

the <filename>LINUX_KERNEL_TYPE</filename> variable

7838

defines the search

7839

arguments used by the kernel tools to find the appropriate

7840

description within the kernel

7841

<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>

7842

with which to build out the sources and configuration.

</para>

</glossdef>

</glossentry>

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

7848

<info>

7849

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>

7854

The Linux version from <filename>kernel.org</filename>

7855

on which the Linux kernel image being built using the

7856

OpenEmbedded build system is based.

7857

You define this variable in the kernel recipe.

7858

For example, the <filename>linux-yocto-3.4.bb</filename>

7859

kernel recipe found in

7860

<filename>meta/recipes-kernel/linux</filename>

7861

defines the variables as follows:

7862

7863

LINUX_VERSION ?= "3.4.24"

</literallayout>

</para>

<para>

The <filename>LINUX_VERSION</filename> variable is used to

7869

define <link linkend='var-PV'><filename>PV</filename></link>

7870

for the recipe:

7871

7872

PV = "${LINUX_VERSION}+git${SRCPV}"

</literallayout>

</para>

</glossdef>

</glossentry>

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

7879

<info>

7880

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>

7885

A string extension compiled into the version

7886

string of the Linux kernel built with the OpenEmbedded

7887

build system.

7888

You define this variable in the kernel recipe.

7889

For example, the linux-yocto kernel recipes all define

7890

the variable as follows:

7891

7892

LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"

</literallayout>

</para>

<para>

Defining this variable essentially sets the

7898

Linux kernel configuration item

7899

<filename>CONFIG_LOCALVERSION</filename>, which is visible

7900

through the <filename>uname</filename> command.

7901

Here is an example that shows the extension assuming it

7902

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>

7918

Specifies the directory to which the OpenEmbedded build

7919

system writes overall log files.

7920

The default directory is <filename>${TMPDIR}/log</filename>.

</para>

<para>

For the directory containing logs specific to each task,

7925

see the <link linkend='var-T'><filename>T</filename></link>

variable.

</para>

</glossdef>

</glossentry>

</glossdiv>

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

7936

<info>

7937

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>

7942

Specifies the target device for which the image is built.

7943

You define <filename>MACHINE</filename> in the

7944

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

7945

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

7946

By default, <filename>MACHINE</filename> is set to

7947

"qemux86", which is an x86-based architecture machine to

7948

be emulated using QEMU:

MACHINE ?= "qemux86"

</literallayout>

</para>

<para>

The variable corresponds to a machine configuration file of the

7956

same name, through which machine-specific configurations are set.

7957

Thus, when <filename>MACHINE</filename> is set to "qemux86" there

7958

exists the corresponding <filename>qemux86.conf</filename> machine

7959

configuration file, which can be found in the

7960

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

7961

in <filename>meta/conf/machine</filename>.

</para>

<para>

The list of machines supported by the Yocto Project as

7966

shipped include the following:

7967

7968

MACHINE ?= "qemuarm"

7969

MACHINE ?= "qemuarm64"

7970

MACHINE ?= "qemumips"

7971

MACHINE ?= "qemumips64"

7972

MACHINE ?= "qemuppc"

7973

MACHINE ?= "qemux86"

7974

MACHINE ?= "qemux86-64"

7975

MACHINE ?= "genericx86"

7976

MACHINE ?= "genericx86-64"

7977

MACHINE ?= "beaglebone"

7978

MACHINE ?= "mpc8315e-rdb"

7979

MACHINE ?= "edgerouter"

7980

</literallayout>

7981

The last five are Yocto Project reference hardware boards, which

7982

are provided in the <filename>meta-yocto-bsp</filename> layer.

7983

<note>Adding additional Board Support Package (BSP) layers

7984

to your configuration adds new possible settings for

7985

<filename>MACHINE</filename>.

</note>

</para>

</glossdef>

</glossentry>

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

7992

<info>

7993

MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH."

</info>

7998

Specifies the name of the machine-specific architecture.

7999

This variable is set automatically from

or

You should not hand-edit the

8004

<filename>MACHINE_ARCH</filename> variable.

</para>

</glossdef>

</glossentry>

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

8010

<info>

8011

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>

8016

A list of required machine-specific packages to install as part of

8017

the image being built.

8018

The build process depends on these packages being present.

8019

Furthermore, because this is a "machine essential" variable, the list of

8020

packages are essential for the machine to boot.

8021

The impact of this variable affects images based on

8022

<filename>packagegroup-core-boot</filename>,

8023

including the <filename>core-image-minimal</filename> image.

</para>

<para>

This variable is similar to the

8028

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

8029

variable with the exception that the image being built has a build

8030

dependency on the variable's list of packages.

8031

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

8036

<filename>example-init</filename> to be run during boot to initialize the hardware.

8037

In this case, you would use the following in the machine's

8038

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

8039

8040

MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"

</literallayout>

</para>

</glossdef>

</glossentry>

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

8047

<info>

8048

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>

8053

A list of recommended machine-specific packages to install as part of

8054

the image being built.

8055

The build process does not depend on these packages being present.

8056

However, because this is a "machine essential" variable, the list of

8057

packages are essential for the machine to boot.

8058

The impact of this variable affects images based on

8059

<filename>packagegroup-core-boot</filename>,

8060

including the <filename>core-image-minimal</filename> image.

</para>

<para>

This variable is similar to the

8065

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

8066

variable with the exception that the image being built does not have a build

8067

dependency on the variable's list of packages.

8068

In other words, the image will still build if a package in this list is not found.

8069

Typically, this variable is used to handle essential kernel modules, whose

8070

functionality may be selected to be built into the kernel rather than as a module,

8071

in which case a package will not be produced.

</para>

<para>

Consider an example where you have a custom kernel where a specific touchscreen

8076

driver is required for the machine to be usable.

8077

However, the driver can be built as a module or

8078

into the kernel depending on the kernel configuration.

8079

If the driver is built as a module, you want it to be installed.

8080

But, when the driver is built into the kernel, you still want the

8081

build to succeed.

8082

This variable sets up a "recommends" relationship so that in the latter case,

8083

the build will not fail due to the missing package.

8084

To accomplish this, assuming the package for the module was called

8085

<filename>kernel-module-ab123</filename>, you would use the

8086

following in the machine's <filename>.conf</filename> configuration

8087

file:

8088

8089

MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"

8090

</literallayout>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

8091

<note>

8092

In this example, the

8093

<filename>kernel-module-ab123</filename> recipe

8094

needs to explicitly set its

8095

8096

variable to ensure that BitBake does not use the

8097

kernel recipe's

8098

8099

variable to satisfy the dependency.

8100

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

Some examples of these machine essentials are flash, screen, keyboard, mouse,

8105

or touchscreen drivers (depending on the machine).

</para>

</glossdef>

</glossentry>

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

8111

<info>

8112

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>

8117

A list of machine-specific packages to install as part of the

8118

image being built that are not essential for the machine to boot.

8119

However, the build process for more fully-featured images

8120

depends on the packages being present.

</para>

<para>

This variable affects all images based on

8125

<filename>packagegroup-base</filename>, which does not include the

8126

<filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>

images.

</para>

<para>

The variable is similar to the

8132

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

8133

variable with the exception that the image being built has a build

8134

dependency on the variable's list of packages.

8135

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

8140

essential for the machine to boot the image.

8141

However, if you are building a more fully-featured image, you want to enable

8142

the WiFi.

8143

The package containing the firmware for the WiFi hardware is always

8144

expected to exist, so it is acceptable for the build process to depend upon

8145

finding the package.

8146

In this case, assuming the package for the firmware was called

8147

<filename>wifidriver-firmware</filename>, you would use the following in the

8148

<filename>.conf</filename> file for the machine:

8149

8150

MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"

</literallayout>

</para>

</glossdef>

</glossentry>

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

8157

<info>

8158

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>

8163

A list of machine-specific packages to install as part of the

8164

image being built that are not essential for booting the machine.

8165

The image being built has no build dependency on this list of packages.

</para>

<para>

This variable affects only images based on

8170

<filename>packagegroup-base</filename>, which does not include the

8171

<filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>

images.

</para>

<para>

This variable is similar to the

8177

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

8178

variable with the exception that the image being built does not have a build

8179

dependency on the variable's list of packages.

8180

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

8185

For the machine to boot the image.

8186

However, if you are building a more fully-featured image, you want to enable

8187

WiFi.

8188

In this case, the package containing the WiFi kernel module will not be produced

8189

if the WiFi driver is built into the kernel, in which case you still want the

8190

build to succeed instead of failing as a result of the package not being found.

8191

To accomplish this, assuming the package for the module was called

8192

<filename>kernel-module-examplewifi</filename>, you would use the

8193

following in the <filename>.conf</filename> file for the machine:

8194

8195

MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"

</literallayout>

</para>

</glossdef>

</glossentry>

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

8202

<info>

8203

MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports."

</info>

8208

Specifies the list of hardware features the

8209

8210

of supporting.

8211

For related information on enabling features, see the

and

variables.

</para>

<para>

For a list of hardware features supported by the Yocto

8221

Project as shipped, see the

8222

"<link linkend='ref-features-machine'>Machine Features</link>"

section.

</para>

</glossdef>

</glossentry>

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

8229

<info>

8230

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>

8235

Features to be added to

8236

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

8237

if not also present in

8238

<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.

8243

It is not intended to be user-configurable.

8244

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

8245

being backfilled for all machine configurations.

8246

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>

8253

<info>

8254

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>

8259

Features from

8260

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

8261

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

8262

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

8263

during the build.

8264

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

more information.

</para>

</glossdef>

</glossentry>

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

8271

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8272

MACHINEOVERRIDES[doc] = "A colon-separated list of overrides that apply to the current machine."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8277

A colon-separated list of overrides that apply to the

8278

current machine.

8279

By default, this list includes the value of

8280

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8281

</para>

8282

8283

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8284

You can extend <filename>MACHINEOVERRIDES</filename>

8285

to add extra overrides that should apply to a machine.

8286

For example, all machines emulated in QEMU (e.g.

8287

<filename>qemuarm</filename>, <filename>qemux86</filename>,

8288

and so forth) include a file named

8289

<filename>meta/conf/machine/include/qemu.inc</filename>

8290

that prepends the following override to

8291

<filename>MACHINEOVERRIDES</filename>:

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8292

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8293

MACHINEOVERRIDES =. "qemuall:"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8294

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8295

This override allows variables to be overriden for all

8296

machines emulated in QEMU, like in the following example

8297

from the <filename>connman-conf</filename> recipe:

8298

8299

SRC_URI_append_qemuall = "file://wired.config \

file://wired-setup \

"

</literallayout>

The underlying mechanism behind

8304

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

8305

included in the default value of

8306

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

8312

<info>

8313

MAINTAINER[doc] = "The email address of the distribution maintainer."

</info>

8318

The email address of the distribution maintainer.

</para>

</glossdef>

</glossentry>

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

8324

<info>

8325

MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."

</info>

8330

Specifies additional paths from which the OpenEmbedded

8331

build system gets source code.

8332

When the build system searches for source code, it first

8333

tries the local download directory.

8334

If that location fails, the build system tries locations

8335

defined by

8336

8337

the upstream source, and then locations specified by

8338

<filename>MIRRORS</filename> in that order.

</para>

<para>

Assuming your distribution

8343

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

8344

is "poky", the default value for

8345

<filename>MIRRORS</filename> is defined in the

8346

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

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

8347

<filename>meta-poky</filename> Git repository.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

8353

<info>

8354

MLPREFIX[doc] = "Specifies a prefix has been added to PN to create a special version of a recipe or package, such as a Multilib version."

</info>

8359

Specifies a prefix has been added to

8360

8361

of a recipe or package, such as a Multilib version.

8362

The variable is used in places where the prefix needs to be

8363

added to or removed from a the name (e.g. the

8364

8365

<filename>MLPREFIX</filename> gets set when a prefix has been

8366

added to <filename>PN</filename>.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8367

<note>

8368

The "ML" in <filename>MLPREFIX</filename> stands for

8369

"MultiLib".

8370

This representation is historical and comes from

8371

a time when <filename>nativesdk</filename> was a suffix

8372

rather than a prefix on the recipe name.

8373

When <filename>nativesdk</filename> was turned into a

8374

prefix, it made sense to set

8375

<filename>MLPREFIX</filename> for it as well.

</note>

</para>

<para>

To help understand when <filename>MLPREFIX</filename>

8381

might be needed, consider when

8382

8383

is used to provide a <filename>nativesdk</filename> version

8384

of a recipe in addition to the target version.

8385

If that recipe declares build-time dependencies on tasks in

8386

other recipes by using

8387

8388

then a dependency on "foo" will automatically get rewritten

8389

to a dependency on "nativesdk-foo".

8390

However, dependencies like the following will not get

8391

rewritten automatically:

8392

8393

do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo"

8394

</literallayout>

8395

If you want such a dependency to also get transformed,

8396

you can do the following:

8397

8398

do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo"

8399

</literallayout>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

8405

<info>

8406

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>

8411

This variable has been replaced by the

8412

<filename>KERNEL_MODULE_AUTOLOAD</filename> variable.

8413

You should replace all occurrences of

8414

<filename>module_autoload</filename> with additions to

8415

<filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:

8416

8417

module_autoload_rfcomm = "rfcomm"

</literallayout>

</para>

<para>

should now be replaced with:

8423

8424

KERNEL_MODULE_AUTOLOAD += "rfcomm"

</literallayout>

See the

variable for more information.

</para>

</glossdef>

</glossentry>

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

8434

<info>

8435

module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file."

</info>

8440

Specifies

8441

<ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>

8442

syntax lines for inclusion in the

8443

<filename>/etc/modprobe.d/modname.conf</filename> file.

</para>

<para>

You can use this variable anywhere that it can be

8448

recognized by the kernel recipe or out-of-tree kernel

8449

module recipe (e.g. a machine configuration file, a

8450

distribution configuration file, an append file for the

8451

recipe, or the recipe itself).

8452

If you use this variable, you must also be sure to list

8453

the module name in the

variable.

</para>

<para>

Here is the general syntax:

8460

8461

module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>"

8462

</literallayout>

8463

You must use the kernel module name override.

</para>

<para>

Run <filename>man modprobe.d</filename> in the shell to

8468

find out more information on the exact syntax

8469

you want to provide with <filename>module_conf</filename>.

</para>

<para>

Including <filename>module_conf</filename> causes the

8474

OpenEmbedded build system to populate the

8475

<filename>/etc/modprobe.d/modname.conf</filename>

8476

file with <filename>modprobe.d</filename> syntax lines.

8477

Here is an example that adds the options

8478

8479

to a module named <filename>mymodule</filename>:

8480

8481

module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"

</literallayout>

</para>

<para>

For information on how to specify kernel modules to

8487

auto-load on boot, see the

variable.

</para>

</glossdef>

</glossentry>

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

8495

<info>

8496

MODULE_IMAGE_BASE_NAME[doc] = "The base name of the kernel modules tarball."

</info>

8501

The base name of the kernel modules tarball.

8502

This variable is set in the

as follows:

MODULE_IMAGE_BASE_NAME ?= "modules-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"

</literallayout>

</para>

<para>

See the

and

variables for additional information.

</para>

</glossdef>

</glossentry>

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

8524

<info>

8525

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>

8530

Controls creation of the <filename>modules-*.tgz</filename>

8531

file.

8532

Set this variable to "0" to disable creation of this

8533

file, which contains all of the kernel modules resulting

from a kernel build.

</para>

</glossdef>

</glossentry>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

8539

<!--

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8540

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

8541

<info>

8542

MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories."

</info>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

8546

-->

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8547

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

8548

<!--

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8549

Serves the same purpose as

8550

8551

but for the "HOST" system, in situations that involve a

8552

"HOST" and a "TARGET" system.

8553

See the

8554

8555

variable for more information.

</para>

<para>

The default value of this variable is:

8560

8561

${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS}

</literallayout>

</para>

</glossdef>

</glossentry>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

8566

-->

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8567

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8568

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

8569

<info>

8570

MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories."

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8575

Uniquely identifies the type of the target system for

8576

which packages are being built.

8577

This variable allows output for different types of target

8578

systems to be put into different subdirectories of the same

output directory.

</para>

<para>

The default value of this variable is:

8584

8585

${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.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8596

See the

8597

8598

variable for more information.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

</glossdiv>

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

8608

<info>

8609

NATIVELSBSTRING[doc] = "A string identifying the host distribution."

</info>

8614

A string identifying the host distribution.

8615

Strings consist of the host distributor ID

8616

followed by the release, as reported by the

8617

<filename>lsb_release</filename> tool

8618

or as read from <filename>/etc/lsb-release</filename>.

8619

For example, when running a build on Ubuntu 12.10, the value

8620

is "Ubuntu-12.10".

8621

If this information is unable to be determined, the value

8622

resolves to "Unknown".

</para>

<para>

This variable is used by default to isolate native shared

8627

state packages for different distributions (e.g. to avoid

8628

problems with <filename>glibc</filename> version

8629

incompatibilities).

8630

Additionally, the variable is checked against

8631

8632

if that variable is set.

</para>

</glossdef>

</glossentry>

<info>

NM[doc] = "Minimal command and arguments to run 'nm'."

</info>

8644

The minimal command and arguments to run

8645

<filename>nm</filename>.

</para>

</glossdef>

</glossentry>

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

8651

<info>

8652

NO_RECOMMENDATIONS[doc] = "When set to '1', no recommended packages will be installed. Realize that 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>

8657

Prevents installation of all "recommended-only" packages.

8658

Recommended-only packages are packages installed only

through the

variable).

Setting the <filename>NO_RECOMMENDATIONS</filename> variable

8663

to "1" turns this feature on:

8664

8665

NO_RECOMMENDATIONS = "1"

</literallayout>

</para>

<para>

You can set this variable globally in your

8671

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

8672

a specific image recipe by using the recipe name override:

8673

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

8674

NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "1"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</literallayout>

</para>

<para>

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

8680

packages using this variable and some other packages are

8681

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

8682

8683

variable), the OpenEmbedded build system ignores your

8684

request and will install the packages to avoid dependency

8685

errors.

8686

<note>

8687

Some recommended packages might be required for certain

8688

system functionality, such as kernel modules.

8689

It is up to you to add packages with the

variable.

</note>

</para>

<para>

Support for this variable exists only when using the

8697

IPK and RPM packaging backend.

8698

Support does not exist for DEB.

</para>

<para>

See the

and the

variables for related information.

</para>

</glossdef>

</glossentry>

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

8712

<info>

8713

NOHDD[doc] = "Causes the OpenEmbedded build system to skip building the .hddimg image."

</info>

8718

Causes the OpenEmbedded build system to skip building the

8719

<filename>.hddimg</filename> image.

8720

The <filename>NOHDD</filename> variable is used with the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

8721

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8722

class.

8723

Set the variable to "1" to prevent the

8724

<filename>.hddimg</filename> image from being built.

</para>

</glossdef>

</glossentry>

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

8730

<info>

8731

NOISO[doc] = "Causes the OpenEmbedded build system to skip building the ISO image."

</info>

8736

Causes the OpenEmbedded build system to skip building the

8737

ISO image.

8738

The <filename>NOISO</filename> variable is used with the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

8739

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8740

class.

8741

Set the variable to "1" to prevent the ISO image from

8742

being built.

8743

To enable building an ISO image, set the variable to "0".

</para>

</glossdef>

</glossentry>

</glossdiv>

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

8753

<info>

8754

OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'."

</info>

8759

The minimal command and arguments to run

8760

<filename>objcopy</filename>.

</para>

</glossdef>

</glossentry>

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

8766

<info>

8767

OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'."

</info>

8772

The minimal command and arguments to run

8773

<filename>objdump</filename>.

</para>

</glossdef>

</glossentry>

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

8779

<info>

8780

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.

8789

The sed command alters any paths in configuration scripts

8790

that have been set up during compilation.

8791

Inheriting this class results in all paths in these scripts

8792

being changed to point into the

8793

<filename>sysroots/</filename> directory so that all builds

8794

that use the script will use the correct directories

8795

for the cross compiling layout.

</para>

<para>

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

8800

in the

8801

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

8802

for details on how this class applies these additional

8803

sed command arguments.

8804

For general information on the

8805

<filename>binconfig.bbclass</filename> class, see the

8806

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

section.

</para>

</glossdef>

</glossentry>

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

8813

<info>

8814

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>

8819

An internal variable used to tell the OpenEmbedded build

8820

system what Python modules to import for every Python

8821

function run by the system.

</para>

<note>

Do not set this variable.

8826

It is for internal use only.

</note>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

8831

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

8832

<info>

8833

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>

8838

The name of the build environment setup script for the

8839

purposes of setting up the environment within the

8840

extensible SDK.

8841

The default value is "oe-init-build-env".

</para>

<para>

If you use a custom script to set up your build

8846

environment, set the

8847

<filename>OE_INIT_ENV_SCRIPT</filename> variable to its

name.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8853

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

8854

<info>

8855

OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system."

</info>

8860

Controls how the OpenEmbedded build system spawns

8861

interactive terminals on the host development system

8862

(e.g. using the BitBake command with the

8863

<filename>-c devshell</filename> command-line option).

8864

For more information, see the

8865

"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section

8866

in the Yocto Project Development Manual.

</para>

<para>

You can use the following values for the

8871

<filename>OE_TERMINAL</filename> variable:

auto

gnome

xfce

rxvt

screen

konsole

none

</literallayout>

</para>

</glossdef>

</glossentry>

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

8886

<info>

8887

OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced."

</info>

8892

The directory from which the top-level build environment

8893

setup script is sourced.

8894

The Yocto Project makes two top-level build environment

8895

setup scripts available:

and

When you run one of these scripts, the

8900

<filename>OEROOT</filename> variable resolves to the

8901

directory that contains the script.

</para>

<para>

For additional information on how this variable is used,

8906

see the initialization scripts.

</para>

</glossdef>

</glossentry>

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

8912

<info>

8913

OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support."

</info>

8918

Declares the oldest version of the Linux kernel that the

8919

produced binaries must support.

8920

This variable is passed into the build of the Embedded

8921

GNU C Library (<filename>glibc</filename>).

</para>

<para>

The default for this variable comes from the

8926

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

8927

file.

8928

You can override this default by setting the variable

8929

in a custom distribution configuration file.

</para>

</glossdef>

</glossentry>

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

8935

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8936

OVERRIDES[doc] = "A colon-separated list of overrides that currently apply."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8941

A colon-separated list of overrides that currently apply.

8942

Overrides are a BitBake mechanism that allows variables to

8943

be selectively overridden at the end of parsing.

8944

The set of overrides in <filename>OVERRIDES</filename>

8945

represents the "state" during building, which includes

8946

the current recipe being built, the machine for which

8947

it is being built, and so forth.

</para>

<para>

As an example, if the string "an-override" appears as an

8952

element in the colon-separated list in

8953

<filename>OVERRIDES</filename>, then the following

8954

assignment will override <filename>FOO</filename> with the

8955

value "overridden" at the end of parsing:

8956

8957

FOO_an-override = "overridden"

8958

</literallayout>

8959

See the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8960

"<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8961

section in the BitBake User Manual for more information on

8962

the overrides mechanism.

</para>

<para>

The default value of <filename>OVERRIDES</filename>

8967

includes the values of the

and

variables.

Another important override included by default is

8974

<filename>pn-${PN}</filename>.

8975

This override allows variables to be set for a single

8976

recipe within configuration (<filename>.conf</filename>)

files.

Here is an example:

FOO_pn-myrecipe = "myrecipe-specific value"

8981

</literallayout>

8982

8983

An easy way to see what overrides apply is to search for

8984

<filename>OVERRIDES</filename> in the output of the

8985

<filename>bitbake -e</filename> command.

8986

See the

8987

"<link linkend='usingpoky-debugging-viewing-variable-values'>Viewing Variable Values</link>"

8988

section for more information.

8989

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

</glossdiv>

<info>

P[doc] = "The recipe name and version. P is comprised of ${PN}-${PV}."

</info>

9004

The recipe name and version.

9005

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

${PN}-${PV}

</literallayout>

</para>

</glossdef>

</glossentry>

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

9014

<info>

9015

PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."

</info>

9020

The architecture of the resulting package or packages.

</para>

<para>

By default, the value of this variable is set to

9025

9026

when building for the target,

9027

<filename>BUILD_ARCH</filename> when building for the

9028

build host and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building

9029

for the SDK.

9030

However, if your recipe's output packages are built

9031

specific to the target machine rather than general for

9032

the architecture of the machine, you should set

9033

<filename>PACKAGE_ARCH</filename> to the value of

9034

9035

in the recipe as follows:

9036

9037

PACKAGE_ARCH = "${MACHINE_ARCH}"

</literallayout>

</para>

</glossdef>

</glossentry>

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

9044

<info>

9045

PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority."

</info>

9050

Specifies a list of architectures compatible with

9051

the target machine.

9052

This variable is set automatically and should not

9053

normally be hand-edited.

9054

Entries are separated using spaces and listed in order

9055

of priority.

9056

The default value for

9057

<filename>PACKAGE_ARCHS</filename> is "all any noarch

9058

${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".

</para>

</glossdef>

</glossentry>

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

9064

<info>

9065

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>

9070

Enables easily adding packages to

9071

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

9072

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

9073

so that those added packages can pick up files that would normally be

9074

included in the default package.

</para>

</glossdef>

</glossentry>

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

9080

<info>

9081

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>

9086

This variable, which is set in the

9087

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

9088

the <filename>conf</filename> folder of the

9089

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,

9090

specifies the package manager the OpenEmbedded build system

9091

uses when packaging data.

</para>

<para>

You can provide one or more of the following arguments for

9096

the variable:

9097

9098

PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"

9099

</literallayout>

9100

<note><title>Warning</title>

9101

While it is a legal option, the

9102

<filename>package_tar</filename> class is broken

9103

and is not supported.

9104

It is recommended that you do not use it.

9105

</note>

9106

The build system uses only the first argument in the list

9107

as the package manager when creating your image or SDK.

9108

However, packages will be created using any additional

9109

packaging classes you specify.

9110

For example, if you use the following in your

9111

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

9112

9113

PACKAGE_CLASSES ?= "package_ipk"

9114

</literallayout>

9115

The OpenEmbedded build system uses the IPK package manager

9116

to create your image or SDK.

</para>

<para>

For information on packaging and build performance effects

9121

as a result of the package manager in use, see the

9122

"<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>

9129

<info>

9130

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>

9135

Determines how to split up the binary and debug information

9136

when creating <filename>*-dbg</filename> packages to be

9137

used with the GNU Project Debugger (GDB).

</para>

<para>

With the

<filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,

9143

you can control where debug information, which can include

9144

or exclude source files, is stored:

9145

9146

9147

".debug": Debug symbol files are placed next

9148

to the binary in a <filename>.debug</filename>

9149

directory on the target.

9150

For example, if a binary is installed into

9151

<filename>/bin</filename>, the corresponding debug

9152

symbol files are installed in

9153

<filename>/bin/.debug</filename>.

9154

Source files are placed in

9155

<filename>/usr/src/debug</filename>.

9156

This is the default behavior.

9157

</para></listitem>

9158

9159

"debug-file-directory": Debug symbol files are

9160

placed under <filename>/usr/lib/debug</filename>

9161

on the target, and separated by the path from where

9162

the binary is installed.

9163

For example, if a binary is installed in

9164

<filename>/bin</filename>, the corresponding debug

9165

symbols are installed in

9166

<filename>/usr/lib/debug/bin</filename>.

9167

Source files are placed in

9168

<filename>/usr/src/debug</filename>.

9169

</para></listitem>

9170

9171

"debug-without-src": The same behavior as

9172

".debug" previously described with the exception

9173

that no source files are installed.

</para></listitem>.

</itemizedlist>

</para>

<para>

You can find out more about debugging using GDB by reading

9180

the

9181

"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"

9182

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

9187

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

9188

<info>

9189

PACKAGE_EXCLUDE_COMPLEMENTARY[doc] = "Prevents specific packages from being installed when you are installing complementary packages."

</info>

9194

Prevents specific packages from being installed when

9195

you are installing complementary packages.

</para>

<para>

You might find that you want to prevent installing certain

9200

packages when you are installing complementary packages.

9201

For example, if you are using

9202

9203

to install <filename>dev-pkgs</filename>, you might not want

9204

to install all packages from a particular multilib.

9205

If you find yourself in this situation, you can use the

9206

<filename>PACKAGE_EXCLUDE_COMPLEMENTARY</filename> variable

9207

to specify regular expressions to match the packages you

want to exclude.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9213

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

9214

<info>

9215

PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated."

</info>

9220

Lists packages that should not be installed into an image.

9221

For example:

9222

9223

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

9229

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

9230

a specific image recipe by using the recipe name override:

9231

9232

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

</literallayout>

</para>

<para>

If you choose to not install

9238

a package using this variable and some other package is

9239

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

9240

9241

variable), the OpenEmbedded build system generates a fatal

9242

installation error.

9243

Because the build system halts the process with a fatal

9244

error, you can use the variable with an iterative

9245

development process to remove specific components from a

system.

</para>

<para>

Support for this variable exists only when using the

9251

IPK and RPM packaging backend.

9252

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>

9266

<info>

9267

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>

9272

Specifies the list of architectures compatible with the device CPU.

9273

This variable is useful when you build for several different devices that use

9274

miscellaneous processors such as XScale and ARM926-EJS.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

9279

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

9280

<info>

9281

PACKAGE_FEED_ARCHS[doc] = "Specifies user-defined package architectures when constructing package feed URIs."

</info>

9286

Specifies the package architectures used as part of the

9287

package feed URIs during the build.

9288

The <filename>PACKAGE_FEED_ARCHS</filename> variable is

9289

appended to the final package feed URI, which is constructed

using the

and

variables.

</para>

<para>

Consider the following example where the

9299

<filename>PACKAGE_FEED_URIS</filename>,

9300

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

9301

<filename>PACKAGE_FEED_ARCHS</filename> variables are

9302

defined in your <filename>local.conf</filename> file:

9303

9304

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

9305

https://example.com/packagerepos/updates"

9306

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

9307

PACKAGE_FEED_ARCHS = "all core2-64"

9308

</literallayout>

9309

Given these settings, the resulting package feeds are

9310

as follows:

9311

9312

https://example.com/packagerepos/release/rpm/all

9313

https://example.com/packagerepos/release/rpm/core2-64

9314

https://example.com/packagerepos/release/rpm-dev/all

9315

https://example.com/packagerepos/release/rpm-dev/core2-64

9316

https://example.com/packagerepos/updates/rpm/all

9317

https://example.com/packagerepos/updates/rpm/core2-64

9318

https://example.com/packagerepos/updates/rpm-dev/all

9319

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>

9326

<info>

9327

PACKAGE_FEED_BASE_PATHS[doc] = "Specifies base path used when constructing package feed URIs."

</info>

9332

Specifies the base path used when constructing package feed

9333

URIs.

9334

The <filename>PACKAGE_FEED_BASE_PATHS</filename> variable

9335

makes up the middle portion of a package feed URI used

9336

by the OpenEmbedded build system.

9337

The base path lies between the

and

variables.

</para>

<para>

Consider the following example where the

9346

<filename>PACKAGE_FEED_URIS</filename>,

9347

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

9348

<filename>PACKAGE_FEED_ARCHS</filename> variables are

9349

defined in your <filename>local.conf</filename> file:

9350

9351

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

9352

https://example.com/packagerepos/updates"

9353

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

9354

PACKAGE_FEED_ARCHS = "all core2-64"

9355

</literallayout>

9356

Given these settings, the resulting package feeds are

9357

as follows:

9358

9359

https://example.com/packagerepos/release/rpm/all

9360

https://example.com/packagerepos/release/rpm/core2-64

9361

https://example.com/packagerepos/release/rpm-dev/all

9362

https://example.com/packagerepos/release/rpm-dev/core2-64

9363

https://example.com/packagerepos/updates/rpm/all

9364

https://example.com/packagerepos/updates/rpm/core2-64

9365

https://example.com/packagerepos/updates/rpm-dev/all

9366

https://example.com/packagerepos/updates/rpm-dev/core2-64

</literallayout>

</para>

</glossdef>

</glossentry>

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

9373

<info>

9374

PACKAGE_FEED_URIS[doc] = "Specifies the front portion of the package feed URI used by the OpenEmbedded build system."

</info>

9379

Specifies the front portion of the package feed URI

9380

used by the OpenEmbedded build system.

9381

Each final package feed URI is comprised of

9382

<filename>PACKAGE_FEED_URIS</filename>,

and

variables.

</para>

<para>

Consider the following example where the

9391

<filename>PACKAGE_FEED_URIS</filename>,

9392

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

9393

<filename>PACKAGE_FEED_ARCHS</filename> variables are

9394

defined in your <filename>local.conf</filename> file:

9395

9396

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

9397

https://example.com/packagerepos/updates"

9398

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

9399

PACKAGE_FEED_ARCHS = "all core2-64"

9400

</literallayout>

9401

Given these settings, the resulting package feeds are

9402

as follows:

9403

9404

https://example.com/packagerepos/release/rpm/all

9405

https://example.com/packagerepos/release/rpm/core2-64

9406

https://example.com/packagerepos/release/rpm-dev/all

9407

https://example.com/packagerepos/release/rpm-dev/core2-64

9408

https://example.com/packagerepos/updates/rpm/all

9409

https://example.com/packagerepos/updates/rpm/core2-64

9410

https://example.com/packagerepos/updates/rpm-dev/all

9411

https://example.com/packagerepos/updates/rpm-dev/core2-64

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9417

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

9418

<info>

9419

PACKAGE_GROUP[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES."

</info>

9424

The <filename>PACKAGE_GROUP</filename> variable has been

9425

renamed to

9426

9427

See the variable description for

9428

<filename>FEATURE_PACKAGES</filename> for information.

</para>

<para>

If if you use the <filename>PACKAGE_GROUP</filename>

9433

variable, the OpenEmbedded build system issues a warning

message.

</para>

</glossdef>

</glossentry>

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

9440

<info>

9441

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>

9446

The final list of packages passed to the package manager

9447

for installation into the image.

</para>

<para>

Because the package manager controls actual installation

9452

of all packages, the list of packages passed using

9453

<filename>PACKAGE_INSTALL</filename> is not the final list

9454

of packages that are actually installed.

9455

This variable is internal to the image construction

9456

code.

9457

Consequently, in general, you should use the

9458

9459

variable to specify packages for installation.

9460

The exception to this is when working with

9461

the

9462

9463

image.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

9464

When working with an initial RAM filesystem (initramfs)

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9465

image, use the <filename>PACKAGE_INSTALL</filename>

9466

variable.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

9467

For information on creating an initramfs, see the

9468

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

9469

section in the Yocto Project Development Manual.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

9475

<info>

9476

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>

9481

Specifies a list of packages the OpenEmbedded build

9482

system attempts to install when creating an image.

9483

If a listed package fails to install, the build system

9484

does not generate an error.

9485

This variable is generally not user-defined.

</para>

</glossdef>

</glossentry>

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

9491

<info>

9492

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>

9497

Specifies a list of functions run to pre-process the

9498

9499

directory prior to splitting the files out to individual

packages.

</para>

</glossdef>

</glossentry>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

9505

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

9506

<info>

9507

PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script dependencies on native/cross tools."

</info>

9512

Specifies a list of dependencies for post-installation and

9513

pre-installation scripts on native/cross tools.

9514

If your post-installation or pre-installation script can

9515

execute at rootfs creation time rather than on the

9516

target but depends on a native tool in order to execute,

9517

you need to list the tools in

9518

<filename>PACKAGE_WRITE_DEPENDS</filename>.

</para>

<para>

For information on running post-installation scripts, see

9523

the

9524

"<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"

9525

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9530

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

9531

<info>

9532

PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis."

</info>

9537

This variable provides a means of enabling or disabling

9538

features of a recipe on a per-recipe basis.

9539

<filename>PACKAGECONFIG</filename> blocks are defined

9540

in recipes when you specify features and then arguments

9541

that define feature behaviors.

9542

Here is the basic block structure:

9543

9544

PACKAGECONFIG ??= "f1 f2 f3 ..."

9545

PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"

9546

PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"

9547

PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"

</literallayout>

</para>

<para>

The <filename>PACKAGECONFIG</filename>

9553

variable itself specifies a space-separated list of the

9554

features to enable.

9555

Following the features, you can determine the behavior of

9556

each feature by providing up to four order-dependent

9557

arguments, which are separated by commas.

9558

You can omit any argument you like but must retain the

9559

separating commas.

9560

The order is important and specifies the following:

9561

9562

<listitem><para>Extra arguments

9563

that should be added to the configure script

9564

argument list

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9565

(<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>

9566

or

9567

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9568

if the feature is enabled.</para></listitem>

9569

<listitem><para>Extra arguments

9570

that should be added to <filename>EXTRA_OECONF</filename>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9571

or <filename>PACKAGECONFIG_CONFARGS</filename>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9572

if the feature is disabled.

9573

</para></listitem>

9574

<listitem><para>Additional build dependencies

9575

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

9576

that should be added if the feature is enabled.

9577

</para></listitem>

9578

<listitem><para>Additional runtime dependencies

9579

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

9580

that should be added if the feature is enabled.

</para></listitem>

</orderedlist>

</para>

<para>

Consider the following

9587

<filename>PACKAGECONFIG</filename> block taken from the

9588

<filename>librsvg</filename> recipe.

9589

In this example the feature is <filename>croco</filename>,

9590

which has three arguments that determine the feature's

9591

behavior.

9592

9593

PACKAGECONFIG ??= "croco"

9594

PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"

9595

</literallayout>

9596

The <filename>--with-croco</filename> and

9597

<filename>libcroco</filename> arguments apply only if

9598

the feature is enabled.

9599

In this case, <filename>--with-croco</filename> is

9600

added to the configure script argument list and

9601

<filename>libcroco</filename> is added to

9602

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

9603

On the other hand, if the feature is disabled say through

9604

a <filename>.bbappend</filename> file in another layer, then

9605

the second argument <filename>--without-croco</filename> is

9606

added to the configure script rather than

9607

<filename>--with-croco</filename>.

</para>

<para>

The basic <filename>PACKAGECONFIG</filename> structure

9612

previously described holds true regardless of whether you

9613

are creating a block or changing a block.

9614

When creating a block, use the structure inside your

recipe.

</para>

<para>

If you want to change an existing

9620

<filename>PACKAGECONFIG</filename> block, you can do so

9621

one of two ways:

9622

9623

<listitem><para><emphasis>Append file:</emphasis>

9624

Create an append file named

9625

<replaceable>recipename</replaceable><filename>.bbappend</filename>

9626

in your layer and override the value of

9627

<filename>PACKAGECONFIG</filename>.

9628

You can either completely override the variable:

9629

9630

PACKAGECONFIG="f4 f5"

9631

</literallayout>

9632

Or, you can just append the variable:

9633

9634

PACKAGECONFIG_append = " f4"

9635

</literallayout></para></listitem>

9636

<listitem><para><emphasis>Configuration file:</emphasis>

9637

This method is identical to changing the block

9638

through an append file except you edit your

9639

<filename>local.conf</filename> or

9640

<filename><replaceable>mydistro</replaceable>.conf</filename> file.

9641

As with append files previously described,

9642

you can either completely override the variable:

9643

9644

PACKAGECONFIG_pn-<replaceable>recipename</replaceable>="f4 f5"

9645

</literallayout>

9646

Or, you can just amend the variable:

9647

9648

PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4"

9649

</literallayout></para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9655

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

9656

<info>

9657

PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from PACKAGECONFIG."

</info>

9662

A space-separated list of configuration options generated

9663

from the

9664

9665

setting.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9666

</para>

9667

9668

<para>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

Classes such as

and

use <filename>PACKAGECONFIG_CONFARGS</filename> to pass

9674

9675

options to <filename>configure</filename> and

9676

<filename>cmake</filename>, respectively.

9677

If you are using

9678

<filename>PACKAGECONFIG</filename> but not a class that

9679

handles the <filename>do_configure</filename> task, then

9680

you need to use

9681

<filename>PACKAGECONFIG_CONFARGS</filename> appropriately.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

</para>

<para>

For additional information, see the

variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9692

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

9693

<info>

9694

PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe."

</info>

9699

For recipes inheriting the

9700

9701

class, setting

9702

<filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to

9703

"1" specifies that the normal complementary packages

9704

(i.e. <filename>-dev</filename>,

9705

<filename>-dbg</filename>, and so forth) should not be

9706

automatically created by the

9707

<filename>packagegroup</filename> recipe, which is the

default behavior.

</para>

</glossdef>

</glossentry>

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

9714

<info>

9715

PACKAGES[doc] = "The list of packages to be created from the recipe."

</info>

9720

The list of packages to be created from the recipe.

9721

The default value is the following:

9722

9723

${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}

9724

</literallayout>

9725

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9726

9727

<para>

9728

During packaging, the

9729

9730

task goes through <filename>PACKAGES</filename> and uses

9731

the

9732

9733

variable corresponding to each package to assign files to

9734

the package.

9735

If a file matches the <filename>FILES</filename> variable

9736

for more than one package in <filename>PACKAGES</filename>,

9737

it will be assigned to the earliest (leftmost) package.

</para>

<para>

Packages in the variable's list that are empty (i.e. where

9742

none of the patterns in

9743

<filename>FILES_</filename><replaceable>pkg</replaceable>

9744

match any files installed by the

9745

9746

task) are not generated, unless generation is forced through

the

variable.

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

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

9755

<info>

9756

PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes."

</info>

9761

A promise that your recipe satisfies runtime dependencies

9762

for optional modules that are found in other recipes.

9763

<filename>PACKAGES_DYNAMIC</filename>

9764

does not actually satisfy the dependencies, it only states that

9765

they should be satisfied.

9766

For example, if a hard, runtime dependency

9767

(<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)

9768

of another package is satisfied

9769

at build time through the <filename>PACKAGES_DYNAMIC</filename>

9770

variable, but a package with the module name is never actually

9771

produced, then the other package will be broken.

9772

Thus, if you attempt to include that package in an image,

9773

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

9781

occur and the package that is not created is valid

9782

without the dependency being satisfied, then you should use

9783

9784

(a soft runtime dependency) instead of

9785

<filename>RDEPENDS</filename>.

</para>

<para>

For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>

9790

variable when you are splitting packages, see the

9791

"<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section

9792

in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>

9798

<info>

9799

PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages."

</info>

9804

Specifies a list of functions run to perform additional

9805

splitting of files into individual packages.

9806

Recipes can either prepend to this variable or prepend

9807

to the <filename>populate_packages</filename> function

9808

in order to perform additional package splitting.

9809

In either case, the function should set

and other packaging variables appropriately in order to

9814

perform the desired splitting.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>

9820

<info>

9821

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>

9826

Extra options passed to the <filename>make</filename>

9827

command during the

9828

9829

task in order to specify parallel compilation on the local

9830

build host.

9831

This variable is usually in the form "-j <replaceable>x</replaceable>",

9832

where <replaceable>x</replaceable> represents the maximum

9833

number of parallel threads <filename>make</filename> can

9834

run.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9835

<note><title>Caution</title>

9836

In order for <filename>PARALLEL_MAKE</filename> to be

9837

effective, <filename>make</filename> must be called

9838

with

9839

<filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.

9840

An easy way to ensure this is to use the

9841

<filename>oe_runmake</filename> function.

9842

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

By default, the OpenEmbedded build system automatically

9847

sets this variable to be equal to the number of cores the

9848

build system uses.

9849

<note>

9850

If the software being built experiences dependency

9851

issues during the <filename>do_compile</filename>

9852

task that result in race conditions, you can clear

9853

the <filename>PARALLEL_MAKE</filename> variable within

9854

the recipe as a workaround.

9855

For information on addressing race conditions, see the

9856

"<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"

9857

section in the Yocto Project Development Manual.

9858

</note>

9859

For single socket systems (i.e. one CPU), you should not

9860

have to override this variable to gain optimal parallelism

9861

during builds.

9862

However, if you have very large systems that employ

9863

multiple physical CPUs, you might want to make sure the

9864

<filename>PARALLEL_MAKE</filename> variable is not

9865

set higher than "-j 20".

</para>

<para>

For more information on speeding up builds, see the

9870

"<link linkend='speeding-up-the-build'>Speeding Up the Build</link>"

section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>

9877

<info>

9878

PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation."

</info>

9883

Extra options passed to the

9884

<filename>make install</filename> command during the

9885

9886

task in order to specify parallel installation.

9887

This variable defaults to the value of

9888

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9889

<note><title>Notes and Cautions</title>

9890

<para>In order for <filename>PARALLEL_MAKEINST</filename>

9891

to be

9892

effective, <filename>make</filename> must be called

9893

with

9894

<filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.

9895

An easy way to ensure this is to use the

9896

<filename>oe_runmake</filename> function.</para>

9897

9898

<para>If the software being built experiences

9899

dependency issues during the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9900

<filename>do_install</filename> task that result in

9901

race conditions, you can clear the

9902

<filename>PARALLEL_MAKEINST</filename> variable within

9903

the recipe as a workaround.

9904

For information on addressing race conditions, see the

9905

"<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9906

section in the Yocto Project Development Manual.</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>

9913

<info>

9914

PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution."

</info>

9919

Determines the action to take when a patch fails.

9920

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

9926

when the OpenEmbedded build system cannot successfully

9927

apply a patch.

9928

Setting the value to "user" causes the build system to

9929

launch a shell and places you in the right location so that

9930

you can manually resolve the conflicts.

</para>

<para>

Set this variable in your

9935

<filename>local.conf</filename> file.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>

9941

<info>

9942

PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch."

</info>

9947

Specifies the utility used to apply patches for a recipe

during the

task.

You can specify one of three utilities: "patch", "quilt", or

9952

"git".

9953

The default utility used is "quilt" except for the

9954

quilt-native recipe itself.

9955

Because the quilt tool is not available at the

9956

time quilt-native is being patched, it uses "patch".

</para>

<para>

If you wish to use an alternative patching tool, set the

9961

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>

9978

The epoch of the recipe.

9979

By default, this variable is unset.

9980

The variable is used to make upgrades possible when the

9981

versioning scheme changes in some backwards incompatible

9982

way.

9983

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9984

9985

<para>

9986

<filename>PE</filename> is the default value of the

9987

9988

variable.

9989

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</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>

10000

Specifies the recipe or package name and includes all version and revision

10001

numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and

10002

<filename>bash-4.2-r1/</filename>).

10003

This variable is comprised of the following:

10004

10005

${<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>

10012

<info>

10013

PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf."

</info>

10018

When inheriting the

10019

10020

class, this variable identifies packages that contain

10021

the pixbuf loaders used with

10022

<filename>gdk-pixbuf</filename>.

10023

By default, the <filename>pixbufcache</filename> class

10024

assumes that the loaders are in the recipe's main package

10025

(i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).

10026

Use this variable if the loaders you need are in a package

10027

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>

10039

The name of the resulting package created by the

10040

OpenEmbedded build system.

10041

<note>

10042

When using the <filename>PKG</filename> variable, you

10043

must use a package name override.

</note>

</para>

<para>

For example, when the

10049

10050

class renames the output package, it does so by setting

10051

<filename>PKG_<replaceable>packagename</replaceable></filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PKG_CONFIG_PATH'><glossterm>PKG_CONFIG_PATH</glossterm>

10057

<info>

10058

PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context."

</info>

10063

The path to <filename>pkg-config</filename> files for the

10064

current build context.

10065

<filename>pkg-config</filename> reads this variable

10066

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>

10078

Points to the destination directory for files to be

10079

packaged before they are split into individual packages.

10080

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>

10093

<info>

10094

PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process."

</info>

10099

Points to a shared, global-state directory that holds data

10100

generated during the packaging process.

10101

During the packaging process, the

10102

10103

task packages data for each recipe and installs it into

10104

this temporary, shared area.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10105

This directory defaults to the following, which you should

10106

not change:

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10107

10108

${STAGING_DIR_HOST}/pkgdata

10109

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10110

For examples of how this data is used, see the

10111

"<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"

10112

section and the

10113

"<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"

10114

section.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>

10120

<info>

10121

PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages."

</info>

10126

Points to the parent directory for files to be packaged

10127

after they have been split into individual packages.

10128

This directory defaults to the following:

10129

10130

${WORKDIR}/packages-split

</literallayout>

</para>

<para>

Under this directory, the build system creates

10136

directories for each package specified in

10137

10138

Do not change this default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>

10144

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10145

PKGDESTWORK[doc] = "Points to a temporary work area where the do_package task saves package metadata."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10150

Points to a temporary work area where the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10151

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10152

task saves package metadata.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10153

The <filename>PKGDESTWORK</filename> location defaults to

the following:

${WORKDIR}/pkgdata

</literallayout>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10158

Do not change this default.

10159

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

<para>

The

task copies the package metadata from

10165

<filename>PKGDESTWORK</filename> to

10166

10167

to make it available globally.

10168

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10174

PKGE[doc] = "The epoch of the package(s) built by the recipe."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10179

The epoch of the package(s) built by the recipe.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10180

By default, <filename>PKGE</filename> is set to

</para>

</glossdef>

</glossentry>

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10188

PKGR[doc] = "The revision of the package(s) built by the recipe."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10193

The revision of the package(s) built by the recipe.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10194

By default, <filename>PKGR</filename> is set to

</para>

</glossdef>

</glossentry>

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10202

PKGV[doc] = "The version of the package(s) built by the recipe."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10207

The version of the package(s) built by the

10208

recipe.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10209

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. It refers to a package name in the context of a file created or produced by the OpenEmbedded build system."

</info>

10222

This variable can have two separate functions depending on the context: a recipe

10223

name or a resulting package name.

</para>

<para>

<filename>PN</filename> refers to a recipe name in the context of a file used

10228

by the OpenEmbedded build system as input to create a package.

10229

The name is normally extracted from the recipe file name.

10230

For example, if the recipe is named

10231

<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

10237

OpenEmbedded build system.

</para>

<para>

If applicable, the <filename>PN</filename> variable also contains any special

10242

suffix or prefix.

10243

For example, using <filename>bash</filename> to build packages for the native

10244

machine, <filename>PN</filename> is <filename>bash-native</filename>.

10245

Using <filename>bash</filename> to build packages for the target and for Multilib,

10246

<filename>PN</filename> would be <filename>bash</filename> and

10247

<filename>lib64-bash</filename>, respectively.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>

10253

<info>

10254

PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build."

</info>

10259

Lists recipes you do not want the OpenEmbedded build system

10260

to build.

10261

This variable works in conjunction with the

10262

10263

class, which the recipe must inherit globally.

</para>

<para>

To prevent a recipe from being built, inherit the class

10268

globally and use the variable in your

10269

<filename>local.conf</filename> file.

10270

Here is an example that prevents

10271

<filename>myrecipe</filename> from being built:

10272

10273

INHERIT += "blacklist"

10274

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>

10281

<info>

10282

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>

10287

Specifies a list of functions to call once the

10288

OpenEmbedded build system has created the host part of

10289

the SDK.

10290

You can specify functions separated by semicolons:

10291

10292

POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the SDK path to a command

10298

within a function, you can use

10299

<filename>${SDK_DIR}</filename>, which points to

10300

the parent directory used by the OpenEmbedded build

10301

system when creating SDK output.

10302

See the

10303

10304

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-POPULATE_SDK_POST_TARGET_COMMAND'><glossterm>POPULATE_SDK_POST_TARGET_COMMAND</glossterm>

10310

<info>

10311

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>

10316

Specifies a list of functions to call once the

10317

OpenEmbedded build system has created the target part of

10318

the SDK.

10319

You can specify functions separated by semicolons:

10320

10321

POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the SDK path to a command

10327

within a function, you can use

10328

<filename>${SDK_DIR}</filename>, which points to

10329

the parent directory used by the OpenEmbedded build

10330

system when creating SDK output.

10331

See the

10332

10333

variable for more information.

</para>

</glossdef>

</glossentry>

<info>

PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'."

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10345

The revision of the recipe. The default value for this

10346

variable is "r0".

10347

Subsequent revisions of the recipe conventionally have the

10348

values "r1", "r2", and so forth.

10349

When

10350

10351

increases, <filename>PR</filename> is conventionally reset

10352

to "r0".

10353

<note>

10354

The OpenEmbedded build system does not need the aid of

10355

<filename>PR</filename> to know when to rebuild a

10356

recipe.

10357

The build system uses the task

10358

<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>input checksums</ulink>

along with the

and

mechanisms.

</note>

The <filename>PR</filename> variable primarily becomes

10366

significant when a package manager dynamically installs

10367

packages on an already built image.

10368

In this case, <filename>PR</filename>, which is the default

10369

value of

10370

10371

helps the package manager distinguish which package is the

10372

most recent one in cases where many packages have the same

10373

<filename>PV</filename> (i.e. <filename>PKGV</filename>).

10374

A component having many packages with the same

10375

<filename>PV</filename> usually means that the packages all

10376

install the same upstream version, but with later

10377

(<filename>PR</filename>) version packages including

10378

packaging fixes.

10379

<note>

10380

<filename>PR</filename> does not need to be increased

10381

for changes that do not change the package contents or

10382

metadata.

10383

</note>

10384

Because manually managing <filename>PR</filename> can be

10385

cumbersome and error-prone, an automated solution exists.

10386

See the

10387

"<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"

10388

section for more information.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>

10394

<info>

10395

PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference."

</info>

10400

If multiple recipes provide an item, this variable

10401

determines which recipe should be given preference.

10402

You should always suffix the variable with the name of the

10403

provided item, and you should set it to the

10404

10405

of the recipe to which you want to give precedence.

10406

Some examples:

10407

10408

PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"

10409

PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"

10410

PREFERRED_PROVIDER_virtual/libgl ?= "mesa"

10411

</literallayout>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

10412

<note>

10413

If you set <filename>PREFERRED_PROVIDER</filename>

10414

for a <filename>virtual/*</filename> item, then any

10415

recipe that

10416

10417

that item that is not selected by

10418

<filename>PREFERRED_PROVIDER</filename> is prevented

10419

from building, which is usually desirable since this

10420

mechanism is designed to select between mutually

10421

exclusive alternative providers.

10422

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>

10428

<info>

10429

PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference."

</info>

10434

If there are multiple versions of recipes available, this

10435

variable determines which recipe should be given preference.

10436

You must always suffix the variable with the

10437

10438

you want to select, and you should set the

10439

10440

accordingly for precedence.

10441

You can use the "<filename>%</filename>" character as a

10442

wildcard to match any number of characters, which can be

10443

useful when specifying versions that contain long revision

10444

numbers that could potentially change.

10445

Here are two examples:

10446

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10447

PREFERRED_VERSION_python = "3.4.0"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10448

PREFERRED_VERSION_linux-yocto = "3.19%"

10449

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10450

<note>

10451

The specified version is matched against

10452

10453

which does not necessarily match the version part of

10454

the recipe's filename.

10455

For example, consider two recipes

10456

<filename>foo_1.2.bb</filename> and

10457

<filename>foo_git.bb</filename> where

10458

<filename>foo_git.bb</filename> contains the following

10459

assignment:

10460

10461

PV = "1.1+git${SRCPV}"

10462

</literallayout>

10463

In this case, the correct way to select

10464

<filename>foo_git.bb</filename> is by using an

10465

assignment such as the following:

10466

10467

PREFERRED_VERSION_foo = "1.1+git%"

10468

</literallayout>

10469

Compare that previous example against the following

10470

incorrect example, which does not work:

10471

10472

PREFERRED_VERSION_foo = "git"

10473

</literallayout>

10474

</note>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

10475

Sometimes the <filename>PREFERRED_VERSION</filename>

10476

variable can be set by configuration files in a way that

is hard to change.

You can use

to set a machine-specific override.

10481

Here is an example:

10482

10483

PREFERRED_VERSION_linux-yocto_qemux86 = "3.4%"

10484

</literallayout>

10485

Although not recommended, worst case, you can also use the

10486

"forcevariable" override, which is the strongest override

possible.

Here is an example:

PREFERRED_VERSION_linux-yocto_forcevariable = "3.4%"

10491

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10492

<note>

10493

The <filename>_forcevariable</filename> override is

10494

not handled specially.

10495

This override only works because the default value of

10496

10497

includes "forcevariable".

10498

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>

10504

<info>

10505

PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."

</info>

10510

Specifies additional paths from which the OpenEmbedded

10511

build system gets source code.

10512

When the build system searches for source code, it first

10513

tries the local download directory.

10514

If that location fails, the build system tries locations

10515

defined by <filename>PREMIRRORS</filename>, the upstream

10516

source, and then locations specified by

in that order.

</para>

<para>

Assuming your distribution

10523

(<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)

10524

is "poky", the default value for

10525

<filename>PREMIRRORS</filename> is defined in the

10526

<filename>conf/distro/poky.conf</filename> file in the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

10527

<filename>meta-poky</filename> Git repository.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

Typically, you could add a specific server for the

10532

build system to attempt before any others by adding

10533

something like the following to the

10534

<filename>local.conf</filename> configuration file in the

10535

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:

10536

10537

PREMIRRORS_prepend = "\

10538

git://.*/.* http://www.yoctoproject.org/sources/ \n \

10539

ftp://.*/.* http://www.yoctoproject.org/sources/ \n \

10540

http://.*/.* http://www.yoctoproject.org/sources/ \n \

10541

https://.*/.* http://www.yoctoproject.org/sources/ \n"

10542

</literallayout>

10543

These changes cause the build system to intercept

10544

Git, FTP, HTTP, and HTTPS requests and direct them to

10545

the <filename>http://</filename> sources mirror.

10546

You can use <filename>file://</filename> URLs to point

10547

to local directories or network shares as well.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PRIORITY'><glossterm>PRIORITY</glossterm>

10553

<info>

10554

PRIORITY[doc] = "Indicates the importance of a package. The default value is 'optional'. Other standard values are 'required', 'standard' and 'extra'."

</info>

10559

Indicates the importance of a package.

</para>

<para>

<filename>PRIORITY</filename> is considered to be part of

10564

the distribution policy because the importance of any given

10565

recipe depends on the purpose for which the distribution

10566

is being produced.

10567

Thus, <filename>PRIORITY</filename> is not normally set

within recipes.

</para>

<para>

You can set <filename>PRIORITY</filename> to "required",

10573

"standard", "extra", and "optional", which is the default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>

10579

<info>

10580

PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver."

</info>

10585

Specifies libraries installed within a recipe that

10586

should be ignored by the OpenEmbedded build system's

10587

shared library resolver.

10588

This variable is typically used when software being

10589

built by a recipe has its own private versions of a

10590

library normally provided by another recipe.

10591

In this case, you would not want the package containing

10592

the private libraries to be set as a dependency on other

10593

unrelated packages that should instead depend on the

10594

package providing the standard version of the library.

</para>

<para>

Libraries specified in this variable should be specified

10599

by their file name.

10600

For example, from the Firefox recipe in meta-browser:

10601

10602

PRIVATE_LIBS = "libmozjs.so \

libxpcom.so \

libnspr4.so \

libxul.so \

libmozalloc.so \

libplc4.so \

libplds4.so"

</literallayout>

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10611

10612

<para>

10613

For more information, see the

10614

"<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"

10615

section.

10616

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

<glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>

10621

<info>

10622

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>

10627

A list of aliases by which a particular recipe can be

10628

known.

10629

By default, a recipe's own

10630

10631

is implicitly already in its <filename>PROVIDES</filename>

10632

list.

10633

If a recipe uses <filename>PROVIDES</filename>, the

10634

additional aliases are synonyms for the recipe and can

10635

be useful satisfying dependencies of other recipes during

10636

the build as specified by

10637

<filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.

</para>

<para>

Consider the following example

10642

<filename>PROVIDES</filename> statement from a recipe

10643

file <filename>libav_0.8.11.bb</filename>:

10644

10645

PROVIDES += "libpostproc"

10646

</literallayout>

10647

The <filename>PROVIDES</filename> statement results in

10648

the "libav" recipe also being known as "libpostproc".

10649

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10650

10651

<para>

10652

In addition to providing recipes under alternate names,

10653

the <filename>PROVIDES</filename> mechanism is also used

10654

to implement virtual targets.

10655

A virtual target is a name that corresponds to some

10656

particular functionality (e.g. a Linux kernel).

10657

Recipes that provide the functionality in question list the

10658

virtual target in <filename>PROVIDES</filename>.

10659

Recipes that depend on the functionality in question can

10660

include the virtual target in

10661

10662

to leave the choice of provider open.

</para>

<para>

Conventionally, virtual targets have names on the form

10667

"virtual/function" (e.g. "virtual/kernel").

10668

The slash is simply part of the name and has no

10669

syntactical significance.

</para>

<para>

The

variable is used to select which particular recipe

10676

provides a virtual target.

10677

<note>

10678

<para>A corresponding mechanism for virtual runtime

10679

dependencies (packages) exists.

10680

However, the mechanism does not depend on any special

10681

functionality beyond ordinary variable assignments.

10682

For example,

10683

<filename>VIRTUAL-RUNTIME_dev_manager</filename>

10684

refers to the package of the component that manages

10685

the <filename>/dev</filename> directory.</para>

10686

10687

<para>Setting the "preferred provider" for runtime

10688

dependencies is as simple as using the following

10689

assignment in a configuration file:</para>

10690

10691

VIRTUAL-RUNTIME_dev_manager = "udev"

10692

</literallayout>

10693

</note>

10694

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

<glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>

10699

<info>

10700

PRSERV_HOST[doc] = "The network based PR service host and port."

</info>

10705

The network based

10706

10707

service host and port.

</para>

<para>

The <filename>conf/local.conf.sample.extended</filename>

10712

configuration file in the

10713

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

10714

shows how the <filename>PRSERV_HOST</filename> variable is

10715

set:

10716

10717

PRSERV_HOST = "localhost:0"

10718

</literallayout>

10719

You must set the variable if you want to automatically

10720

start a local

10721

<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.

10722

You can set <filename>PRSERV_HOST</filename> to other

10723

values to use a remote PR service.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm>

10729

<info>

10730

PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe."

</info>

10735

Specifies whether or not

10736

<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink>

10737

(ptest) functionality is enabled when building a recipe.

10738

You should not set this variable directly.

10739

Enabling and disabling building Package Tests

10740

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>

10754

The version of the recipe.

10755

The version is normally extracted from the recipe filename.

10756

For example, if the recipe is named

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10757

<filename>expat_2.0.1.bb</filename>, then the default value

10758

of <filename>PV</filename> will be "2.0.1".

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10759

<filename>PV</filename> is generally not overridden within

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10760

a recipe unless it is building an unstable (i.e.

10761

development) version from a source code repository

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10762

(e.g. Git or Subversion).

10763

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10764

10765

<para>

10766

<filename>PV</filename> is the default value of the

10767

10768

variable.

10769

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

<glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>

10774

<info>

10775

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>

10780

When used by recipes that inherit the

or

classes, denotes the Application Binary Interface (ABI)

10787

currently in use for Python.

10788

By default, the ABI is "m".

10789

You do not have to set this variable as the OpenEmbedded

10790

build system sets it for you.

</para>

<para>

The OpenEmbedded build system uses the ABI to construct

10795

directory names used when installing the Python headers

10796

and libraries in sysroot

10797

(e.g. <filename>.../python3.3m/...</filename>).

</para>

<para>

Recipes that inherit the

10802

10803

class during cross-builds also use this variable to

10804

locate the headers and libraries of the appropriate Python

10805

that the extension is targeting.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>

10811

<info>

10812

PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built."

</info>

10817

When used by recipes that inherit the

or

classes, specifies the major Python version being built.

10824

For Python 2.x, <filename>PYTHON_PN</filename> would

10825

be "python2". For Python 3.x, the variable would be

10826

"python3".

10827

You do not have to set this variable as the

10828

OpenEmbedded build system automatically sets it for you.

</para>

<para>

The variable allows recipes to use common infrastructure

10833

such as the following:

10834

10835

DEPENDS += "${PYTHON_PN}-native"

10836

</literallayout>

10837

In the previous example, the version of the dependency

10838

is <filename>PYTHON_PN</filename>.

</para>

</glossdef>

</glossentry>

</glossdiv>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10845

10846

10847

<glossentry id='var-RANLIB'><glossterm>RANLIB</glossterm>

10848

<info>

10849

RANLIB[doc] = "Minimal command and arguments to run 'ranlib'."

</info>

10854

The minimal command and arguments to run

10855

<filename>ranlib</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>

10861

<info>

10862

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>

10867

The list of packages that conflict with packages.

10868

Note that packages will not be installed if conflicting

10869

packages are not first removed.

</para>

<para>

Like all package-controlling variables, you must always use

10874

them in conjunction with a package name override.

10875

Here is an example:

10876

10877

RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>"

</literallayout>

</para>

<para>

BitBake, which the OpenEmbedded build system uses, supports

10883

specifying versioned dependencies.

10884

Although the syntax varies depending on the packaging

10885

format, BitBake hides these differences from you.

10886

Here is the general syntax to specify versions with

10887

the <filename>RCONFLICTS</filename> variable:

10888

10889

RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

10890

</literallayout>

10891

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a dependency on version

10901

1.2 or greater of the package <filename>foo</filename>:

10902

10903

RCONFLICTS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>

10910

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10911

RDEPENDS[doc] = "Lists runtime dependencies of a package."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10916

Lists runtime dependencies of a package.

10917

These dependencies are other packages that must be

10918

installed in order for the package to function correctly.

10919

As an example, the following assignment declares that the

10920

package <filename>foo</filename> needs the packages

10921

<filename>bar</filename> and <filename>baz</filename> to

10922

be installed:

10923

10924

RDEPENDS_foo = "bar baz"

10925

</literallayout>

10926

The most common types of package runtime dependencies are

10927

automatically detected and added.

10928

Therefore, most recipes do not need to set

10929

<filename>RDEPENDS</filename>.

10930

For more information, see the

10931

"<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"

10932

section.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10933

</para>

10934

10935

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10936

The practical effect of the above

10937

<filename>RDEPENDS</filename> assignment is that

10938

10939

will be declared as dependencies inside the package

10940

<filename>foo</filename> when it is written out by one of

the

tasks.

Exactly how this is done depends on which package format

10945

is used, which is determined by

10946

10947

When the corresponding package manager installs the

10948

package, it will know to also install the packages on

which it depends.

</para>

<para>

To ensure that the packages <filename>bar</filename> and

10954

<filename>baz</filename> get built, the previous

10955

<filename>RDEPENDS</filename> assignment also causes a task

10956

dependency to be added.

10957

This dependency is from the recipe's

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10958

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10959

(not to be confused with

10960

10961

task to the <filename>do_package_write_*</filename>

10962

task of the recipes that build <filename>bar</filename> and

10963

<filename>baz</filename>.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

The names of the packages you list within

10968

<filename>RDEPENDS</filename> must be the names of other

10969

packages - they cannot be recipe names.

10970

Although package names and recipe names usually match,

10971

the important point here is that you are

10972

providing package names within the

10973

<filename>RDEPENDS</filename> variable.

10974

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

10982

to packages being built, you should always use the variable

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10983

in a form with an attached package name (remember that a

10984

single recipe can build multiple packages).

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10985

For example, suppose you are building a development package

10986

that depends on the <filename>perl</filename> package.

10987

In this case, you would use the following

10988

<filename>RDEPENDS</filename> statement:

10989

10990

RDEPENDS_${PN}-dev += "perl"

10991

</literallayout>

10992

In the example, the development package depends on

10993

the <filename>perl</filename> package.

10994

Thus, the <filename>RDEPENDS</filename> variable has the

10995

<filename>${PN}-dev</filename> package name as part of the

10996

variable.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10997

<note>

10998

<title>Caution</title>

10999

<filename>RDEPENDS_${PN}-dev</filename> includes

11000

11001

by default.

11002

This default is set in the BitBake configuration file

11003

(<filename>meta/conf/bitbake.conf</filename>).

11004

Be careful not to accidentally remove

11005

<filename>${PN}</filename> when modifying

11006

<filename>RDEPENDS_${PN}-dev</filename>.

11007

Use the "+=" operator rather than the "=" operator.

11008

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11009

</para>

11010

11011

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

11012

The package names you use with

11013

<filename>RDEPENDS</filename> must appear as they would in

11014

the <filename>PACKAGES</filename> variable.

11015

The

11016

11017

variable allows a different name to be used for

11018

the final package (e.g. the

11019

11020

class uses this to rename packages), but this final package

11021

name cannot be used with <filename>RDEPENDS</filename>,

11022

which makes sense as <filename>RDEPENDS</filename> is meant

11023

to be independent of the package format used.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

BitBake, which the OpenEmbedded build system uses, supports

11028

specifying versioned dependencies.

11029

Although the syntax varies depending on the packaging

11030

format, BitBake hides these differences from you.

11031

Here is the general syntax to specify versions with

11032

the <filename>RDEPENDS</filename> variable:

11033

11034

RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

11035

</literallayout>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

11036

For <replaceable>operator</replaceable>, you can specify the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

following:

=

<

>

<=

>=

</literallayout>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

11045

For <replaceable>version</replaceable>, provide the version

number.

You can use

to provide a full package version specification.

11051

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11052

For example, the following sets up a dependency on version

11053

1.2 or greater of the package <filename>foo</filename>:

11054

11055

RDEPENDS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

<para>

For information on build-time dependencies, see the

11061

11062

variable.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

11063

You can also see the

11064

"<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and

11065

"<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"

11066

sections in the BitBake User Manual for additional

11067

information on tasks and dependencies.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>

11073

<info>

11074

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

11083

exist in the current configuration in order for the

11084

OpenEmbedded build system to build the recipe.

11085

In other words, if the

11086

<filename>REQUIRED_DISTRO_FEATURES</filename> variable

11087

lists a feature that does not appear in

11088

<filename>DISTRO_FEATURES</filename> within the

11089

current configuration, an error occurs and the

build stops.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11095

<glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>

11096

<info>

11097

RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed."

</info>

11102

With <filename>rm_work</filename> enabled, this

11103

variable specifies a list of recipes whose work directories

11104

should not be removed.

11105

See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"

11106

section for more details.

</para>

</glossdef>

</glossentry>

<info>

ROOT_HOME[doc] = "Defines the root home directory."

</info>

11118

Defines the root home directory.

11119

By default, this directory is set as follows in the

11120

BitBake configuration file:

11121

11122

ROOT_HOME ??= "/home/root"

11123

</literallayout>

11124

<note>

11125

This default value is likely used because some

11126

embedded solutions prefer to have a read-only root

11127

filesystem and prefer to keep writeable data in one

place.

</note>

</para>

<para>

You can override the default by setting the variable

11134

in any layer or in the <filename>local.conf</filename> file.

11135

Because the default is set using a "weak" assignment

11136

(i.e. "??="), you can use either of the following forms

11137

to define your override:

ROOT_HOME = "/root"

ROOT_HOME ?= "/root"

</literallayout>

These override examples use <filename>/root</filename>,

11143

which is probably the most commonly used override.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>

11149

<info>

11150

ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem."

</info>

11155

Indicates a filesystem image to include as the root

filesystem.

</para>

<para>

The <filename>ROOTFS</filename> variable is an optional

11161

variable used with the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11162

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_POSTINSTALL_COMMAND'><glossterm>ROOTFS_POSTINSTALL_COMMAND</glossterm>

11169

<info>

11170

ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."

</info>

11175

Specifies a list of functions to call after the

11176

OpenEmbedded build system has installed packages.

11177

You can specify functions separated by semicolons:

11178

11179

ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

11185

within a function, you can use

11186

<filename>${IMAGE_ROOTFS}</filename>, which points to

11187

the directory that becomes the root filesystem image.

11188

See the

11189

11190

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>

11196

<info>

11197

ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."

</info>

11202

Specifies a list of functions to call once the

11203

OpenEmbedded build system has created the root filesystem.

11204

You can specify functions separated by semicolons:

11205

11206

ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

11212

within a function, you can use

11213

<filename>${IMAGE_ROOTFS}</filename>, which points to

11214

the directory that becomes the root filesystem image.

11215

See the

11216

11217

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>

11223

<info>

11224

ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."

</info>

11229

Specifies a list of functions to call after the

11230

OpenEmbedded build system has removed unnecessary

11231

packages.

11232

When runtime package management is disabled in the

11233

image, several packages are removed including

11234

<filename>base-passwd</filename>,

11235

<filename>shadow</filename>, and

11236

<filename>update-alternatives</filename>.

11237

You can specify functions separated by semicolons:

11238

11239

ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

11245

within a function, you can use

11246

<filename>${IMAGE_ROOTFS}</filename>, which points to

11247

the directory that becomes the root filesystem image.

11248

See the

11249

11250

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>

11256

<info>

11257

ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."

</info>

11262

Specifies a list of functions to call before the

11263

OpenEmbedded build system has created the root filesystem.

11264

You can specify functions separated by semicolons:

11265

11266

ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

11272

within a function, you can use

11273

<filename>${IMAGE_ROOTFS}</filename>, which points to

11274

the directory that becomes the root filesystem image.

11275

See the

11276

11277

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>

11283

<info>

11284

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>

11289

A list of package name aliases that a package also provides.

11290

These aliases are useful for satisfying runtime dependencies

11291

of other packages both during the build and on the target

11292

(as specified by

11293

<filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).

11294

<note>

11295

A package's own name is implicitly already in its

11296

<filename>RPROVIDES</filename> list.

</note>

</para>

<para>

As with all package-controlling variables, you must always

11302

use the variable in conjunction with a package name override.

11303

Here is an example:

11304

11305

RPROVIDES_${PN} = "widget-abi-2"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>

11312

<info>

11313

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>

11318

A list of packages that extends the usability of a package

11319

being built.

11320

The package being built does not depend on this list of

11321

packages in order to successfully build, but rather

11322

uses them for extended usability.

11323

To specify runtime dependencies for packages, see the

11324

<filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>

variable.

</para>

<para>

The package manager will automatically install the

11330

<filename>RRECOMMENDS</filename> list of packages when

11331

installing the built package.

11332

However, you can prevent listed packages from being

11333

installed by using the

and

variables.

</para>

<para>

Packages specified in

11343

<filename>RRECOMMENDS</filename> need not actually be

11344

produced.

11345

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.

11353

If such a recipe does exist and the package is not produced,

11354

the build continues without error.

</para>

<para>

Because the <filename>RRECOMMENDS</filename> variable

11359

applies to packages being built, you should always attach

11360

an override to the variable to specify the particular

11361

package whose usability is being extended.

11362

For example, suppose you are building a development package

11363

that is extended to support wireless functionality.

11364

In this case, you would use the following:

11365

11366

RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>"

11367

</literallayout>

11368

In the example, the package name

11369

(<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)

11370

must appear as it would in the

11371

<filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>

11372

namespace before any renaming of the output package by

11373

classes such as <filename>debian.bbclass</filename>.

</para>

<para>

BitBake, which the OpenEmbedded build system uses, supports

11378

specifying versioned recommends.

11379

Although the syntax varies depending on the packaging

11380

format, BitBake hides these differences from you.

11381

Here is the general syntax to specify versions with

11382

the <filename>RRECOMMENDS</filename> variable:

11383

11384

RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

11385

</literallayout>

11386

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a recommend on version

11396

1.2 or greater of the package <filename>foo</filename>:

11397

11398

RRECOMMENDS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>

11405

<info>

11406

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>

11411

A list of packages replaced by a package.

11412

The package manager uses this variable to determine which

11413

package should be installed to replace other package(s)

11414

during an upgrade.

11415

In order to also have the other package(s) removed at the

11416

same time, you must add the name of the other

11417

package to the

11418

<filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.

</para>

<para>

As with all package-controlling variables, you must use

11423

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

11433

specifying versioned replacements.

11434

Although the syntax varies depending on the packaging

11435

format, BitBake hides these differences from you.

11436

Here is the general syntax to specify versions with

11437

the <filename>RREPLACES</filename> variable:

11438

11439

RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

11440

</literallayout>

11441

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a replacement using

11451

version 1.2 or greater of the package

11452

<filename>foo</filename>:

11453

11454

RREPLACES_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>

11461

<info>

11462

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>

11467

A list of additional packages that you can suggest for

11468

installation by the package manager at the time a package

11469

is installed.

11470

Not all package managers support this functionality.

</para>

<para>

As with all package-controlling variables, you must always

11475

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>

11496

The location in the

11497

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>

11498

where unpacked recipe source code resides.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11499

By default, this directory is

11500

<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>,

11501

where <filename>${BPN}</filename> is the base recipe name

11502

and <filename>${PV}</filename> is the recipe version.

11503

If the source tarball extracts the code to a directory

11504

named anything other than <filename>${BPN}-${PV}</filename>,

11505

or if the source code if fetched from an SCM such as

11506

Git or Subversion, then you must set <filename>S</filename>

11507

in the recipe so that the OpenEmbedded build system

11508

knows where to find the unpacked source.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

As an example, assume a

11513

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

11514

top-level folder named <filename>poky</filename> and a

11515

default Build Directory at <filename>poky/build</filename>.

11516

In this case, the work directory the build system uses

11517

to keep the unpacked recipe for <filename>db</filename>

11518

is the following:

11519

11520

poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19

11521

</literallayout>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11522

The unpacked source code resides in the

11523

<filename>db-5.1.19</filename> folder.

</para>

<para>

This next example assumes a Git repository.

11528

By default, Git repositories are cloned to

11529

<filename>${WORKDIR}/git</filename> during

11530

11531

Since this path is different from the default value of

11532

<filename>S</filename>, you must set it specifically

11533

so the source can be located:

11534

11535

SRC_URI = "git://path/to/repo.git"

11536

S = "${WORKDIR}/git"

11537

</literallayout>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm>SANITY_REQUIRED_UTILITIES</glossterm>

11543

<info>

11544

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>

11549

Specifies a list of command-line utilities that should be

11550

checked for during the initial sanity checking process when

11551

running BitBake.

11552

If any of the utilities are not installed on the build host,

11553

then BitBake immediately exits with an error.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>

11559

<info>

11560

SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against."

</info>

11565

A list of the host distribution identifiers that the

11566

build system has been tested against.

11567

Identifiers consist of the host distributor ID

11568

followed by the release,

11569

as reported by the <filename>lsb_release</filename> tool

11570

or as read from <filename>/etc/lsb-release</filename>.

11571

Separate the list items with explicit newline

11572

characters (<filename>\n</filename>).

11573

If <filename>SANITY_TESTED_DISTROS</filename> is not empty

11574

and the current value of

11575

11576

does not appear in the list, then the build system reports

11577

a warning that indicates the current host distribution has

11578

not been tested as a build host.

</para>

</glossdef>

</glossentry>

<info>

SDK_ARCH[doc] = "The target architecture for the SDK."

</info>

11590

The target architecture for the SDK.

11591

Typically, you do not directly set this variable.

Instead, use

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>

11599

<info>

11600

SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed."

</info>

11605

The directory set up and used by the

11606

11607

to which the SDK is deployed.

11608

The <filename>populate_sdk_base</filename> class defines

11609

<filename>SDK_DEPLOY</filename> as follows:

11610

11611

SDK_DEPLOY = "${<link linkend='var-TMPDIR'>TMPDIR</link>}/deploy/sdk"

</literallayout>

</para>

</glossdef>

</glossentry>

<info>

SDK_DIR[doc] = "The parent directory used by the OpenEmbedded build system when creating SDK output."

</info>

11624

The parent directory used by the OpenEmbedded build system

11625

when creating SDK output.

11626

The

11627

11628

class defines the variable as follows:

11629

11630

SDK_DIR = "${<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>}/sdk"

11631

</literallayout>

11632

<note>

11633

The <filename>SDK_DIR</filename> directory is a

11634

temporary directory as it is part of

11635

<filename>WORKDIR</filename>.

11636

The final output directory is

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11643

11644

<info>

11645

SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK."

</info>

11650

Controls whether or not shared state artifacts are copied

11651

into the extensible SDK.

11652

The default value of "full" copies all of the required

11653

shared state artifacts into the extensible SDK.

11654

The value "minimal" leaves these artifacts out of the

11655

SDK.

11656

<note>

11657

If you set the variable to "minimal", you need to

11658

ensure

11659

11660

is set in the SDK's configuration to enable the

11661

artifacts to be fetched as needed.

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11667

<glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm>

11668

<info>

11669

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>

11674

The manifest file for the host part of the SDK.

11675

This file lists all the installed packages that make up

11676

the host part of SDK.

11677

The file contains package information on a line-per-package

11678

basis as follows:

11679

11680

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

11688

11689

SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"

11690

</literallayout>

11691

The location is derived using the

and

variables.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11700

<glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm>

11701

<info>

11702

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>

11707

When set to "1", specifies to include the packagedata for

11708

all recipes in the "world" target in the extensible SDK.

11709

Including this data allows the

11710

<filename>devtool search</filename> command to find these

11711

recipes in search results, as well as allows the

11712

<filename>devtool add</filename> command to map

11713

dependencies more effectively.

11714

<note>

11715

Enabling the <filename>SDK_INCLUDE_PKGDATA</filename>

11716

variable significantly increases build time because

11717

all of world needs to be built.

11718

Enabling the variable also slightly increases the size

11719

of the extensible SDK.

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

11725

<glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm>

11726

<info>

11727

SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK."

</info>

11732

When set to "1", specifies to include the toolchain in the

11733

extensible SDK.

11734

Including the toolchain is useful particularly when

11735

11736

is set to "minimal" to keep the SDK reasonably small

11737

but you still want to provide a usable toolchain.

11738

For example, suppose you want to use the toolchain from an

11739

IDE (e.g. Eclipse) or from other tools and you do not

11740

want to perform additional steps to install the toolchain.

</para>

<para>

The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable

11745

defaults to "0" if <filename>SDK_EXT_TYPE</filename>

11746

is set to "minimal", and defaults to "1" if

11747

<filename>SDK_EXT_TYPE</filename> is set to "full".

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11752

<glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm>

11753

<info>

11754

SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration."

</info>

11759

A list of classes to remove from the

11760

11761

value globally within the extensible SDK configuration.

11762

The default value is "buildhistory icecc".

</para>

<para>

Some classes are not generally applicable within

11767

the extensible SDK context and you can use this variable

to disable them.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_LOCAL_CONF_BLACKLIST'><glossterm>SDK_LOCAL_CONF_BLACKLIST</glossterm>

11774

<info>

11775

SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration."

</info>

11780

A list of variables not allowed through from the build

11781

system configuration into the extensible SDK configuration.

11782

Usually, these are variables that are specific to the

11783

machine on which the build system is running and thus

11784

would be potentially problematic within the extensible SDK.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm>

11790

<info>

11791

SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration."

</info>

11796

A list of variables allowed through from the build system

11797

configuration into the extensible SDK configuration.

11798

This list overrides the variables specified using the

11799

11800

variable as well as any variables identified by automatic

11801

blacklisting due to the "/" character being found at the

11802

start of the value, which is usually indicative of being a

11803

path and thus might not be valid on the system where the

SDK is installed.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11809

11810

<info>

11811

SDK_NAME[doc] = "The base name for SDK output files."

</info>

11816

The base name for SDK output files.

11817

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>

11839

Specifies the operating system for which the SDK

11840

will be built.

11841

The default value is the value of

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>

11848

<info>

11849

SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output."

</info>

11854

The location used by the OpenEmbedded build system when

creating SDK output.

The

class defines the variable as follows:

11859

11860

SDK_OUTPUT = "${<link linkend='var-SDK_DIR'>SDK_DIR</link>}/image"

11861

</literallayout>

11862

<note>

11863

The <filename>SDK_OUTPUT</filename> directory is a

11864

temporary directory as it is part of

11865

<filename>WORKDIR</filename> by way of

11866

<filename>SDK_DIR</filename>.

11867

The final output directory is

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>

11875

<info>

11876

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>

11881

Specifies a list of architectures compatible with

11882

the SDK machine.

11883

This variable is set automatically and should not

11884

normally be hand-edited.

11885

Entries are separated using spaces and listed in order

11886

of priority.

11887

The default value for

11888

<filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch

11889

${SDK_ARCH}-${SDKPKGSUFFIX}".

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>

11895

<info>

11896

SDK_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the SDK."

</info>

11901

Specifies a list of functions to call once the

11902

OpenEmbedded build system has created the SDK.

11903

You can specify functions separated by semicolons:

11904

11905

SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass an SDK path to a command within a

11911

function, you can use

11912

<filename>${SDK_DIR}</filename>, which points to

11913

the parent directory used by the OpenEmbedded build system

11914

when creating SDK output.

11915

See the

11916

11917

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>

11923

<info>

11924

SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."

</info>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11929

The toolchain binary prefix used for

11930

<filename>nativesdk</filename> recipes.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11931

The OpenEmbedded build system uses the

11932

<filename>SDK_PREFIX</filename> value to set the

11933

11934

when building <filename>nativesdk</filename> recipes.

11935

The default value is "${SDK_SYS}-".

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11940

<glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm>

11941

<info>

11942

SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK."

</info>

11947

A list of shared state tasks added to the extensible SDK.

11948

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

11956

<filename>SDK_RECRDEP_TASKS</filename> variable, the

11957

above four tasks are always added to the SDK.

11958

To specify tasks beyond these four, you need to use

11959

the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g.

11960

you are defining additional tasks that are needed in

order to build

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11967

11968

<info>

11969

SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built."

</info>

11974

Specifies the system, including the architecture and the

11975

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>

11992

<info>

11993

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>

11998

The manifest file for the target part of the SDK.

11999

This file lists all the installed packages that make up

12000

the target part of the SDK.

12001

The file contains package information on a line-per-package

12002

basis as follows:

12003

12004

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

12012

12013

SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"

12014

</literallayout>

12015

The location is derived using the

and

variables.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

12024

<glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm>

12025

<info>

12026

SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation."

</info>

12031

A list of targets to install from shared state as part of

12032

the standard or extensible SDK installation.

12033

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

12039

internal variable and typically would not be changed.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm>

12045

<info>

12046

SDK_TITLE[doc] = "Specifies a title to be printed when running the SDK installer."

</info>

12051

Specifies a title to be printed when running the SDK

12052

installer.

12053

The <filename>SDK_TITLE</filename> variable defaults to

12054

"<replaceable>distro</replaceable> SDK" for the standard

12055

SDK and "<replaceable>distro</replaceable> Extensible SDK"

12056

for the extensible SDK, where

12057

<replaceable>distro</replaceable> is the first one of

or

that is set in your configuration.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_UPDATE_URL'><glossterm>SDK_UPDATE_URL</glossterm>

12067

<info>

12068

SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK."

</info>

12073

An optional URL for an update server for the extensible

12074

SDK.

12075

If set, the value is used as the default update server when

12076

running <filename>devtool sdk-update</filename> within the

extensible SDK.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12082

<glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm>

12083

<info>

12084

SDK_VENDOR[doc] = "Specifies the name of the SDK vendor."

</info>

12089

Specifies the name of the SDK vendor.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_VERSION'><glossterm>SDK_VERSION</glossterm>

12095

<info>

12096

SDK_VERSION[doc] = "Specifies the version for the SDK."

</info>

12101

Specifies the version of the SDK.

12102

The distribution configuration file (e.g.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

12103

<filename>/meta-poky/conf/distro/poky.conf</filename>)

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12104

defines the <filename>SDK_VERSION</filename> as follows:

12105

12106

SDK_VERSION := "${@'${DISTRO_VERSION}'.replace('snapshot-${DATE}','snapshot')}"

</literallayout>

</para>

<para>

For additional information, see the

and

variables.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>

12121

<info>

12122

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>

12127

Equivalent to

12128

<filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.

12129

However, this variable applies to the SDK generated from an

12130

image using the following command:

12131

12132

$ bitbake -c populate_sdk <replaceable>imagename</replaceable>

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>

12139

<info>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

12140

SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK items."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

12145

The machine for which the SDK is built.

12146

In other words, the SDK is built such that it

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12147

runs on the target you specify with the

12148

<filename>SDKMACHINE</filename> value.

12149

The value points to a corresponding

12150

<filename>.conf</filename> file under

12151

<filename>conf/machine-sdk/</filename>.

</para>

<para>

You can use "i686" and "x86_64" as possible values

12156

for this variable. The variable defaults to "i686"

12157

and is set in the local.conf file in the Build Directory.

SDKMACHINE ?= "i686"

</literallayout>

<note>

You cannot set the <filename>SDKMACHINE</filename>

12163

variable in your distribution configuration file.

12164

If you do, the configuration will not take affect.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>

12171

<info>

12172

SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system."

</info>

12177

Defines the path offered to the user for installation

12178

of the SDK that is generated by the OpenEmbedded build

12179

system.

12180

The path appears as the default location for installing

12181

the SDK when you run the SDK's installation script.

12182

You can override the offered path when you run the

script.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm>

12189

<info>

12190

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>

12195

The full path to the sysroot used for cross-compilation

12196

within an SDK as it will be when installed into the

default

</para>

</glossdef>

</glossentry>

<glossentry id='var-SECTION'><glossterm>SECTION</glossterm>

12204

<info>

12205

SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable."

</info>

12210

The section in which packages should be categorized.

12211

Package management utilities can make use of this variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>

12217

<info>

12218

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>

12223

Specifies the optimization flags passed to the C compiler

12224

when building for the target.

12225

The flags are passed through the default value of the

variable.

</para>

<para>

The <filename>SELECTED_OPTIMIZATION</filename> variable

12232

takes the value of

12233

<filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>

12234

unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".

12235

If that is the case, the value of

12236

<filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>

12242

<info>

12243

SERIAL_CONSOLE[doc] = "The speed and device for the serial port used to attach the serial console. This variable is given to the kernel as the 'console' parameter. After booting occurs, getty is started on that port so remote login is possible."

</info>

12248

Defines a serial console (TTY) to enable using getty.

12249

Provide a value that specifies the baud rate followed by

12250

the TTY device name separated by a space.

12251

You cannot specify more than one TTY device:

12252

12253

SERIAL_CONSOLE = "115200 ttyS0"

12254

</literallayout>

12255

<note>

12256

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>

12267

<info>

12268

SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty."

</info>

12273

Defines the serial consoles (TTYs) to enable using getty.

12274

Provide a value that specifies the baud rate followed by

12275

the TTY device name separated by a semicolon.

12276

Use spaces to separate multiple devices:

12277

12278

SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>

12285

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12286

SERIAL_CONSOLES_CHECK[doc] = "Selected SERIAL_CONSOLES to check against /proc/console before enabling using getty. Supported only by SysVinit."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12291

Specifies serial consoles, which must be listed in

12292

12293

to check against <filename>/proc/console</filename>

12294

before enabling them using getty.

12295

This variable allows aliasing in the format:

12296

<device>:<alias>.

12297

If a device was listed as "sclp_line0"

12298

in <filename>/dev/</filename> and "ttyS0" was listed

12299

in <filename>/proc/console</filename>, you would do the

12300

following:

12301

12302

SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"

12303

</literallayout>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12304

This variable is currently only supported with SysVinit

12305

(i.e. not with systemd).

</para>

</glossdef>

</glossentry>

<glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>

12311

<info>

12312

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>

12317

A list of recipe dependencies that should not be used to

12318

determine signatures of tasks from one recipe when they

12319

depend on tasks from another recipe.

12320

For example:

12321

12322

SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"

</literallayout>

</para>

<para>

In this example, <filename>intone</filename> depends on

12328

<filename>mplayer2</filename>.

</para>

<para>

Use of this variable is one mechanism to remove dependencies

12333

that affect task signatures and thus force rebuilds when a

12334

recipe changes.

12335

<note><title>Caution</title>

12336

If you add an inappropriate dependency for a recipe

12337

relationship, the software might break during

12338

runtime if the interface of the second recipe was

12339

changed after the first recipe had been built.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>

12346

<info>

12347

SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change."

</info>

12352

A list of recipes that are completely stable and will

12353

never change.

12354

The ABI for the recipes in the list are presented by

12355

output from the tasks run to build the recipe.

12356

Use of this variable is one way to remove dependencies from

12357

one recipe on another that affect task signatures and

12358

thus force rebuilds when the recipe changes.

12359

<note><title>Caution</title>

12360

If you add an inappropriate variable to this list,

12361

the software might break at runtime if the

12362

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>

12370

<info>

12371

SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU."

</info>

12376

Specifies the number of bits for the target system CPU.

12377

The value should be either "32" or "64".

</para>

</glossdef>

</glossentry>

<glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>

12383

<info>

12384

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>

12389

Specifies the endian byte order of the target system.

12390

The value should be either "le" for little-endian or "be" for big-endian.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12395

<glossentry id='var-SKIP_FILEDEPS'><glossterm>SKIP_FILEDEPS</glossterm>

12396

<info>

12397

SKIP_FILEDEPS[doc] = "Enables you to remove all files from

12398

the "Provides" section of an RPM package."

</info>

12403

Enables removal of all files from the "Provides" section of

12404

an RPM package.

12405

Removal of these files is required for packages containing

12406

prebuilt binaries and libraries such as

12407

<filename>libstdc++</filename> and

12408

<filename>glibc</filename>.

</para>

<para>

To enable file removal, set the variable to "1" in your

12413

<filename>conf/local.conf</filename> configuration file

12414

in your:

12415

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

SKIP_FILEDEPS = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12423

<glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>

12424

<info>

12425

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>

12430

Groups together machines based upon the same family

12431

of SOC (System On Chip).

12432

You typically set this variable in a common

12433

<filename>.inc</filename> file that you include in the

12434

configuration files of all the machines.

12435

<note>

12436

You must include

12437

<filename>conf/machine/include/soc-family.inc</filename>

12438

for this variable to appear in

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>

12446

<info>

12447

SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform."

</info>

12452

Defines the suffix for shared libraries used on the

12453

target platform.

12454

By default, this suffix is ".so.*" for all Linux-based

12455

systems and is defined in the

12456

<filename>meta/conf/bitbake.conf</filename> configuration

file.

</para>

<para>

You will see this variable referenced in the default values

12462

of <filename>FILES_${PN}</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>

12468

<info>

12469

SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform."

</info>

12474

Defines the suffix for the development symbolic link

12475

(symlink) for shared libraries on the target platform.

12476

By default, this suffix is ".so" for Linux-based

12477

systems and is defined in the

12478

<filename>meta/conf/bitbake.conf</filename> configuration

file.

</para>

<para>

You will see this variable referenced in the default values

12484

of <filename>FILES_${PN}-dev</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm>

12490

<info>

12491

SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks."

</info>

12496

When you are fetching files to create a mirror of sources

12497

(i.e. creating a source mirror), setting

12498

<filename>SOURCE_MIRROR_FETCH</filename> to "1" in your

12499

<filename>local.conf</filename> configuration file ensures

12500

the source for all recipes are fetched regardless of

12501

whether or not a recipe is compatible with the

12502

configuration.

12503

A recipe is considered incompatible with the currently

12504

configured machine when either or both the

variable and

variables specify compatibility with a machine other

12509

than that of the current machine or host.

12510

<note><title>Warning</title>

12511

Do not set the

12512

<filename>SOURCE_MIRROR_FETCH</filename> variable

12513

unless you are creating a source mirror.

12514

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>

12522

<info>

12523

SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI."

</info>

12528

Defines your own

12529

12530

from which to first fetch source before attempting to fetch

12531

from the upstream specified in

</para>

<para>

To use this variable, you must globally inherit the

12537

12538

class and then provide the URL to your mirrors.

12539

Here is the general syntax:

12540

12541

INHERIT += "own-mirrors"

12542

SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>"

12543

</literallayout>

12544

<note>

12545

You can specify only a single URL in

12546

<filename>SOURCE_MIRROR_URL</filename>.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>

12553

<info>

12554

SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/."

</info>

12559

Maps commonly used license names to their SPDX counterparts

12560

found in <filename>meta/files/common-licenses/</filename>.

12561

For the default <filename>SPDXLICENSEMAP</filename>

12562

mappings, see the

12563

<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>

12575

<info>

12576

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>

12581

A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the

12582

OpenEmbedded build system to create variants of recipes or packages.

12583

The list specifies the prefixes to strip off during certain circumstances

12584

such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.

</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>

12596

The list of source files - local or remote.

12597

This variable tells the OpenEmbedded build system which bits

12598

to pull in for the build and how to pull them in.

12599

For example, if the recipe or append file only needs to

12600

fetch a tarball from the Internet, the recipe or

12601

append file uses a single <filename>SRC_URI</filename>

12602

entry.

12603

On the other hand, if the recipe or append file needs to

12604

fetch a tarball, apply two patches, and include a custom

12605

file, the recipe or append file would include four

12606

instances of the variable.

12607

</para>

12608

12609

<para>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12610

The following list explains the available URI protocols.

12611

URI protocols are highly dependent on particular BitBake

12612

Fetcher submodules.

12613

Depending on the fetcher BitBake uses, various URL

12614

parameters are employed.

12615

For specifics on the supported Fetchers, see the

12616

"<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"

12617

section in the BitBake User Manual.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12618

12619

12620

Fetches files, which are usually files shipped with

12621

the

12622

<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,

12623

from the local machine.

12624

The path is relative to the

12625

12626

variable.

12627

Thus, the build system searches, in order, from the

12628

following directories, which are assumed to be a

12629

subdirectories of the directory in which the

12630

recipe file (<filename>.bb</filename>) or

12631

append file (<filename>.bbappend</filename>)

resides:

The base recipe name without any special

12636

suffix or version numbers.

12637

</para></listitem>

12638

12639

<filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.

12640

The base recipe name and version but without

12641

any special package name suffix.

12642

</para></listitem>

12643

<listitem><para><emphasis>files -</emphasis>

12644

Files within a directory, which is named

12645

<filename>files</filename> and is also

12646

alongside the recipe or append file.

</para></listitem>

</itemizedlist>

<note>

If you want the build system to pick up files

12651

specified through a

12652

12653

statement from your append file, you need to be

12654

sure to extend the

12655

<filename>FILESPATH</filename>

12656

variable by also using the

12657

12658

variable from within your append file.

12659

</note>

12660

</para></listitem>

12661

<listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a

12662

Bazaar revision control repository.</para></listitem>

12663

<listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a

12664

Git revision control repository.</para></listitem>

12665

<listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from

12666

an OSC (OpenSUSE Build service) revision control repository.</para></listitem>

12667

<listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from

12668

a repo (Git) repository.</para></listitem>

12669

12670

Fetches files from a ClearCase repository.

12671

</para></listitem>

12672

<listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from

12673

the Internet using <filename>http</filename>.</para></listitem>

12674

<listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files

12675

from the Internet using <filename>https</filename>.</para></listitem>

12676

<listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files

12677

from the Internet using <filename>ftp</filename>.</para></listitem>

12678

<listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from

12679

a CVS revision control repository.</para></listitem>

12680

<listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from

12681

a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>

12682

<listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from

12683

a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>

12684

<listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from

12685

a secure shell.</para></listitem>

12686

<listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from

12687

a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>

</itemizedlist>

</para>

<para>

Standard and recipe-specific options for <filename>SRC_URI</filename> exist.

12693

Here are standard options:

12694

12695

<listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply

12696

the patch or not.

12697

The default action is to apply the patch.</para></listitem>

12698

<listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which

12699

striplevel to use when applying the patch.

12700

The default level is 1.</para></listitem>

12701

<listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies

12702

the directory in which the patch should be applied.

12703

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:

12710

12711

<listitem><para><emphasis><filename>mindate</filename> -</emphasis>

12712

Apply the patch only if

12713

12714

is equal to or greater than <filename>mindate</filename>.

12715

</para></listitem>

12716

<listitem><para><emphasis><filename>maxdate</filename> -</emphasis>

12717

Apply the patch only if <filename>SRCDATE</filename>

12718

is not later than <filename>mindate</filename>.

12719

</para></listitem>

12720

<listitem><para><emphasis><filename>minrev</filename> -</emphasis>

12721

Apply the patch only if <filename>SRCREV</filename>

12722

is equal to or greater than <filename>minrev</filename>.

12723

</para></listitem>

12724

<listitem><para><emphasis><filename>maxrev</filename> -</emphasis>

12725

Apply the patch only if <filename>SRCREV</filename>

12726

is not later than <filename>maxrev</filename>.

12727

</para></listitem>

12728

12729

Apply the patch only if <filename>SRCREV</filename>

12730

is equal to <filename>rev</filename>.

12731

</para></listitem>

12732

<listitem><para><emphasis><filename>notrev</filename> -</emphasis>

12733

Apply the patch only if <filename>SRCREV</filename>

12734

is not equal to <filename>rev</filename>.

</para></listitem>

</itemizedlist>

</para>

<para>

Here are some additional options worth mentioning:

12741

12742

<listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls

12743

whether or not to unpack the file if it is an archive.

12744

The default action is to unpack the file.</para></listitem>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12745

<listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file

12746

(or extracts its contents) into the specified

12747

subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

12748

when the Git fetcher is used.

12749

</para></listitem>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12750

<listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file

12751

(or extracts its contents) into the specified

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12752

subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

12753

when the local (<filename>file://</filename>)

12754

fetcher is used.

12755

</para></listitem>

12756

<listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file

12757

(or extracts its contents) into the specified

12758

subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

12759

when the CVS fetcher is used.

12760

</para></listitem>

12761

<listitem><para><emphasis><filename>subpath</filename> -</emphasis>

12762

Limits the checkout to a specific subpath of the

12763

tree when using the Git fetcher is used.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12764

</para></listitem>

12765

<listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a

12766

name to be used for association with <filename>SRC_URI</filename> checksums

12767

when you have more than one file specified in <filename>SRC_URI</filename>.

12768

</para></listitem>

12769

<listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies

12770

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>

12777

<info>

12778

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>

12783

By default, the OpenEmbedded build system automatically detects whether

12784

12785

contains files that are machine-specific.

12786

If so, the build system automatically changes

12787

<filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.

12788

Setting this variable to "0" disables this behavior.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>

12794

<info>

12795

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>

12800

The date of the source code used to build the package.

12801

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>

12807

<info>

12808

SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV."

</info>

12813

Returns the version string of the current package.

12814

This string is used to help define the value of

</para>

<para>

The <filename>SRCPV</filename> variable is defined in the

12820

<filename>meta/conf/bitbake.conf</filename> configuration

12821

file in the

12822

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

12823

as follows:

12824

12825

SRCPV = "${@bb.fetch2.get_srcrev(d)}"

</literallayout>

</para>

<para>

Recipes that need to define <filename>PV</filename> do so

12831

with the help of the <filename>SRCPV</filename>.

12832

For example, the <filename>ofono</filename> recipe

12833

(<filename>ofono_git.bb</filename>) located in

12834

<filename>meta/recipes-connectivity</filename> in the

12835

Source Directory defines <filename>PV</filename> as

12836

follows:

12837

12838

PV = "0.12-git${SRCPV}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>

12845

<info>

12846

SRCREV[doc] = "The revision of the source code used to build the package. This variable applies to Subversion, Git, Mercurial and Bazaar only."

</info>

12851

The revision of the source code used to build the package.

12852

This variable applies to Subversion, Git, Mercurial and

12853

Bazaar only.

12854

Note that if you want to build a fixed revision and you

12855

want to avoid performing a query on the remote repository

12856

every time BitBake parses your recipe, you should specify

12857

a <filename>SRCREV</filename> that is a

12858

full revision identifier and not just a tag.

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

12859

<note>

12860

For information on limitations when inheriting the

12861

latest revision of software using

12862

<filename>SRCREV</filename>, see the

12863

12864

variable description and the

12865

"<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"

12866

section, which is in the Yocto Project Development Manual.

12867

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12868

</para>

12869

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>

12874

<info>

12875

SSTATE_DIR[doc] = "The directory for the shared state cache."

</info>

12880

The directory for the shared state cache.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>

12886

<info>

12887

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 has been disabled by setting BB_NO_NETWORK to "1"."

</info>

12892

If set to "1", allows fetches from

12893

mirrors that are specified in

12894

12895

to work even when fetching from the network has been

12896

disabled by setting <filename>BB_NO_NETWORK</filename>

12897

to "1".

12898

Using the

12899

<filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>

12900

variable is useful if you have set

12901

<filename>SSTATE_MIRRORS</filename> to point to an

12902

internal server for your shared state cache, but

12903

you want to disable any other fetching from the network.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>

12909

<info>

12910

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>

12915

Configures the OpenEmbedded build system to search other

12916

mirror locations for prebuilt cache data objects before

12917

building out the data.

12918

This variable works like fetcher

12919

12920

and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>

12921

and points to the cache locations to check for the shared

objects.

</para>

<para>

You can specify a filesystem directory or a remote URL such

12927

as HTTP or FTP.

12928

The locations you specify need to contain the shared state

12929

cache (sstate-cache) results from previous builds.

12930

The sstate-cache you point to can also be from builds on

other machines.

</para>

<para>

If a mirror uses the same structure as

12936

12937

you need to add

12938

"PATH" at the end as shown in the examples below.

12939

The build system substitutes the correct path within the

12940

directory structure.

12941

12942

SSTATE_MIRRORS ?= "\

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12943

file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12944

file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH"

</literallayout>

</para>

</glossdef>

</glossentry>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

12950

<glossentry id='var-SSTATE_SCAN_FILES'><glossterm>SSTATE_SCAN_FILES</glossterm>

12951

<info>

12952

SSTATE_SCAN_FILES[doc] = "Controls the list of files the OpenEmbedded build system scans for hardcoded installation paths."

</info>

12957

Controls the list of files the OpenEmbedded build system

12958

scans for hardcoded installation paths. The variable uses a

12959

space-separated list of filenames (not paths) with standard

12960

wildcard characters allowed.

</para>

<para>

During a build, the OpenEmbedded build system creates a

12965

shared state (sstate) object during the first stage of

12966

preparing the sysroots. That object is scanned for

12967

hardcoded paths for original installation locations.

12968

The list of files that are scanned for paths is controlled

12969

by the <filename>SSTATE_SCAN_FILES</filename> variable.

12970

Typically, recipes add files they want to be scanned to the

12971

value of <filename>SSTATE_SCAN_FILES</filename> rather than

12972

the variable being comprehensively set. The

12973

12974

class specifies the default list of files.

</para>

<para>

For details on the process, see the

class.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12985

<glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>

12986

<info>

12987

STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host."

</info>

12992

Specifies the path to the <filename>/lib</filename>

12993

subdirectory of the sysroot directory for the

build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>

13000

<info>

13001

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>

13006

Specifies the path to the <filename>/lib</filename>

13007

subdirectory of the sysroot directory for the target

13008

for which the current recipe is being built

13009

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>

13015

<info>

13016

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>

13021

Specifies the path to the

13022

<filename>/usr/bin</filename> subdirectory of the

13023

sysroot directory for the target for which the current

13024

recipe is being built

13025

(<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>

13031

<info>

13032

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>

13037

Specifies the path to the directory containing binary

13038

configuration scripts.

13039

These scripts provide configuration information for

13040

other software that wants to make use of libraries or

13041

include files provided by the software associated with

13042

the script.

13043

<note>

13044

This style of build configuration has been largely

13045

replaced by <filename>pkg-config</filename>.

13046

Consequently, if <filename>pkg-config</filename>

13047

is supported by the library to which you are linking,

13048

it is recommended you use

13049

<filename>pkg-config</filename> instead of a

13050

provided configuration script.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>

13057

<info>

13058

STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host."

</info>

13063

Specifies the path to the

13064

<filename>/usr/bin</filename> subdirectory of the

13065

sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>

13071

<info>

13072

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>

13077

Specifies the path to the <filename>/usr/share</filename>

13078

subdirectory of the sysroot directory for the target

13079

for which the current recipe is being built

13080

(<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>

13086

<info>

13087

STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host."

</info>

13092

Specifies the path to the <filename>/usr/share</filename>

13093

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>

13099

<info>

13100

STAGING_DIR[doc] = "Specifies the path to the top-level sysroots directory (i.e. ${TMPDIR}/sysroots)."

</info>

13105

Specifies the path to the top-level sysroots directory

13106

(i.e.

13107

<filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots</filename>).

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

</para>

<para>

<filename>STAGING_DIR</filename> contains the directories

13112

that are staged into the sysroot by the

task.

See the

variable and the

"<ulink url='&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes'>Sharing Files Between Recipes</ulink>"

13119

section for more information.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13120

<note>

13121

Recipes should never write files directly under

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

13122

the <filename>STAGING_DIR</filename> directory because

13123

the OpenEmbedded build system

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13124

manages the directory automatically.

13125

Instead, files should be installed to

within your recipe's

task and then the OpenEmbedded build system will

13130

stage a subset of those files into the sysroot.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>

13137

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13138

STAGING_DIR_HOST[doc] = "Specifies the path to the sysroot directory for the system that the component is built to run on."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13143

Specifies the path to the sysroot directory for the system

13144

that the component is built to run on (the system that hosts

13145

the component).

13146

For most recipes, this sysroot is the one that the recipe's

13147

13148

task copies files into.

13149

Exceptions include <filename>-native</filename> recipes,

13150

where the <filename>do_populate_sysroot</filename> task

13151

instead uses

13152

13153

Depending on the type of recipe and the build target,

13154

<filename>STAGING_DIR_HOST</filename> can have the

13155

following values:

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13156

13157

<listitem><para>For recipes building for the target

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13158

machine, the value is

13159

"${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".

13160

</para></listitem>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

13161

<listitem><para>For native recipes building

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13162

for the build host, the value is empty given the

13163

assumption that when building for the build host,

13164

the build host's own directories should be used.

13165

13166

<filename>-native</filename> recipes are not

13167

installed into host paths like such as

13168

<filename>/usr</filename>.

13169

Rather, these recipes are installed into

13170

<filename>STAGING_DIR_NATIVE</filename>.

13171

When compiling <filename>-native</filename>

13172

recipes, standard build environment variables

such as

and

are set up so that both host paths and

13178

<filename>STAGING_DIR_NATIVE</filename> are

13179

searched for libraries and headers using, for

13180

example, GCC's <filename>-isystem</filename>

13181

option.</para>

13182

13183

<para>This emphasizes that the

13184

<filename>STAGING_DIR*</filename> variables

13185

should be viewed as input variables by tasks

such as

and

Having the real system root correspond to

13192

<filename>STAGING_DIR_HOST</filename> makes

13193

conceptual sense for

13194

<filename>-native</filename> recipes, as

13195

they make use of host headers and libraries.

13196

</para>

13197

</note>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

13198

</para></listitem>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>

13205

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13206

STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory used when building components that run on the build host itself."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13211

Specifies the path to the sysroot directory used when

13212

building components that run on the build host itself.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm>

13218

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13219

STAGING_DIR_TARGET[doc] = "Specifies the path to the sysroot used for the system for which the component generates code."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13224

Specifies the path to the sysroot used for the system for

13225

which the component generates code.

13226

For components that do not generate code, which is the

13227

majority, <filename>STAGING_DIR_TARGET</filename> is set

13228

to match

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

Some recipes build binaries that can run on the target

13234

system but those binaries in turn generate code for

13235

another different system (e.g. cross-canadian recipes).

13236

Using terminology from GNU, the primary system is referred

13237

to as the "HOST" and the secondary, or different, system is

13238

referred to as the "TARGET".

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13239

Thus, the binaries run on the "HOST" system

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13240

and generate binaries for the "TARGET" system.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13241

The <filename>STAGING_DIR_HOST</filename> variable points

13242

to the sysroot used for the "HOST" system, while

13243

<filename>STAGING_DIR_TARGET</filename>

13244

points to the sysroot used for the "TARGET" system.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm>

13250

<info>

13251

STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host."

</info>

13256

Specifies the path to the <filename>/etc</filename>

13257

subdirectory of the sysroot directory for the

build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>

13264

<info>

13265

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>

13270

Specifies the path to the <filename>/usr</filename>

13271

subdirectory of the sysroot directory for the target

13272

for which the current recipe is being built

13273

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>

13279

<info>

13280

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>

13285

Specifies the path to the

13286

<filename>/usr/include</filename> subdirectory of the

13287

sysroot directory for the target for which the current

13288

recipe being built

13289

(<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>

13295

<info>

13296

STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host."

</info>

13301

Specifies the path to the <filename>/usr/include</filename>

13302

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

13307

<glossentry id='var-STAGING_KERNEL_BUILDDIR'><glossterm>STAGING_KERNEL_BUILDDIR</glossterm>

13308

<info>

13309

STAGING_KERNEL_BUILDDIR[doc] = "Points to the directory containing the kernel build artifacts."

</info>

13314

Points to the directory containing the kernel build

13315

artifacts.

13316

Recipes building software that needs to access kernel

13317

build artifacts

13318

(e.g. <filename>systemtap-uprobes</filename>) can look in

13319

the directory specified with the

13320

<filename>STAGING_KERNEL_BUILDDIR</filename> variable to

13321

find these artifacts after the kernel has been built.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13326

<glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>

13327

<info>

13328

STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules."

</info>

13333

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>

13340

<info>

13341

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>

13346

Specifies the path to the <filename>/usr/lib</filename>

13347

subdirectory of the sysroot directory for the target for

13348

which the current recipe is being built

13349

(<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>

13355

<info>

13356

STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host."

</info>

13361

Specifies the path to the <filename>/usr/lib</filename>

13362

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAMP'><glossterm>STAMP</glossterm>

13368

<info>

13369

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>

13374

Specifies the base path used to create recipe stamp files.

13375

The path to an actual stamp file is constructed by evaluating this

13376

string and then appending additional information.

13377

Currently, the default assignment for <filename>STAMP</filename>

13378

as set in the <filename>meta/conf/bitbake.conf</filename> file

13379

is:

13380

13381

STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"

</literallayout>

</para>

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13386

For information on how BitBake uses stamp files to determine

13387

if a task should be rerun, see the

13388

"<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>"

section.

</para>

<para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13393

See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,

information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>

13405

<info>

13406

STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps."

</info>

13411

Specifies the base directory in which the OpenEmbedded

13412

build system places stamps.

13413

The default directory is

13414

<filename>${TMPDIR}/stamps</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STRIP'><glossterm>STRIP</glossterm>

13420

<info>

13421

STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)."

</info>

13426

The minimal command and arguments to run

13427

<filename>strip</filename>, which is used to strip

symbols.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>

13434

<info>

13435

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>

13440

The short (72 characters or less) summary of the binary package for packaging

13441

systems such as <filename>opkg</filename>, <filename>rpm</filename> or

13442

<filename>dpkg</filename>.

13443

By default, <filename>SUMMARY</filename> is used to define

13444

the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>

13445

variable if <filename>DESCRIPTION</filename> is not set

in the recipe.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>

13452

<info>

13453

SVNDIR[doc] = "The directory where Subversion checkouts will be stored."

</info>

13458

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>

13465

<info>

13466

SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console."

</info>

13471

Specifies the kernel boot default console.

13472

If you want to use a console other than the default,

13473

set this variable in your recipe as follows where "X" is

13474

the console number you want to use:

13475

13476

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>

13490

<info>

13491

SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file."

</info>

13496

Lists additional options to add to the syslinux file.

13497

You need to set this variable in your recipe.

13498

If you want to list multiple options, separate the options

13499

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>

13511

<info>

13512

SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off."

</info>

13517

Specifies the alternate serial port or turns it off.

13518

To turn off serial, set this variable to an empty string

13519

in your recipe.

13520

The variable's default value is set in the

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>

13535

<info>

13536

SYSLINUX_SPLASH[doc] = "An .LSS file used as the background for the VGA boot menu when you are using the boot menu."

</info>

13541

An <filename>.LSS</filename> file used as the background

13542

for the VGA boot menu when you are using the boot menu.

13543

You need to set this variable in your recipe.

</para>

<para>

The

class checks for this variable and if found, the

13550

OpenEmbedded build system installs the splash screen.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>

13556

<info>

13557

SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument."

</info>

13562

Specifies the alternate console=tty... kernel boot argument.

13563

The variable's default value is set in the

as follows:

SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"

</literallayout>

</para>

<para>

The class checks for and uses the variable as needed.

</para>

</glossdef>

</glossentry>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

13577

<glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm>

13578

<info>

13579

SYSROOT_DESTDIR[doc] = "Points to the temporary work directory (default ${WORKDIR}/sysroot-destdir) where the files that will be populated into the sysroot are assembled during the do_populate_sysroot task."

</info>

13584

Points to the temporary directory under the work directory

13585

(default

13586

<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destidir</filename>)

13587

where the files

13588

that will be populated into the sysroot are assembled

during the

task.

SYSROOT_DESTDIR ?= "console=ttyS0,115200"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13599

<glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>

13600

<info>

13601

SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task."

</info>

13606

Directories that are staged into the sysroot by the

13607

13608

task.

13609

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>

13624

<info>

13625

SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task."

</info>

13630

Directories that are not staged into the sysroot by the

13631

13632

task.

13633

You can use this variable to exclude certain subdirectories

13634

of directories listed in

13635

13636

from staging.

13637

By default, the following directories are not staged:

13638

13639

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>

13654

<info>

13655

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>

13660

Extra directories staged into the sysroot by the

13661

13662

task for <filename>-native</filename> recipes, in addition

13663

to those specified in

13664

13665

By default, the following extra directories are staged:

13666

13667

SYSROOT_DIRS_NATIVE = " \

${bindir} \

${sbindir} \

${base_bindir} \

${base_sbindir} \

${libexecdir} \

${sysconfdir} \

${localstatedir} \

"

</literallayout>

<note>

Programs built by <filename>-native</filename> recipes

13679

run directly from the sysroot

13680

(<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>),

13681

which is why additional directories containing program

13682

executables and supporting files need to be staged.

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13688

<glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>

13689

<info>

13690

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>

13695

A list of functions to execute after files are staged into

13696

the sysroot.

13697

These functions are usually used to apply additional

13698

processing on the staged files, or to stage additional

files.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>

13705

<info>

13706

SYSTEMD_AUTO_ENABLE[doc] = "For recipes that inherit the systemd class, this variable specifies whether the service you have specified in SYSTEMD_SERVICE should be started automatically or not."

</info>

13711

When inheriting the

13712

13713

class, this variable specifies whether the service you have

13714

specified in

13715

13716

should be started automatically or not.

13717

By default, the service is enabled to automatically start

13718

at boot time.

13719

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>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13734

<glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm>

13735

<info>

13736

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>

13741

When

13742

13743

is set to "systemd-boot", the

13744

<filename>SYSTEMD_BOOT_CFG</filename> variable specifies the

13745

configuration file that should be used.

13746

By default, the

13747

13748

class sets the <filename>SYSTEMD_BOOT_CFG</filename> as

13749

follows:

13750

13751

SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf"

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

13757

<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>

13763

<info>

13764

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 be installed containing one boot entry per file."

</info>

13769

When

13770

13771

is set to "systemd-boot", the

13772

<filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies

13773

a list of entry files

13774

(<filename>*.conf</filename>) to be installed

13775

containing one boot entry per file.

13776

By default, the

13777

13778

class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as

13779

follows:

13780

13781

SYSTEMD_BOOT_ENTRIES ?= ""

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

13787

<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>

13793

<info>

13794

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>

13799

When

13800

13801

is set to "systemd-boot", the

13802

<filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies

13803

the boot menu timeout in seconds.

13804

By default, the

13805

13806

class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as

13807

follows:

13808

13809

SYSTEMD_BOOT_TIMEOUT ?= "10"

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

13815

<ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13820

<glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>

13821

<info>

13822

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>

13827

When inheriting the

13828

13829

class, this variable locates the systemd unit files when

13830

they are not found in the main recipe's package.

13831

By default, the

13832

<filename>SYSTEMD_PACKAGES</filename> variable is set

13833

such that the systemd unit files are assumed to reside in

13834

the recipes main package:

13835

13836

SYSTEMD_PACKAGES ?= "${PN}"

</literallayout>

</para>

<para>

If these unit files are not in this recipe's main

13842

package, you need to use

13843

<filename>SYSTEMD_PACKAGES</filename> to list the package

13844

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>

13851

<info>

13852

SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package."

</info>

13857

When inheriting the

13858

13859

class, this variable specifies the systemd service name for

a package.

</para>

<para>

When you specify this file in your recipe, use a package

13865

name override to indicate the package to which the value

13866

applies.

13867

Here is an example from the connman recipe:

13868

13869

SYSTEMD_SERVICE_${PN} = "connman.service"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>

13876

<info>

13877

SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should be running a getty, the default is '1'."

</info>

13882

When using

13883

<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,

13884

specifies a space-separated list of the virtual terminals

13885

that should be running a

13886

<ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>

13887

(allowing login), assuming

is not set to "0".

</para>

<para>

The default value for

13894

<filename>SYSVINIT_ENABLED_GETTYS</filename> is "1"

13895

(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>

13911

This variable points to a directory were BitBake places

13912

temporary files, which consist mostly of task logs and

13913

scripts, when building a particular recipe.

13914

The variable is typically set as follows:

13915

13916

T = "${WORKDIR}/temp"

</literallayout>

</para>

<para>

The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

13922

is the directory into which BitBake unpacks and builds the

13923

recipe.

13924

The default <filename>bitbake.conf</filename> file sets this variable.</para>

13925

<para>The <filename>T</filename> variable is not to be confused with

13926

the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,

13927

which points to the root of the directory tree where BitBake

13928

places the output of an entire build.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>

13934

<info>

13935

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>

13940

The target machine's architecture.

13941

The OpenEmbedded build system supports many

13942

architectures.

13943

Here is an example list of architectures supported.

13944

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>

13967

<info>

13968

TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system."

</info>

13973

Specifies architecture-specific assembler flags for the

13974

target system.

13975

<filename>TARGET_AS_ARCH</filename> is initialized from

13976

13977

by default in the BitBake configuration file

13978

(<filename>meta/conf/bitbake.conf</filename>):

13979

13980

TARGET_AS_ARCH = "${TUNE_ASARGS}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>

13987

<info>

13988

TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system."

</info>

13993

Specifies architecture-specific C compiler flags for the

13994

target system.

13995

<filename>TARGET_CC_ARCH</filename> is initialized from

by default.

<note>

It is a common workaround to append

14000

14001

to <filename>TARGET_CC_ARCH</filename>

14002

in recipes that build software for the target that

14003

would not otherwise respect the exported

14004

<filename>LDFLAGS</filename> variable.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>

14011

<info>

14012

TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune."

</info>

14017

This is a specific kernel compiler flag for a CPU or

14018

Application Binary Interface (ABI) tune.

14019

The flag is used rarely and only for cases where a

14020

userspace

14021

14022

is not compatible with the kernel compilation.

14023

The <filename>TARGET_CC_KERNEL_ARCH</filename> variable

14024

allows the kernel (and associated modules) to use a

14025

different configuration.

14026

See the

14027

<filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>

14028

file in the

14029

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

for an example.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>

14036

<info>

14037

TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS."

</info>

14042

Specifies the flags to pass to the C compiler when building

14043

for the target.

14044

When building in the target context,

14045

14046

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

14051

the

14052

14053

variable in the environment to the

14054

<filename>TARGET_CFLAGS</filename> value so that

14055

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>

14062

<info>

14063

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>

14068

Specifies the flags to pass to the C pre-processor

14069

(i.e. to both the C and the C++ compilers) when building

14070

for the target.

14071

When building in the target context,

14072

14073

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

14078

the

14079

14080

variable in the environment to the

14081

<filename>TARGET_CPPFLAGS</filename> value so that

14082

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>

14089

<info>

14090

TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target."

</info>

14095

Specifies the flags to pass to the C++ compiler when

14096

building for the target.

14097

When building in the target context,

14098

14099

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

14104

the

14105

14106

variable in the environment to the

14107

<filename>TARGET_CXXFLAGS</filename> value so that

14108

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>

14115

<info>

14116

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>

14121

Specifies the method for handling FPU code.

14122

For FPU-less targets, which include most ARM CPUs, the variable must be

14123

set to "soft".

14124

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>

14130

<info>

14131

TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system."

</info>

14136

Specifies architecture-specific linker flags for the

14137

target system.

14138

<filename>TARGET_LD_ARCH</filename> is initialized from

14139

14140

by default in the BitBake configuration file

14141

(<filename>meta/conf/bitbake.conf</filename>):

14142

14143

TARGET_LD_ARCH = "${TUNE_LDARGS}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>

14150

<info>

14151

TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target."

</info>

14156

Specifies the flags to pass to the linker when building

14157

for the target.

14158

When building in the target context,

14159

14160

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

14165

the

14166

14167

variable in the environment to the

14168

<filename>TARGET_LDFLAGS</filename> value so that

14169

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>

14176

<info>

14177

TARGET_OS[doc] = "Specifies the target's operating system."

</info>

14182

Specifies the target's operating system.

14183

The variable can be set to "linux" for <filename>glibc</filename>-based systems and

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

14184

to "linux-musl" for <filename>musl</filename>.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

14185

For ARM/EABI targets, there are also "linux-gnueabi" and

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

14186

"linux-musleabi" values possible.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_PREFIX'><glossterm>TARGET_PREFIX</glossterm>

14192

<info>

14193

TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools."

</info>

14198

Specifies the prefix used for the toolchain binary target

tools.

</para>

<para>

Depending on the type of recipe and the build target,

14204

<filename>TARGET_PREFIX</filename> is set as follows:

14205

14206

14207

For recipes building for the target machine,

14208

the value is

14209

"${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".

14210

</para></listitem>

14211

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14212

For native recipes, the build system sets the

14213

variable to the value of

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

14214

<filename>BUILD_PREFIX</filename>.

14215

</para></listitem>

14216

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14217

For native SDK recipes

14218

(<filename>nativesdk</filename>), the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

14219

build system sets the variable to the value of

14220

<filename>SDK_PREFIX</filename>.

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm>

14228

<info>

14229

TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."

</info>

14234

Specifies the system, including the architecture and the

14235

operating system, for which the build is occurring in

14236

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

14249

<filename>TARGET_SYS</filename> variable yourself.

</note>

</para>

<para>

Consider these two examples:

14255

14256

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14257

Given a native recipe on a 32-bit, x86 machine

14258

running Linux, the value is "i686-linux".

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

14259

</para></listitem>

14260

14261

Given a recipe being built for a little-endian,

14262

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>

14271

<info>

14272

TARGET_VENDOR[doc] = "The name of the target vendor."

</info>

14277

Specifies the name of the target vendor.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm>

14283

<info>

14284

TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."

</info>

14289

Specifies a suffix to be appended onto the

14290

14291

value.

14292

The suffix identifies the <filename>libc</filename> variant

14293

for building.

14294

When you are building for multiple variants with the same

14295

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,

14296

this mechanism ensures that output for different

14297

<filename>libc</filename> variants is kept separate to

14298

avoid potential conflicts.

</para>

<para>

In the <filename>defaultsetup.conf</filename> file, the

14303

default value of <filename>TCLIBCAPPEND</filename> is

14304

"-${TCLIBC}".

14305

However, distros such as poky, which normally only support

14306

one <filename>libc</filename> variant, set

14307

<filename>TCLIBCAPPEND</filename> to "" in their distro

14308

configuration file resulting in no suffix being applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>

14314

<info>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

14315

TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc' or 'musl'."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

14320

Specifies the GNU standard C library (<filename>libc</filename>)

14321

variant to use during the build process.

14322

This variable replaces <filename>POKYLIBC</filename>, which is no longer

supported.

</para>

<para>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

14327

You can select "glibc" or "musl".

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>

14333

<info>

14334

TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'."

</info>

14339

Specifies the toolchain selector.

14340

<filename>TCMODE</filename> controls the characteristics

14341

of the generated packages and images by telling the

14342

OpenEmbedded build system which toolchain profile to use.

14343

By default, the OpenEmbedded build system builds its own

14344

internal toolchain.

14345

The variable's default value is "default", which uses

14346

that internal toolchain.

14347

<note>

14348

If <filename>TCMODE</filename> is set to a value

14349

other than "default", then it is your responsibility

14350

to ensure that the toolchain is compatible with the

14351

default toolchain.

14352

Using older or newer versions of these components

14353

might cause build problems.

14354

See the

14355

<ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>

14356

for the specific components with which the toolchain

must be compatible.

</note>

</para>

<para>

The <filename>TCMODE</filename> variable is similar to

14363

14364

which controls the variant of the GNU standard C library

14365

(<filename>libc</filename>) used during the build process:

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

14366

<filename>glibc</filename> or <filename>musl</filename>.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

With additional layers, it is possible to use a pre-compiled

14371

external toolchain.

14372

One example is the Sourcery G++ Toolchain.

14373

The support for this toolchain resides in the separate

14374

<trademark class='registered'>Mentor Graphics</trademark>

14375

<filename>meta-sourcery</filename> layer at

14376

<ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.

</para>

<para>

The layer's <filename>README</filename> file contains

14381

information on how to use the Sourcery G++ Toolchain as

14382

an external toolchain.

14383

In summary, you must be sure to add the layer to your

14384

<filename>bblayers.conf</filename> file in front of the

14385

<filename>meta</filename> layer and then set the

14386

<filename>EXTERNAL_TOOLCHAIN</filename>

14387

variable in your <filename>local.conf</filename> file

14388

to the location in which you installed the toolchain.

</para>

<para>

The fundamentals used for this example apply to any

14393

external toolchain.

14394

You can use <filename>meta-sourcery</filename> as a

14395

template for adding support for other external toolchains.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>

14401

<info>

14402

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>

14407

The location the OpenEmbedded build system uses to export

14408

tests when the

14409

14410

variable is set to "1".

</para>

<para>

The <filename>TEST_EXPORT_DIR</filename> variable defaults

14415

to <filename>"${TMPDIR}/testimage/${PN}"</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>

14421

<info>

14422

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>

14427

Specifies to export the tests only.

14428

Set this variable to "1" if you do not want to run the

14429

tests but you want them to be exported in a manner that

14430

you to run them outside of the build system.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>

14436

<info>

14437

TEST_IMAGE[doc] = "Enables test booting of virtual machine images under the QEMU emulator after any root filesystems are created and runs tests against those images."

</info>

14442

Automatically runs the series of automated tests for

14443

images when an image is successfully built.

</para>

<para>

These tests are written in Python making use of the

14448

<filename>unittest</filename> module, and the majority of

14449

them run commands on the target system over

14450

<filename>ssh</filename>.

14451

You can set this variable to "1" in your

14452

<filename>local.conf</filename> file in the

14453

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>

14454

to have the OpenEmbedded build system automatically run

14455

these tests after an image successfully builds:

TEST_IMAGE = "1"

</literallayout>

For more information on enabling, running, and writing

14460

these tests, see the

14461

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

14462

section in the Yocto Project Development Manual and the

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

14463

"<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

section.

</para>

</glossdef>

</glossentry>

<info>

TEST_LOG_DIR[doc] = "Holds the SSH log and the boot log for QEMU machines. The <filename>TEST_LOG_DIR</filename> variable defaults to "${WORKDIR}/testimage"."

</info>

14476

Holds the SSH log and the boot log for QEMU machines.

14477

The <filename>TEST_LOG_DIR</filename> variable defaults

14478

to <filename>"${WORKDIR}/testimage"</filename>.

14479

<note>

14480

Actual test results reside in the task log

14481

(<filename>log.do_testimage</filename>), which is in

14482

the <filename>${WORKDIR}/temp/</filename> directory.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>

14489

<info>

14490

TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test"

</info>

14495

For automated hardware testing, specifies the command to

14496

use to control the power of the target machine under test.

14497

Typically, this command would point to a script that

14498

performs the appropriate action (e.g. interacting

14499

with a web-enabled power strip).

14500

The specified command should expect to receive as the last

14501

argument "off", "on" or "cycle" specifying to power off,

14502

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>

14509

<info>

14510

TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD"

</info>

14515

For automated hardware testing, specifies additional

14516

arguments to pass through to the command specified in

14517

14518

Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>

14519

is optional.

14520

You can use it if you wish, for example, to separate the

14521

machine-specific and non-machine-specific parts of the

arguments.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>

14528

<info>

14529

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>

14534

The time in seconds allowed for an image to boot before

14535

automated runtime tests begin to run against an

14536

image.

14537

The default timeout period to allow the boot process to

14538

reach the login prompt is 500 seconds.

14539

You can specify a different value in the

14540

<filename>local.conf</filename> file.

</para>

<para>

For more information on testing images, see the

14545

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

14546

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>

14552

<info>

14553

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>

14558

For automated hardware testing, specifies the command

14559

to use to connect to the serial console of the target

14560

machine under test.

14561

This command simply needs to connect to the serial console

14562

and forward that connection to standard input and output

14563

as any normal terminal program does.

</para>

<para>

For example, to use the Picocom terminal program on

14568

serial device <filename>/dev/ttyUSB0</filename> at

14569

115200bps, you would set the variable as follows:

14570

14571

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>

14578

<info>

14579

TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD."

</info>

14584

For automated hardware testing, specifies additional

14585

arguments to pass through to the command specified in

14586

14587

Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>

14588

is optional.

14589

You can use it if you wish, for example, to separate the

14590

machine-specific and non-machine-specific parts of the

command.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>

14597

<info>

14598

TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected."

</info>

14603

The IP address of the build machine (host machine).

14604

This IP address is usually automatically detected.

14605

However, if detection fails, this variable needs to be set

14606

to the IP address of the build machine (i.e. where

14607

the build is taking place).

14608

<note>

14609

The <filename>TEST_SERVER_IP</filename> variable

14610

is only used for a small number of tests such as

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

14611

the "dnf" test suite, which needs to download

14612

packages from

14613

<filename>WORKDIR/oe-rootfs-repo</filename>.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>

14620

<info>

14621

TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine."

</info>

14626

Specifies the target controller to use when running tests

14627

against a test image.

14628

The default controller to use is "qemu":

TEST_TARGET = "qemu"

</literallayout>

</para>

<para>

A target controller is a class that defines how an

14636

image gets deployed on a target and how a target is started.

14637

A layer can extend the controllers by adding a module

14638

in the layer's <filename>/lib/oeqa/controllers</filename>

14639

directory and by inheriting the

14640

<filename>BaseTarget</filename> class, which is an abstract

14641

class that cannot be used as a value of

14642

<filename>TEST_TARGET</filename>.

</para>

<para>

You can provide the following arguments with

14647

<filename>TEST_TARGET</filename>:

14648

14649

<listitem><para><emphasis>"qemu" and "QemuTarget":</emphasis>

14650

Boots a QEMU image and runs the tests.

14651

See the

14652

"<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"

14653

section in the Yocto Project Development Manual for

14654

more information.

14655

</para></listitem>

14656

<listitem><para><emphasis>"simpleremote" and "SimpleRemoteTarget":</emphasis>

14657

Runs the tests on target hardware that is already

14658

up and running.

14659

The hardware can be on the network or it can be

14660

a device running an image on QEMU.

14661

You must also set

14662

14663

when you use "simpleremote" or "SimpleRemoteTarget".

14664

<note>

14665

This argument is defined in

14666

<filename>meta/lib/oeqa/targetcontrol.py</filename>.

14667

The small caps names are kept for compatibility

reasons.

</note>

</para></listitem>

<listitem><para><emphasis>"GummibootTarget":</emphasis>

14672

Automatically deploys and runs tests on an

14673

EFI-enabled machine that has a master image

14674

installed.

14675

<note>

14676

This argument is defined in

14677

<filename>meta/lib/oeqa/controllers/masterimage.py</filename>.

</note>

</para></listitem>

</itemizedlist>

</para>

<para>

For information on running tests on hardware, see the

14685

"<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"

14686

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>

14692

<info>

14693

TEST_TARGET_IP[doc] = "The IP address of your hardware under test."

</info>

14698

The IP address of your hardware under test.

14699

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"

14711

</literallayout>

14712

Specifying a port is useful when SSH is started on a

14713

non-standard port or in cases when your hardware under test

14714

is behind a firewall or network that is not directly

14715

accessible from your host and you need to do port address

translation.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>

14722

<info>

14723

TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing."

</info>

14728

An ordered list of tests (modules) to run against

14729

an image when performing automated runtime testing.

</para>

<para>

The OpenEmbedded build system provides a core set of tests

14734

that can be used against images.

14735

<note>

14736

Currently, there is only support for running these tests

14737

under QEMU.

14738

</note>

14739

Tests include <filename>ping</filename>,

14740

<filename>ssh</filename>, <filename>df</filename> among

14741

others.

14742

You can add your own tests to the list of tests by

14743

appending <filename>TEST_SUITES</filename> as follows:

14744

14745

TEST_SUITES_append = " <replaceable>mytest</replaceable>"

14746

</literallayout>

14747

Alternatively, you can provide the "auto" option to

14748

have all applicable tests run against the image.

14749

14750

TEST_SUITES_append = " auto"

14751

</literallayout>

14752

Using this option causes the build system to automatically

14753

run tests that are applicable to the image.

14754

Tests that are not applicable are skipped.

</para>

<para>

The order in which tests are run is important.

14759

Tests that depend on another test must appear later in the

14760

list than the test on which they depend.

14761

For example, if you append the list of tests with two

14762

tests (<filename>test_A</filename> and

14763

<filename>test_B</filename>) where

14764

<filename>test_B</filename> is dependent on

14765

<filename>test_A</filename>, then you must order the tests

14766

as follows:

14767

14768

TEST_SUITES = " test_A test_B"

</literallayout>

</para>

<para>

For more information on testing images, see the

14774

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

14775

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>

14781

<info>

14782

THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located."

</info>

14787

The directory in which the file BitBake is currently

14788

parsing is located.

14789

Do not manually set this variable.

</para>

</glossdef>

</glossentry>

<info>

TIME[doc] = "The time the build was started using HMS format."

</info>

14801

The time the build was started.

14802

Times appear using the hour, minute, and second (HMS)

14803

format (e.g. "140159" for one minute and fifty-nine

14804

seconds past 1400 hours).

</para>

</glossdef>

</glossentry>

<glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>

14810

<info>

14811

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>

14816

This variable is the base directory the OpenEmbedded

14817

build system uses for all build output and intermediate

14818

files (other than the shared state cache).

14819

By default, the <filename>TMPDIR</filename> variable points

14820

to <filename>tmp</filename> within the

14821

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

</para>

<para>

If you want to establish this directory in a location other

14826

than the default, you can uncomment and edit the following

14827

statement in the

14828

<filename>conf/local.conf</filename> file in the

14829

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:

14830

14831

#TMPDIR = "${TOPDIR}/tmp"

14832

</literallayout>

14833

An example use for this scenario is to set

14834

<filename>TMPDIR</filename> to a local disk, which does

14835

not use NFS, while having the Build Directory use NFS.

</para>

<para>

The filesystem used by <filename>TMPDIR</filename> must

14840

have standard filesystem semantics (i.e. mixed-case files

14841

are unique, POSIX file locking, and persistent inodes).

14842

Due to various issues with NFS and bugs in some

14843

implementations, NFS does not meet this minimum

14844

requirement.

14845

Consequently, <filename>TMPDIR</filename> cannot be on

NFS.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>

14852

<info>

14853

TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment."

</info>

14858

This variable lists packages the OpenEmbedded build system

14859

uses when building an SDK, which contains a

14860

cross-development environment.

14861

The packages specified by this variable are part of the

14862

toolchain set that runs on the

14863

14864

and each package should usually have the prefix

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14865

<filename>nativesdk-</filename>.

14866

For example, consider the following command when

14867

building an SDK:

14868

14869

$ bitbake -c populate_sdk <replaceable>imagename</replaceable>

14870

</literallayout>

14871

In this case, a default list of packages is set in this

14872

variable, but you can add additional packages to the list.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

14873

See the

14874

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"

14875

section in the Yocto Project Software Development Kit (SDK)

14876

Developer's Guide for more information.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

For background information on cross-development toolchains

14881

in the Yocto Project development environment, see the

14882

"<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"

14883

section.

14884

For information on setting up a cross-development

14885

environment, see the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14886

<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-TOOLCHAIN_OUTPUTNAME'><glossterm>TOOLCHAIN_OUTPUTNAME</glossterm>

14892

<info>

14893

TOOLCHAIN_OUTPUTNAME[doc] = "Defines the name used for the toolchain output."

</info>

14898

This variable defines the name used for the toolchain

output.

The

class sets the

<filename>TOOLCHAIN_OUTPUTNAME</filename> variable as

14904

follows:

14905

14906

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>

14918

<info>

14919

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>

14924

This variable lists packages the OpenEmbedded build system

14925

uses when it creates the target part of an SDK

14926

(i.e. the part built for the target hardware), which

14927

includes libraries and headers.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame]

14928

Use this variable to add individual packages to the

14929

part of the SDK that runs on the target.

14930

See the

14931

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"

14932

section in the Yocto Project Software Development Kit (SDK)

14933

Developer's Guide for more information.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

For background information on cross-development toolchains

14938

in the Yocto Project development environment, see the

14939

"<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"

14940

section.

14941

For information on setting up a cross-development

14942

environment, see the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14943

<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>

14949

<info>

14950

TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images."

</info>

14955

The top-level

14956

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

14957

BitBake automatically sets this variable when you

14958

initialize your build environment using either

or

</para>

</glossdef>

</glossentry>

<glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>

14967

<info>

14968

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>

14973

A sanitized version of

14974

14975

This variable is used where the architecture is needed in

14976

a value where underscores are not allowed, for example

14977

within package filenames.

14978

In this case, dash characters replace any underscore

14979

characters used in TARGET_ARCH.

</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>

14995

The GNU canonical architecture for a specific architecture

14996

(i.e. <filename>arm</filename>,

14997

<filename>armeb</filename>,

14998

<filename>mips</filename>,

14999

<filename>mips64</filename>, and so forth).

15000

BitBake uses this value to setup configuration.

</para>

<para>

<filename>TUNE_ARCH</filename> definitions are specific to

15005

a given architecture.

15006

The definitions can be a single static definition, or

15007

can be dynamically adjusted.

15008

You can see details for a given CPU family by looking at

15009

the architecture's <filename>README</filename> file.

15010

For example, the

15011

<filename>meta/conf/machine/include/mips/README</filename>

15012

file in the

15013

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

15014

provides information for <filename>TUNE_ARCH</filename>

15015

specific to the <filename>mips</filename> architecture.

</para>

<para>

<filename>TUNE_ARCH</filename> is tied closely to

15020

15021

which defines the target machine's architecture.

15022

The BitBake configuration file

15023

(<filename>meta/conf/bitbake.conf</filename>) sets

15024

<filename>TARGET_ARCH</filename> as follows:

15025

15026

TARGET_ARCH = "${TUNE_ARCH}"

</literallayout>

</para>

<para>

The following list, which is by no means complete since

15032

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>

15048

<info>

15049

TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system."

</info>

15054

Specifies architecture-specific assembler flags for

15055

the target system.

15056

The set of flags is based on the selected tune features.

15057

<filename>TUNE_ASARGS</filename> is set using

15058

the tune include files, which are typically under

15059

<filename>meta/conf/machine/include/</filename> and are

influenced through

For example, the

<filename>meta/conf/machine/include/x86/arch-x86.inc</filename>

15064

file defines the flags for the x86 architecture as follows:

15065

15066

TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"

15067

</literallayout>

15068

<note>

15069

Board Support Packages (BSPs) select the tune.

15070

The selected tune, in turn, affects the tune variables

15071

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>

15079

<info>

15080

TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system."

</info>

15085

Specifies architecture-specific C compiler flags for

15086

the target system.

15087

The set of flags is based on the selected tune features.

15088

<filename>TUNE_CCARGS</filename> is set using

15089

the tune include files, which are typically under

15090

<filename>meta/conf/machine/include/</filename> and are

influenced through

<note>

Board Support Packages (BSPs) select the tune.

15095

The selected tune, in turn, affects the tune variables

15096

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>

15104

<info>

15105

TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system."

</info>

15110

Specifies architecture-specific linker flags for

15111

the target system.

15112

The set of flags is based on the selected tune features.

15113

<filename>TUNE_LDARGS</filename> is set using

15114

the tune include files, which are typically under

15115

<filename>meta/conf/machine/include/</filename> and are

influenced through

For example, the

<filename>meta/conf/machine/include/x86/arch-x86.inc</filename>

15120

file defines the flags for the x86 architecture as follows:

15121

15122

TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"

15123

</literallayout>

15124

<note>

15125

Board Support Packages (BSPs) select the tune.

15126

The selected tune, in turn, affects the tune variables

15127

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>

15135

<info>

15136

TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor."

</info>

15141

Features used to "tune" a compiler for optimal use

15142

given a specific processor.

15143

The features are defined within the tune files and allow

15144

arguments (i.e. <filename>TUNE_*ARGS</filename>) to be

15145

dynamically generated based on the features.

</para>

<para>

The OpenEmbedded build system verifies the features

15150

to be sure they are not conflicting and that they are

supported.

</para>

<para>

The BitBake configuration file

15156

(<filename>meta/conf/bitbake.conf</filename>) defines

15157

<filename>TUNE_FEATURES</filename> as follows:

15158

15159

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>

15169

<info>

15170

TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages."

</info>

15175

The package architecture understood by the packaging

15176

system to define the architecture, ABI, and tuning of

15177

output packages.

15178

The specific tune is defined using the "_tune" override

15179

as follows:

15180

15181

TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>"

</literallayout>

</para>

<para>

These tune-specific package architectures are defined in

15187

the machine include files.

15188

Here is an example of the "core2-32" tuning as used

15189

in the

15190

<filename>meta/conf/machine/include/tune-core2.inc</filename>

15191

file:

15192

15193

TUNE_PKGARCH_tune-core2-32 = "core2-32"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>

15200

<info>

15201

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>

15206

An underlying Application Binary Interface (ABI) used by

15207

a particular tuning in a given toolchain layer.

15208

Providers that use prebuilt libraries can use the

15209

<filename>TUNEABI</filename>,

and

variables to check compatibility of tunings against their

15214

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>

15228

<info>

15229

TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST."

</info>

15234

If set, the OpenEmbedded system ignores the

15235

15236

variable.

15237

Providers that use prebuilt libraries can use the

15238

<filename>TUNEABI_OVERRIDE</filename>,

15239

<filename>TUNEABI_WHITELIST</filename>,

15240

and

15241

15242

variables to check compatibility of a tuning against their

15243

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>

15255

<info>

15256

TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed."

</info>

15261

A whitelist of permissible

15262

15263

values.

15264

If <filename>TUNEABI_WHITELIST</filename> is not set,

15265

all tunes are allowed.

15266

Providers that use prebuilt libraries can use the

15267

<filename>TUNEABI_WHITELIST</filename>,

15268

15269

and <filename>TUNEABI</filename> variables to check

15270

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>

15283

<info>

15284

TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature."

</info>

15289

Specifies CPU or Application Binary Interface (ABI)

15290

tuning features that conflict with <replaceable>feature</replaceable>.

</para>

<para>

Known tuning conflicts are specified in the machine include

15295

files in the

15296

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

15297

Here is an example from the

15298

<filename>meta/conf/machine/include/mips/arch-mips.inc</filename>

15299

include file that lists the "o32" and "n64" features as

15300

conflicting with the "n32" feature:

15301

15302

TUNECONFLICTS[n32] = "o32 n64"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm>

15309

<info>

15310

TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features."

</info>

15315

Specifies a valid CPU or Application Binary Interface (ABI)

15316

tuning feature.

15317

The specified feature is stored as a flag.

15318

Valid features are specified in the machine include files

15319

(e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).

15320

Here is an example from that file:

15321

15322

TUNEVALID[bigendian] = "Enable big-endian mode."

</literallayout>

</para>

<para>

See the machine include files in the

15328

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

for these features.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>

15339

<info>

15340

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

15354

<filename>meta-fsl-arm</filename> layer.

15355

15356

UBOOT_CONFIG ??= "sd"

15357

UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"

15358

UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"

15359

UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"

15360

UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"

15361

</literallayout>

15362

In this example, "sd" is selected as the configuration

15363

of the possible four for the

15364

<filename>UBOOT_MACHINE</filename>.

15365

The "sd" configuration defines "mx6qsabreauto_config"

15366

as the value for <filename>UBOOT_MACHINE</filename>, while

15367

the "sdcard" specifies the

15368

<filename>IMAGE_FSTYPES</filename> to use for the U-boot

image.

</para>

<para>

For more information on how the

15374

<filename>UBOOT_CONFIG</filename> is handled, see the

15375

<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_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>

15382

<info>

15383

UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."

</info>

15388

Specifies the entry point for the U-Boot image.

15389

During U-Boot image creation, the

15390

<filename>UBOOT_ENTRYPOINT</filename> variable is passed

15391

as a command-line parameter to the

15392

<filename>uboot-mkimage</filename> utility.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>

15398

<info>

15399

UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image."

</info>

15404

Specifies the load address for the U-Boot image.

15405

During U-Boot image creation, the

15406

<filename>UBOOT_LOADADDRESS</filename> variable is passed

15407

as a command-line parameter to the

15408

<filename>uboot-mkimage</filename> utility.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>

15414

<info>

15415

UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image."

</info>

15420

Appends a string to the name of the local version of the

15421

U-Boot image.

15422

For example, assuming the version of the U-Boot image

15423

built was "2013.10, the full version string reported by

15424

U-Boot would be "2013.10-yocto" given the following

15425

statement:

15426

15427

UBOOT_LOCALVERSION = "-yocto"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>

15434

<info>

15435

UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image."

</info>

15440

Specifies the value passed on the

15441

<filename>make</filename> command line when building

15442

a U-Boot image.

15443

The value indicates the target platform configuration.

15444

You typically set this variable from the machine

15445

configuration file (i.e.

15446

<filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>).

</para>

<para>

Please see the "Selection of Processor Architecture and

15451

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>

15458

<info>

15459

UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile."

</info>

15464

Specifies the target called in the

15465

<filename>Makefile</filename>.

15466

The default target is "all".

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>

15472

<info>

15473

UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."

</info>

15478

Points to the generated U-Boot extension.

15479

For example, <filename>u-boot.sb</filename> has a

15480

<filename>.sb</filename> extension.

</para>

<para>

The default U-Boot extension is

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>

15491

<info>

15492

UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."

</info>

15497

Specifies the target used for building U-Boot.

15498

The target is passed directly as part of the "make" command

15499

(e.g. SPL and AIS).

15500

If you do not specifically set this variable, the

15501

OpenEmbedded build process passes and uses "all" for the

15502

target during the U-Boot building process.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UNKNOWN_CONFIGURE_WHITELIST'><glossterm>UNKNOWN_CONFIGURE_WHITELIST</glossterm>

15508

<info>

15509

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>

15514

Specifies a list of options that, if reported by the

15515

configure script as being invalid, should not generate a

warning during the

task.

Normally, invalid configure options are simply not passed

15520

to the configure script (e.g. should be removed from

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

or

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15524

However, common options, for example, exist that are passed

15525

to all configure scripts at a class level that might not

15526

be valid for some configure scripts.

15527

It follows that no benefit exists in seeing a warning about

15528

these options.

15529

For these cases, the options are added to

15530

<filename>UNKNOWN_CONFIGURE_WHITELIST</filename>.

</para>

<para>

The configure arguments check that uses

15535

<filename>UNKNOWN_CONFIGURE_WHITELIST</filename> is part

15536

of the

15537

15538

class and is only enabled if the recipe inherits the

class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>

15546

<info>

15547

UPDATERCPN[doc] = "Specifies the package that contains the initscript that is to be enabled."

</info>

15552

For recipes inheriting the

15553

15554

class, <filename>UPDATERCPN</filename> specifies

15555

the package that contains the initscript that is to be

enabled.

</para>

<para>

The default value is "${PN}".

15561

Given that almost all recipes that install initscripts

15562

package them in the main package for the recipe, you

15563

rarely need to set this variable in individual recipes.

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15568

<glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm>

15569

<info>

15570

UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository."

</info>

15575

When the

15576

15577

class is enabled globally, you can perform a per-recipe

15578

check for what the latest upstream source code version is

15579

by calling

15580

<filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.

15581

If the recipe source code is provided from Git

15582

repositories, the OpenEmbedded build system determines the

15583

latest upstream version by picking the latest tag from the

15584

list of all repository tags.

15585

You can use the

15586

<filename>UPSTREAM_CHECK_GITTAGREGEX</filename>

15587

variable to provide a regular expression to filter only the

15588

relevant tags should the default filter not work

15589

correctly.

15590

15591

UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm>

15598

<info>

15599

UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI."

</info>

15604

When the

15605

15606

class is enabled globally, use the

15607

<filename>UPSTREAM_CHECK_REGEX</filename> variable to

15608

specify a different regular expression instead of the

15609

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>

15620

<info>

15621

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>

15626

When the

15627

15628

class is enabled globally, you can perform a per-recipe

15629

check for what the latest upstream source code version is

15630

by calling <filename>bitbake -c checkpkg</filename>

15631

<replaceable>recipe</replaceable>.

15632

If the source code is provided from tarballs, the latest

15633

version is determined by fetching the directory listing

15634

where the tarball is and attempting to find a later tarball.

15635

When this approach does not work, you can use

15636

<filename>UPSTREAM_CHECK_URI</filename> to

15637

provide a different URI that contains the link to the

15638

latest tarball.

15639

15640

UPSTREAM_CHECK_URI = "recipe_url"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15646

<glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm>

15647

<info>

15648

USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population."

</info>

15653

Determines if <filename>devtmpfs</filename> is used for

15654

<filename>/dev</filename> population.

15655

The default value used for <filename>USE_DEVFS</filename>

15656

is "1" when no value is specifically set.

15657

Typically, you would set <filename>USE_DEVFS</filename>

15658

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>"

15665

section in the Yocto Project Development Manual for

15666

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>

15678

When using

15679

<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,

15680

determines whether or not to run a

15681

<ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>

15682

on any virtual terminals in order to enable logging in

15683

through those terminals.

</para>

<para>

The default value used for <filename>USE_VT</filename>

15688

is "1" when no default value is specifically set.

15689

Typically, you would set <filename>USE_VT</filename>

15690

to "0" in the machine configuration file for machines

15691

that do not have a graphical display attached and

15692

therefore do not need virtual terminal functionality.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>

15698

<info>

15699

USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features."

</info>

15704

A list of classes to globally inherit.

15705

These classes are used by the OpenEmbedded build system

15706

to enable extra features (e.g.

15707

<filename>buildstats</filename>,

15708

<filename>image-mklibs</filename>, and so forth).

</para>

<para>

The default list is set in your

15713

<filename>local.conf</filename> file:

15714

15715

USER_CLASSES ?= "buildstats image-mklibs image-prelink"

15716

</literallayout>

15717

For more information, see

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

15718

<filename>meta-poky/conf/local.conf.sample</filename> in

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15719

the

15720

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>

15726

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15727

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 files/passwd and files/group files. If set to 'warn', a warning will be issued instead."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15732

If set to "error", forces the OpenEmbedded build system to

15733

produce an error if the user identification

15734

(<filename>uid</filename>) and group identification

15735

(<filename>gid</filename>) values are not defined

15736

in <filename>files/passwd</filename>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15737

and <filename>files/group</filename> files.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15738

If set to "warn", a warning will be issued instead.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

The default behavior for the build system is to dynamically

15743

apply <filename>uid</filename> and

15744

<filename>gid</filename> values.

15745

Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>

15746

variable is by default not set.

15747

If you plan on using statically assigned

15748

15749

values, you should set

15750

the <filename>USERADD_ERROR_DYNAMIC</filename> variable in

15751

your <filename>local.conf</filename> file as

15752

follows:

15753

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15754

USERADD_ERROR_DYNAMIC = "error"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15755

</literallayout>

15756

Overriding the default behavior implies you are going to

15757

also take steps to set static <filename>uid</filename> and

15758

<filename>gid</filename> values through use of the

and

variables.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>

15769

<info>

15770

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>

15775

Specifies a password file to use for obtaining static

15776

group identification (<filename>gid</filename>) values

15777

when the OpenEmbedded build system adds a group to the

15778

system during package installation.

</para>

<para>

When applying static group identification

15783

(<filename>gid</filename>) values, the OpenEmbedded build

15784

system looks in

15785

15786

for a <filename>files/group</filename> file and then applies

15787

those <filename>uid</filename> values.

15788

Set the variable as follows in your

15789

<filename>local.conf</filename> file:

15790

15791

USERADD_GID_TABLES = "files/group"

</literallayout>

</para>

<note>

Setting the

variable to "useradd-staticids" causes the build system

15799

to use static <filename>gid</filename> values.

</note>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>

15805

<info>

15806

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

15815

require users and/or groups to be added.

</para>

<para>

You must set this variable if the recipe inherits the

15820

class.

15821

For example, the following enables adding a user for the

15822

main package in a recipe:

15823

15824

USERADD_PACKAGES = "${PN}"

15825

</literallayout>

15826

<note>

15827

If follows that if you are going to use the

15828

<filename>USERADD_PACKAGES</filename> variable,

15829

you need to set one or more of the

or

variables.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>

15842

<info>

15843

USERADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the useradd command if you wish to 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 be passed

15852

to the <filename>useradd</filename> command

15853

if you wish to add a user to the system when the package

is installed.

</para>

<para>

Here is an example from the <filename>dbus</filename>

15859

recipe:

15860

15861

USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \

15862

--no-create-home --shell /bin/false \

15863

--user-group messagebus"

15864

</literallayout>

15865

For information on the standard Linux shell command

15866

<filename>useradd</filename>, see

15867

<ulink url='http://linux.die.net/man/8/useradd'></ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>

15873

<info>

15874

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>

15879

Specifies a password file to use for obtaining static

15880

user identification (<filename>uid</filename>) values

15881

when the OpenEmbedded build system adds a user to the

15882

system during package installation.

</para>

<para>

When applying static user identification

15887

(<filename>uid</filename>) values, the OpenEmbedded build

15888

system looks in

15889

15890

for a <filename>files/passwd</filename> file and then applies

15891

those <filename>uid</filename> values.

15892

Set the variable as follows in your

15893

<filename>local.conf</filename> file:

15894

15895

USERADD_UID_TABLES = "files/passwd"

</literallayout>

</para>

<note>

Setting the

variable to "useradd-staticids" causes the build system

15903

to use static <filename>uid</filename> values.

</note>

</glossdef>

</glossentry>

<glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>

15909

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15910

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."

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</info>

15915

When set to "useradd-staticids", causes the

15916

OpenEmbedded build system to base all user and group

15917

additions on a static

15918

<filename>passwd</filename> and

15919

<filename>group</filename> files found in

</para>

<para>

To use static user identification (<filename>uid</filename>)

15925

and group identification (<filename>gid</filename>)

15926

values, set the variable

15927

as follows in your <filename>local.conf</filename> file:

15928

15929

USERADDEXTENSION = "useradd-staticids"

15930

</literallayout>

15931

<note>

15932

Setting this variable to use static

15933

15934

values causes the OpenEmbedded build system to employ

15935

the

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

15936

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

class.

</note>

</para>

<para>

If you use static <filename>uid</filename> and

15943

<filename>gid</filename> information, you must also

15944

specify the <filename>files/passwd</filename> and

15945

<filename>files/group</filename> files by setting the

and

variables.

Additionally, you should also set the

variable.

</para>

</glossdef>

</glossentry>

</glossdiv>

Brad Bishop

2018-02-01 10:27:11 -0500

[diff] [blame^]

15959

15960

15961

<glossentry id='var-VOLATILE_LOG_DIR'><glossterm>VOLATILE_LOG_DIR</glossterm>

15962

<info>

15963

VOLATILE_LOG_DIR[doc] = "Specifies the persistence of the target's /var/log directory, which is used to house postinstall target log files."

</info>

15968

Specifies the persistence of the target's

15969

<filename>/var/log</filename> directory, which is used to

15970

house postinstall target log files.

</para>

<para>

By default, <filename>VOLATILE_LOG_DIR</filename> is set

15975

to "yes", which means the file is not persistent.

15976

You can override this setting by setting the

15977

variable to "no" to make the log directory persistent.

</para>

</glossdef>

</glossentry>

</glossdiv>

Patrick Williams