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

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

[diff] [blame]

539

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

545

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

546

variable.

547

Most Autotools-based recipes support separating these

548

directories.

549

The build system defaults to using separate directories for

550

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

</para>

</glossdef>

</glossentry>

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

556

<info>

557

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>

562

Lists "recommended-only" packages to not install.

563

Recommended-only packages are packages installed only

through the

variable.

You can prevent any of these "recommended" packages from

568

being installed by listing them with the

569

<filename>BAD_RECOMMENDATIONS</filename> variable:

570

571

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

577

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

578

a specific image recipe by using the recipe name override:

579

580

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

586

packages using this variable and some other packages are

587

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

588

589

variable), the OpenEmbedded build system ignores your

590

request and will install the packages to avoid dependency

errors.

</para>

<para>

Support for this variable exists only when using the

596

IPK and RPM packaging backend.

597

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>

617

The library directory name for the CPU or Application

618

Binary Interface (ABI) tune.

619

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

620

Multilib context.

621

See the

622

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

623

section in the Yocto Project Development Manual for

624

information on Multilib.

</para>

<para>

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

629

the machine include files in the

630

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

631

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

</para>

</glossdef>

</glossentry>

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

637

<info>

638

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

</info>

643

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

644

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

</para>

</glossdef>

</glossentry>

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

650

<info>

651

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

656

is allowed to use to obtain the required source code.

657

Following are considerations surrounding this variable:

658

659

660

This host list is only used if

661

<filename>BB_NO_NETWORK</filename> is either not

set or set to "0".

</para></listitem>

Limited support for wildcard matching against the

666

beginning of host names exists.

667

For example, the following setting matches

668

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

669

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

670

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

671

672

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

689

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

690

being fetched from an allowed location and avoids raising

691

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

692

693

statement.

694

This is because the fetcher does not attempt to use the

695

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

696

successful fetch from the

697

<filename>PREMIRRORS</filename> occurs.

</para>

</glossdef>

</glossentry>

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

703

<info>

704

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

</info>

709

Defines how BitBake handles situations where an append

710

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

711

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

712

This condition often occurs when layers get out of sync

713

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

714

recipe version and the old recipe no longer exists and the

715

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

721

the sane reaction given something is out of sync.

722

It is important to realize when your changes are no longer

being applied.

</para>

<para>

You can change the default behavior by setting this

728

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

729

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

730

located in the

731

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

732

Here is an example:

733

734

BB_DANGLINGAPPENDS_WARNONLY = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

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

741

<info>

742

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>

747

Monitors disk space and available inodes during the build

748

and allows you to control the build based on these

parameters.

</para>

<para>

Disk space monitoring is disabled by default.

754

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

755

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

756

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

757

Use the following form:

758

759

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

where:

<replaceable>action</replaceable> is:

764

ABORT: Immediately abort the build when

765

a threshold is broken.

766

STOPTASKS: Stop the build after the currently

767

executing tasks have finished when

768

a threshold is broken.

769

WARN: Issue a warning but continue the

770

build when a threshold is broken.

771

Subsequent warnings are issued as

772

defined by the

773

774

which must be defined in the

775

conf/local.conf file.

776

777

<replaceable>dir</replaceable> is:

778

Any directory you choose. You can specify one or

779

more directories to monitor by separating the

780

groupings with a space. If two directories are

781

on the same device, only the first directory

782

is monitored.

783

784

<replaceable>threshold</replaceable> is:

785

Either the minimum available disk space,

786

the minimum number of free inodes, or

787

both. You must specify at least one. To

788

omit one or the other, simply omit the value.

789

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

790

Mbytes, and Kbytes, respectively. If you do

791

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

792

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

</literallayout>

</para>

<para>

Here are some examples:

798

799

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

800

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

801

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

802

</literallayout>

803

The first example works only if you also provide

804

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

805

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

806

This example causes the build system to immediately

807

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

808

below 1 Gbyte or the available free inodes drops below

809

100 Kbytes.

810

Because two directories are provided with the variable, the

811

build system also issue a

812

warning when the disk space in the

813

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

814

below 1 Gbyte or the number of free inodes drops

815

below 100 Kbytes.

816

Subsequent warnings are issued during intervals as

817

defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>

variable.

</para>

<para>

The second example stops the build after all currently

823

executing tasks complete when the minimum disk space

824

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

825

directory drops below 1 Gbyte.

826

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

</para>

<para>

The final example immediately aborts the build when the

831

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

832

drops below 100 Kbytes.

833

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>

840

<info>

841

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>

846

Defines the disk space and free inode warning intervals.

847

To set these intervals, define the variable in your

848

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

849

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

</para>

<para>

If you are going to use the

854

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

855

also use the

856

857

and define its action as "WARN".

858

During the build, subsequent warnings are issued each time

859

disk space or number of free inodes further reduces by

860

the respective interval.

</para>

<para>

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

865

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

866

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

867

the following:

868

869

BB_DISKMON_WARNINTERVAL = "50M,5K"

</literallayout>

</para>

<para>

When specifying the variable in your configuration file,

875

use the following form:

876

877

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

where:

<replaceable>disk_space_interval</replaceable> is:

882

An interval of memory expressed in either

883

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

884

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

885

886

<replaceable>disk_inode_interval</replaceable> is:

887

An interval of free inodes expressed in either

888

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

889

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

</literallayout>

</para>

<para>

Here is an example:

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

897

BB_DISKMON_WARNINTERVAL = "50M,5K"

898

</literallayout>

899

These variables cause the OpenEmbedded build system to

900

issue subsequent warnings each time the available

901

disk space further reduces by 50 Mbytes or the number

902

of free inodes further reduces by 5 Kbytes in the

903

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

904

Subsequent warnings based on the interval occur each time

905

a respective interval is reached beyond the initial warning

906

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

</para>

</glossdef>

</glossentry>

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

912

<info>

913

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

</info>

918

Causes tarballs of the Git repositories, including the

919

Git metadata, to be placed in the

directory.

</para>

<para>

For performance reasons, creating and placing tarballs of

926

the Git repositories is not the default action by the

927

OpenEmbedded build system.

928

929

BB_GENERATE_MIRROR_TARBALLS = "1"

930

</literallayout>

931

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

932

file in the

933

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

939

<info>

940

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>

945

The maximum number of tasks BitBake should run in parallel

946

at any one time.

947

The OpenEmbedded build system automatically configures

948

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

949

build system.

950

For example, a system with a dual core processor that

951

also uses hyper-threading causes the

952

<filename>BB_NUMBER_THREADS</filename> variable to default

to "4".

</para>

<para>

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

958

have to override this variable to gain optimal parallelism

959

during builds.

960

However, if you have very large systems that employ

961

multiple physical CPUs, you might want to make sure the

962

<filename>BB_NUMBER_THREADS</filename> variable is not

963

set higher than "20".

</para>

<para>

For more information on speeding up builds, see the

968

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

section.

</para>

</glossdef>

</glossentry>

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

975

<info>

976

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>

981

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

982

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

983

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

984

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

985

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

986

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

987

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

988

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

993

is as simple as adding the following to your recipe:

994

995

BBCLASSEXTEND =+ "native nativesdk"

996

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

997

</literallayout>

Patrick Williams

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

[diff] [blame]

998

<note>

999

<para>

1000

Internally, the <filename>BBCLASSEXTEND</filename>

1001

mechanism generates recipe variants by rewriting

1002

variable values and applying overrides such as

1003

<filename>_class-native</filename>.

1004

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

1005

a

1006

1007

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

on "foo-native".

</para>

<para>

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

1013

recipe is only parsed once.

1014

Parsing once adds some limitations.

1015

For example, it is not possible to

1016

include a different file depending on the variant,

1017

since <filename>include</filename> statements are

1018

processed when the recipe is parsed.

1019

</para>

1020

</note>

Patrick Williams

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

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

1026

<info>

1027

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

</info>

1032

Lists the names of configured layers.

1033

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

1034

variables.

1035

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

1036

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

</para>

</glossdef>

</glossentry>

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

1042

<info>

1043

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>

1048

Variable that expands to match files from

1049

1050

in a particular layer.

1051

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

1052

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

1053

<filename>BBFILE_PATTERN_emenlow</filename>).

</para>

</glossdef>

</glossentry>

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

1059

<info>

1060

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>

1065

Assigns the priority for recipe files in each layer.

</para>

<para>

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

1070

more than one layer.

1071

Setting this variable allows you to prioritize a

1072

layer against other layers that contain the same recipe - effectively

1073

letting you control the precedence for the multiple layers.

1074

The precedence established through this variable stands regardless of a

1075

recipe's version

1076

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

1077

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

1078

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

1084

precedence.

1085

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

1086

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

1087

dependencies (see the

1088

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

1089

more information.

1090

The default priority, if unspecified

1091

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

1092

(or 1 if no priorities are defined).

1093

</para>

1094

<tip>

1095

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

1096

all configured layers along with their priorities.

</tip>

</glossdef>

</glossentry>

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

1102

<info>

1103

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

</info>

1108

List of recipe files used by BitBake to build software.

</para>

</glossdef>

</glossentry>

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

1114

<info>

1115

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

</info>

1120

Variable that controls how BitBake displays logs on build failure.

</para>

</glossdef>

</glossentry>

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

1126

<info>

1127

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

</info>

1132

If

1133

1134

is set, specifies the maximum number of lines from the

1135

task log file to print when reporting a failed task.

1136

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

1137

the entire log is printed.

</para>

</glossdef>

</glossentry>

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

1143

<info>

1144

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

</info>

1149

Lists the layers to enable during the build.

1150

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

1151

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]

1156

/home/scottrif/poky/meta-poky \

Patrick Williams

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

[diff] [blame]

1157

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

1158

/home/scottrif/poky/meta-mykernel \

1159

"

Patrick Williams

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

[diff] [blame]

1160

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

1165

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

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

1170

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

1171

<info>

Patrick Williams

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

[diff] [blame]

1172

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

Patrick Williams

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

[diff] [blame]

</info>

1177

Prevents BitBake from processing recipes and recipe

1178

append files.

Patrick Williams

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

[diff] [blame]

</para>

<para>

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

1183

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

1184

<filename>.bbappend</filename> files.

1185

BitBake ignores any recipe or recipe append files that

Patrick Williams

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

[diff] [blame]

1186

match any of the expressions.

Patrick Williams

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

[diff] [blame]

1187

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

1188

Consequently, matching files are not parsed or otherwise

1189

used by BitBake.</para>

1190

<para>

Patrick Williams

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

[diff] [blame]

1191

The values you provide are passed to Python's regular

Patrick Williams

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

[diff] [blame]

1192

expression compiler.

Patrick Williams

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

[diff] [blame]

1193

The expressions are compared against the full paths to

Patrick Williams

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

[diff] [blame]

1194

the files.

1195

For complete syntax information, see Python's

1196

documentation at

1197

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

</para>

<para>

The following example uses a complete regular expression

1202

to tell BitBake to ignore all recipe and recipe append

1203

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

1204

directory:

1205

1206

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

1207

</literallayout>

1208

If you want to mask out multiple directories or recipes,

Patrick Williams

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

[diff] [blame]

1209

you can specify multiple regular expression fragments.

Patrick Williams

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

[diff] [blame]

1210

This next example masks out multiple directories and

1211

individual recipes:

1212

Patrick Williams

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

[diff] [blame]

1213

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

1214

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

1215

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

1216

BBMASK += "opencv.*\.bbappend"

1217

BBMASK += "lzma"

Patrick Williams

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

[diff] [blame]

1218

</literallayout>

Patrick Williams

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

[diff] [blame]

1219

<note>

1220

When specifying a directory name, use the trailing

1221

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]

1228

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

1229

<info>

1230

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

</info>

1235

Specifies each separate configuration when you are

1236

building targets with multiple configurations.

1237

Use this variable in your

1238

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

1239

Specify a <replaceable>multiconfigname</replaceable> for

1240

each configuration file you are using.

1241

For example, the following line specifies three

1242

configuration files:

1243

1244

BBMULTIFONFIG = "configA configB configC"

1245

</literallayout>

1246

Each configuration file you use must reside in the

1247

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

1248

<filename>conf/multiconfig</filename> directory

1249

(e.g.

1250

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

</para>

<para>

For information on how to use

1255

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

1256

supports building targets with multiple configurations,

1257

see the

1258

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

1259

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

1264

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

1265

<info>

1266

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

</info>

1271

Used by BitBake to locate

1272

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

1273

This variable is analogous to the

1274

<filename>PATH</filename> variable.

1275

<note>

1276

If you run BitBake from a directory outside of the

1277

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

1278

you must be sure to set

1279

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

1280

Build Directory.

1281

Set the variable as you would any environment variable

1282

and then run BitBake:

1283

1284

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

1285

$ export BBPATH

1286

$ bitbake <replaceable>target</replaceable>

</literallayout>

</note>

</para>

</glossdef>

</glossentry>

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

1294

<info>

1295

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

</info>

1300

Points to the server that runs memory-resident BitBake.

1301

This variable is set by the

1302

1303

setup script and should not be hand-edited.

1304

The variable is only used when you employ memory-resident

1305

BitBake.

1306

The setup script exports the value as follows:

1307

1308

export BBSERVER=localhost:$port

</literallayout>

</para>

<para>

For more information on how the

1314

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

1315

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

1316

is located in the

1317

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

</para>

</glossdef>

</glossentry>

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

1323

<info>

1324

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>

1329

When inheriting the

1330

1331

class, this variable specifies binary configuration

1332

scripts to disable in favor of using

1333

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

1334

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

1335

modify the specified scripts to return an error so that

1336

calls to them can be easily found and replaced.

</para>

<para>

To add multiple scripts, separate them by spaces.

1341

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

1342

recipe:

1343

1344

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

1351

<info>

1352

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

</info>

1357

When inheriting the

1358

1359

class, this variable specifies a wildcard for

1360

configuration scripts that need editing.

1361

The scripts are edited to correct any paths that have been

1362

set up during compilation so that they are correct for

1363

use when installed into the sysroot and called by the

1364

build processes of other recipes.

</para>

<para>

For more information on how this variable works, see

1369

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

1370

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

1371

You can also find general information on the class in the

1372

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

1385

The base recipe name and version but without any special

1386

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

1387

and so forth).

1388

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

1398

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]

1403

This variable is a version of the

1404

Patrick Williams

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

[diff] [blame]

1405

variable with common prefixes and suffixes

1406

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

1407

<filename>-cross</filename>,

1408

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

Patrick Williams

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

[diff] [blame]

1409

<filename>lib64-</filename> and

1410

<filename>lib32-</filename>.

Patrick Williams

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

[diff] [blame]

1411

The exact lists of prefixes and suffixes removed are

1412

specified by the

Patrick Williams

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

[diff] [blame]

1413

Patrick Williams

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

[diff] [blame]

1414

and

1415

1416

variables, respectively.

Patrick Williams

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

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

1422

<info>

1423

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

</info>

1428

Specifies a URL for an upstream bug tracking website for

1429

a recipe.

1430

The OpenEmbedded build system does not use this variable.

1431

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

1432

in the software being built needs to be manually reported.

</para>

</glossdef>

</glossentry>

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

1438

<info>

1439

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

</info>

1444

Specifies the architecture of the build host

1445

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

1446

The OpenEmbedded build system sets the value of

1447

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

1448

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

</para>

</glossdef>

</glossentry>

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

1454

<info>

1455

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

</info>

1460

Specifies the flags to pass to the C compiler when building

1461

for the build host.

1462

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

1463

1464

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1470

<info>

1471

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>

1476

Specifies the flags to pass to the C pre-processor

1477

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

1478

for the build host.

Patrick Williams

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

[diff] [blame]

1479

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

Patrick Williams

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

[diff] [blame]

1480

1481

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1487

<info>

1488

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

</info>

1493

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

1494

building for the build host.

Patrick Williams

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

[diff] [blame]

1495

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

Patrick Williams

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

[diff] [blame]

1496

1497

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1503

<info>

1504

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

</info>

1509

Specifies the flags to pass to the linker when building

1510

for the build host.

1511

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

1512

1513

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1519

<info>

1520

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

</info>

1525

Specifies the optimization flags passed to the C compiler

1526

when building for the build host or the SDK.

1527

The flags are passed through the

and

default values.

</para>

<para>

The default value of the

1536

<filename>BUILD_OPTIMIZATION</filename> variable is

"-O2 -pipe".

</para>

</glossdef>

</glossentry>

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

1543

<info>

1544

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

</info>

1549

Specifies the operating system in use on the build

1550

host (e.g. "linux").

1551

The OpenEmbedded build system sets the value of

1552

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

1553

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

1554

converted to lower-case characters.

</para>

</glossdef>

</glossentry>

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

1560

<info>

1561

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

</info>

1566

The toolchain binary prefix used for native recipes.

1567

The OpenEmbedded build system uses the

1568

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

1569

Patrick Williams

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

[diff] [blame]

1570

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>

1576

<info>

1577

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

</info>

1582

Specifies the system, including the architecture and

1583

the operating system, to use when building for the build

1584

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>

1602

<info>

1603

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

</info>

1608

Specifies the vendor name to use when building for the

1609

build host.

1610

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

</para>

</glossdef>

</glossentry>

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

1616

<info>

1617

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

</info>

1622

Points to the location of the

1623

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

1624

You can define this directory indirectly through the

and

scripts by passing in a Build Directory path when you run

1629

the scripts.

1630

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

1631

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

1632

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

</para>

</glossdef>

</glossentry>

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

1638

<info>

1639

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>

1644

When inheriting the

1645

1646

class, this variable specifies whether or not to commit the

1647

build history output in a local Git repository.

1648

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

1649

automatically by the

1650

<filename>buildhistory</filename>

1651

class and a commit will be created on every

1652

build for changes to each top-level subdirectory of the

1653

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

1654

If you want to track changes to build history over

1655

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

</para>

<para>

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

1660

does not commit the build history output in a local

1661

Git repository:

1662

1663

BUILDHISTORY_COMMIT ?= "0"

</literallayout>

</para>

</glossdef>

</glossentry>

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

1670

<info>

1671

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

</info>

1676

When inheriting the

1677

1678

class, this variable specifies the author to use for each

1679

Git commit.

1680

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

1681

variable to work, the

1682

1683

variable must be set to "1".

</para>

<para>

Git requires that the value you provide for the

1688

<filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable

1689

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

1690

Providing an email address or host that is not valid does

1691

not produce an error.

</para>

<para>

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

1696

sets the variable as follows:

1697

1698

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

1705

<info>

1706

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

</info>

1711

When inheriting the

1712

1713

class, this variable specifies the directory in which

1714

build history information is kept.

1715

For more information on how the variable works, see the

1716

<filename>buildhistory.class</filename>.

</para>

<para>

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

1721

sets the directory as follows:

1722

1723

BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"

</literallayout>

</para>

</glossdef>

</glossentry>

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

1730

<info>

1731

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

</info>

1736

When inheriting the

1737

1738

class, this variable specifies the build history features

1739

to be enabled.

1740

For more information on how build history works, see the

1741

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

section.

</para>

<para>

You can specify three features in the form of a

1747

space-separated list:

1748

1749

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

1750

Analysis of the contents of images, which

1751

includes the list of installed packages among other

1752

things.

1753

</para></listitem>

1754

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

1755

Analysis of the contents of individual packages.

1756

</para></listitem>

1757

1758

Analysis of the contents of the software

1759

development kit (SDK).

</para></listitem>

</itemizedlist>

</para>

<para>

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

1766

enables all three features:

1767

1768

BUILDHISTORY_FEATURES ?= "image package sdk"

</literallayout>

</para>

</glossdef>

</glossentry>

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

1775

<info>

1776

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>

1781

When inheriting the

1782

1783

class, this variable specifies a list of paths to files

1784

copied from the

1785

image contents into the build history directory under

1786

an "image-files" directory in the directory for

1787

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

1788

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

1789

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

1790

monitor for changes in user and group entries.

1791

You can modify the list to include any file.

1792

Specifying an invalid path does not produce an error.

1793

Consequently, you can include files that might

1794

not always be present.

</para>

<para>

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

1799

provides paths to the following files:

1800

1801

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

1808

<info>

1809

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

</info>

1814

When inheriting the

1815

1816

class, this variable optionally specifies a remote

1817

repository to which build history pushes Git changes.

1818

In order for <filename>BUILDHISTORY_PUSH_REPO</filename>

to work,

must be set to "1".

</para>

<para>

The repository should correspond to a remote

1826

address that specifies a repository as understood by

1827

Git, or alternatively to a remote name that you have

1828

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

1829

within the local repository.

</para>

<para>

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

1834

sets the variable as follows:

1835

1836

BUILDHISTORY_PUSH_REPO ?= ""

</literallayout>

</para>

</glossdef>

</glossentry>

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

1843

<info>

1844

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

</info>

1849

Specifies the flags to pass to the C compiler when building

1850

for the SDK.

Patrick Williams

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

[diff] [blame]

1851

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

Patrick Williams

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

[diff] [blame]

1852

context,

1853

1854

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1860

<info>

1861

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>

1866

Specifies the flags to pass to the C pre-processor

1867

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

1868

for the SDK.

Patrick Williams

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

[diff] [blame]

1869

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

Patrick Williams

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

[diff] [blame]

1870

context,

1871

1872

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1878

<info>

1879

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

</info>

1884

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

1885

building for the SDK.

Patrick Williams

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

[diff] [blame]

1886

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

Patrick Williams

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

[diff] [blame]

1887

context,

1888

1889

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1895

<info>

1896

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

</info>

1901

Specifies the flags to pass to the linker when building

1902

for the SDK.

1903

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

1904

context,

1905

1906

is set to the value of this variable by default.

</para>

</glossdef>

</glossentry>

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

1912

<info>

1913

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

</info>

1918

Points to the location of the directory that holds build

1919

statistics when you use and enable the

1920

1921

class.

1922

The <filename>BUILDSTATS_BASE</filename> directory defaults

1923

to

1924

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

1930

<info>

1931

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>

1936

For the BusyBox recipe, specifies whether to split the

1937

output executable file into two parts: one for features

1938

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

1939

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

1940

<filename>setuid root</filename>).

</para>

<para>

The <filename>BUSYBOX_SPLIT_SUID</filename> variable

1945

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

1946

executable file.

1947

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

</para>

</glossdef>

</glossentry>

</glossdiv>

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

1957

<info>

1958

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

</info>

1963

Specifies the directory BitBake uses to store a cache

1964

of the

1965

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

1966

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>

1979

The minimal command and arguments used to run the C

compiler.

</para>

</glossdef>

</glossentry>

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

1986

<info>

1987

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

</info>

1992

Specifies the flags to pass to the C compiler.

1993

This variable is exported to an environment

1994

variable and thus made visible to the software being

1995

built during the compilation step.

</para>

<para>

Default initialization for <filename>CFLAGS</filename>

2000

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

2009

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

2014

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

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

2022

<info>

2023

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

</info>

2028

An internal variable specifying the special class override

2029

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

2030

"class-native", and so forth).

Patrick Williams

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

[diff] [blame]

2031

The classes that use this variable (e.g.

2032

2033

2034

and so forth) set the variable to appropriate values.

2035

<note>

2036

<filename>CLASSOVERRIDE</filename> gets its default

2037

"class-target" value from the

2038

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

2039

</note>

Patrick Williams

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

[diff] [blame]

2040

</para>

2041

2042

<para>

Patrick Williams

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

[diff] [blame]

2043

As an example, the following override allows you to install

2044

extra files, but only when building for the target:

Patrick Williams

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

[diff] [blame]

2045

Patrick Williams

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

[diff] [blame]

2046

do_install_append_class-target() {

2047

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

2048

}

Patrick Williams

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

[diff] [blame]

2049

</literallayout>

Patrick Williams

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

[diff] [blame]

2050

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

2051

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

2052

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

2053

2054

FOO_class-native = "native"

2055

FOO = "other"

2056

</literallayout>

2057

The underlying mechanism behind

2058

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

2059

included in the default value of

2060

Patrick Williams

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

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

2066

<info>

2067

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

</info>

2072

If set to "1" within a recipe,

2073

<filename>CLEANBROKEN</filename> specifies that

2074

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

2075

not work for the software being built.

2076

Consequently, the OpenEmbedded build system will not try

2077

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

2078

2079

task, which is the default behavior.

</para>

</glossdef>

</glossentry>

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

2085

<info>

2086

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

</info>

2091

Provides a list of hardware features that are enabled in

both

and

This select list of features contains features that make

2097

sense to be controlled both at the machine and distribution

2098

configuration level.

2099

For example, the "bluetooth" feature requires hardware

2100

support but should also be optional at the distribution

2101

level, in case the hardware supports Bluetooth but you

2102

do not ever intend to use it.

</para>

<para>

For more information, see the

2107

2108

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>

2115

<info>

2116

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

</info>

2121

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

2122

in the

2123

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

2124

which is where generic license files reside.

</para>

</glossdef>

</glossentry>

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

2130

<info>

2131

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>

2136

A regular expression that resolves to one or more hosts

2137

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

2138

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

2139

The regular expression is matched against

2140

2141

You can use the variable to stop recipes from being built

2142

for classes of systems with which the recipes are not

2143

compatible.

2144

Stopping these builds is particularly useful with kernels.

2145

The variable also helps to increase parsing speed

2146

since the build system skips parsing recipes not

2147

compatible with the current system.

</para>

</glossdef>

</glossentry>

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

2153

<info>

2154

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

</info>

2159

A regular expression that resolves to one or more

2160

target machines with which a recipe is compatible.

2161

The regular expression is matched against

2162

2163

You can use the variable to stop recipes from being built

2164

for machines with which the recipes are not compatible.

2165

Stopping these builds is particularly useful with kernels.

2166

The variable also helps to increase parsing speed

2167

since the build system skips parsing recipes not

2168

compatible with the current machine.

</para>

</glossdef>

</glossentry>

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

2174

<info>

2175

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

</info>

2180

Defines wildcards to match when installing a list of

2181

complementary packages for all the packages explicitly

2182

(or implicitly) installed in an image.

2183

The resulting list of complementary packages is associated

2184

with an item that can be added to

2185

2186

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

2187

added to <filename>IMAGE_FEATURES</filename> will

2188

install -dev packages (containing headers and other

2189

development files) for every package in the image.

</para>

<para>

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

2194

variable flag to specify the feature item name and

2195

use the value to specify the wildcard.

2196

Here is an example:

2197

2198

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

2205

<info>

2206

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

</info>

2211

Tracks the version of the local configuration file

2212

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

2213

The value for <filename>CONF_VERSION</filename>

2214

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

2215

compatibility changes.

</para>

</glossdef>

</glossentry>

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

2221

<info>

2222

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

</info>

2227

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

2228

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

2229

packages on the target system, it is possible that

2230

configuration files you have changed after the original installation

2231

and that you now want to remain unchanged are overwritten.

2232

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

2233

want reset as part of the package update process.

2234

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

2235

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

2240

override that identifies the resulting package.

2241

Then, provide a space-separated list of files.

2242

Here is an example:

2243

2244

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

2245

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

</literallayout>

</para>

<para>

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

2251

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

2252

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

2253

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

2254

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

2255

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

2256

it makes sense that

2257

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

2258

<filename>FILES</filename> variable.

</para>

<note>

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

2263

it is good practice to use appropriate path variables.

2264

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

2265

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

2266

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

2267

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

2268

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

2269

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

2275

<info>

Brad Bishop

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

[diff] [blame^]

2276

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

2281

Identifies the initial RAM filesystem (initramfs) source

2282

files.

Patrick Williams

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

[diff] [blame]

2283

The OpenEmbedded build system receives and uses

2284

this kernel Kconfig variable as an environment variable.

2285

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

</para>

<para>

The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be

2290

either a single cpio archive with a

2291

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

2292

space-separated list of directories and files for building

2293

the initramfs image.

2294

A cpio archive should contain a filesystem archive

2295

to be used as an initramfs image.

2296

Directories should contain a filesystem layout to be

2297

included in the initramfs image.

2298

Files should contain entries according to the format

2299

described by the

2300

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

kernel tree.

</para>

<para>

If you specify multiple directories and files, the

2306

initramfs image will be the aggregate of all of them.

2307

</para>

Brad Bishop

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

[diff] [blame^]

2308

2309

<para>

2310

For information on creating an initramfs, see the

2311

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

2312

section in the Yocto Project Development Manual.

2313

</para>

Patrick Williams

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

[diff] [blame]

</glossdef>

</glossentry>

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

2318

<info>

2319

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>

2324

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

2325

to the current build.

2326

This variable is used by the Autotools utilities when running

2327

<filename>configure</filename>.

</para>

</glossdef>

</glossentry>

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

2333

<info>

2334

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

</info>

2339

The minimal arguments for GNU configure.

</para>

</glossdef>

</glossentry>

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

2345

<info>

2346

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

2355

be in conflict should the recipe

2356

be built.

2357

In other words, if the

2358

<filename>CONFLICT_DISTRO_FEATURES</filename> variable

2359

lists a feature that also appears in

2360

<filename>DISTRO_FEATURES</filename> within the

2361

current configuration, an error occurs and the

build stops.

</para>

</glossdef>

</glossentry>

<info>

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

</info>

2374

If set to "1" along with the

2375

2376

variable, the OpenEmbedded build system copies

2377

into the image the license files, which are located in

2378

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

2379

for each package.

2380

The license files are placed

Patrick Williams

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

[diff] [blame]

2381

in directories within the image itself during build time.

2382

<note>

2383

The <filename>COPY_LIC_DIRS</filename> does not

2384

offer a path for adding licenses for newly installed

2385

packages to an image, which might be most suitable

2386

for read-only filesystems that cannot be upgraded.

2387

See the

2388

2389

variable for additional information.

2390

You can also reference the

2391

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

2392

section in the Yocto Project Development Manual for

2393

information on providing license text.

2394

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

2400

<info>

2401

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>

2406

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

2407

the license manifest for the image to

2408

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

Patrick Williams

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

[diff] [blame]

2409

within the image itself during build time.

2410

<note>

2411

The <filename>COPY_LIC_MANIFEST</filename> does not

2412

offer a path for adding licenses for newly installed

2413

packages to an image, which might be most suitable

2414

for read-only filesystems that cannot be upgraded.

2415

See the

2416

2417

variable for additional information.

2418

You can also reference the

2419

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

2420

section in the Yocto Project Development Manual for

2421

information on providing license text.

2422

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

2428

<info>

2429

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>

2434

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

2435

You should only set this variable in the

2436

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

2437

in the

2438

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

2448

<info>

2449

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

</info>

2454

Specifies the parent directory of the OpenEmbedded

2455

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

</para>

<para>

It is an important distinction that

2460

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

2461

layer and not the layer itself.

2462

Consider an example where you have cloned the Poky Git

2463

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

2464

name for your local copy of the repository.

2465

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

2466

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

2467

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

layer.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

2473

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

2474

<info>

2475

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

</info>

2480

Lists files from the

2481

2482

directory that should be copied other than the layers

2483

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

2484

The <filename>COREBASE_FILES</filename> variable exists

2485

for the purpose of copying metadata from the

2486

OpenEmbedded build system into the extensible

SDK.

</para>

<para>

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

2492

is needed because it typically contains build

2493

directories and other files that should not normally

2494

be copied into the extensible SDK.

2495

Consequently, the value of

2496

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

2497

only copy the files that are actually needed.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

2502

2503

<info>

2504

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

</info>

2509

The minimal command and arguments used to run the C

preprocessor.

</para>

</glossdef>

</glossentry>

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

2516

<info>

2517

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

</info>

2522

Specifies the flags to pass to the C pre-processor

2523

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

2524

This variable is exported to an environment

2525

variable and thus made visible to the software being

2526

built during the compilation step.

</para>

<para>

Default initialization for <filename>CPPFLAGS</filename>

2531

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

2540

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

2545

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

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

2553

<info>

2554

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

</info>

2559

The toolchain binary prefix for the target tools.

2560

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

same as the

variable.

<note>

The OpenEmbedded build system sets the

2566

<filename>CROSS_COMPILE</filename> variable only in

2567

certain contexts (e.g. when building for kernel

2568

and kernel module recipes).

</note>

</para>

</glossdef>

</glossentry>

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

2575

<info>

2576

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

</info>

2581

The directory in which files checked out under the

2582

CVS system are stored.

</para>

</glossdef>

</glossentry>

<info>

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

</info>

2594

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

compiler.

</para>

</glossdef>

</glossentry>

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

2601

<info>

2602

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

</info>

2607

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

2608

This variable is exported to an environment

2609

variable and thus made visible to the software being

2610

built during the compilation step.

</para>

<para>

Default initialization for <filename>CXXFLAGS</filename>

2615

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

2624

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

Patrick Williams

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

[diff] [blame]

2629

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

2647

The destination directory.

2648

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

2649

where components are installed by the

2650

2651

task.

2652

This location defaults to:

2653

Patrick Williams

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

[diff] [blame]

2654

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

Patrick Williams

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

[diff] [blame]

2655

</literallayout>

Patrick Williams

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

[diff] [blame]

2656

<note><title>Caution</title>

2657

Tasks that read from or write to this directory should

2658

run under

2659

2660

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

2672

The date the build was started.

2673

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

2674

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

</para>

</glossdef>

</glossentry>

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

2680

<info>

2681

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

</info>

2686

The date and time on which the current build started.

2687

The format is suitable for timestamps.

</para>

</glossdef>

</glossentry>

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

2693

<info>

2694

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

</info>

2699

When the

2700

2701

class is inherited, which is the default behavior,

2702

<filename>DEBIAN_NOAUTONAME</filename> specifies a

2703

particular package should not be renamed according to

2704

Debian library package naming.

2705

You must use the package name as an override when you

2706

set this variable.

2707

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

2708

recipe:

2709

2710

DEBIAN_NOAUTONAME_fontconfig-utils = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

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

2717

<info>

2718

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

</info>

2723

When the

2724

2725

class is inherited, which is the default behavior,

2726

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

2727

library name for an individual package.

2728

Overriding the library name in these cases is rare.

2729

You must use the package name as an override when you

2730

set this variable.

2731

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

2732

recipe:

2733

2734

DEBIANNAME_${PN} = "dbus-1"

</literallayout>

</para>

</glossdef>

</glossentry>

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

2741

<info>

2742

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

</info>

2747

Specifies to build packages with debugging information.

2748

This influences the value of the

2749

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

variable.

</para>

</glossdef>

</glossentry>

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

2756

<info>

2757

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>

2762

The options to pass in

2763

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

2764

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

2765

a system for debugging.

2766

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

</para>

</glossdef>

</glossentry>

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

2772

<info>

2773

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

</info>

2778

Specifies a weak bias for recipe selection priority.

</para>

<para>

The most common usage of this is variable is to set

2783

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

2784

piece of software.

2785

Using the variable in this way causes the stable version

2786

of the recipe to build by default in the absence of

2787

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

2788

being used to build the development version.

</para>

<note>

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

2793

is weak and is overridden by

2794

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

2795

if that variable is different between two layers

2796

that contain different versions of the same recipe.

</note>

</glossdef>

</glossentry>

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

2802

<info>

2803

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

</info>

2808

The default CPU and Application Binary Interface (ABI)

2809

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

2810

system.

2811

The <filename>DEFAULTTUNE</filename> helps define

</para>

<para>

The default tune is either implicitly or explicitly set

2817

by the machine

2818

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

2819

However, you can override the setting using available tunes

as defined with

</para>

</glossdef>

</glossentry>

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

2827

<info>

2828

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]

2833

Lists a recipe's build-time dependencies.

2834

These are dependencies on other recipes whose

2835

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

2836

by the recipe at build time.

Patrick Williams

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

[diff] [blame]

2837

</para>

2838

2839

<para>

Patrick Williams

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

[diff] [blame]

2840

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

2841

that contains the following assignment:

Patrick Williams

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

[diff] [blame]

2842

Patrick Williams

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

[diff] [blame]

2843

DEPENDS = "bar"

Patrick Williams

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

[diff] [blame]

2844

</literallayout>

Patrick Williams

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

[diff] [blame]

2845

The practical effect of the previous assignment is that

2846

all files installed by bar will be available in the

2847

appropriate staging sysroot, given by the

2848

2849

variables, by the time the

Patrick Williams

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

[diff] [blame]

2850

Patrick Williams

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

[diff] [blame]

2851

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

2852

This mechanism is implemented by having

2853

<filename>do_configure</filename> depend on the

Patrick Williams

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

[diff] [blame]

2854

Patrick Williams

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

[diff] [blame]

2855

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

2856

through a

2857

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

2863

<filename>STAGING_DIR_HOST</filename> explicitly.

2864

The standard classes and build-related variables are

2865

configured to automatically use the appropriate staging

2866

sysroots.

2867

</note>

2868

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

2869

be used to add utilities that run on the build machine

2870

during the build.

2871

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

2872

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

2873

the following:

2874

2875

DEPENDS = "codegen-native"

2876

</literallayout>

2877

For more information, see the

class and the

variable.

<note>

<title>Notes</title>

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

2887

recipe names.

2888

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

2889

2890

names, which usually match recipe names.

2891

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

2892

<filename>DEPENDS</filename> does not make

2893

sense.

2894

Use "foo" instead, as this will put files

2895

from all the packages that make up

2896

<filename>foo</filename>, which includes

2897

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

the sysroot.

</para></listitem>

One recipe having another recipe in

2902

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

2903

add any runtime dependencies between the

2904

packages produced by the two recipes.

2905

However, as explained in the

2906

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

2907

section, runtime dependencies will often be

2908

added automatically, meaning

2909

<filename>DEPENDS</filename> alone is

2910

sufficient for most recipes.

</para></listitem>

Counterintuitively,

<filename>DEPENDS</filename> is often necessary

2915

even for recipes that install precompiled

2916

components.

2917

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

2918

is a precompiled library that links against

2919

<filename>libbar</filename>, then

2920

linking against <filename>libfoo</filename>

2921

requires both <filename>libfoo</filename>

2922

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

2923

in the sysroot.

2924

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

2925

recipe that installs <filename>libfoo</filename>

2926

to the recipe that installs

2927

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

2928

fail to link against

2929

<filename>libfoo</filename>.

2930

</para></listitem>

2931

</itemizedlist>

2932

</note>

Patrick Williams

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

[diff] [blame]

</para>

<para>

For information on runtime dependencies, see the

2937

2938

variable.

Patrick Williams

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

[diff] [blame]

2939

You can also see the

2940

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

2941

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

2942

sections in the BitBake User Manual for additional

2943

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>

2949

<info>

2950

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>

2955

Points to the general area that the OpenEmbedded build

2956

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

2957

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

2958

By default, this directory resides within the

2959

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

2960

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

</para>

<para>

For more information on the structure of the Build

2965

Directory, see

2966

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

2967

section.

2968

For more detail on the contents of the

2969

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

2970

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

2971

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

2972

and

2973

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

sections.

</para>

</glossdef>

</glossentry>

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

2980

<info>

2981

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>

2986

Points to the area that the OpenEmbedded build system uses

2987

to place Debian packages that are ready to be used outside

2988

of the build system.

2989

This variable applies only when

2990

2991

contains "package_deb".

</para>

<para>

The BitBake configuration file initially defines the

2996

<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

3009

the

3010

3011

task writes Debian packages into the appropriate folder.

3012

For more information on how packaging works, see the

3013

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

section.

</para>

</glossdef>

</glossentry>

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

3020

<info>

3021

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>

3026

Points to the area that the OpenEmbedded build system uses

3027

to place images and other associated output files that are

3028

ready to be deployed onto the target machine.

3029

The directory is machine-specific as it contains the

3030

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

3031

By default, this directory resides within the

3032

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

3033

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

</para>

<para>

For more information on the structure of the Build

3038

Directory, see

3039

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

3040

section.

3041

For more detail on the contents of the

3042

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

3043

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

3044

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

sections.

</para>

</glossdef>

</glossentry>

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

3051

<info>

3052

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>

3057

Points to the area that the OpenEmbedded build system uses

3058

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

3059

the build system.

3060

This variable applies only when

3061

3062

contains "package_ipk".

</para>

<para>

The BitBake configuration file initially defines this

3067

variable as a sub-folder of

3068

3069

3070

DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"

</literallayout>

</para>

<para>

The

class uses the

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

3079

the

3080

3081

task writes IPK packages into the appropriate folder.

3082

For more information on how packaging works, see the

3083

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

section.

</para>

</glossdef>

</glossentry>

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

3090

<info>

3091

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>

3096

Points to the area that the OpenEmbedded build system uses

3097

to place RPM packages that are ready to be used outside

3098

of the build system.

3099

This variable applies only when

3100

3101

contains "package_rpm".

</para>

<para>

The BitBake configuration file initially defines this

3106

variable as a sub-folder of

3107

3108

3109

DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"

</literallayout>

</para>

<para>

The

class uses the

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

3118

the

3119

3120

task writes RPM packages into the appropriate folder.

3121

For more information on how packaging works, see the

3122

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

section.

</para>

</glossdef>

</glossentry>

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

3129

<info>

3130

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>

3135

Points to the area that the OpenEmbedded build system uses

3136

to place tarballs that are ready to be used outside of

3137

the build system.

3138

This variable applies only when

3139

3140

contains "package_tar".

</para>

<para>

The BitBake configuration file initially defines this

3145

variable as a sub-folder of

3146

3147

3148

DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"

</literallayout>

</para>

<para>

The

class uses the

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

3157

the

3158

3159

task writes TAR packages into the appropriate folder.

3160

For more information on how packaging works, see the

3161

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

section.

</para>

</glossdef>

</glossentry>

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

3168

<info>

3169

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

</info>

3174

When inheriting the

3175

3176

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

3177

temporary work area for deployed files that is set in the

3178

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

3179

3180

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

</literallayout>

</para>

<para>

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

3186

should copy files to be deployed into

3187

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

3188

care of copying them into

afterwards.

</para>

</glossdef>

</glossentry>

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

3196

<info>

3197

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

</info>

3202

The package description used by package managers.

3203

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

the value of the

variable.

</para>

</glossdef>

</glossentry>

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

3212

<info>

3213

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

</info>

3218

A 32-bit MBR disk signature used by

3219

<filename>directdisk</filename> images.

</para>

<para>

By default, the signature is set to an automatically

3224

generated random value that allows the OpenEmbedded

3225

build system to create a boot loader.

3226

You can override the signature in the image recipe

3227

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

3228

8-digit hex string.

3229

You might want to override

3230

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

3231

signature to remain constant between image builds.

</para>

<para>

When using Linux 3.8 or later, you can use

3236

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

3237

by UUID to allow the kernel to locate the root device

3238

even if the device name changes due to differences in

3239

hardware configuration.

Patrick Williams

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

[diff] [blame]

3240

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

Patrick Williams

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

[diff] [blame]

3241

as follows:

3242

Patrick Williams

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

[diff] [blame]

3243

ROOT_VM ?= "root=/dev/sda2"

Patrick Williams

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

[diff] [blame]

3244

</literallayout>

3245

However, you can change this to locate the root device

3246

using the disk signature instead:

3247

Patrick Williams

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

[diff] [blame]

3248

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

3254

<filename>DISK_SIGNATURE</filename> variable in your

3255

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

3256

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

3257

changing for each build.

3258

You might find this useful when you want to upgrade the

3259

root filesystem on a device without having to recreate or

3260

modify the master boot record.

</para>

</glossdef>

</glossentry>

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

3266

<info>

3267

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

</info>

3272

The short name of the distribution.

3273

This variable corresponds to a distribution

3274

configuration file whose root name is the same as the

3275

variable's argument and whose filename extension is

3276

<filename>.conf</filename>.

3277

For example, the distribution configuration file for the

3278

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

3279

and resides in the

Patrick Williams

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

[diff] [blame]

3280

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

Patrick Williams

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

[diff] [blame]

3281

the

3282

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

</para>

<para>

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

3287

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

DISTRO = "poky"

</literallayout>

</para>

<para>

Distribution configuration files are located in a

3295

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

3296

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

3297

that contains the distribution configuration.

3298

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

3299

spaces, and is typically all lower-case.

3300

<note>

3301

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

3302

of default configurations are used, which are specified

3303

within

3304

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

3305

also in the Source Directory.

</note>

</para>

</glossdef>

</glossentry>

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

3312

<info>

3313

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

</info>

3318

Specifies a codename for the distribution being built.

</para>

</glossdef>

</glossentry>

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

3324

<info>

3325

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>

3330

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

3331

This variable takes affect through

3332

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

3333

variable only really applies to the more full-featured

3334

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

3335

You can use this variable to keep distro policy out of

3336

generic images.

3337

As with all other distro variables, you set this variable

3338

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

</para>

</glossdef>

</glossentry>

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

3344

<info>

3345

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>

3350

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

3351

if the packages exist.

3352

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

3353

The list of packages are automatically installed but you can

remove them.

</para>

</glossdef>

</glossentry>

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

3360

<info>

3361

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

</info>

3366

The software support you want in your distribution for

3367

various features.

3368

You define your distribution features in the distribution

configuration file.

</para>

<para>

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

3374

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

3375

appropriate option supplied to the configure script

3376

during the

3377

3378

task for recipes that optionally support the feature.

3379

For example, specifying "x11" in

3380

<filename>DISTRO_FEATURES</filename>, causes

3381

every piece of software built for the target that can

3382

optionally support X11 to have its X11 support enabled.

</para>

<para>

Two more examples are Bluetooth and NFS support.

3387

For a more complete list of features that ships with the

3388

Yocto Project and that you can provide with this variable,

3389

see the

3390

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

section.

</para>

</glossdef>

</glossentry>

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

3397

<info>

3398

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>

3403

Features to be added to

3404

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

3405

if not also present in

3406

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

3411

It is not intended to be user-configurable.

3412

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

3413

being backfilled for all distro configurations.

3414

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>

3421

<info>

3422

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>

3427

Features from

3428

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

3429

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

3430

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

3431

during the build.

3432

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>

3439

<info>

3440

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

</info>

3445

A convenience variable that gives you the default

3446

list of distro features with the exception of any

3447

features specific to the C library

3448

(<filename>libc</filename>).

</para>

<para>

When creating a custom distribution, you might find it

3453

useful to be able to reuse the default

3454

3455

options without the need to write out the full set.

3456

Here is an example that uses

3457

<filename>DISTRO_FEATURES_DEFAULT</filename> from a

3458

custom distro configuration file:

3459

3460

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

3467

<info>

3468

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

</info>

3473

A convenience variable that specifies the list of distro

3474

features that are specific to the C library

3475

(<filename>libc</filename>).

3476

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

3477

control which features are enabled at during the build

3478

within the C library itself.

</para>

</glossdef>

</glossentry>

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

3484

<info>

3485

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

</info>

3490

The long name of the distribution.

</para>

</glossdef>

</glossentry>

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

3496

<info>

3497

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

</info>

3502

The version of the distribution.

</para>

</glossdef>

</glossentry>

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

3508

<info>

Patrick Williams

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

[diff] [blame]

3509

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]

3514

A colon-separated list of overrides specific to the

3515

current distribution.

3516

By default, this list includes the value of

</para>

<para>

You can extend <filename>DISTROOVERRIDES</filename>

3522

to add extra overrides that should apply to

the distribution.

</para>

<para>

The underlying mechanism behind

3528

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

3529

is included in the default value of

3530

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>

3542

The central download directory used by the build process to

3543

store downloads.

3544

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

3545

suitable for mirroring for everything except Git

3546

repositories.

3547

If you want tarballs of Git repositories, use the

variable.

</para>

<para>

You can set this directory by defining the

3554

<filename>DL_DIR</filename> variable in the

3555

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

3556

This directory is self-maintaining and you should not have

3557

to touch it.

3558

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

3559

in the

3560

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

3561

3562

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

3563

</literallayout>

3564

To specify a different download directory, simply remove

3565

the comment from the line and provide your directory.

</para>

<para>

During a first build, the system downloads many different

3570

source code tarballs from various upstream projects.

3571

Downloading can take a while, particularly if your network

3572

connection is slow.

3573

Tarballs are all stored in the directory defined by

3574

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

3575

first to find source tarballs.

3576

<note>

3577

When wiping and rebuilding, you can preserve this

3578

directory to speed up this part of subsequent

builds.

</note>

</para>

<para>

You can safely share this directory between multiple builds

3585

on the same development machine.

3586

For additional information on how the build process gets

3587

source files when working behind a firewall or proxy server,

3588

see this specific question in the

3589

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

3590

chapter.

Patrick Williams

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

[diff] [blame]

3591

You can also refer to the

3592

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

3593

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>

3599

<info>

3600

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>

3605

When inheriting the

3606

3607

class, this variable sets the compression policy used when

3608

the OpenEmbedded build system compresses man pages and info

3609

pages.

3610

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

3611

Other policies available are xz and bz2.

</para>

<para>

For information on policies and on how to use this

3616

variable, see the comments in the

3617

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

</para>

</glossdef>

</glossentry>

</glossdiv>

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

3627

<info>

3628

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>

3633

When building bootable images (i.e. where

3634

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

3635

is in

3636

3637

the <filename>EFI_PROVIDER</filename> variable specifies

3638

the EFI bootloader to use.

Patrick Williams

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

[diff] [blame]

3639

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]

3645

Patrick Williams

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

[diff] [blame]

3646

class for more information.

</para>

</glossdef>

</glossentry>

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

3652

<info>

3653

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>

3658

Variable that controls which locales for

3659

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

3660

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>

3667

<info>

3668

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>

3673

When used with the

3674

3675

class, specifies the path used for storing the debug files

3676

created by the

3677

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

3678

which allows you to submit build errors you encounter to a

3679

central database.

3680

By default, the value of this variable is

3681

<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

3686

you want the error reporting tool to store the debug files

3687

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

3688

3689

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

3696

<info>

3697

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

</info>

3702

Specifies the quality assurance checks whose failures are

3703

reported as errors by the OpenEmbedded build system.

3704

You set this variable in your distribution configuration

3705

file.

3706

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

3707

see the

3708

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

3714

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

3715

<info>

3716

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

</info>

3721

Triggers the OpenEmbedded build system's shared libraries

3722

resolver to exclude an entire package when scanning for

3723

shared libraries.

3724

<note>

3725

The shared libraries resolver's functionality results

3726

in part from the internal function

3727

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

the

task.

You should be aware that the shared libraries resolver

3732

might implicitly define some dependencies between

3733

packages.

3734

</note>

3735

The <filename>EXCLUDE_FROM_SHLIBS</filename> variable is

3736

similar to the

3737

3738

variable, which excludes a package's particular libraries

3739

only and not the whole package.

</para>

<para>

Use the

<filename>EXCLUDE_FROM_SHLIBS</filename> variable by

3745

setting it to "1" for a particular package:

3746

3747

EXCLUDE_FROM_SHLIBS = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

3753

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

3754

<info>

3755

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

</info>

3760

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

3761

<filename>bitbake world</filename>).

3762

During world builds, BitBake locates, parses and builds all

3763

recipes found in every layer exposed in the

3764

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

</para>

<para>

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

3769

set the variable to "1" in the recipe.

</para>

<note>

Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>

3774

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

3775

dependencies of other recipes.

3776

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

3777

only ensures that the recipe is not explicitly added

3778

to the list of build targets in a world build.

</note>

</glossdef>

</glossentry>

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

3784

<info>

3785

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>

3790

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

3791

version based on the recipe's

3792

3793

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

3794

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

3795

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

3796

becomes "1_").

3797

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

3798

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

3799

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

3800

variable for an example.

</para>

</glossdef>

</glossentry>

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

3806

<info>

3807

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

</info>

3812

The full package version specification as it appears on the

3813

final packages produced by a recipe.

3814

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

3815

dependency to the exact same version of another package

3816

in the same recipe:

3817

3818

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

</literallayout>

</para>

<para>

The dependency relationships are intended to force the

3824

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>

3831

<info>

3832

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

</info>

3837

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

3838

variable indicates that these tools are not in the

source tree.

</para>

<para>

When kernel tools are available in the tree, they are

3844

preferred over any externally installed tools.

3845

Setting the <filename>EXTERNAL_KERNEL_TOOLS</filename>

3846

variable tells the OpenEmbedded build system to prefer

3847

the installed external tools.

3848

See the

3849

3850

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

3851

the variable is used.

</para>

</glossdef>

</glossentry>

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

3857

<info>

3858

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

</info>

3863

When inheriting the

3864

3865

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

3866

outside of the OpenEmbedded build system.

3867

When set, this variable sets the

3868

3869

variable, which is what the OpenEmbedded build system uses

3870

to locate unpacked recipe source code.

</para>

<para>

For more information on

3875

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

3876

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

3877

section.

3878

You can also find information on how to use this variable

3879

in the

3880

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

3881

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

3887

<info>

3888

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>

3893

When inheriting the

3894

3895

class, this variable points to the directory in which the

3896

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

3897

OpenEmbedded build system.

3898

When set, this variable sets the

3899

3900

variable, which is what the OpenEmbedded build system uses

3901

to locate the Build Directory.

</para>

<para>

For more information on

3906

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

3907

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

3908

section.

3909

You can also find information on how to use this variable

3910

in the

3911

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

3912

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

3918

<info>

3919

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

</info>

3924

For recipes inheriting the

3925

3926

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

3927

specify extra options to pass to the

3928

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

3941

<info>

3942

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>

3947

A list of additional features to include in an image.

3948

When listing more than one feature, separate them with

a space.

</para>

<para>

Typically, you configure this variable in your

3954

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

3955

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

3956

Although you can use this variable from within a recipe,

3957

best practices dictate that you do not.

3958

<note>

3959

To enable primary features from within the image

recipe, use the

variable.

</note>

</para>

<para>

Here are some examples of features you can add:

3968

3969

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

3970

including symbol information for debugging and

3971

profiling.

3972

3973

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

3974

For example, allows root logins without

3975

passwords and enables post-installation

3976

logging. See the 'allow-empty-password'

3977

and 'post-install-logging' features in

3978

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

3979

more information.

3980

3981

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

3982

This is useful if you want to develop against

3983

the libraries in the image.

3984

3985

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

3986

filesystem is read-only. See the

3987

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

3988

section in the Yocto Project

3989

Development Manual for more

3990

information

3991

3992

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

3993

strace.

3994

Patrick Williams

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

[diff] [blame]

3995

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

3996

pkgconfig and so forth.

3997

3998

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

3999

ts_print, aplay, arecord and so

forth.

</literallayout>

</para>

<para>

For a complete list of image features that ships with the

4007

Yocto Project, see the

4008

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

section.

</para>

<para>

For an example that shows how to customize your image by

4014

using this variable, see the

4015

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

4016

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

4022

<info>

4023

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>

4028

Specifies additional options for the image

4029

creation command that has been specified in

4030

4031

When setting this variable, you should

4032

use an override for the associated type.

4033

Here is an example:

4034

4035

EXTRA_IMAGECMD_ext3 ?= "-i 4096"

</literallayout>

</para>

</glossdef>

</glossentry>

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

4042

<info>

4043

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>

4048

A list of recipes to build that do not provide packages

4049

for installing into the root filesystem.

</para>

<para>

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

4054

needed in the root filesystem.

4055

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

4056

list these recipes and thus specify the dependencies.

4057

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

</para>

<note>

To add packages to the root filesystem, see the various

4062

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

4063

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

variables.

</note>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

4069

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

4070

<info>

4071

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

</info>

4076

A list of subdirectories of

4077

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

4078

added to the beginning of the environment variable

4079

<filename>PATH</filename>.

4080

As an example, the following prepends

4081

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

4082

to <filename>PATH</filename>:

4083

4084

EXTRANATIVEPATH = "foo bar"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

4090

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

4091

<info>

4092

EXTRA_OECMAKE[doc] = "Additional cmake options."

</info>

4097

Additional <filename>cmake</filename> options.

</para>

</glossdef>

</glossentry>

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

4103

<info>

4104

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

</info>

4109

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

Patrick Williams

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

[diff] [blame]

4110

See

4111

4112

for additional information on passing configure script

4113

options.

Patrick Williams

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

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

4119

<info>

4120

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

</info>

4125

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

4126

</para>

Patrick Williams

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

[diff] [blame]

4127

4128

<para>

4129

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

4130

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

4131

GNU options.

4132

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

4140

flags.

4141

</para>

Patrick Williams

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

[diff] [blame]

</glossdef>

</glossentry>

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

4146

<info>

4147

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>

4152

When inheriting the

4153

4154

class, this variable specifies additional configuration

4155

options you want to pass to the

4156

<filename>scons</filename> command line.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

4161

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

4162

<info>

4163

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

</info>

4168

When inheriting the

4169

4170

class, this variable provides image level user and group

4171

operations.

4172

This is a more global method of providing user and group

4173

configuration as compared to using the

4174

4175

class, which ties user and group configurations to a

specific recipe.

</para>

<para>

The set list of commands you can configure using the

4181

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

4182

<filename>extrausers</filename> class.

4183

These commands map to the normal Unix commands of the same

4184

names:

4185

4186

# EXTRA_USERS_PARAMS = "\

4187

# useradd -p '' tester; \

4188

# groupadd developers; \

4189

# userdel nobody; \

4190

# groupdel -g video; \

4191

# groupmod -g 1020 developers; \

4192

# usermod -s /bin/sh tester; \

# "

</literallayout>

</para>

</glossdef>

</glossentry>

</glossdiv>

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

4204

<info>

4205

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>

4210

Defines one or more packages to include in an image when

4211

a specific item is included in

4212

4213

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

4214

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

4215

Here is an example:

4216

4217

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

</literallayout>

</para>

<para>

In this example, if "widget" were added to

4223

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

4224

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

4225

<note>

4226

Packages installed by features defined through

4227

<filename>FEATURE_PACKAGES</filename> are often package

4228

groups.

4229

While similarly named, you should not confuse the

4230

<filename>FEATURE_PACKAGES</filename> variable with

4231

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>

4239

<info>

4240

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>

4245

Points to the base URL of the server and location within

4246

the document-root that provides the metadata and

4247

packages required by OPKG to support runtime package

4248

management of IPK packages.

4249

You set this variable in your

4250

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

</para>

<para>

Consider the following example:

4255

4256

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

4257

</literallayout>

4258

This example assumes you are serving your packages over

4259

HTTP and your databases are located in a directory

4260

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

4261

your HTTP server's document-root.

4262

In this case, the OpenEmbedded build system generates a set

4263

of configuration files for you in your target that work

with the feed.

</para>

</glossdef>

</glossentry>

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

4270

<info>

Patrick Williams

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

[diff] [blame]

4271

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]

4276

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

4285

package name override that identifies the resulting package.

4286

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

4287

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]

4291

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

4297

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

4298

to use appropriate path variables.

4299

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

4300

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

4301

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

4302

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

4303

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

4304

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

4305

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

Patrick Williams

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

[diff] [blame]

4306

You will also find the default values of the various

4307

<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

4312

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

4313

know they should not be overwritten during the package

4314

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

4315

can identify these files so that the PMS will not

overwrite them.

See the

variable for information on how to identify these files to

4320

the PMS.

4321

</para>

Patrick Williams

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

[diff] [blame]

</glossdef>

</glossentry>

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

4326

<info>

4327

FILES_SOLIBSDEV[doc] = "Defines the full path name of the development symbolic link (symlink) for shared libraries on the target platform."

</info>

4332

Defines the file specification to match

4333

4334

In other words, <filename>FILES_SOLIBSDEV</filename>

4335

defines the full path name of the development symbolic link

4336

(symlink) for shared libraries on the target platform.

</para>

<para>

The following statement from the

4341

<filename>bitbake.conf</filename> shows how it is set:

4342

4343

FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"

</literallayout>

</para>

</glossdef>

</glossentry>

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

4350

<info>

4351

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>

4356

Extends the search path the OpenEmbedded build system uses

4357

when looking for files and patches as it processes recipes

4358

and append files.

4359

The default directories BitBake uses when it processes

4360

recipes are initially defined by the

4361

4362

variable.

4363

You can extend <filename>FILESPATH</filename> variable

4364

by using <filename>FILESEXTRAPATHS</filename>.

</para>

<para>

Best practices dictate that you accomplish this by using

4369

<filename>FILESEXTRAPATHS</filename> from within a

4370

<filename>.bbappend</filename> file and that you prepend

4371

paths as follows:

4372

4373

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"

4374

</literallayout>

4375

In the above example, the build system first looks for files

4376

in a directory that has the same name as the corresponding

4377

append file.

4378

<note>

4379

<para>When extending <filename>FILESEXTRAPATHS</filename>,

4380

be sure to use the immediate expansion

4381

(<filename>:=</filename>) operator.

4382

Immediate expansion makes sure that BitBake evaluates

4383

4384

at the time the directive is encountered rather than at

4385

some later time when expansion might result in a

4386

directory that does not contain the files you need.

4387

</para>

4388

<para>Also, include the trailing separating colon

4389

character if you are prepending.

4390

The trailing colon character is necessary because you

4391

are directing BitBake to extend the path by prepending

4392

directories to the search path.</para>

4393

</note>

4394

Here is another common use:

4395

4396

FILESEXTRAPATHS_prepend := "${THISDIR}/files:"

4397

</literallayout>

4398

In this example, the build system extends the

4399

<filename>FILESPATH</filename> variable to include a

4400

directory named <filename>files</filename> that is in the

4401

same directory as the corresponding append file.

</para>

<para>

Here is a final example that specifically adds three paths:

4406

4407

FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"

</literallayout>

</para>

<para>

By prepending paths in <filename>.bbappend</filename>

4413

files, you allow multiple append files that reside in

4414

different layers but are used for the same recipe to

4415

correctly extend the path.

</para>

</glossdef>

</glossentry>

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

4421

<info>

4422

FILESOVERRIDES[doc] = "A subset of OVERRIDES used by the OpenEmbedded build system for creating FILESPATH."

</info>

4427

A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>

4428

used by the OpenEmbedded build system for creating

4429

4430

You can find more information on how overrides are handled

4431

in the

4432

<ulink url='&YOCTO_DOCS_BB_URL;'>BitBake Manual</ulink>.

</para>

<para>

By default, the <filename>FILESOVERRIDES</filename>

4437

variable is defined as:

4438

4439

FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"

</literallayout>

<note>

Do not hand-edit the <filename>FILESOVERRIDES</filename>

4444

variable.

4445

The values match up with expected overrides and are

4446

used in an expected manner by the build system.

</note>

</para>

</glossdef>

</glossentry>

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

4453

<info>

4454

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>

4459

The default set of directories the OpenEmbedded build system

4460

uses when searching for patches and files.

4461

During the build process, BitBake searches each directory in

4462

<filename>FILESPATH</filename> in the specified order when

4463

looking for files and patches specified by each

4464

<filename>file://</filename> URI in a recipe.

</para>

<para>

The default value for the <filename>FILESPATH</filename>

4469

variable is defined in the <filename>base.bbclass</filename>

4470

class found in <filename>meta/classes</filename> in the

4471

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

4472

4473

FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \

4474

"${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"

4475

</literallayout>

4476

<note>

4477

Do not hand-edit the <filename>FILESPATH</filename>

4478

variable.

4479

If you want the build system to look in directories

4480

other than the defaults, extend the

4481

<filename>FILESPATH</filename> variable by using the

variable.

</note>

Be aware that the default <filename>FILESPATH</filename>

4486

directories do not map to directories in custom layers

4487

where append files (<filename>.bbappend</filename>)

4488

are used.

4489

If you want the build system to find patches or files

4490

that reside with your append files, you need to extend

4491

the <filename>FILESPATH</filename> variable by using

the

variable.

</para>

</glossdef>

</glossentry>

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

4500

<info>

4501

FILESYSTEM_PERMS_TABLES[doc] = "Allows you to define your own file permissions settings table as part of your configuration for the packaging process."

</info>

4506

Allows you to define your own file permissions settings table as part of

4507

your configuration for the packaging process.

4508

For example, suppose you need a consistent set of custom permissions for

4509

a set of groups and users across an entire work project.

4510

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

4516

is located in the <filename>meta/files</filename> folder in the

4517

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

4518

If you create your own file permissions setting table, you should place it in your

4519

layer or the distro's layer.

</para>

<para>

You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the

4524

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

4525

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

4526

point to your custom <filename>fs-perms.txt</filename>.

4527

You can specify more than a single file permissions setting table.

4528

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,

4534

examine the existing <filename>fs-perms.txt</filename>.

</para>

</glossdef>

</glossentry>

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

4540

<info>

4541

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>

4546

When inheriting the

4547

4548

class, this variable specifies the runtime dependencies

4549

for font packages.

4550

By default, the <filename>FONT_EXTRA_RDEPENDS</filename>

4551

is set to "fontconfig-utils".

</para>

</glossdef>

</glossentry>

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

4557

<info>

4558

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>

4563

When inheriting the

4564

4565

class, this variable identifies packages containing font

4566

files that need to be cached by Fontconfig.

4567

By default, the <filename>fontcache</filename> class assumes

4568

that fonts are in the recipe's main package

4569

(i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).

4570

Use this variable if fonts you need are in a package

4571

other than that main package.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

4576

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

4577

<info>

4578

FORCE_RO_REMOVE[doc] = "Forces the removal of the packages listed in ROOTFS_RO_UNNEEDED during the generation of the root filesystem."

</info>

4583

Forces the removal of the packages listed in

4584

<filename>ROOTFS_RO_UNNEEDED</filename> during the

4585

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]

4595

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

4596

<info>

4597

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>

4602

The options to pass in

4603

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

4604

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

4605

when compiling an optimized system.

4606

This variable defaults to

4607

"-O2 -pipe ${DEBUG_FLAGS}".

</para>

</glossdef>

</glossentry>

</glossdiv>

<info>

GDB[doc] = "The minimal command and arguments to run the GNU Debugger."

</info>

4622

The minimal command and arguments to run the GNU Debugger.

</para>

</glossdef>

</glossentry>

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

4628

<info>

4629

GITDIR[doc] = "The directory where Git clones will be stored."

</info>

4634

The directory in which a local copy of a Git repository

4635

is stored when it is cloned.

</para>

</glossdef>

</glossentry>

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

4641

<info>

4642

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>

4647

Specifies the list of GLIBC locales to generate should you

4648

not wish generate all LIBC locals, which can be time

4649

consuming.

4650

<note>

4651

If you specifically remove the locale

4652

<filename>en_US.UTF-8</filename>, you must set

appropriately.

</note>

</para>

<para>

You can set <filename>GLIBC_GENERATE_LOCALES</filename>

4660

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

4661

By default, all locales are generated.

4662

4663

GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"

</literallayout>

</para>

</glossdef>

</glossentry>

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

4670

<info>

4671

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

4680

to the <filename>groupadd</filename> command

4681

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>

4687

recipe:

4688

4689

GROUPADD_PARAM_${PN} = "-r netdev"

4690

</literallayout>

4691

For information on the standard Linux shell command

4692

<filename>groupadd</filename>, see

4693

<ulink url='http://linux.die.net/man/8/groupadd'></ulink>.

</para>

</glossdef>

</glossentry>

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

4699

<info>

4700

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

4709

to the <filename>groupmems</filename> command

4710

if you wish to modify the members of a group when the

4711

package is installed.

</para>

<para>

For information on the standard Linux shell command

4716

<filename>groupmems</filename>, see

4717

<ulink url='http://linux.die.net/man/8/groupmems'></ulink>.

</para>

</glossdef>

</glossentry>

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

4723

<info>

4724

GRUB_GFXSERIAL[doc] = "Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu."

</info>

4729

Configures the GNU GRand Unified Bootloader (GRUB) to have

4730

graphics and serial in the boot menu.

4731

Set this variable to "1" in your

4732

<filename>local.conf</filename> or distribution

4733

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>

4752

Additional options to add to the GNU GRand Unified

4753

Bootloader (GRUB) configuration.

4754

Use a semi-colon character (<filename>;</filename>) to

4755

separate multiple options.

</para>

<para>

The <filename>GRUB_OPTS</filename> variable is optional.

4760

See the

4761

4762

class for more information on how this variable is used.

</para>

</glossdef>

</glossentry>

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

4768

<info>

4769

GRUB_TIMEOUT[doc] = "Specifies the timeout before executing the default LABEL in the GNU GRand Unified Bootloader (GRUB)."

</info>

4774

Specifies the timeout before executing the default

4775

<filename>LABEL</filename> in the GNU GRand Unified

Bootloader (GRUB).

</para>

<para>

The <filename>GRUB_TIMEOUT</filename> variable is optional.

4781

See the

4782

4783

class for more information on how this variable is used.

</para>

</glossdef>

</glossentry>

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

4789

<info>

4790

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>

4795

When inheriting the

4796

4797

class, this variable specifies the packages that contain the

4798

GTK+ input method modules being installed when the modules

4799

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>

4809

<info>

4810

HOMEPAGE[doc] = "Website where more information about the software the recipe is building can be found."

</info>

4815

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>

4829

The name of the target architecture, which is normally

4830

the same as

4831

4832

The OpenEmbedded build system supports many

4833

architectures.

4834

Here is an example list of architectures supported.

4835

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>

4857

Specifies architecture-specific compiler flags that are

4858

passed to the C compiler.

</para>

<para>

Default initialization for <filename>HOST_CC_ARCH</filename>

4863

varies depending on what is being built:

when building for the target

4868

</para></listitem>

4869

4870

<filename>BUILD_CC_ARCH</filename>

4871

when building for the build host (i.e.

Patrick Williams

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

[diff] [blame]

4872

<filename>-native</filename>)

Patrick Williams

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

[diff] [blame]

4873

</para></listitem>

4874

4875

<filename>BUILDSDK_CC_ARCH</filename>

4876

when building for an SDK (i.e.

Patrick Williams

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

[diff] [blame]

4877

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

4891

Specifies the name of the target operating system, which

4892

is normally the same as the

4893

4894

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

4895

to "linux-musl" for <filename>musl</filename>.

Patrick Williams

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

[diff] [blame]

4896

For ARM/EABI targets, there are also "linux-gnueabi" and

Brad Bishop

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

[diff] [blame^]

4897

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

4903

<info>

4904

HOST_PREFIX[doc] = "The prefix for the cross compile toolchain. Normally same as the TARGET_PREFIX."

</info>

4909

Specifies the prefix for the cross-compile toolchain.

4910

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

4923

Specifies the system, including the architecture and the

4924

operating system, for which the build is occurring

4925

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:

4943

4944

<listitem><para>Given a native recipe on a 32-bit

4945

x86 machine running Linux, the value is

4946

"i686-linux".

4947

</para></listitem>

4948

<listitem><para>Given a recipe being built for a

4949

little-endian MIPS target running Linux,

4950

the value might be "mipsel-linux".

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

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

4958

<info>

4959

HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR."

</info>

4964

Specifies the name of the vendor.

4965

<filename>HOST_VENDOR</filename> is normally the same as

</para>

</glossdef>

</glossentry>

</glossdiv>

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

4976

<info>

4977

ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function."

</info>

4982

Disables or enables the <filename>icecc</filename>

4983

(Icecream) function.

4984

For more information on this function and best practices

4985

for using this variable, see the

4986

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

section.

</para>

<para>

Setting this variable to "1" in your

4992

<filename>local.conf</filename> disables the function:

4993

4994

ICECC_DISABLED ??= "1"

4995

</literallayout>

4996

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>

5005

<info>

5006

ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide."

</info>

5011

Points to the <filename>icecc-create-env</filename> script

5012

that you provide.

5013

This variable is used by the

5014

5015

class.

5016

You set this variable in your

5017

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

</para>

<para>

If you do not point to a script that you provide, the

5022

OpenEmbedded build system uses the default script provided

5023

by the <filename>icecc-create-env.bb</filename> recipe,

5024

which is a modified version and not the one that comes with

5025

<filename>icecc</filename>.

</para>

</glossdef>

</glossentry>

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

5031

<info>

5032

ICECC_PARALLEL_MAKE[doc] = "Extra options passed to the make command during the do_compile task that specify parallel compilation."

</info>

5037

Extra options passed to the <filename>make</filename>

5038

command during the

5039

5040

task that specify parallel compilation.

5041

This variable usually takes the form of

5042

"-j <replaceable>x</replaceable>", where

5043

<replaceable>x</replaceable> represents the maximum

5044

number of parallel threads <filename>make</filename> can

5045

run.

5046

<note>

5047

The options passed affect builds on all enabled

5048

machines on the network, which are machines running the

5049

<filename>iceccd</filename> daemon.

</note>

</para>

<para>

If your enabled machines support multiple cores,

5055

coming up with the maximum number of parallel threads

5056

that gives you the best performance could take some

5057

experimentation since machine speed, network lag,

5058

available memory, and existing machine loads can all

5059

affect build time.

5060

Consequently, unlike the

5061

5062

variable, there is no rule-of-thumb for setting

5063

<filename>ICECC_PARALLEL_MAKE</filename> to achieve

optimal performance.

</para>

<para>

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

5069

the build system does not use it (i.e. the system does

5070

not detect and assign the number of cores as is done with

5071

<filename>PARALLEL_MAKE</filename>).

</para>

</glossdef>

</glossentry>

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

5077

<info>

5078

ICECC_PATH[doc] = "The location of the icecc binary."

</info>

5083

The location of the <filename>icecc</filename> binary.

5084

You can set this variable in your

5085

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

5086

If your <filename>local.conf</filename> file does not define

5087

this variable, the

5088

5089

class attempts to define it by locating

5090

<filename>icecc</filename> using <filename>which</filename>.

</para>

</glossdef>

</glossentry>

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

5096

<info>

5097

ICECC_USER_CLASS_BL[doc] = "Identifies user classes that you do not want the Icecream distributed compile support to consider."

</info>

5102

Identifies user classes that you do not want the

5103

Icecream distributed compile support to consider.

5104

This variable is used by the

5105

5106

class.

5107

You set this variable in your

5108

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

</para>

<para>

When you list classes using this variable, you are

5113

"blacklisting" them from distributed compilation across

5114

remote hosts.

5115

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>

5122

<info>

5123

ICECC_USER_PACKAGE_BL[doc] = "Identifies user recipes that you do not want the Icecream distributed compile support to consider."

</info>

5128

Identifies user recipes that you do not want the

5129

Icecream distributed compile support to consider.

5130

This variable is used by the

5131

5132

class.

5133

You set this variable in your

5134

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

</para>

<para>

When you list packages using this variable, you are

5139

"blacklisting" them from distributed compilation across

5140

remote hosts.

5141

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>

5148

<info>

5149

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>

5154

Identifies user recipes that use an empty

5155

5156

variable that you want to force remote distributed

5157

compilation on using the Icecream distributed compile

5158

support.

5159

This variable is used by the

5160

5161

class.

5162

You set this variable in your

5163

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

</para>

</glossdef>

</glossentry>

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

5169

<info>

5170

IMAGE_BASENAME[doc] = "The base name of image output files."

</info>

5175

The base name of image output files.

5176

This variable defaults to the recipe name

5177

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

5183

<info>

5184

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>

5189

A space-separated list of files installed into the

5190

boot partition when preparing an image using the

5191

<filename>wic</filename> tool with the

5192

<filename>bootimg-partition</filename> source

5193

plugin.

5194

By default, the files are installed under

5195

the same name as the source files.

5196

To change the installed name, separate it from the

5197

original name with a semi-colon (;).

5198

Source files need to be located in

5199

5200

Here are two examples:

5201

5202

5203

IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"

5204

IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"

</literallayout>

</para>

<para>

Alternatively, source files can be picked up using

5210

a glob pattern.

5211

In this case, the destination file

5212

will have the same name as the base name of the source file

5213

path.

5214

To install files into a directory within the

5215

target location, pass its name after a semi-colon

5216

(;).

5217

Here are two examples:

5218

5219

IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"

5220

IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"

5221

</literallayout>

5222

The first example installs all files from

5223

<filename>${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles</filename>

5224

into the root of the target partition.

5225

The second example installs the same files into a

5226

<filename>boot</filename> directory within the

target partition.

</para>

</glossdef>

</glossentry>

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

5233

<info>

5234

IMAGE_CLASSES[doc] = "A list of classes that all images should inherit."

</info>

5239

A list of classes that all images should inherit.

5240

You typically use this variable to specify the list of

5241

classes that register the different types of images

5242

the OpenEmbedded build system creates.

</para>

<para>

The default value for <filename>IMAGE_CLASSES</filename> is

5247

<filename>image_types</filename>.

5248

You can set this variable in your

5249

<filename>local.conf</filename> or in a distribution

configuration file.

</para>

<para>

For more information, see

5255

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

5256

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

</para>

</glossdef>

</glossentry>

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

5262

<info>

5263

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>

5268

Specifies the command to create the image file for a

5269

specific image type, which corresponds to the value set

5270

set in

5271

5272

(e.g. <filename>ext3</filename>,

5273

<filename>btrfs</filename>, and so forth).

5274

When setting this variable, you should use

5275

an override for the associated type.

5276

Here is an example:

5277

5278

IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \

5279

--faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \

${EXTRA_IMAGECMD}"

</literallayout>

</para>

<para>

You typically do not need to set this variable unless

5286

you are adding support for a new image type.

5287

For more examples on how to set this variable, see the

5288

5289

class file, which is

5290

<filename>meta/classes/image_types.bbclass</filename>.

</para>

</glossdef>

</glossentry>

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

5296

<info>

5297

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>

5302

Specifies one or more files that contain custom device

5303

tables that are passed to the

5304

<filename>makedevs</filename> command as part of creating

5305

an image.

5306

These files list basic device nodes that should be

5307

created under <filename>/dev</filename> within the image.

5308

If <filename>IMAGE_DEVICE_TABLES</filename> is not set,

5309

<filename>files/device_table-minimal.txt</filename> is

5310

used, which is located by

5311

5312

For details on how you should write device table files,

5313

see <filename>meta/files/device_table-minimal.txt</filename>

as an example.

</para>

</glossdef>

</glossentry>

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

5320

<info>

5321

IMAGE_FEATURES[doc] = "The primary list of features to include in an image. Configure this variable in an image recipe."

</info>

5326

The primary list of features to include in an image.

5327

Typically, you configure this variable in an image recipe.

5328

Although you can use this variable from your

5329

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

5330

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

5331

best practices dictate that you do not.

5332

<note>

5333

To enable extra features from outside the image recipe,

5334

use the

5335

<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

5341

Project, see the

5342

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

section.

</para>

<para>

For an example that shows how to customize your image by

5348

using this variable, see the

5349

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

5350

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

5356

<info>

5357

IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created."

</info>

5362

Specifies the formats the OpenEmbedded build system uses

5363

during the build when creating the root filesystem.

5364

For example, setting <filename>IMAGE_FSTYPES</filename>

5365

as follows causes the build system to create root

5366

filesystems using two formats: <filename>.ext3</filename>

5367

and <filename>.tar.bz2</filename>:

5368

5369

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>

5381

inside an image recipe, be sure that you do so prior to the

5382

"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

5388

possible to update its contents using

5389

<filename>_append</filename> or

5390

<filename>_prepend</filename>. To add one or more

5391

additional options to this variable the

5392

<filename>+=</filename> operator must be used.

</note>

</glossdef>

</glossentry>

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

5398

<info>

5399

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>

5404

Specifies the packages to install into an image.

5405

The <filename>IMAGE_INSTALL</filename> variable is a

5406

mechanism for an image recipe and you should use it

5407

with care to avoid ordering issues.

<note>

When working with an

image, do not use the <filename>IMAGE_INSTALL</filename>

5412

variable to specify packages for installation.

5413

Instead, use the

5414

Brad Bishop

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

[diff] [blame^]

5415

variable, which allows the initial RAM filesystem

5416

(initramfs) recipe to use a fixed set of packages and

5417

not be affected by <filename>IMAGE_INSTALL</filename>.

5418

For information on creating an initramfs, see the

5419

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

5420

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>

5426

to specify the packages to install into an image through

5427

<filename>image.bbclass</filename>.

5428

Additionally, "helper" classes exist, such as

5429

<filename>core-image.bbclass</filename>, that can take

5430

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

5431

lists and turn these into auto-generated entries in

5432

<filename>IMAGE_INSTALL</filename> in addition to its

default contents.

</para>

<para>

Using <filename>IMAGE_INSTALL</filename> with the

5438

<filename>+=</filename> operator from the

5439

<filename>/conf/local.conf</filename> file or from within

5440

an image recipe is not recommended as it can cause ordering

5441

issues.

5442

Since <filename>core-image.bbclass</filename> sets

5443

<filename>IMAGE_INSTALL</filename> to a default value using

5444

the <filename>?=</filename> operator, using a

5445

<filename>+=</filename> operation against

5446

<filename>IMAGE_INSTALL</filename> will result in

5447

unexpected behavior when used in

5448

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

5449

Furthermore, the same operation from within an image

5450

recipe may or may not succeed depending on the specific

5451

situation.

5452

In both these cases, the behavior is contrary to how most

5453

users expect the <filename>+=</filename> operator to work.

</para>

<para>

When you use this variable, it is best to use it as follows:

5458

5459

IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"

5460

</literallayout>

5461

Be sure to include the space between the quotation character

5462

and the start of the package name or names.

</para>

</glossdef>

</glossentry>

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

5468

<info>

5469

IMAGE_LINGUAS[doc] = "Specifies the list of locales to install into the image during the root filesystem construction process."

</info>

5474

Specifies the list of locales to install into the image

5475

during the root filesystem construction process.

5476

The OpenEmbedded build system automatically splits locale

5477

files, which are used for localization, into separate

5478

packages.

5479

Setting the <filename>IMAGE_LINGUAS</filename> variable

5480

ensures that any locale packages that correspond to packages

5481

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

5491

Portuguese and German locale files that correspond to

5492

packages in the image are installed (i.e.

5493

<filename>*-locale-pt-br</filename>

5494

and <filename>*-locale-de-de</filename> as well as

5495

<filename>*-locale-pt</filename>

5496

and <filename>*-locale-de</filename>, since some software

5497

packages only provide locale files by language and not by

5498

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>

5510

<info>

5511

IMAGE_MANIFEST[doc] = "The manifest file for the image. This file lists all the installed packages that make up the image."

</info>

5516

The manifest file for the image.

5517

This file lists all the installed packages that make up

5518

the image.

5519

The file contains package information on a line-per-package

5520

basis as follows:

5521

5522

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

5530

5531

IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"

5532

</literallayout>

5533

The location is derived using the

and

variables.

You can find information on how the image

5539

is created in the

5540

"<link linkend='image-generation-dev-environment'>Image Generation</link>"

section.

</para>

</glossdef>

</glossentry>

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

5547

<info>

5548

IMAGE_NAME[doc] = "The name of the output image files minus the extension."

</info>

5553

The name of the output image files minus the extension.

5554

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>

5568

<info>

5569

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>

5574

Defines a multiplier that the build system applies to the initial image

5575

size for cases when the multiplier times the returned disk usage value

5576

for the image is greater than the sum of

5577

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

5578

and

5579

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

5580

The result of the multiplier applied to the initial image size creates

5581

free disk space in the image as overhead.

5582

By default, the build process uses a multiplier of 1.3 for this variable.

5583

This default value results in 30% free disk space added to the image when this

5584

method is used to determine the final generated image size.

5585

You should be aware that post install scripts and the package management

5586

system uses disk space inside this overhead area.

5587

Consequently, the multiplier does not produce an image with

5588

all the theoretical free disk space.

5589

See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>

5590

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

5595

and allows for basic post installs while still leaving a small amount of

5596

free disk space.

5597

If 30% free space is inadequate, you can increase the default value.

5598

For example, the following setting gives you 50% free space added to the image:

5599

5600

IMAGE_OVERHEAD_FACTOR = "1.5"

</literallayout>

</para>

<para>

Alternatively, you can ensure a specific amount of free disk space is added

5606

to the image by using the

5607

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

5614

<info>

5615

IMAGE_PKGTYPE[doc] = "Defines the package type (DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system."

</info>

5620

Defines the package type (DEB, RPM, IPK, or TAR) used

5621

by the OpenEmbedded build system.

5622

The variable is defined appropriately by the

or

class.

<note><title>Warning</title>

5630

The <filename>package_tar</filename> class is broken

5631

and is not supported.

5632

It is recommended that you do not use it.

</note>

</para>

<para>

The

Patrick Williams

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

[diff] [blame]

5638

Patrick Williams

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

[diff] [blame]

5639

and

5640

5641

classes use the <filename>IMAGE_PKGTYPE</filename> for

5642

packaging up images and SDKs.

</para>

<para>

You should not set the <filename>IMAGE_PKGTYPE</filename>

5647

manually.

5648

Rather, the variable is set indirectly through the

appropriate

class using the

variable.

The OpenEmbedded build system uses the first package type

5655

(e.g. DEB, RPM, or IPK) that appears with the variable

5656

<note>

5657

Files using the <filename>.tar</filename> format are

5658

never used as a substitute packaging format for DEB,

5659

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>

5666

<info>

5667

IMAGE_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the final image output files."

</info>

5672

Specifies a list of functions to call once the

5673

OpenEmbedded build system has created the final image

5674

output files.

5675

You can specify functions separated by semicolons:

5676

5677

IMAGE_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

5683

within the function, you can use

5684

<filename>${IMAGE_ROOTFS}</filename>, which points to

5685

the directory that becomes the root filesystem image.

Patrick Williams

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

[diff] [blame]

5686

See the

5687

5688

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>

5694

<info>

5695

IMAGE_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the final image output files."

</info>

5700

Specifies a list of functions to call before the

5701

OpenEmbedded build system has created the final image

5702

output files.

5703

You can specify functions separated by semicolons:

5704

5705

IMAGE_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

5711

within the function, you can use

5712

<filename>${IMAGE_ROOTFS}</filename>, which points to

5713

the directory that becomes the root filesystem image.

Patrick Williams

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

[diff] [blame]

5714

See the

5715

5716

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>

5722

<info>

5723

IMAGE_ROOTFS[doc] = "The location of the root filesystem while it is under construction (i.e. during do_rootfs)."

</info>

5728

The location of the root filesystem while it is under

5729

construction (i.e. during the

5730

5731

task).

5732

This variable is not configurable.

Do not change it.

</para>

</glossdef>

</glossentry>

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

5739

<info>

5740

IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes."

</info>

5745

Specifies the alignment for the output image file in

5746

Kbytes.

5747

If the size of the image is not a multiple of

5748

this value, then the size is rounded up to the nearest

5749

multiple of the value.

5750

The default value is "1".

5751

See

5752

5753

for additional information.

</para>

</glossdef>

</glossentry>

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

5759

<info>

5760

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>

5765

Defines additional free disk space created in the image in Kbytes.

5766

By default, this variable is set to "0".

5767

This free disk space is added to the image after the build system determines

5768

the image size as described in

5769

<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

5774

specific amount of free disk space is available on a device after an image

5775

is installed and running.

5776

For example, to be sure 5 Gbytes of free disk space is available, set the

5777

variable as follows:

5778

5779

IMAGE_ROOTFS_EXTRA_SPACE = "5242880"

</literallayout>

</para>

<para>

For example, the Yocto Project Build Appliance specifically requests 40 Gbytes

5785

of extra space with the line:

5786

5787

IMAGE_ROOTFS_EXTRA_SPACE = "41943040"

</literallayout>

</para>

</glossdef>

</glossentry>

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

5794

<info>

5795

IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image."

</info>

5800

Defines the size in Kbytes for the generated image.

5801

The OpenEmbedded build system determines the final size for the generated

5802

image using an algorithm that takes into account the initial disk space used

5803

for the generated image, a requested size for the image, and requested

5804

additional free disk space to be added to the image.

5805

Programatically, the build system determines the final size of the

5806

generated image as follows:

5807

5808

if (image-du * overhead) < rootfs-size:

5809

internal-rootfs-size = rootfs-size + xspace

5810

else:

5811

internal-rootfs-size = (image-du * overhead) + xspace

where:

image-du = Returned value of the du command on

5816

the image.

5817

5818

overhead = IMAGE_OVERHEAD_FACTOR

5819

5820

rootfs-size = IMAGE_ROOTFS_SIZE

5821

5822

internal-rootfs-size = Initial root filesystem

5823

size before any modifications.

5824

5825

xspace = IMAGE_ROOTFS_EXTRA_SPACE

</literallayout>

</para>

<para>

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

5831

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

5832

variables for related information.

5833

<!-- In the above example, <filename>overhead</filename> is defined by the

5834

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

5835

variable, <filename>xspace</filename> is defined by the

5836

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

5837

variable, and <filename>du</filename> is the results of the disk usage command

5838

on the initially generated image. -->

</para>

</glossdef>

</glossentry>

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

5844

<info>

5845

IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another."

</info>

5850

Specifies a dependency from one image type on another.

5851

Here is an example from the

class:

IMAGE_TYPEDEP_live = "ext3"

</literallayout>

</para>

<para>

In the previous example, the variable ensures that when

5861

"live" is listed with the

5862

5863

variable, the OpenEmbedded build system produces an

5864

<filename>ext3</filename> image first since one of the

5865

components of the live

5866

image is an <filename>ext3</filename>

5867

formatted partition containing the root

filesystem.

</para>

</glossdef>

</glossentry>

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

5874

<info>

5875

IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default."

</info>

5880

Specifies the complete list of supported image types

5881

by default:

5882

Patrick Williams

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

[diff] [blame]

5883

btrfs

Patrick Williams

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

[diff] [blame]

5884

cpio

5885

cpio.gz

Patrick Williams

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

[diff] [blame]

5886

cpio.lz4

Patrick Williams

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

[diff] [blame]

5887

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]

5916

vdi

5917

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

5927

<filename>meta/classes/image_types*.bbclass</filename>

5928

in the

5929

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

5941

Helps define the recipe revision for recipes that share

5942

a common <filename>include</filename> file.

5943

You can think of this variable as part of the recipe revision

5944

as set from within an include file.

</para>

<para>

Suppose, for example, you have a set of recipes that

5949

are used across several projects.

5950

And, within each of those recipes the revision

5951

(its <link linkend='var-PR'><filename>PR</filename></link>

5952

value) is set accordingly.

5953

In this case, when the revision of those recipes changes,

5954

the burden is on you to find all those recipes and

5955

be sure that they get changed to reflect the updated

5956

version of the recipe.

5957

In this scenario, it can get complicated when recipes

5958

that are used in many places and provide common functionality

5959

are upgraded to a new revision.

</para>

<para>

A more efficient way of dealing with this situation is

5964

to set the <filename>INC_PR</filename> variable inside

5965

the <filename>include</filename> files that the recipes

5966

share and then expand the <filename>INC_PR</filename>

5967

variable within the recipes to help

5968

define the recipe revision.

</para>

<para>

The following provides an example that shows how to use

5973

the <filename>INC_PR</filename> variable

5974

given a common <filename>include</filename> file that

5975

defines the variable.

5976

Once the variable is defined in the

5977

<filename>include</filename> file, you can use the

5978

variable to set the <filename>PR</filename> values in

5979

each recipe.

5980

You will notice that when you set a recipe's

5981

<filename>PR</filename> you can provide more granular

5982

revisioning by appending values to the

5983

<filename>INC_PR</filename> variable:

5984

5985

recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"

5986

recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"

5987

recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"

5988

recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"

5989

</literallayout>

5990

The first line of the example establishes the baseline

5991

revision to be used for all recipes that use the

5992

<filename>include</filename> file.

5993

The remaining lines in the example are from individual

5994

recipes and show how the <filename>PR</filename> value

is set.

</para>

</glossdef>

</glossentry>

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

6001

<info>

6002

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>

6007

Specifies a space-separated list of license names

6008

(as they would appear in

6009

6010

that should be excluded from the build.

6011

Recipes that provide no alternatives to listed incompatible

6012

licenses are not built.

6013

Packages that are individually licensed with the specified

6014

incompatible licenses will be deleted.

</para>

<note>

This functionality is only regularly tested using

6019

the following setting:

6020

6021

INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"

6022

</literallayout>

6023

Although you can use other settings, you might be required

6024

to remove dependencies on or provide alternatives to

6025

components that are required to produce a functional system

image.

</note>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

6031

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

6032

<info>

6033

INHERIT[doc] = "Causes the named class to be inherited at this point during parsing. The variable is only valid in configuration files."

</info>

6038

Causes the named class to be inherited at

6039

this point during parsing.

6040

The variable is only valid in configuration files.

</para>

</glossdef>

</glossentry>

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

6046

<info>

6047

INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable."

</info>

6052

Lists classes that will be inherited at the

6053

distribution level.

6054

It is unlikely that you want to edit this variable.

</para>

<para>

The default value of the variable is set as follows in the

6059

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

6060

file:

6061

6062

INHERIT_DISTRO ?= "debian devshell sstate license"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

6068

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

6069

<info>

6070

INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS."

</info>

6075

Prevents the default dependencies, namely the C compiler

6076

and standard C library (libc), from being added to

6077

6078

This variable is usually used within recipes that do not

6079

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>

6090

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6091

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>

6096

Prevents the OpenEmbedded build system from splitting

6097

out debug information during packaging.

6098

By default, the build system splits out debugging

6099

information during the

6100

6101

task.

6102

For more information on how debug information is split out,

see the

variable.

</para>

<para>

To prevent the build system from splitting out

6110

debug information during packaging, set the

6111

<filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable

6112

as follows:

6113

6114

INHIBIT_PACKAGE_DEBUG_SPLIT = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>

6121

<info>

6122

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]

6127

If set to "1", causes the build to not strip binaries in

6128

resulting packages and prevents the

6129

<filename>-dbg</filename> package from containing the

source files.

</para>

<para>

By default, the OpenEmbedded build system strips

6135

binaries and puts the debugging symbols into

6136

<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-dbg</filename>.

6137

Consequently, you should not set

6138

<filename>INHIBIT_PACKAGE_STRIP</filename> when you plan

6139

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]

6144

<glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>

6145

<info>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

6146

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>

6151

Defines the format for the output image of an initial

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

6152

RAM filesystem (initramfs), which is used during boot.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6153

Supported formats are the same as those supported by the

6154

6155

variable.

6156

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6157

6158

<para>

6159

The default value of this variable, which is set in the

6160

<filename>meta/conf/bitbake.conf</filename> configuration

6161

file in the

6162

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,

6163

is "cpio.gz".

6164

The Linux kernel's initramfs mechanism, as opposed to the

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

6165

initial RAM filesystem

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6166

<ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>

6167

mechanism, expects an optionally compressed cpio

6168

archive.

6169

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

<glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>

6174

<info>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

6175

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]

6180

Specifies the

6181

6182

name of an image recipe that is used to build an initial

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

6183

RAM filesystem (initramfs) image.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6184

An initramfs provides a temporary root filesystem used for

6185

early system initialization (e.g. loading of modules

6186

needed to locate and mount the "real" root filesystem).

6187

The specified recipe is added as a dependency of the root

6188

filesystem recipe (e.g.

6189

<filename>core-image-sato</filename>).

6190

See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename>

6191

recipe in the

6192

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

6193

for an example initramfs recipe.

6194

To select this recipe to provide the initramfs,

6195

set <filename>INITRAMFS_IMAGE</filename> to

6196

"core-image-minimal-initramfs".

6197

<note>

6198

The initramfs image recipe should set

to

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6203

</para>

6204

6205

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6206

You can also find more information by referencing the

6207

<filename>meta/poky/conf/local.conf.sample.extended</filename>

6208

configuration file in the

6209

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,

6210

the

6211

6212

class, and the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6213

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6214

class to see how to use the

6215

<filename>INITRAMFS_IMAGE</filename> variable.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6216

</para>

6217

6218

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6219

If <filename>INITRAMFS_IMAGE</filename> is empty, which is

6220

the default, then no initramfs is built.

6221

</para>

6222

6223

<para>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

6224

For more information, you can also see the

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6225

6226

variable, which allows the generated image to be bundled

6227

inside the kernel image.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

6228

Additionally, for information on creating an initramfs, see

6229

the

6230

"<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"

6231

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>

6237

<info>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

6238

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>

6243

Controls whether or not the image recipe specified by

6244

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6245

is run through an extra pass

6246

(<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)

6247

during kernel compilation in order to build a single binary

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

6248

that contains both the kernel image and the initial RAM

6249

filesystem (initramfs) image.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6250

This makes use of the

kernel feature.

<note>

Using an extra compilation pass to bundle the initramfs

6255

avoids a circular dependency between the kernel recipe and

6256

the initramfs recipe should the initramfs include kernel

6257

modules.

6258

Should that be the case, the initramfs recipe depends on

6259

the kernel for the kernel modules, and the kernel depends

6260

on the initramfs recipe since the initramfs is bundled

6261

inside the kernel image.

6262

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

The combined binary is deposited into the

6267

<filename>tmp/deploy</filename> directory, which is part

6268

of the

6269

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

6270

</para>

6271

6272

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6273

Setting the variable to "1" in a configuration file causes the

6274

OpenEmbedded build system to generate a kernel image with the

6275

initramfs specified in

6276

6277

bundled within:

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6278

6279

INITRAMFS_IMAGE_BUNDLE = "1"

</literallayout>

By default, the

class sets this variable to a null string as follows:

6284

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

6285

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

6290

a configuration file.

6291

You cannot set the variable in a recipe file.

6292

</note>

6293

See the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

6294

<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]

6295

file for additional information.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

6296

Also, for information on creating an initramfs, see the

6297

"<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"

6298

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>

6304

<info>

6305

INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)."

</info>

6310

Indicates list of filesystem images to concatenate and use

6311

as an initial RAM disk (<filename>initrd</filename>).

</para>

<para>

The <filename>INITRD</filename> variable is an optional

6316

variable used with the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

6317

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITRD_IMAGE'><glossterm>INITRD_IMAGE</glossterm>

6324

<info>

6325

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>

6330

When building a "live" bootable image (i.e. when

6331

6332

contains "live"), <filename>INITRD_IMAGE</filename>

6333

specifies the image recipe that should be built

6334

to provide the initial RAM disk image.

6335

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>

6347

<info>

6348

INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d."

</info>

6353

The filename of the initialization script as installed to

6354

<filename>${sysconfdir}/init.d</filename>.

</para>

<para>

This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.

6359

The variable is mandatory.

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>

6365

<info>

6366

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>

6371

A list of the packages that contain initscripts.

6372

If multiple packages are specified, you need to append the package name

6373

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>.

6378

The variable is optional and defaults to the

</para>

</glossdef>

</glossentry>

<glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>

6385

<info>

6386

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>

6391

Specifies the options to pass to <filename>update-rc.d</filename>.

6392

Here is an example:

6393

6394

INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."

</literallayout>

</para>

<para>

In this example, the script has a runlevel of 99,

6400

starts the script in initlevels 2 and 5, and

6401

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

6414

to the <filename>update-rc.d</filename> command.

6415

For more information on valid parameters, please see the

6416

<filename>update-rc.d</filename> manual page at

6417

<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>

6423

<info>

6424

INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe."

</info>

6429

Specifies the QA checks to skip for a specific package

6430

within a recipe.

6431

For example, to skip the check for symbolic link

6432

<filename>.so</filename> files in the main package of a

6433

recipe, add the following to the recipe.

6434

The package name override must be used, which in this

6435

example is <filename>${PN}</filename>:

6436

6437

INSANE_SKIP_${PN} += "dev-so"

</literallayout>

</para>

<para>

See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"

6443

section for a list of the valid QA checks you can

6444

specify using this variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

6449

<glossentry id='var-INSTALL_TIMEZONE_FILE'><glossterm>INSTALL_TIMEZONE_FILE</glossterm>

6450

<info>

6451

INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file."

</info>

6456

By default, the <filename>tzdata</filename> recipe packages

6457

an <filename>/etc/timezone</filename> file.

6458

Set the <filename>INSTALL_TIMEZONE_FILE</filename>

6459

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]

6465

6466

<info>

6467

IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image."

</info>

6472

When the IPK backend is in use and package management

6473

is enabled on the target, you can use this variable to

6474

set up <filename>opkg</filename> in the target image

6475

to point to package feeds on a nominated server.

6476

Once the feed is established, you can perform

6477

installations or upgrades using the package manager

at runtime.

</para>

</glossdef>

</glossentry>

<!--

<glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>

6485

6486

<para>

6487

An environment variable that defines the directory where

6488

post installation hooks are installed for the

6489

post install environment.

6490

This variable is fixed as follows:

6491

6492

${WORKDIR}/intercept_scripts

</literallayout>

</para>

<para>

After installation of a target's root filesystem,

6498

post installation scripts, which are essentially bash scripts,

6499

are all executed just a single time.

6500

Limiting execution of these scripts minimizes installation

6501

time that would be lengthened due to certain packages

6502

triggering redundant operations.

6503

For example, consider the installation of font packages

6504

as a common example.

6505

Without limiting the execution of post installation scripts,

6506

all font directories would be rescanned to create the

6507

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>

6526

<info>

6527

KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions."

</info>

6532

Defines the kernel architecture used when assembling

6533

the configuration.

6534

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

6547

<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>

6553

<info>

6554

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>

6559

A regular expression used by the build process to explicitly

6560

identify the kernel branch that is validated, patched,

6561

and configured during a build.

6562

You must set this variable to ensure the exact kernel

6563

branch you want is being used by the build process.

</para>

<para>

Values for this variable are set in the kernel's recipe

6568

file and the kernel's append file.

6569

For example, if you are using the Yocto Project kernel that

6570

is based on the Linux 3.14 kernel, the kernel recipe file

6571

is the

6572

<filename>meta/recipes-kernel/linux/linux-yocto_3.14.bb</filename>

6573

file.

6574

Following is an example for a kernel recipe file:

6575

6576

KBRANCH ?= "standard/base"

</literallayout>

</para>

<para>

This variable is also used from the kernel's append file

6582

to identify the kernel branch specific to a particular

6583

machine or target hardware.

6584

The kernel's append file is located in the BSP layer for

6585

a given machine.

6586

For example, the kernel append file for the Emenlow BSP is in the

6587

<filename>meta-intel</filename> Git repository and is named

6588

<filename>meta-emenlow/recipes-kernel/linux/linux-yocto_3.14.bbappend</filename>.

6589

Here are the related statements from the append file:

6590

6591

COMPATIBLE_MACHINE_emenlow-noemgd = "emenlow-noemgd"

6592

KMACHINE_emenlow-noemgd = "emenlow"

6593

KBRANCH_emenlow-noemgd = "standard/base"

6594

KERNEL_FEATURES_append_emenlow-noemgd = " features/drm-gma500/drm-gma500.scc"

6595

</literallayout>

6596

The <filename>KBRANCH</filename> statement identifies

6597

the kernel branch to use when building for the Emenlow

BSP.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KBUILD_DEFCONFIG'><glossterm>KBUILD_DEFCONFIG</glossterm>

6604

<info>

6605

KBUILD_DEFCONFIG[doc] = "Specifies an "in-tree" kernel configuration file for use during a kernel build."

</info>

6610

When used with the

6611

6612

class, specifies an "in-tree" kernel configuration file

6613

for use during a kernel build.

</para>

<para>

Typically, when using a <filename>defconfig</filename> to

6618

configure a kernel during a build, you place the

6619

file in your layer in the same manner as you would

6620

patch files and configuration fragment files (i.e.

6621

"out-of-tree").

6622

However, if you want to use a <filename>defconfig</filename>

6623

file that is part of the kernel tree (i.e. "in-tree"),

6624

you can use the

6625

<filename>KBUILD_DEFCONFIG</filename> variable to point

6626

to the <filename>defconfig</filename> file.

</para>

<para>

To use the variable, set it in the append file for your

6631

kernel recipe using the following form:

6632

6633

KBUILD_DEFCONFIG_<link linkend='var-KMACHINE'>KMACHINE</link> ?= <replaceable>defconfig_file</replaceable>

6634

</literallayout>

6635

Here is an example from a "raspberrypi2"

6636

<filename>KMACHINE</filename> build that uses a

6637

<filename>defconfig</filename> file named

6638

"bcm2709_defconfig":

6639

6640

KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"

6641

</literallayout>

6642

As an alternative, you can use the following within your

6643

append file:

6644

6645

KBUILD_DEFCONFIG_pn-linux-yocto ?= <replaceable>defconfig_file</replaceable>

6646

</literallayout>

6647

For more information on how to use the

6648

<filename>KBUILD_DEFCONFIG</filename> variable, see the

6649

"<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]

6655

<glossentry id='var-KERNEL_ALT_IMAGETYPE'><glossterm>KERNEL_ALT_IMAGETYPE</glossterm>

6656

<info>

6657

KERNEL_ALT_IMAGETYPE[doc] = "Specifies an alternate kernel image type for creation."

</info>

6662

Specifies an alternate kernel image type for creation in

6663

addition to the kernel image type specified using the

variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

6670

<glossentry id='var-KERNEL_CLASSES'><glossterm>KERNEL_CLASSES</glossterm>

6671

<info>

6672

KERNEL_CLASSES[doc] = "A list of classes defining kernel image types that kernel class should inherit."

</info>

6677

A list of classes defining kernel image types that the

6678

6679

class should inherit.

6680

You typically append this variable to enable extended image

6681

types.

6682

An example is the "kernel-fitimage", which enables

6683

fitImage support and resides in

6684

<filename>meta/classes/kernel-fitimage.bbclass</filename>.

6685

You can register custom kernel image types with the

6686

<filename>kernel</filename> class using this variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

6691

<glossentry id='var-KERNEL_DEVICETREE'><glossterm>KERNEL_DEVICETREE</glossterm>

6692

<info>

6693

KERNEL_DEVICETREE[doc] = "Specifies the name of the generated Linux kernel device tree (i.e. the <filename>.dtb</filename>) file."

</info>

6698

Specifies the name of the generated Linux kernel device tree

6699

(i.e. the <filename>.dtb</filename>) file.

6700

<note>

6701

Legacy support exists for specifying the full path

6702

to the device tree.

6703

However, providing just the <filename>.dtb</filename>

6704

file is preferred.

6705

</note>

6706

In order to use this variable, you must have the include

6707

files in your kernel recipe:

6708

6709

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]

6719

<glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>

6720

<info>

6721

KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel."

</info>

6726

Specifies additional <filename>make</filename>

6727

command-line arguments the OpenEmbedded build system

6728

passes on when compiling the kernel.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>

6734

<info>

6735

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>

6740

Includes additional metadata from the Yocto Project kernel Git repository.

6741

In the OpenEmbedded build system, the default Board Support Packages (BSPs)

6742

<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>

6743

is provided through

6744

the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>

6745

and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables.

6746

You can use the <filename>KERNEL_FEATURES</filename> variable to further

6747

add metadata for all BSPs.

</para>

<para>

The metadata you add through this variable includes config fragments and

6752

features descriptions,

6753

which usually includes patches as well as config fragments.

6754

You typically override the <filename>KERNEL_FEATURES</filename> variable

6755

for a specific machine.

6756

In this way, you can provide validated, but optional, sets of kernel

6757

configurations and features.

</para>

<para>

For example, the following adds <filename>netfilter</filename> to all

6762

the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>

6763

machine:

6764

6765

# Add netfilter to all linux-yocto kernels

6766

KERNEL_FEATURES="features/netfilter/netfilter.scc"

6767

6768

# Add sound support to the qemux86 machine

6769

KERNEL_FEATURES_append_qemux86=" cfg/sound.scc"

6770

</literallayout></para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_IMAGE_BASE_NAME'><glossterm>KERNEL_IMAGE_BASE_NAME</glossterm>

6775

<info>

6776

KERNEL_IMAGE_BASE_NAME[doc] = "The base name of the kernel image."

</info>

6781

The base name of the kernel image.

6782

This variable is set in the

as follows:

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

6786

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>

6804

<info>

6805

KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."

</info>

6810

Specifies the maximum size of the kernel image file in

6811

kilobytes.

6812

If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,

6813

the size of the kernel image file is checked against

6814

the set value during the

6815

6816

task.

6817

The task fails if the kernel image file is larger than

the setting.

</para>

<para>

<filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for

6823

target devices that have a limited amount of space in

6824

which the kernel image must be stored.

</para>

<para>

By default, this variable is not set, which means the

6829

size of the kernel image is not checked.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>

6835

<info>

6836

KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."

</info>

6841

The type of kernel to build for a device, usually set by the

6842

machine configuration files and defaults to "zImage".

6843

This variable is used

6844

when building the kernel and is passed to <filename>make</filename> as the target to

6845

build.

6846

</para>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

6847

6848

<para>

6849

If you want to build an alternate kernel image type, use the

6850

6851

variable.

6852

</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>

6857

<info>

6858

KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot"

</info>

6863

Lists kernel modules that need to be auto-loaded during

6864

boot.

6865

<note>

6866

This variable replaces the deprecated

variable.

</note>

</para>

<para>

You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename>

6874

variable anywhere that it can be

6875

recognized by the kernel recipe or by an out-of-tree kernel

6876

module recipe (e.g. a machine configuration file, a

6877

distribution configuration file, an append file for the

6878

recipe, or the recipe itself).

</para>

<para>

Specify it as follows:

6883

6884

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

6890

the OpenEmbedded build system to populate the

6891

<filename>/etc/modules-load.d/modname.conf</filename>

6892

file with the list of modules to be auto-loaded on boot.

6893

The modules appear one-per-line in the file.

6894

Here is an example of the most common use case:

6895

6896

KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>"

</literallayout>

</para>

<para>

For information on how to populate the

6902

<filename>modname.conf</filename> file with

6903

<filename>modprobe.d</filename> syntax lines, see the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm>

6911

<info>

6912

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>

6917

Provides a list of modules for which the OpenEmbedded

6918

build system expects to find

6919

<filename>module_conf_</filename><replaceable>modname</replaceable>

6920

values that specify configuration for each of the modules.

6921

For information on how to provide those module

6922

configurations, see the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>

6930

<info>

6931

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>

6936

The location of the kernel sources.

6937

This variable is set to the value of the

within the

class.

For information on how this variable is used, see the

6943

"<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

6949

used to build modules, the OpenEmbedded build system also

6950

recognizes and uses the

6951

6952

variable, which is identical to the

6953

<filename>KERNEL_PATH</filename> variable.

6954

Both variables are common variables used by external

6955

Makefiles to point to the kernel source directory.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>

6961

<info>

6962

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>

6967

The location of the kernel sources.

6968

This variable is set to the value of the

within the

class.

For information on how this variable is used, see the

6974

"<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

6980

used to build modules, the OpenEmbedded build system also

6981

recognizes and uses the

6982

6983

variable, which is identical to the

6984

<filename>KERNEL_SRC</filename> variable.

6985

Both variables are common variables used by external

6986

Makefiles to point to the kernel source directory.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

6991

<glossentry id='var-KERNEL_VERSION'><glossterm>KERNEL_VERSION</glossterm>

6992

<info>

6993

KERNEL_VERSION[doc] = "Specifies the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources."

</info>

6998

Specifies the version of the kernel as extracted from

6999

<filename>version.h</filename> or

7000

<filename>utsrelease.h</filename> within the kernel sources.

7001

Effects of setting this variable do not take affect until

7002

the kernel has been configured.

7003

Consequently, attempting to refer to this variable in

7004

contexts prior to configuration will not work.

</para>

</glossdef>

</glossentry>

<glossentry id='var-KERNELDEPMODDEPEND'><glossterm>KERNELDEPMODDEPEND</glossterm>

7010

<info>

7011

KERNELDEPMODDEPEND[doc] = "Specifies whether or not to use the data referenced through the PKGDATA_DIR directory."

</info>

7016

Specifies whether the data referenced through

7017

7018

is needed or not.

7019

The <filename>KERNELDEPMODDEPEND</filename> does not

7020

control whether or not that data exists,

7021

but simply whether or not it is used.

7022

If you do not need to use the data, set the

7023

<filename>KERNELDEPMODDEPEND</filename> variable in your

7024

<filename>initramfs</filename> recipe.

7025

Setting the variable there when the data is not needed

7026

avoids a potential dependency loop.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

7031

<glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>

7032

<info>

7033

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>

7038

Provides a short description of a configuration fragment.

7039

You use this variable in the <filename>.scc</filename>

7040

file that describes a configuration fragment file.

7041

Here is the variable used in a file named

7042

<filename>smp.scc</filename> to describe SMP being

7043

enabled:

7044

7045

define KFEATURE_DESCRIPTION "Enable SMP"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>

7052

<info>

7053

KMACHINE[doc] = "The machine as known by the kernel."

</info>

7058

The machine as known by the kernel.

7059

Sometimes the machine name used by the kernel does not

7060

match the machine name used by the OpenEmbedded build

7061

system.

7062

For example, the machine name that the OpenEmbedded build

7063

system understands as

7064

<filename>core2-32-intel-common</filename> goes by a

7065

different name in the Linux Yocto kernel.

7066

The kernel understands that machine as

7067

<filename>intel-core2-32</filename>.

7068

For cases like these, the <filename>KMACHINE</filename>

7069

variable maps the kernel machine name to the OpenEmbedded

7070

build system machine name.

</para>

<para>

These mappings between different names occur in the

7075

Yocto Linux Kernel's <filename>meta</filename> branch.

7076

As an example take a look in the

7077

<filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename>

7078

file:

7079

7080

LINUX_VERSION_core2-32-intel-common = "3.19.0"

7081

COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"

7082

SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"

7083

SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"

7084

KMACHINE_core2-32-intel-common = "intel-core2-32"

7085

KBRANCH_core2-32-intel-common = "standard/base"

7086

KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"

7087

</literallayout>

7088

The <filename>KMACHINE</filename> statement says that

7089

the kernel understands the machine name as

7090

"intel-core2-32".

7091

However, the OpenEmbedded build system understands the

7092

machine as "core2-32-intel-common".

</para>

</glossdef>

</glossentry>

<glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>

7099

<info>

7100

KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration."

</info>

7105

Defines the kernel type to be used in assembling the

7106

configuration.

7107

The linux-yocto recipes define "standard", "tiny",

7108

and "preempt-rt" kernel types.

7109

See the

7110

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"

7111

section in the Yocto Project Linux Kernel Development

7112

Manual for more information on kernel types.

</para>

<para>

You define the <filename>KTYPE</filename> variable in the

7117

<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.

7118

The value you use must match the value used for the

7119

7120

value used by the kernel recipe.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-LABELS'><glossterm>LABELS</glossterm>

7129

<info>

7130

LABELS[doc] = "Provides a list of targets for automatic configuration."

</info>

7135

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>

7147

<info>

7148

LAYERDEPENDS[doc] = "Lists the layers, separated by spaces, upon which this recipe depends. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer."

</info>

7153

Lists the layers that this recipe depends upon, separated by spaces.

7154

Optionally, you can specify a specific layer version for a dependency

7155

by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"

7156

to be compared against

7157

7158

in this case).

7159

An error will be produced if any dependency is missing or

7160

the version numbers do not match exactly (if specified).

7161

This variable is used in the <filename>conf/layer.conf</filename> file

7162

and must be suffixed with the name of the specific layer (e.g.

7163

<filename>LAYERDEPENDS_mylayer</filename>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>

7169

<info>

7170

LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer."

</info>

7175

When used inside the <filename>layer.conf</filename> configuration

7176

file, this variable provides the path of the current layer.

7177

This variable is not available outside of <filename>layer.conf</filename>

7178

and references are expanded immediately when parsing of the file completes.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>

7184

<info>

7185

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>

7190

Optionally specifies the version of a layer as a single number.

7191

You can use this within

7192

7193

for another layer in order to depend on a specific version

7194

of the layer.

7195

This variable is used in the <filename>conf/layer.conf</filename> file

7196

and must be suffixed with the name of the specific layer (e.g.

7197

<filename>LAYERVERSION_mylayer</filename>).

</para>

</glossdef>

</glossentry>

<info>

LD[doc] = "Minimal command and arguments to run the linker."

</info>

7209

The minimal command and arguments used to run the

linker.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm>

7216

<info>

7217

LDFLAGS[doc] = "Specifies the flags to pass to the linker."

</info>

7222

Specifies the flags to pass to the linker.

7223

This variable is exported to an environment

7224

variable and thus made visible to the software being

7225

built during the compilation step.

</para>

<para>

Default initialization for <filename>LDFLAGS</filename>

7230

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

7239

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

7244

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>

7252

<info>

7253

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>

7258

Specifies the lead (or primary) compiled library file

7259

(<filename>.so</filename>) that the

7260

7261

class applies its naming policy to given a recipe that

7262

packages multiple libraries.

</para>

<para>

This variable works in conjunction with the

7267

<filename>debian</filename> class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>

7273

<info>

7274

LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code."

</info>

7279

Checksums of the license text in the recipe source code.

</para>

<para>

This variable tracks changes in license text of the source

7284

code files.

7285

If the license text is changed, it will trigger a build

7286

failure, which gives the developer an opportunity to review any

license change.

</para>

<para>

This variable must be defined for all recipes (unless

7292

7293

is set to "CLOSED").</para>

7294

<para>For more information, see the

7295

"<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>

7296

Tracking License Changes</link>" section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>

7302

<info>

7303

LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &, '|', and parentheses can be used."

</info>

7308

The list of source licenses for the recipe.

7309

Follow these rules:

7310

7311

<listitem><para>Do not use spaces within individual

7312

license names.</para></listitem>

7313

<listitem><para>Separate license names using

7314

| (pipe) when there is a choice between licenses.

7315

</para></listitem>

7316

<listitem><para>Separate license names using

7317

& (ampersand) when multiple licenses exist

7318

that cover different parts of the source.

7319

</para></listitem>

7320

<listitem><para>You can use spaces between license

7321

names.</para></listitem>

7322

<listitem><para>For standard licenses, use the names

7323

of the files in

7324

<filename>meta/files/common-licenses/</filename>

7325

or the

7326

7327

flag names defined in

7328

<filename>meta/conf/licenses.conf</filename>.

</para></listitem>

</itemizedlist>

</para>

<para>

Here are some examples:

7335

7336

LICENSE = "LGPLv2.1 | GPLv3"

7337

LICENSE = "MPL-1 & LGPLv2.1"

7338

LICENSE = "GPLv2+"

7339

</literallayout>

7340

The first example is from the recipes for Qt, which the user

7341

may choose to distribute under either the LGPL version

7342

2.1 or GPL version 3.

7343

The second example is from Cairo where two licenses cover

7344

different parts of the source code.

7345

The final example is from <filename>sysstat</filename>,

7346

which presents a single license.

</para>

<para>

You can also specify licenses on a per-package basis to

7351

handle situations where components of the output have

7352

different licenses.

7353

For example, a piece of software whose code is

7354

licensed under GPLv2 but has accompanying documentation

7355

licensed under the GNU Free Documentation License 1.2 could

7356

be specified as follows:

7357

7358

LICENSE = "GFDL-1.2 & GPLv2"

7359

LICENSE_${PN} = "GPLv2"

7360

LICENSE_${PN}-doc = "GFDL-1.2"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

7366

<glossentry id='var-LICENSE_CREATE_PACKAGE'><glossterm>LICENSE_CREATE_PACKAGE</glossterm>

7367

<info>

7368

LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."

</info>

7373

Setting <filename>LICENSE_CREATE_PACKAGE</filename>

7374

to "1" causes the OpenEmbedded build system to create

7375

an extra package (i.e.

7376

<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)

7377

for each recipe and to add those packages to the

</para>

<para>

The <filename>${PN}-lic</filename> package installs a

7383

directory in <filename>/usr/share/licenses</filename>

7384

named <filename>${PN}</filename>, which is the recipe's

7385

base name, and installs files in that directory that

7386

contain license and copyright information (i.e. copies of

7387

the appropriate license files from

7388

<filename>meta/common-licenses</filename> that match the

7389

licenses specified in the

7390

7391

variable of the recipe metadata and copies of files marked

7392

in

7393

7394

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>"

7404

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

7409

<glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm>

7410

<info>

7411

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>

7416

Specifies additional flags for a recipe you must

7417

whitelist through

7418

7419

in order to allow the recipe to be built.

7420

When providing multiple flags, separate them with

spaces.

</para>

<para>

This value is independent of

7426

7427

and is typically used to mark recipes that might

7428

require additional licenses in order to be used in a

7429

commercial product.

7430

For more information, see the

7431

"<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>

7438

<info>

7439

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>

7444

Lists license flags that when specified in

7445

7446

within a recipe should not prevent that recipe from being

7447

built.

7448

This practice is otherwise known as "whitelisting"

7449

license flags.

7450

For more information, see the

section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>

7458

<info>

7459

LICENSE_PATH[doc] = "Path to additional licenses used during the build."

</info>

7464

Path to additional licenses used during the build.

7465

By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>

7466

to define the directory that holds common license text used during the build.

7467

The <filename>LICENSE_PATH</filename> variable allows you to extend that

7468

location to other areas that have additional licenses:

7469

7470

LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>

7477

<info>

7478

LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration."

</info>

7483

Defines the kernel type to be used in assembling the

7484

configuration.

7485

The linux-yocto recipes define "standard", "tiny", and

7486

"preempt-rt" kernel types.

7487

See the

7488

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"

7489

section in the Yocto Project Linux Kernel Development

7490

Manual for more information on kernel types.

</para>

<para>

If you do not specify a

7495

<filename>LINUX_KERNEL_TYPE</filename>, it defaults to

"standard".

Together with

the <filename>LINUX_KERNEL_TYPE</filename> variable

7500

defines the search

7501

arguments used by the kernel tools to find the appropriate

7502

description within the kernel

7503

<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>

7504

with which to build out the sources and configuration.

</para>

</glossdef>

</glossentry>

<glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>

7510

<info>

7511

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>

7516

The Linux version from <filename>kernel.org</filename>

7517

on which the Linux kernel image being built using the

7518

OpenEmbedded build system is based.

7519

You define this variable in the kernel recipe.

7520

For example, the <filename>linux-yocto-3.4.bb</filename>

7521

kernel recipe found in

7522

<filename>meta/recipes-kernel/linux</filename>

7523

defines the variables as follows:

7524

7525

LINUX_VERSION ?= "3.4.24"

</literallayout>

</para>

<para>

The <filename>LINUX_VERSION</filename> variable is used to

7531

define <link linkend='var-PV'><filename>PV</filename></link>

7532

for the recipe:

7533

7534

PV = "${LINUX_VERSION}+git${SRCPV}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>

7541

<info>

7542

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>

7547

A string extension compiled into the version

7548

string of the Linux kernel built with the OpenEmbedded

7549

build system.

7550

You define this variable in the kernel recipe.

7551

For example, the linux-yocto kernel recipes all define

7552

the variable as follows:

7553

7554

LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"

</literallayout>

</para>

<para>

Defining this variable essentially sets the

7560

Linux kernel configuration item

7561

<filename>CONFIG_LOCALVERSION</filename>, which is visible

7562

through the <filename>uname</filename> command.

7563

Here is an example that shows the extension assuming it

7564

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>

7580

Specifies the directory to which the OpenEmbedded build

7581

system writes overall log files.

7582

The default directory is <filename>${TMPDIR}/log</filename>.

</para>

<para>

For the directory containing logs specific to each task,

7587

see the <link linkend='var-T'><filename>T</filename></link>

variable.

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>

7598

<info>

7599

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>

7604

Specifies the target device for which the image is built.

7605

You define <filename>MACHINE</filename> in the

7606

<filename>local.conf</filename> file found in the

7607

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

7608

By default, <filename>MACHINE</filename> is set to

7609

"qemux86", which is an x86-based architecture machine to

7610

be emulated using QEMU:

MACHINE ?= "qemux86"

</literallayout>

</para>

<para>

The variable corresponds to a machine configuration file of the

7618

same name, through which machine-specific configurations are set.

7619

Thus, when <filename>MACHINE</filename> is set to "qemux86" there

7620

exists the corresponding <filename>qemux86.conf</filename> machine

7621

configuration file, which can be found in the

7622

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

7623

in <filename>meta/conf/machine</filename>.

</para>

<para>

The list of machines supported by the Yocto Project as

7628

shipped include the following:

7629

7630

MACHINE ?= "qemuarm"

7631

MACHINE ?= "qemuarm64"

7632

MACHINE ?= "qemumips"

7633

MACHINE ?= "qemumips64"

7634

MACHINE ?= "qemuppc"

7635

MACHINE ?= "qemux86"

7636

MACHINE ?= "qemux86-64"

7637

MACHINE ?= "genericx86"

7638

MACHINE ?= "genericx86-64"

7639

MACHINE ?= "beaglebone"

7640

MACHINE ?= "mpc8315e-rdb"

7641

MACHINE ?= "edgerouter"

7642

</literallayout>

7643

The last five are Yocto Project reference hardware boards, which

7644

are provided in the <filename>meta-yocto-bsp</filename> layer.

7645

<note>Adding additional Board Support Package (BSP) layers

7646

to your configuration adds new possible settings for

7647

<filename>MACHINE</filename>.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm>

7654

<info>

7655

MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH."

</info>

7660

Specifies the name of the machine-specific architecture.

7661

This variable is set automatically from

or

You should not hand-edit the

7666

<filename>MACHINE_ARCH</filename> variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>

7672

<info>

7673

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>

7678

A list of required machine-specific packages to install as part of

7679

the image being built.

7680

The build process depends on these packages being present.

7681

Furthermore, because this is a "machine essential" variable, the list of

7682

packages are essential for the machine to boot.

7683

The impact of this variable affects images based on

7684

<filename>packagegroup-core-boot</filename>,

7685

including the <filename>core-image-minimal</filename> image.

</para>

<para>

This variable is similar to the

7690

<filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>

7691

variable with the exception that the image being built has a build

7692

dependency on the variable's list of packages.

7693

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

7698

<filename>example-init</filename> to be run during boot to initialize the hardware.

7699

In this case, you would use the following in the machine's

7700

<filename>.conf</filename> configuration file:

7701

7702

MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>

7709

<info>

7710

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>

7715

A list of recommended machine-specific packages to install as part of

7716

the image being built.

7717

The build process does not depend on these packages being present.

7718

However, because this is a "machine essential" variable, the list of

7719

packages are essential for the machine to boot.

7720

The impact of this variable affects images based on

7721

<filename>packagegroup-core-boot</filename>,

7722

including the <filename>core-image-minimal</filename> image.

</para>

<para>

This variable is similar to the

7727

<filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>

7728

variable with the exception that the image being built does not have a build

7729

dependency on the variable's list of packages.

7730

In other words, the image will still build if a package in this list is not found.

7731

Typically, this variable is used to handle essential kernel modules, whose

7732

functionality may be selected to be built into the kernel rather than as a module,

7733

in which case a package will not be produced.

</para>

<para>

Consider an example where you have a custom kernel where a specific touchscreen

7738

driver is required for the machine to be usable.

7739

However, the driver can be built as a module or

7740

into the kernel depending on the kernel configuration.

7741

If the driver is built as a module, you want it to be installed.

7742

But, when the driver is built into the kernel, you still want the

7743

build to succeed.

7744

This variable sets up a "recommends" relationship so that in the latter case,

7745

the build will not fail due to the missing package.

7746

To accomplish this, assuming the package for the module was called

7747

<filename>kernel-module-ab123</filename>, you would use the

7748

following in the machine's <filename>.conf</filename> configuration

7749

file:

7750

7751

MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"

7752

</literallayout>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

7753

<note>

7754

In this example, the

7755

<filename>kernel-module-ab123</filename> recipe

7756

needs to explicitly set its

7757

7758

variable to ensure that BitBake does not use the

7759

kernel recipe's

7760

7761

variable to satisfy the dependency.

7762

</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,

7767

or touchscreen drivers (depending on the machine).

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>

7773

<info>

7774

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>

7779

A list of machine-specific packages to install as part of the

7780

image being built that are not essential for the machine to boot.

7781

However, the build process for more fully-featured images

7782

depends on the packages being present.

</para>

<para>

This variable affects all images based on

7787

<filename>packagegroup-base</filename>, which does not include the

7788

<filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>

images.

</para>

<para>

The variable is similar to the

7794

<filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>

7795

variable with the exception that the image being built has a build

7796

dependency on the variable's list of packages.

7797

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

7802

essential for the machine to boot the image.

7803

However, if you are building a more fully-featured image, you want to enable

7804

the WiFi.

7805

The package containing the firmware for the WiFi hardware is always

7806

expected to exist, so it is acceptable for the build process to depend upon

7807

finding the package.

7808

In this case, assuming the package for the firmware was called

7809

<filename>wifidriver-firmware</filename>, you would use the following in the

7810

<filename>.conf</filename> file for the machine:

7811

7812

MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>

7819

<info>

7820

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>

7825

A list of machine-specific packages to install as part of the

7826

image being built that are not essential for booting the machine.

7827

The image being built has no build dependency on this list of packages.

</para>

<para>

This variable affects only images based on

7832

<filename>packagegroup-base</filename>, which does not include the

7833

<filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>

images.

</para>

<para>

This variable is similar to the

7839

<filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>

7840

variable with the exception that the image being built does not have a build

7841

dependency on the variable's list of packages.

7842

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

7847

For the machine to boot the image.

7848

However, if you are building a more fully-featured image, you want to enable

7849

WiFi.

7850

In this case, the package containing the WiFi kernel module will not be produced

7851

if the WiFi driver is built into the kernel, in which case you still want the

7852

build to succeed instead of failing as a result of the package not being found.

7853

To accomplish this, assuming the package for the module was called

7854

<filename>kernel-module-examplewifi</filename>, you would use the

7855

following in the <filename>.conf</filename> file for the machine:

7856

7857

MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>

7864

<info>

7865

MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports."

</info>

7870

Specifies the list of hardware features the

7871

7872

of supporting.

7873

For related information on enabling features, see the

and

variables.

</para>

<para>

For a list of hardware features supported by the Yocto

7883

Project as shipped, see the

7884

"<link linkend='ref-features-machine'>Machine Features</link>"

section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>

7891

<info>

7892

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>

7897

Features to be added to

7898

<filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>

7899

if not also present in

7900

<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.

7905

It is not intended to be user-configurable.

7906

It is best to just reference the variable to see which machine features are

7907

being backfilled for all machine configurations.

7908

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>

7915

<info>

7916

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>

7921

Features from

7922

<filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>

7923

that should not be backfilled (i.e. added to

7924

<filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)

7925

during the build.

7926

See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for

more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>

7933

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

7934

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]

7939

A colon-separated list of overrides that apply to the

7940

current machine.

7941

By default, this list includes the value of

7942

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

7943

</para>

7944

7945

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

7946

You can extend <filename>MACHINEOVERRIDES</filename>

7947

to add extra overrides that should apply to a machine.

7948

For example, all machines emulated in QEMU (e.g.

7949

<filename>qemuarm</filename>, <filename>qemux86</filename>,

7950

and so forth) include a file named

7951

<filename>meta/conf/machine/include/qemu.inc</filename>

7952

that prepends the following override to

7953

<filename>MACHINEOVERRIDES</filename>:

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

7954

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

7955

MACHINEOVERRIDES =. "qemuall:"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

7956

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

7957

This override allows variables to be overriden for all

7958

machines emulated in QEMU, like in the following example

7959

from the <filename>connman-conf</filename> recipe:

7960

7961

SRC_URI_append_qemuall = "file://wired.config \

file://wired-setup \

"

</literallayout>

The underlying mechanism behind

7966

<filename>MACHINEOVERRIDES</filename> is simply that it is

7967

included in the default value of

7968

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>

7974

<info>

7975

MAINTAINER[doc] = "The email address of the distribution maintainer."

</info>

7980

The email address of the distribution maintainer.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>

7986

<info>

7987

MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."

</info>

7992

Specifies additional paths from which the OpenEmbedded

7993

build system gets source code.

7994

When the build system searches for source code, it first

7995

tries the local download directory.

7996

If that location fails, the build system tries locations

7997

defined by

7998

7999

the upstream source, and then locations specified by

8000

<filename>MIRRORS</filename> in that order.

</para>

<para>

Assuming your distribution

8005

(<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)

8006

is "poky", the default value for

8007

<filename>MIRRORS</filename> is defined in the

8008

<filename>conf/distro/poky.conf</filename> file in the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

8009

<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>

8015

<info>

8016

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>

8021

Specifies a prefix has been added to

8022

8023

of a recipe or package, such as a Multilib version.

8024

The variable is used in places where the prefix needs to be

8025

added to or removed from a the name (e.g. the

8026

8027

<filename>MLPREFIX</filename> gets set when a prefix has been

8028

added to <filename>PN</filename>.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8029

<note>

8030

The "ML" in <filename>MLPREFIX</filename> stands for

8031

"MultiLib".

8032

This representation is historical and comes from

8033

a time when <filename>nativesdk</filename> was a suffix

8034

rather than a prefix on the recipe name.

8035

When <filename>nativesdk</filename> was turned into a

8036

prefix, it made sense to set

8037

<filename>MLPREFIX</filename> for it as well.

</note>

</para>

<para>

To help understand when <filename>MLPREFIX</filename>

8043

might be needed, consider when

8044

8045

is used to provide a <filename>nativesdk</filename> version

8046

of a recipe in addition to the target version.

8047

If that recipe declares build-time dependencies on tasks in

8048

other recipes by using

8049

8050

then a dependency on "foo" will automatically get rewritten

8051

to a dependency on "nativesdk-foo".

8052

However, dependencies like the following will not get

8053

rewritten automatically:

8054

8055

do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo"

8056

</literallayout>

8057

If you want such a dependency to also get transformed,

8058

you can do the following:

8059

8060

do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo"

8061

</literallayout>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>

8067

<info>

8068

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>

8073

This variable has been replaced by the

8074

<filename>KERNEL_MODULE_AUTOLOAD</filename> variable.

8075

You should replace all occurrences of

8076

<filename>module_autoload</filename> with additions to

8077

<filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:

8078

8079

module_autoload_rfcomm = "rfcomm"

</literallayout>

</para>

<para>

should now be replaced with:

8085

8086

KERNEL_MODULE_AUTOLOAD += "rfcomm"

</literallayout>

See the

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-module_conf'><glossterm>module_conf</glossterm>

8096

<info>

8097

module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file."

</info>

8102

Specifies

8103

<ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>

8104

syntax lines for inclusion in the

8105

<filename>/etc/modprobe.d/modname.conf</filename> file.

</para>

<para>

You can use this variable anywhere that it can be

8110

recognized by the kernel recipe or out-of-tree kernel

8111

module recipe (e.g. a machine configuration file, a

8112

distribution configuration file, an append file for the

8113

recipe, or the recipe itself).

8114

If you use this variable, you must also be sure to list

8115

the module name in the

variable.

</para>

<para>

Here is the general syntax:

8122

8123

module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>"

8124

</literallayout>

8125

You must use the kernel module name override.

</para>

<para>

Run <filename>man modprobe.d</filename> in the shell to

8130

find out more information on the exact syntax

8131

you want to provide with <filename>module_conf</filename>.

</para>

<para>

Including <filename>module_conf</filename> causes the

8136

OpenEmbedded build system to populate the

8137

<filename>/etc/modprobe.d/modname.conf</filename>

8138

file with <filename>modprobe.d</filename> syntax lines.

8139

Here is an example that adds the options

8140

8141

to a module named <filename>mymodule</filename>:

8142

8143

module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"

</literallayout>

</para>

<para>

For information on how to specify kernel modules to

8149

auto-load on boot, see the

variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-MODULE_IMAGE_BASE_NAME'><glossterm>MODULE_IMAGE_BASE_NAME</glossterm>

8157

<info>

8158

MODULE_IMAGE_BASE_NAME[doc] = "The base name of the kernel modules tarball."

</info>

8163

The base name of the kernel modules tarball.

8164

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>

8186

<info>

8187

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>

8192

Controls creation of the <filename>modules-*.tgz</filename>

8193

file.

8194

Set this variable to "0" to disable creation of this

8195

file, which contains all of the kernel modules resulting

from a kernel build.

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8201

<glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm>

8202

<info>

8203

MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories."

</info>

8208

Serves the same purpose as

8209

8210

but for the "HOST" system, in situations that involve a

8211

"HOST" and a "TARGET" system.

8212

See the

8213

8214

variable for more information.

</para>

<para>

The default value of this variable is:

8219

8220

${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS}

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8226

<glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>

8227

<info>

8228

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]

8233

Uniquely identifies the type of the target system for

8234

which packages are being built.

8235

This variable allows output for different types of target

8236

systems to be put into different subdirectories of the same

output directory.

</para>

<para>

The default value of this variable is:

8242

8243

${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.

8254

8255

is the corresponding variable for the host system in

8256

situations that involve a "HOST" and a "TARGET" system.

8257

See the

8258

8259

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>

8269

<info>

8270

NATIVELSBSTRING[doc] = "A string identifying the host distribution."

</info>

8275

A string identifying the host distribution.

8276

Strings consist of the host distributor ID

8277

followed by the release, as reported by the

8278

<filename>lsb_release</filename> tool

8279

or as read from <filename>/etc/lsb-release</filename>.

8280

For example, when running a build on Ubuntu 12.10, the value

8281

is "Ubuntu-12.10".

8282

If this information is unable to be determined, the value

8283

resolves to "Unknown".

</para>

<para>

This variable is used by default to isolate native shared

8288

state packages for different distributions (e.g. to avoid

8289

problems with <filename>glibc</filename> version

8290

incompatibilities).

8291

Additionally, the variable is checked against

8292

8293

if that variable is set.

</para>

</glossdef>

</glossentry>

<info>

NM[doc] = "Minimal command and arguments to run 'nm'."

</info>

8305

The minimal command and arguments to run

8306

<filename>nm</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>

8312

<info>

8313

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>

8318

Prevents installation of all "recommended-only" packages.

8319

Recommended-only packages are packages installed only

through the

variable).

Setting the <filename>NO_RECOMMENDATIONS</filename> variable

8324

to "1" turns this feature on:

8325

8326

NO_RECOMMENDATIONS = "1"

</literallayout>

</para>

<para>

You can set this variable globally in your

8332

<filename>local.conf</filename> file or you can attach it to

8333

a specific image recipe by using the recipe name override:

8334

8335

NO_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

8341

packages using this variable and some other packages are

8342

dependent on them (i.e. listed in a recipe's

8343

8344

variable), the OpenEmbedded build system ignores your

8345

request and will install the packages to avoid dependency

8346

errors.

8347

<note>

8348

Some recommended packages might be required for certain

8349

system functionality, such as kernel modules.

8350

It is up to you to add packages with the

variable.

</note>

</para>

<para>

Support for this variable exists only when using the

8358

IPK and RPM packaging backend.

8359

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>

8373

<info>

8374

NOHDD[doc] = "Causes the OpenEmbedded build system to skip building the .hddimg image."

</info>

8379

Causes the OpenEmbedded build system to skip building the

8380

<filename>.hddimg</filename> image.

8381

The <filename>NOHDD</filename> variable is used with the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

8382

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8383

class.

8384

Set the variable to "1" to prevent the

8385

<filename>.hddimg</filename> image from being built.

</para>

</glossdef>

</glossentry>

<glossentry id='var-NOISO'><glossterm>NOISO</glossterm>

8391

<info>

8392

NOISO[doc] = "Causes the OpenEmbedded build system to skip building the ISO image."

</info>

8397

Causes the OpenEmbedded build system to skip building the

8398

ISO image.

8399

The <filename>NOISO</filename> variable is used with the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

8400

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8401

class.

8402

Set the variable to "1" to prevent the ISO image from

8403

being built.

8404

To enable building an ISO image, set the variable to "0".

</para>

</glossdef>

</glossentry>

</glossdiv>

<glossentry id='var-OBJCOPY'><glossterm>OBJCOPY</glossterm>

8414

<info>

8415

OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'."

</info>

8420

The minimal command and arguments to run

8421

<filename>objcopy</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-OBJDUMP'><glossterm>OBJDUMP</glossterm>

8427

<info>

8428

OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'."

</info>

8433

The minimal command and arguments to run

8434

<filename>objdump</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>

8440

<info>

8441

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.

8450

The sed command alters any paths in configuration scripts

8451

that have been set up during compilation.

8452

Inheriting this class results in all paths in these scripts

8453

being changed to point into the

8454

<filename>sysroots/</filename> directory so that all builds

8455

that use the script will use the correct directories

8456

for the cross compiling layout.

</para>

<para>

See the <filename>meta/classes/binconfig.bbclass</filename>

8461

in the

8462

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

8463

for details on how this class applies these additional

8464

sed command arguments.

8465

For general information on the

8466

<filename>binconfig.bbclass</filename> class, see the

8467

"<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>

8474

<info>

8475

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>

8480

An internal variable used to tell the OpenEmbedded build

8481

system what Python modules to import for every Python

8482

function run by the system.

</para>

<note>

Do not set this variable.

8487

It is for internal use only.

</note>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

8492

<glossentry id='var-OE_INIT_ENV_SCRIPT'><glossterm>OE_INIT_ENV_SCRIPT</glossterm>

8493

<info>

8494

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>

8499

The name of the build environment setup script for the

8500

purposes of setting up the environment within the

8501

extensible SDK.

8502

The default value is "oe-init-build-env".

</para>

<para>

If you use a custom script to set up your build

8507

environment, set the

8508

<filename>OE_INIT_ENV_SCRIPT</filename> variable to its

name.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8514

<glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>

8515

<info>

8516

OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system."

</info>

8521

Controls how the OpenEmbedded build system spawns

8522

interactive terminals on the host development system

8523

(e.g. using the BitBake command with the

8524

<filename>-c devshell</filename> command-line option).

8525

For more information, see the

8526

"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section

8527

in the Yocto Project Development Manual.

</para>

<para>

You can use the following values for the

8532

<filename>OE_TERMINAL</filename> variable:

auto

gnome

xfce

rxvt

screen

konsole

none

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>

8547

<info>

8548

OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced."

</info>

8553

The directory from which the top-level build environment

8554

setup script is sourced.

8555

The Yocto Project makes two top-level build environment

8556

setup scripts available:

and

When you run one of these scripts, the

8561

<filename>OEROOT</filename> variable resolves to the

8562

directory that contains the script.

</para>

<para>

For additional information on how this variable is used,

8567

see the initialization scripts.

</para>

</glossdef>

</glossentry>

<glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>

8573

<info>

8574

OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support."

</info>

8579

Declares the oldest version of the Linux kernel that the

8580

produced binaries must support.

8581

This variable is passed into the build of the Embedded

8582

GNU C Library (<filename>glibc</filename>).

</para>

<para>

The default for this variable comes from the

8587

<filename>meta/conf/bitbake.conf</filename> configuration

8588

file.

8589

You can override this default by setting the variable

8590

in a custom distribution configuration file.

</para>

</glossdef>

</glossentry>

<glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>

8596

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8597

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]

8602

A colon-separated list of overrides that currently apply.

8603

Overrides are a BitBake mechanism that allows variables to

8604

be selectively overridden at the end of parsing.

8605

The set of overrides in <filename>OVERRIDES</filename>

8606

represents the "state" during building, which includes

8607

the current recipe being built, the machine for which

8608

it is being built, and so forth.

</para>

<para>

As an example, if the string "an-override" appears as an

8613

element in the colon-separated list in

8614

<filename>OVERRIDES</filename>, then the following

8615

assignment will override <filename>FOO</filename> with the

8616

value "overridden" at the end of parsing:

8617

8618

FOO_an-override = "overridden"

8619

</literallayout>

8620

See the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

8621

"<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

8622

section in the BitBake User Manual for more information on

8623

the overrides mechanism.

</para>

<para>

The default value of <filename>OVERRIDES</filename>

8628

includes the values of the

and

variables.

Another important override included by default is

8635

<filename>pn-${PN}</filename>.

8636

This override allows variables to be set for a single

8637

recipe within configuration (<filename>.conf</filename>)

files.

Here is an example:

FOO_pn-myrecipe = "myrecipe-specific value"

8642

</literallayout>

8643

8644

An easy way to see what overrides apply is to search for

8645

<filename>OVERRIDES</filename> in the output of the

8646

<filename>bitbake -e</filename> command.

8647

See the

8648

"<link linkend='usingpoky-debugging-viewing-variable-values'>Viewing Variable Values</link>"

8649

section for more information.

8650

</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>

8665

The recipe name and version.

8666

<filename>P</filename> is comprised of the following:

${PN}-${PV}

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>

8675

<info>

8676

PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."

</info>

8681

The architecture of the resulting package or packages.

</para>

<para>

By default, the value of this variable is set to

8686

8687

when building for the target,

8688

<filename>BUILD_ARCH</filename> when building for the

8689

build host and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building

8690

for the SDK.

8691

However, if your recipe's output packages are built

8692

specific to the target machine rather than general for

8693

the architecture of the machine, you should set

8694

<filename>PACKAGE_ARCH</filename> to the value of

8695

8696

in the recipe as follows:

8697

8698

PACKAGE_ARCH = "${MACHINE_ARCH}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm>

8705

<info>

8706

PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority."

</info>

8711

Specifies a list of architectures compatible with

8712

the target machine.

8713

This variable is set automatically and should not

8714

normally be hand-edited.

8715

Entries are separated using spaces and listed in order

8716

of priority.

8717

The default value for

8718

<filename>PACKAGE_ARCHS</filename> is "all any noarch

8719

${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>

8725

<info>

8726

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>

8731

Enables easily adding packages to

8732

<filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>

8733

before <filename>${<link linkend='var-PN'>PN</link>}</filename>

8734

so that those added packages can pick up files that would normally be

8735

included in the default package.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>

8741

<info>

8742

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>

8747

This variable, which is set in the

8748

<filename>local.conf</filename> configuration file found in

8749

the <filename>conf</filename> folder of the

8750

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,

8751

specifies the package manager the OpenEmbedded build system

8752

uses when packaging data.

</para>

<para>

You can provide one or more of the following arguments for

8757

the variable:

8758

8759

PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"

8760

</literallayout>

8761

<note><title>Warning</title>

8762

While it is a legal option, the

8763

<filename>package_tar</filename> class is broken

8764

and is not supported.

8765

It is recommended that you do not use it.

8766

</note>

8767

The build system uses only the first argument in the list

8768

as the package manager when creating your image or SDK.

8769

However, packages will be created using any additional

8770

packaging classes you specify.

8771

For example, if you use the following in your

8772

<filename>local.conf</filename> file:

8773

8774

PACKAGE_CLASSES ?= "package_ipk"

8775

</literallayout>

8776

The OpenEmbedded build system uses the IPK package manager

8777

to create your image or SDK.

</para>

<para>

For information on packaging and build performance effects

8782

as a result of the package manager in use, see the

8783

"<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>

8790

<info>

8791

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>

8796

Determines how to split up the binary and debug information

8797

when creating <filename>*-dbg</filename> packages to be

8798

used with the GNU Project Debugger (GDB).

</para>

<para>

With the

<filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,

8804

you can control where debug information, which can include

8805

or exclude source files, is stored:

8806

8807

8808

".debug": Debug symbol files are placed next

8809

to the binary in a <filename>.debug</filename>

8810

directory on the target.

8811

For example, if a binary is installed into

8812

<filename>/bin</filename>, the corresponding debug

8813

symbol files are installed in

8814

<filename>/bin/.debug</filename>.

8815

Source files are placed in

8816

<filename>/usr/src/debug</filename>.

8817

This is the default behavior.

8818

</para></listitem>

8819

8820

"debug-file-directory": Debug symbol files are

8821

placed under <filename>/usr/lib/debug</filename>

8822

on the target, and separated by the path from where

8823

the binary is installed.

8824

For example, if a binary is installed in

8825

<filename>/bin</filename>, the corresponding debug

8826

symbols are installed in

8827

<filename>/usr/lib/debug/bin</filename>.

8828

Source files are placed in

8829

<filename>/usr/src/debug</filename>.

8830

</para></listitem>

8831

8832

"debug-without-src": The same behavior as

8833

".debug" previously described with the exception

8834

that no source files are installed.

</para></listitem>.

</itemizedlist>

</para>

<para>

You can find out more about debugging using GDB by reading

8841

the

8842

"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"

8843

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

8848

<glossentry id='var-PACKAGE_EXCLUDE_COMPLEMENTARY'><glossterm>PACKAGE_EXCLUDE_COMPLEMENTARY</glossterm>

8849

<info>

8850

PACKAGE_EXCLUDE_COMPLEMENTARY[doc] = "Prevents specific packages from being installed when you are installing complementary packages."

</info>

8855

Prevents specific packages from being installed when

8856

you are installing complementary packages.

</para>

<para>

You might find that you want to prevent installing certain

8861

packages when you are installing complementary packages.

8862

For example, if you are using

8863

8864

to install <filename>dev-pkgs</filename>, you might not want

8865

to install all packages from a particular multilib.

8866

If you find yourself in this situation, you can use the

8867

<filename>PACKAGE_EXCLUDE_COMPLEMENTARY</filename> variable

8868

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]

8874

<glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>

8875

<info>

8876

PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated."

</info>

8881

Lists packages that should not be installed into an image.

8882

For example:

8883

8884

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

8890

<filename>local.conf</filename> file or you can attach it to

8891

a specific image recipe by using the recipe name override:

8892

8893

PACKAGE_EXCLUDE_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"

</literallayout>

</para>

<para>

If you choose to not install

8899

a package using this variable and some other package is

8900

dependent on it (i.e. listed in a recipe's

8901

8902

variable), the OpenEmbedded build system generates a fatal

8903

installation error.

8904

Because the build system halts the process with a fatal

8905

error, you can use the variable with an iterative

8906

development process to remove specific components from a

system.

</para>

<para>

Support for this variable exists only when using the

8912

IPK and RPM packaging backend.

8913

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>

8927

<info>

8928

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>

8933

Specifies the list of architectures compatible with the device CPU.

8934

This variable is useful when you build for several different devices that use

8935

miscellaneous processors such as XScale and ARM926-EJS.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

8940

<glossentry id='var-PACKAGE_FEED_ARCHS'><glossterm>PACKAGE_FEED_ARCHS</glossterm>

8941

<info>

8942

PACKAGE_FEED_ARCHS[doc] = "Specifies user-defined package architectures when constructing package feed URIs."

</info>

8947

Specifies the package architectures used as part of the

8948

package feed URIs during the build.

8949

The <filename>PACKAGE_FEED_ARCHS</filename> variable is

8950

appended to the final package feed URI, which is constructed

using the

and

variables.

</para>

<para>

Consider the following example where the

8960

<filename>PACKAGE_FEED_URIS</filename>,

8961

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

8962

<filename>PACKAGE_FEED_ARCHS</filename> variables are

8963

defined in your <filename>local.conf</filename> file:

8964

8965

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

8966

https://example.com/packagerepos/updates"

8967

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

8968

PACKAGE_FEED_ARCHS = "all core2-64"

8969

</literallayout>

8970

Given these settings, the resulting package feeds are

8971

as follows:

8972

8973

https://example.com/packagerepos/release/rpm/all

8974

https://example.com/packagerepos/release/rpm/core2-64

8975

https://example.com/packagerepos/release/rpm-dev/all

8976

https://example.com/packagerepos/release/rpm-dev/core2-64

8977

https://example.com/packagerepos/updates/rpm/all

8978

https://example.com/packagerepos/updates/rpm/core2-64

8979

https://example.com/packagerepos/updates/rpm-dev/all

8980

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>

8987

<info>

8988

PACKAGE_FEED_BASE_PATHS[doc] = "Specifies base path used when constructing package feed URIs."

</info>

8993

Specifies the base path used when constructing package feed

8994

URIs.

8995

The <filename>PACKAGE_FEED_BASE_PATHS</filename> variable

8996

makes up the middle portion of a package feed URI used

8997

by the OpenEmbedded build system.

8998

The base path lies between the

and

variables.

</para>

<para>

Consider the following example where the

9007

<filename>PACKAGE_FEED_URIS</filename>,

9008

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

9009

<filename>PACKAGE_FEED_ARCHS</filename> variables are

9010

defined in your <filename>local.conf</filename> file:

9011

9012

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

9013

https://example.com/packagerepos/updates"

9014

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

9015

PACKAGE_FEED_ARCHS = "all core2-64"

9016

</literallayout>

9017

Given these settings, the resulting package feeds are

9018

as follows:

9019

9020

https://example.com/packagerepos/release/rpm/all

9021

https://example.com/packagerepos/release/rpm/core2-64

9022

https://example.com/packagerepos/release/rpm-dev/all

9023

https://example.com/packagerepos/release/rpm-dev/core2-64

9024

https://example.com/packagerepos/updates/rpm/all

9025

https://example.com/packagerepos/updates/rpm/core2-64

9026

https://example.com/packagerepos/updates/rpm-dev/all

9027

https://example.com/packagerepos/updates/rpm-dev/core2-64

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_FEED_URIS'><glossterm>PACKAGE_FEED_URIS</glossterm>

9034

<info>

9035

PACKAGE_FEED_URIS[doc] = "Specifies the front portion of the package feed URI used by the OpenEmbedded build system."

</info>

9040

Specifies the front portion of the package feed URI

9041

used by the OpenEmbedded build system.

9042

Each final package feed URI is comprised of

9043

<filename>PACKAGE_FEED_URIS</filename>,

and

variables.

</para>

<para>

Consider the following example where the

9052

<filename>PACKAGE_FEED_URIS</filename>,

9053

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

9054

<filename>PACKAGE_FEED_ARCHS</filename> variables are

9055

defined in your <filename>local.conf</filename> file:

9056

9057

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

9058

https://example.com/packagerepos/updates"

9059

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

9060

PACKAGE_FEED_ARCHS = "all core2-64"

9061

</literallayout>

9062

Given these settings, the resulting package feeds are

9063

as follows:

9064

9065

https://example.com/packagerepos/release/rpm/all

9066

https://example.com/packagerepos/release/rpm/core2-64

9067

https://example.com/packagerepos/release/rpm-dev/all

9068

https://example.com/packagerepos/release/rpm-dev/core2-64

9069

https://example.com/packagerepos/updates/rpm/all

9070

https://example.com/packagerepos/updates/rpm/core2-64

9071

https://example.com/packagerepos/updates/rpm-dev/all

9072

https://example.com/packagerepos/updates/rpm-dev/core2-64

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9078

<glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>

9079

<info>

9080

PACKAGE_GROUP[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES."

</info>

9085

The <filename>PACKAGE_GROUP</filename> variable has been

9086

renamed to

9087

9088

See the variable description for

9089

<filename>FEATURE_PACKAGES</filename> for information.

</para>

<para>

If if you use the <filename>PACKAGE_GROUP</filename>

9094

variable, the OpenEmbedded build system issues a warning

message.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>

9101

<info>

9102

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>

9107

The final list of packages passed to the package manager

9108

for installation into the image.

</para>

<para>

Because the package manager controls actual installation

9113

of all packages, the list of packages passed using

9114

<filename>PACKAGE_INSTALL</filename> is not the final list

9115

of packages that are actually installed.

9116

This variable is internal to the image construction

9117

code.

9118

Consequently, in general, you should use the

9119

9120

variable to specify packages for installation.

9121

The exception to this is when working with

9122

the

9123

9124

image.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

9125

When working with an initial RAM filesystem (initramfs)

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9126

image, use the <filename>PACKAGE_INSTALL</filename>

9127

variable.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

9128

For information on creating an initramfs, see the

9129

"<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"

9130

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>

9136

<info>

9137

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>

9142

Specifies a list of packages the OpenEmbedded build

9143

system attempts to install when creating an image.

9144

If a listed package fails to install, the build system

9145

does not generate an error.

9146

This variable is generally not user-defined.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm>

9152

<info>

9153

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>

9158

Specifies a list of functions run to pre-process the

9159

9160

directory prior to splitting the files out to individual

packages.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>

9167

<info>

9168

PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis."

</info>

9173

This variable provides a means of enabling or disabling

9174

features of a recipe on a per-recipe basis.

9175

<filename>PACKAGECONFIG</filename> blocks are defined

9176

in recipes when you specify features and then arguments

9177

that define feature behaviors.

9178

Here is the basic block structure:

9179

9180

PACKAGECONFIG ??= "f1 f2 f3 ..."

9181

PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"

9182

PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"

9183

PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"

</literallayout>

</para>

<para>

The <filename>PACKAGECONFIG</filename>

9189

variable itself specifies a space-separated list of the

9190

features to enable.

9191

Following the features, you can determine the behavior of

9192

each feature by providing up to four order-dependent

9193

arguments, which are separated by commas.

9194

You can omit any argument you like but must retain the

9195

separating commas.

9196

The order is important and specifies the following:

9197

9198

<listitem><para>Extra arguments

9199

that should be added to the configure script

9200

argument list

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9201

(<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>

9202

or

9203

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9204

if the feature is enabled.</para></listitem>

9205

<listitem><para>Extra arguments

9206

that should be added to <filename>EXTRA_OECONF</filename>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9207

or <filename>PACKAGECONFIG_CONFARGS</filename>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9208

if the feature is disabled.

9209

</para></listitem>

9210

<listitem><para>Additional build dependencies

9211

(<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)

9212

that should be added if the feature is enabled.

9213

</para></listitem>

9214

<listitem><para>Additional runtime dependencies

9215

(<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)

9216

that should be added if the feature is enabled.

</para></listitem>

</orderedlist>

</para>

<para>

Consider the following

9223

<filename>PACKAGECONFIG</filename> block taken from the

9224

<filename>librsvg</filename> recipe.

9225

In this example the feature is <filename>croco</filename>,

9226

which has three arguments that determine the feature's

9227

behavior.

9228

9229

PACKAGECONFIG ??= "croco"

9230

PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"

9231

</literallayout>

9232

The <filename>--with-croco</filename> and

9233

<filename>libcroco</filename> arguments apply only if

9234

the feature is enabled.

9235

In this case, <filename>--with-croco</filename> is

9236

added to the configure script argument list and

9237

<filename>libcroco</filename> is added to

9238

<filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.

9239

On the other hand, if the feature is disabled say through

9240

a <filename>.bbappend</filename> file in another layer, then

9241

the second argument <filename>--without-croco</filename> is

9242

added to the configure script rather than

9243

<filename>--with-croco</filename>.

</para>

<para>

The basic <filename>PACKAGECONFIG</filename> structure

9248

previously described holds true regardless of whether you

9249

are creating a block or changing a block.

9250

When creating a block, use the structure inside your

recipe.

</para>

<para>

If you want to change an existing

9256

<filename>PACKAGECONFIG</filename> block, you can do so

9257

one of two ways:

9258

9259

<listitem><para><emphasis>Append file:</emphasis>

9260

Create an append file named

9261

<replaceable>recipename</replaceable><filename>.bbappend</filename>

9262

in your layer and override the value of

9263

<filename>PACKAGECONFIG</filename>.

9264

You can either completely override the variable:

9265

9266

PACKAGECONFIG="f4 f5"

9267

</literallayout>

9268

Or, you can just append the variable:

9269

9270

PACKAGECONFIG_append = " f4"

9271

</literallayout></para></listitem>

9272

<listitem><para><emphasis>Configuration file:</emphasis>

9273

This method is identical to changing the block

9274

through an append file except you edit your

9275

<filename>local.conf</filename> or

9276

<filename><replaceable>mydistro</replaceable>.conf</filename> file.

9277

As with append files previously described,

9278

you can either completely override the variable:

9279

9280

PACKAGECONFIG_pn-<replaceable>recipename</replaceable>="f4 f5"

9281

</literallayout>

9282

Or, you can just amend the variable:

9283

9284

PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4"

9285

</literallayout></para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9291

<glossentry id='var-PACKAGECONFIG_CONFARGS'><glossterm>PACKAGECONFIG_CONFARGS</glossterm>

9292

<info>

9293

PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from PACKAGECONFIG."

</info>

9298

A space-separated list of configuration options generated

from the

setting.

This list of options helps other classes and

9303

recipes take advantage of the

9304

<filename>PACKAGECONFIG</filename> mechanism without

9305

having to include options from

</para>

<para>

To illustrate how to use

9311

<filename>PACKAGECONFIG_CONFARGS</filename>, consider the

9312

following example:

9313

9314

PACKAGECONFIG_CONFARGS = " \

9315

-prefix ${prefix} \

9316

-sysroot ${STAGING_DIR_NATIVE} \

-no-gcc-sysroot

"

</literallayout>

In the previous example,

9321

<filename>PACKAGECONFIG_CONFARGS</filename> is set with

9322

three configuration options that can be passed using the

9323

<filename>PACKAGECONFIG</filename> mechanism, thus

9324

avoiding having to use <filename>EXTRA_OECONF</filename>.

</para>

<para>

For additional information, see the

variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9335

<glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm>

9336

<info>

9337

PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe."

</info>

9342

For recipes inheriting the

9343

9344

class, setting

9345

<filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to

9346

"1" specifies that the normal complementary packages

9347

(i.e. <filename>-dev</filename>,

9348

<filename>-dbg</filename>, and so forth) should not be

9349

automatically created by the

9350

<filename>packagegroup</filename> recipe, which is the

default behavior.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>

9357

<info>

9358

PACKAGES[doc] = "The list of packages to be created from the recipe."

</info>

9363

The list of packages to be created from the recipe.

9364

The default value is the following:

9365

9366

${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}

9367

</literallayout>

9368

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9369

9370

<para>

9371

During packaging, the

9372

9373

task goes through <filename>PACKAGES</filename> and uses

9374

the

9375

9376

variable corresponding to each package to assign files to

9377

the package.

9378

If a file matches the <filename>FILES</filename> variable

9379

for more than one package in <filename>PACKAGES</filename>,

9380

it will be assigned to the earliest (leftmost) package.

</para>

<para>

Packages in the variable's list that are empty (i.e. where

9385

none of the patterns in

9386

<filename>FILES_</filename><replaceable>pkg</replaceable>

9387

match any files installed by the

9388

9389

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>

9398

<info>

9399

PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes."

</info>

9404

A promise that your recipe satisfies runtime dependencies

9405

for optional modules that are found in other recipes.

9406

<filename>PACKAGES_DYNAMIC</filename>

9407

does not actually satisfy the dependencies, it only states that

9408

they should be satisfied.

9409

For example, if a hard, runtime dependency

9410

(<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)

9411

of another package is satisfied

9412

at build time through the <filename>PACKAGES_DYNAMIC</filename>

9413

variable, but a package with the module name is never actually

9414

produced, then the other package will be broken.

9415

Thus, if you attempt to include that package in an image,

9416

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

9424

occur and the package that is not created is valid

9425

without the dependency being satisfied, then you should use

9426

9427

(a soft runtime dependency) instead of

9428

<filename>RDEPENDS</filename>.

</para>

<para>

For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>

9433

variable when you are splitting packages, see the

9434

"<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section

9435

in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>

9441

<info>

9442

PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages."

</info>

9447

Specifies a list of functions run to perform additional

9448

splitting of files into individual packages.

9449

Recipes can either prepend to this variable or prepend

9450

to the <filename>populate_packages</filename> function

9451

in order to perform additional package splitting.

9452

In either case, the function should set

and other packaging variables appropriately in order to

9457

perform the desired splitting.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>

9463

<info>

9464

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>

9469

Extra options passed to the <filename>make</filename>

9470

command during the

9471

9472

task in order to specify parallel compilation on the local

9473

build host.

9474

This variable is usually in the form "-j <replaceable>x</replaceable>",

9475

where <replaceable>x</replaceable> represents the maximum

9476

number of parallel threads <filename>make</filename> can

9477

run.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9478

<note><title>Caution</title>

9479

In order for <filename>PARALLEL_MAKE</filename> to be

9480

effective, <filename>make</filename> must be called

9481

with

9482

<filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.

9483

An easy way to ensure this is to use the

9484

<filename>oe_runmake</filename> function.

9485

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

By default, the OpenEmbedded build system automatically

9490

sets this variable to be equal to the number of cores the

9491

build system uses.

9492

<note>

9493

If the software being built experiences dependency

9494

issues during the <filename>do_compile</filename>

9495

task that result in race conditions, you can clear

9496

the <filename>PARALLEL_MAKE</filename> variable within

9497

the recipe as a workaround.

9498

For information on addressing race conditions, see the

9499

"<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"

9500

section in the Yocto Project Development Manual.

9501

</note>

9502

For single socket systems (i.e. one CPU), you should not

9503

have to override this variable to gain optimal parallelism

9504

during builds.

9505

However, if you have very large systems that employ

9506

multiple physical CPUs, you might want to make sure the

9507

<filename>PARALLEL_MAKE</filename> variable is not

9508

set higher than "-j 20".

</para>

<para>

For more information on speeding up builds, see the

9513

"<link linkend='speeding-up-the-build'>Speeding Up the Build</link>"

section.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>

9520

<info>

9521

PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation."

</info>

9526

Extra options passed to the

9527

<filename>make install</filename> command during the

9528

9529

task in order to specify parallel installation.

9530

This variable defaults to the value of

9531

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9532

<note><title>Notes and Cautions</title>

9533

<para>In order for <filename>PARALLEL_MAKEINST</filename>

9534

to be

9535

effective, <filename>make</filename> must be called

9536

with

9537

<filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.

9538

An easy way to ensure this is to use the

9539

<filename>oe_runmake</filename> function.</para>

9540

9541

<para>If the software being built experiences

9542

dependency issues during the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9543

<filename>do_install</filename> task that result in

9544

race conditions, you can clear the

9545

<filename>PARALLEL_MAKEINST</filename> variable within

9546

the recipe as a workaround.

9547

For information on addressing race conditions, see the

9548

"<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]

9549

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>

9556

<info>

9557

PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution."

</info>

9562

Determines the action to take when a patch fails.

9563

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

9569

when the OpenEmbedded build system cannot successfully

9570

apply a patch.

9571

Setting the value to "user" causes the build system to

9572

launch a shell and places you in the right location so that

9573

you can manually resolve the conflicts.

</para>

<para>

Set this variable in your

9578

<filename>local.conf</filename> file.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>

9584

<info>

9585

PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch."

</info>

9590

Specifies the utility used to apply patches for a recipe

during the

task.

You can specify one of three utilities: "patch", "quilt", or

9595

"git".

9596

The default utility used is "quilt" except for the

9597

quilt-native recipe itself.

9598

Because the quilt tool is not available at the

9599

time quilt-native is being patched, it uses "patch".

</para>

<para>

If you wish to use an alternative patching tool, set the

9604

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>

9621

The epoch of the recipe.

9622

By default, this variable is unset.

9623

The variable is used to make upgrades possible when the

9624

versioning scheme changes in some backwards incompatible

9625

way.

9626

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9627

9628

<para>

9629

<filename>PE</filename> is the default value of the

9630

9631

variable.

9632

</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>

9643

Specifies the recipe or package name and includes all version and revision

9644

numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and

9645

<filename>bash-4.2-r1/</filename>).

9646

This variable is comprised of the following:

9647

9648

${<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>

9655

<info>

9656

PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf."

</info>

9661

When inheriting the

9662

9663

class, this variable identifies packages that contain

9664

the pixbuf loaders used with

9665

<filename>gdk-pixbuf</filename>.

9666

By default, the <filename>pixbufcache</filename> class

9667

assumes that the loaders are in the recipe's main package

9668

(i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).

9669

Use this variable if the loaders you need are in a package

9670

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>

9682

The name of the resulting package created by the

9683

OpenEmbedded build system.

9684

<note>

9685

When using the <filename>PKG</filename> variable, you

9686

must use a package name override.

</note>

</para>

<para>

For example, when the

9692

9693

class renames the output package, it does so by setting

9694

<filename>PKG_<replaceable>packagename</replaceable></filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PKG_CONFIG_PATH'><glossterm>PKG_CONFIG_PATH</glossterm>

9700

<info>

9701

PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context."

</info>

9706

The path to <filename>pkg-config</filename> files for the

9707

current build context.

9708

<filename>pkg-config</filename> reads this variable

9709

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>

9721

Points to the destination directory for files to be

9722

packaged before they are split into individual packages.

9723

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>

9736

<info>

9737

PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process."

</info>

9742

Points to a shared, global-state directory that holds data

9743

generated during the packaging process.

9744

During the packaging process, the

9745

9746

task packages data for each recipe and installs it into

9747

this temporary, shared area.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9748

This directory defaults to the following, which you should

9749

not change:

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9750

9751

${STAGING_DIR_HOST}/pkgdata

9752

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9753

For examples of how this data is used, see the

9754

"<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"

9755

section and the

9756

"<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"

9757

section.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>

9763

<info>

9764

PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages."

</info>

9769

Points to the parent directory for files to be packaged

9770

after they have been split into individual packages.

9771

This directory defaults to the following:

9772

9773

${WORKDIR}/packages-split

</literallayout>

</para>

<para>

Under this directory, the build system creates

9779

directories for each package specified in

9780

9781

Do not change this default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>

9787

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9788

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]

9793

Points to a temporary work area where the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9794

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9795

task saves package metadata.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9796

The <filename>PKGDESTWORK</filename> location defaults to

the following:

${WORKDIR}/pkgdata

</literallayout>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9801

Do not change this default.

9802

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

<para>

The

task copies the package metadata from

9808

<filename>PKGDESTWORK</filename> to

9809

9810

to make it available globally.

9811

</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]

9817

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]

9822

The epoch of the package(s) built by the recipe.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9823

By default, <filename>PKGE</filename> is set to

</para>

</glossdef>

</glossentry>

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9831

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]

9836

The revision of the package(s) built by the recipe.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9837

By default, <filename>PKGR</filename> is set to

</para>

</glossdef>

</glossentry>

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

9845

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]

9850

The version of the package(s) built by the

9851

recipe.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

9852

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>

9865

This variable can have two separate functions depending on the context: a recipe

9866

name or a resulting package name.

</para>

<para>

<filename>PN</filename> refers to a recipe name in the context of a file used

9871

by the OpenEmbedded build system as input to create a package.

9872

The name is normally extracted from the recipe file name.

9873

For example, if the recipe is named

9874

<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

9880

OpenEmbedded build system.

</para>

<para>

If applicable, the <filename>PN</filename> variable also contains any special

9885

suffix or prefix.

9886

For example, using <filename>bash</filename> to build packages for the native

9887

machine, <filename>PN</filename> is <filename>bash-native</filename>.

9888

Using <filename>bash</filename> to build packages for the target and for Multilib,

9889

<filename>PN</filename> would be <filename>bash</filename> and

9890

<filename>lib64-bash</filename>, respectively.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>

9896

<info>

9897

PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build."

</info>

9902

Lists recipes you do not want the OpenEmbedded build system

9903

to build.

9904

This variable works in conjunction with the

9905

9906

class, which the recipe must inherit globally.

</para>

<para>

To prevent a recipe from being built, inherit the class

9911

globally and use the variable in your

9912

<filename>local.conf</filename> file.

9913

Here is an example that prevents

9914

<filename>myrecipe</filename> from being built:

9915

9916

INHERIT += "blacklist"

9917

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>

9924

<info>

9925

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>

9930

Specifies a list of functions to call once the

9931

OpenEmbedded build system has created the host part of

9932

the SDK.

9933

You can specify functions separated by semicolons:

9934

9935

POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the SDK path to a command

9941

within a function, you can use

9942

<filename>${SDK_DIR}</filename>, which points to

9943

the parent directory used by the OpenEmbedded build

9944

system when creating SDK output.

9945

See the

9946

9947

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-POPULATE_SDK_POST_TARGET_COMMAND'><glossterm>POPULATE_SDK_POST_TARGET_COMMAND</glossterm>

9953

<info>

9954

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>

9959

Specifies a list of functions to call once the

9960

OpenEmbedded build system has created the target part of

9961

the SDK.

9962

You can specify functions separated by semicolons:

9963

9964

POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the SDK path to a command

9970

within a function, you can use

9971

<filename>${SDK_DIR}</filename>, which points to

9972

the parent directory used by the OpenEmbedded build

9973

system when creating SDK output.

9974

See the

9975

9976

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]

9988

The revision of the recipe. The default value for this

9989

variable is "r0".

9990

Subsequent revisions of the recipe conventionally have the

9991

values "r1", "r2", and so forth.

9992

When

9993

9994

increases, <filename>PR</filename> is conventionally reset

9995

to "r0".

9996

<note>

9997

The OpenEmbedded build system does not need the aid of

9998

<filename>PR</filename> to know when to rebuild a

9999

recipe.

10000

The build system uses the task

10001

<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>input checksums</ulink>

along with the

and

mechanisms.

</note>

The <filename>PR</filename> variable primarily becomes

10009

significant when a package manager dynamically installs

10010

packages on an already built image.

10011

In this case, <filename>PR</filename>, which is the default

10012

value of

10013

10014

helps the package manager distinguish which package is the

10015

most recent one in cases where many packages have the same

10016

<filename>PV</filename> (i.e. <filename>PKGV</filename>).

10017

A component having many packages with the same

10018

<filename>PV</filename> usually means that the packages all

10019

install the same upstream version, but with later

10020

(<filename>PR</filename>) version packages including

10021

packaging fixes.

10022

<note>

10023

<filename>PR</filename> does not need to be increased

10024

for changes that do not change the package contents or

10025

metadata.

10026

</note>

10027

Because manually managing <filename>PR</filename> can be

10028

cumbersome and error-prone, an automated solution exists.

10029

See the

10030

"<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"

10031

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>

10037

<info>

10038

PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference."

</info>

10043

If multiple recipes provide an item, this variable

10044

determines which recipe should be given preference.

10045

You should always suffix the variable with the name of the

10046

provided item, and you should set it to the

10047

10048

of the recipe to which you want to give precedence.

10049

Some examples:

10050

10051

PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"

10052

PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"

10053

PREFERRED_PROVIDER_virtual/libgl ?= "mesa"

10054

</literallayout>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

10055

<note>

10056

If you set <filename>PREFERRED_PROVIDER</filename>

10057

for a <filename>virtual/*</filename> item, then any

10058

recipe that

10059

10060

that item that is not selected by

10061

<filename>PREFERRED_PROVIDER</filename> is prevented

10062

from building, which is usually desirable since this

10063

mechanism is designed to select between mutually

10064

exclusive alternative providers.

10065

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>

10071

<info>

10072

PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference."

</info>

10077

If there are multiple versions of recipes available, this

10078

variable determines which recipe should be given preference.

10079

You must always suffix the variable with the

10080

10081

you want to select, and you should set the

10082

10083

accordingly for precedence.

10084

You can use the "<filename>%</filename>" character as a

10085

wildcard to match any number of characters, which can be

10086

useful when specifying versions that contain long revision

10087

numbers that could potentially change.

10088

Here are two examples:

10089

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10090

PREFERRED_VERSION_python = "3.4.0"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10091

PREFERRED_VERSION_linux-yocto = "3.19%"

10092

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10093

<note>

10094

The specified version is matched against

10095

10096

which does not necessarily match the version part of

10097

the recipe's filename.

10098

For example, consider two recipes

10099

<filename>foo_1.2.bb</filename> and

10100

<filename>foo_git.bb</filename> where

10101

<filename>foo_git.bb</filename> contains the following

10102

assignment:

10103

10104

PV = "1.1+git${SRCPV}"

10105

</literallayout>

10106

In this case, the correct way to select

10107

<filename>foo_git.bb</filename> is by using an

10108

assignment such as the following:

10109

10110

PREFERRED_VERSION_foo = "1.1+git%"

10111

</literallayout>

10112

Compare that previous example against the following

10113

incorrect example, which does not work:

10114

10115

PREFERRED_VERSION_foo = "git"

10116

</literallayout>

10117

</note>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

10118

Sometimes the <filename>PREFERRED_VERSION</filename>

10119

variable can be set by configuration files in a way that

is hard to change.

You can use

to set a machine-specific override.

10124

Here is an example:

10125

10126

PREFERRED_VERSION_linux-yocto_qemux86 = "3.4%"

10127

</literallayout>

10128

Although not recommended, worst case, you can also use the

10129

"forcevariable" override, which is the strongest override

possible.

Here is an example:

PREFERRED_VERSION_linux-yocto_forcevariable = "3.4%"

10134

</literallayout>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10135

<note>

10136

The <filename>_forcevariable</filename> override is

10137

not handled specially.

10138

This override only works because the default value of

10139

10140

includes "forcevariable".

10141

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

</glossdef>

</glossentry>

<glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>

10147

<info>

10148

PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."

</info>

10153

Specifies additional paths from which the OpenEmbedded

10154

build system gets source code.

10155

When the build system searches for source code, it first

10156

tries the local download directory.

10157

If that location fails, the build system tries locations

10158

defined by <filename>PREMIRRORS</filename>, the upstream

10159

source, and then locations specified by

in that order.

</para>

<para>

Assuming your distribution

10166

(<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)

10167

is "poky", the default value for

10168

<filename>PREMIRRORS</filename> is defined in the

10169

<filename>conf/distro/poky.conf</filename> file in the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

10170

<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

10175

build system to attempt before any others by adding

10176

something like the following to the

10177

<filename>local.conf</filename> configuration file in the

10178

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:

10179

10180

PREMIRRORS_prepend = "\

10181

git://.*/.* http://www.yoctoproject.org/sources/ \n \

10182

ftp://.*/.* http://www.yoctoproject.org/sources/ \n \

10183

http://.*/.* http://www.yoctoproject.org/sources/ \n \

10184

https://.*/.* http://www.yoctoproject.org/sources/ \n"

10185

</literallayout>

10186

These changes cause the build system to intercept

10187

Git, FTP, HTTP, and HTTPS requests and direct them to

10188

the <filename>http://</filename> sources mirror.

10189

You can use <filename>file://</filename> URLs to point

10190

to local directories or network shares as well.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PRIORITY'><glossterm>PRIORITY</glossterm>

10196

<info>

10197

PRIORITY[doc] = "Indicates the importance of a package. The default value is 'optional'. Other standard values are 'required', 'standard' and 'extra'."

</info>

10202

Indicates the importance of a package.

</para>

<para>

<filename>PRIORITY</filename> is considered to be part of

10207

the distribution policy because the importance of any given

10208

recipe depends on the purpose for which the distribution

10209

is being produced.

10210

Thus, <filename>PRIORITY</filename> is not normally set

within recipes.

</para>

<para>

You can set <filename>PRIORITY</filename> to "required",

10216

"standard", "extra", and "optional", which is the default.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>

10222

<info>

10223

PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver."

</info>

10228

Specifies libraries installed within a recipe that

10229

should be ignored by the OpenEmbedded build system's

10230

shared library resolver.

10231

This variable is typically used when software being

10232

built by a recipe has its own private versions of a

10233

library normally provided by another recipe.

10234

In this case, you would not want the package containing

10235

the private libraries to be set as a dependency on other

10236

unrelated packages that should instead depend on the

10237

package providing the standard version of the library.

</para>

<para>

Libraries specified in this variable should be specified

10242

by their file name.

10243

For example, from the Firefox recipe in meta-browser:

10244

10245

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]

10254

10255

<para>

10256

For more information, see the

10257

"<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"

10258

section.

10259

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

<glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>

10264

<info>

10265

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>

10270

A list of aliases by which a particular recipe can be

10271

known.

10272

By default, a recipe's own

10273

10274

is implicitly already in its <filename>PROVIDES</filename>

10275

list.

10276

If a recipe uses <filename>PROVIDES</filename>, the

10277

additional aliases are synonyms for the recipe and can

10278

be useful satisfying dependencies of other recipes during

10279

the build as specified by

10280

<filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.

</para>

<para>

Consider the following example

10285

<filename>PROVIDES</filename> statement from a recipe

10286

file <filename>libav_0.8.11.bb</filename>:

10287

10288

PROVIDES += "libpostproc"

10289

</literallayout>

10290

The <filename>PROVIDES</filename> statement results in

10291

the "libav" recipe also being known as "libpostproc".

10292

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10293

10294

<para>

10295

In addition to providing recipes under alternate names,

10296

the <filename>PROVIDES</filename> mechanism is also used

10297

to implement virtual targets.

10298

A virtual target is a name that corresponds to some

10299

particular functionality (e.g. a Linux kernel).

10300

Recipes that provide the functionality in question list the

10301

virtual target in <filename>PROVIDES</filename>.

10302

Recipes that depend on the functionality in question can

10303

include the virtual target in

10304

10305

to leave the choice of provider open.

</para>

<para>

Conventionally, virtual targets have names on the form

10310

"virtual/function" (e.g. "virtual/kernel").

10311

The slash is simply part of the name and has no

10312

syntactical significance.

</para>

<para>

The

variable is used to select which particular recipe

10319

provides a virtual target.

10320

<note>

10321

<para>A corresponding mechanism for virtual runtime

10322

dependencies (packages) exists.

10323

However, the mechanism does not depend on any special

10324

functionality beyond ordinary variable assignments.

10325

For example,

10326

<filename>VIRTUAL-RUNTIME_dev_manager</filename>

10327

refers to the package of the component that manages

10328

the <filename>/dev</filename> directory.</para>

10329

10330

<para>Setting the "preferred provider" for runtime

10331

dependencies is as simple as using the following

10332

assignment in a configuration file:</para>

10333

10334

VIRTUAL-RUNTIME_dev_manager = "udev"

10335

</literallayout>

10336

</note>

10337

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

<glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>

10342

<info>

10343

PRSERV_HOST[doc] = "The network based PR service host and port."

</info>

10348

The network based

10349

10350

service host and port.

</para>

<para>

The <filename>conf/local.conf.sample.extended</filename>

10355

configuration file in the

10356

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

10357

shows how the <filename>PRSERV_HOST</filename> variable is

10358

set:

10359

10360

PRSERV_HOST = "localhost:0"

10361

</literallayout>

10362

You must set the variable if you want to automatically

10363

start a local

10364

<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.

10365

You can set <filename>PRSERV_HOST</filename> to other

10366

values to use a remote PR service.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm>

10372

<info>

10373

PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe."

</info>

10378

Specifies whether or not

10379

<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink>

10380

(ptest) functionality is enabled when building a recipe.

10381

You should not set this variable directly.

10382

Enabling and disabling building Package Tests

10383

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>

10397

The version of the recipe.

10398

The version is normally extracted from the recipe filename.

10399

For example, if the recipe is named

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10400

<filename>expat_2.0.1.bb</filename>, then the default value

10401

of <filename>PV</filename> will be "2.0.1".

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10402

<filename>PV</filename> is generally not overridden within

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10403

a recipe unless it is building an unstable (i.e.

10404

development) version from a source code repository

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10405

(e.g. Git or Subversion).

10406

</para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10407

10408

<para>

10409

<filename>PV</filename> is the default value of the

10410

10411

variable.

10412

</para>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</glossdef>

</glossentry>

<glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>

10417

<info>

10418

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>

10423

When used by recipes that inherit the

or

classes, denotes the Application Binary Interface (ABI)

10430

currently in use for Python.

10431

By default, the ABI is "m".

10432

You do not have to set this variable as the OpenEmbedded

10433

build system sets it for you.

</para>

<para>

The OpenEmbedded build system uses the ABI to construct

10438

directory names used when installing the Python headers

10439

and libraries in sysroot

10440

(e.g. <filename>.../python3.3m/...</filename>).

</para>

<para>

Recipes that inherit the

10445

10446

class during cross-builds also use this variable to

10447

locate the headers and libraries of the appropriate Python

10448

that the extension is targeting.

</para>

</glossdef>

</glossentry>

<glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>

10454

<info>

10455

PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built."

</info>

10460

When used by recipes that inherit the

or

classes, specifies the major Python version being built.

10467

For Python 2.x, <filename>PYTHON_PN</filename> would

10468

be "python2". For Python 3.x, the variable would be

10469

"python3".

10470

You do not have to set this variable as the

10471

OpenEmbedded build system automatically sets it for you.

</para>

<para>

The variable allows recipes to use common infrastructure

10476

such as the following:

10477

10478

DEPENDS += "${PYTHON_PN}-native"

10479

</literallayout>

10480

In the previous example, the version of the dependency

10481

is <filename>PYTHON_PN</filename>.

</para>

</glossdef>

</glossentry>

</glossdiv>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10488

10489

10490

<glossentry id='var-RANLIB'><glossterm>RANLIB</glossterm>

10491

<info>

10492

RANLIB[doc] = "Minimal command and arguments to run 'ranlib'."

</info>

10497

The minimal command and arguments to run

10498

<filename>ranlib</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>

10504

<info>

10505

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>

10510

The list of packages that conflict with packages.

10511

Note that packages will not be installed if conflicting

10512

packages are not first removed.

</para>

<para>

Like all package-controlling variables, you must always use

10517

them in conjunction with a package name override.

10518

Here is an example:

10519

10520

RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>"

</literallayout>

</para>

<para>

BitBake, which the OpenEmbedded build system uses, supports

10526

specifying versioned dependencies.

10527

Although the syntax varies depending on the packaging

10528

format, BitBake hides these differences from you.

10529

Here is the general syntax to specify versions with

10530

the <filename>RCONFLICTS</filename> variable:

10531

10532

RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

10533

</literallayout>

10534

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a dependency on version

10544

1.2 or greater of the package <filename>foo</filename>:

10545

10546

RCONFLICTS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>

10553

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10554

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]

10559

Lists runtime dependencies of a package.

10560

These dependencies are other packages that must be

10561

installed in order for the package to function correctly.

10562

As an example, the following assignment declares that the

10563

package <filename>foo</filename> needs the packages

10564

<filename>bar</filename> and <filename>baz</filename> to

10565

be installed:

10566

10567

RDEPENDS_foo = "bar baz"

10568

</literallayout>

10569

The most common types of package runtime dependencies are

10570

automatically detected and added.

10571

Therefore, most recipes do not need to set

10572

<filename>RDEPENDS</filename>.

10573

For more information, see the

10574

"<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>"

10575

section.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10576

</para>

10577

10578

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10579

The practical effect of the above

10580

<filename>RDEPENDS</filename> assignment is that

10581

10582

will be declared as dependencies inside the package

10583

<filename>foo</filename> when it is written out by one of

the

tasks.

Exactly how this is done depends on which package format

10588

is used, which is determined by

10589

10590

When the corresponding package manager installs the

10591

package, it will know to also install the packages on

which it depends.

</para>

<para>

To ensure that the packages <filename>bar</filename> and

10597

<filename>baz</filename> get built, the previous

10598

<filename>RDEPENDS</filename> assignment also causes a task

10599

dependency to be added.

10600

This dependency is from the recipe's

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10601

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10602

(not to be confused with

10603

10604

task to the <filename>do_package_write_*</filename>

10605

task of the recipes that build <filename>bar</filename> and

10606

<filename>baz</filename>.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

The names of the packages you list within

10611

<filename>RDEPENDS</filename> must be the names of other

10612

packages - they cannot be recipe names.

10613

Although package names and recipe names usually match,

10614

the important point here is that you are

10615

providing package names within the

10616

<filename>RDEPENDS</filename> variable.

10617

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

10625

to packages being built, you should always use the variable

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10626

in a form with an attached package name (remember that a

10627

single recipe can build multiple packages).

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10628

For example, suppose you are building a development package

10629

that depends on the <filename>perl</filename> package.

10630

In this case, you would use the following

10631

<filename>RDEPENDS</filename> statement:

10632

10633

RDEPENDS_${PN}-dev += "perl"

10634

</literallayout>

10635

In the example, the development package depends on

10636

the <filename>perl</filename> package.

10637

Thus, the <filename>RDEPENDS</filename> variable has the

10638

<filename>${PN}-dev</filename> package name as part of the

10639

variable.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10640

<note>

10641

<title>Caution</title>

10642

<filename>RDEPENDS_${PN}-dev</filename> includes

10643

10644

by default.

10645

This default is set in the BitBake configuration file

10646

(<filename>meta/conf/bitbake.conf</filename>).

10647

Be careful not to accidentally remove

10648

<filename>${PN}</filename> when modifying

10649

<filename>RDEPENDS_${PN}-dev</filename>.

10650

Use the "+=" operator rather than the "=" operator.

10651

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10652

</para>

10653

10654

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10655

The package names you use with

10656

<filename>RDEPENDS</filename> must appear as they would in

10657

the <filename>PACKAGES</filename> variable.

10658

The

10659

10660

variable allows a different name to be used for

10661

the final package (e.g. the

10662

10663

class uses this to rename packages), but this final package

10664

name cannot be used with <filename>RDEPENDS</filename>,

10665

which makes sense as <filename>RDEPENDS</filename> is meant

10666

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

10671

specifying versioned dependencies.

10672

Although the syntax varies depending on the packaging

10673

format, BitBake hides these differences from you.

10674

Here is the general syntax to specify versions with

10675

the <filename>RDEPENDS</filename> variable:

10676

10677

RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

10678

</literallayout>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

10679

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^]

10688

For <replaceable>version</replaceable>, provide the version

number.

You can use

to provide a full package version specification.

10694

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10695

For example, the following sets up a dependency on version

10696

1.2 or greater of the package <filename>foo</filename>:

10697

10698

RDEPENDS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

<para>

For information on build-time dependencies, see the

10704

10705

variable.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10706

You can also see the

10707

"<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and

10708

"<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"

10709

sections in the BitBake User Manual for additional

10710

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>

10716

<info>

10717

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

10726

exist in the current configuration in order for the

10727

OpenEmbedded build system to build the recipe.

10728

In other words, if the

10729

<filename>REQUIRED_DISTRO_FEATURES</filename> variable

10730

lists a feature that does not appear in

10731

<filename>DISTRO_FEATURES</filename> within the

10732

current configuration, an error occurs and the

build stops.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10738

<glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>

10739

<info>

10740

RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed."

</info>

10745

With <filename>rm_work</filename> enabled, this

10746

variable specifies a list of recipes whose work directories

10747

should not be removed.

10748

See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"

10749

section for more details.

</para>

</glossdef>

</glossentry>

<info>

ROOT_HOME[doc] = "Defines the root home directory."

</info>

10761

Defines the root home directory.

10762

By default, this directory is set as follows in the

10763

BitBake configuration file:

10764

10765

ROOT_HOME ??= "/home/root"

10766

</literallayout>

10767

<note>

10768

This default value is likely used because some

10769

embedded solutions prefer to have a read-only root

10770

filesystem and prefer to keep writeable data in one

place.

</note>

</para>

<para>

You can override the default by setting the variable

10777

in any layer or in the <filename>local.conf</filename> file.

10778

Because the default is set using a "weak" assignment

10779

(i.e. "??="), you can use either of the following forms

10780

to define your override:

ROOT_HOME = "/root"

ROOT_HOME ?= "/root"

</literallayout>

These override examples use <filename>/root</filename>,

10786

which is probably the most commonly used override.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>

10792

<info>

10793

ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem."

</info>

10798

Indicates a filesystem image to include as the root

filesystem.

</para>

<para>

The <filename>ROOTFS</filename> variable is an optional

10804

variable used with the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

10805

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>

10812

<info>

10813

ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."

</info>

10818

Specifies a list of functions to call after the

10819

OpenEmbedded build system has installed packages.

10820

You can specify functions separated by semicolons:

10821

10822

ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

10828

within a function, you can use

10829

<filename>${IMAGE_ROOTFS}</filename>, which points to

10830

the directory that becomes the root filesystem image.

10831

See the

10832

10833

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>

10839

<info>

10840

ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."

</info>

10845

Specifies a list of functions to call once the

10846

OpenEmbedded build system has created the root filesystem.

10847

You can specify functions separated by semicolons:

10848

10849

ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

10855

within a function, you can use

10856

<filename>${IMAGE_ROOTFS}</filename>, which points to

10857

the directory that becomes the root filesystem image.

10858

See the

10859

10860

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>

10866

<info>

10867

ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."

</info>

10872

Specifies a list of functions to call after the

10873

OpenEmbedded build system has removed unnecessary

10874

packages.

10875

When runtime package management is disabled in the

10876

image, several packages are removed including

10877

<filename>base-passwd</filename>,

10878

<filename>shadow</filename>, and

10879

<filename>update-alternatives</filename>.

10880

You can specify functions separated by semicolons:

10881

10882

ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

10888

within a function, you can use

10889

<filename>${IMAGE_ROOTFS}</filename>, which points to

10890

the directory that becomes the root filesystem image.

10891

See the

10892

10893

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>

10899

<info>

10900

ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."

</info>

10905

Specifies a list of functions to call before the

10906

OpenEmbedded build system has created the root filesystem.

10907

You can specify functions separated by semicolons:

10908

10909

ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

10915

within a function, you can use

10916

<filename>${IMAGE_ROOTFS}</filename>, which points to

10917

the directory that becomes the root filesystem image.

10918

See the

10919

10920

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>

10926

<info>

10927

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>

10932

A list of package name aliases that a package also provides.

10933

These aliases are useful for satisfying runtime dependencies

10934

of other packages both during the build and on the target

10935

(as specified by

10936

<filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).

10937

<note>

10938

A package's own name is implicitly already in its

10939

<filename>RPROVIDES</filename> list.

</note>

</para>

<para>

As with all package-controlling variables, you must always

10945

use the variable in conjunction with a package name override.

10946

Here is an example:

10947

10948

RPROVIDES_${PN} = "widget-abi-2"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>

10955

<info>

10956

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>

10961

A list of packages that extends the usability of a package

10962

being built.

10963

The package being built does not depend on this list of

10964

packages in order to successfully build, but rather

10965

uses them for extended usability.

10966

To specify runtime dependencies for packages, see the

10967

<filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>

variable.

</para>

<para>

The package manager will automatically install the

10973

<filename>RRECOMMENDS</filename> list of packages when

10974

installing the built package.

10975

However, you can prevent listed packages from being

10976

installed by using the

and

variables.

</para>

<para>

Packages specified in

10986

<filename>RRECOMMENDS</filename> need not actually be

10987

produced.

10988

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.

10996

If such a recipe does exist and the package is not produced,

10997

the build continues without error.

</para>

<para>

Because the <filename>RRECOMMENDS</filename> variable

11002

applies to packages being built, you should always attach

11003

an override to the variable to specify the particular

11004

package whose usability is being extended.

11005

For example, suppose you are building a development package

11006

that is extended to support wireless functionality.

11007

In this case, you would use the following:

11008

11009

RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>"

11010

</literallayout>

11011

In the example, the package name

11012

(<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)

11013

must appear as it would in the

11014

<filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>

11015

namespace before any renaming of the output package by

11016

classes such as <filename>debian.bbclass</filename>.

</para>

<para>

BitBake, which the OpenEmbedded build system uses, supports

11021

specifying versioned recommends.

11022

Although the syntax varies depending on the packaging

11023

format, BitBake hides these differences from you.

11024

Here is the general syntax to specify versions with

11025

the <filename>RRECOMMENDS</filename> variable:

11026

11027

RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

11028

</literallayout>

11029

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a recommend on version

11039

1.2 or greater of the package <filename>foo</filename>:

11040

11041

RRECOMMENDS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>

11048

<info>

11049

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>

11054

A list of packages replaced by a package.

11055

The package manager uses this variable to determine which

11056

package should be installed to replace other package(s)

11057

during an upgrade.

11058

In order to also have the other package(s) removed at the

11059

same time, you must add the name of the other

11060

package to the

11061

<filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.

</para>

<para>

As with all package-controlling variables, you must use

11066

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

11076

specifying versioned replacements.

11077

Although the syntax varies depending on the packaging

11078

format, BitBake hides these differences from you.

11079

Here is the general syntax to specify versions with

11080

the <filename>RREPLACES</filename> variable:

11081

11082

RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

11083

</literallayout>

11084

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a replacement using

11094

version 1.2 or greater of the package

11095

<filename>foo</filename>:

11096

11097

RREPLACES_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>

11104

<info>

11105

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>

11110

A list of additional packages that you can suggest for

11111

installation by the package manager at the time a package

11112

is installed.

11113

Not all package managers support this functionality.

</para>

<para>

As with all package-controlling variables, you must always

11118

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>

11139

The location in the

11140

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>

11141

where unpacked recipe source code resides.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11142

By default, this directory is

11143

<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>,

11144

where <filename>${BPN}</filename> is the base recipe name

11145

and <filename>${PV}</filename> is the recipe version.

11146

If the source tarball extracts the code to a directory

11147

named anything other than <filename>${BPN}-${PV}</filename>,

11148

or if the source code if fetched from an SCM such as

11149

Git or Subversion, then you must set <filename>S</filename>

11150

in the recipe so that the OpenEmbedded build system

11151

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

11156

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

11157

top-level folder named <filename>poky</filename> and a

11158

default Build Directory at <filename>poky/build</filename>.

11159

In this case, the work directory the build system uses

11160

to keep the unpacked recipe for <filename>db</filename>

11161

is the following:

11162

11163

poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19

11164

</literallayout>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11165

The unpacked source code resides in the

11166

<filename>db-5.1.19</filename> folder.

</para>

<para>

This next example assumes a Git repository.

11171

By default, Git repositories are cloned to

11172

<filename>${WORKDIR}/git</filename> during

11173

11174

Since this path is different from the default value of

11175

<filename>S</filename>, you must set it specifically

11176

so the source can be located:

11177

11178

SRC_URI = "git://path/to/repo.git"

11179

S = "${WORKDIR}/git"

11180

</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>

11186

<info>

11187

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>

11192

Specifies a list of command-line utilities that should be

11193

checked for during the initial sanity checking process when

11194

running BitBake.

11195

If any of the utilities are not installed on the build host,

11196

then BitBake immediately exits with an error.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>

11202

<info>

11203

SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against."

</info>

11208

A list of the host distribution identifiers that the

11209

build system has been tested against.

11210

Identifiers consist of the host distributor ID

11211

followed by the release,

11212

as reported by the <filename>lsb_release</filename> tool

11213

or as read from <filename>/etc/lsb-release</filename>.

11214

Separate the list items with explicit newline

11215

characters (<filename>\n</filename>).

11216

If <filename>SANITY_TESTED_DISTROS</filename> is not empty

11217

and the current value of

11218

11219

does not appear in the list, then the build system reports

11220

a warning that indicates the current host distribution has

11221

not been tested as a build host.

</para>

</glossdef>

</glossentry>

<info>

SDK_ARCH[doc] = "The target architecture for the SDK."

</info>

11233

The target architecture for the SDK.

11234

Typically, you do not directly set this variable.

Instead, use

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>

11242

<info>

11243

SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed."

</info>

11248

The directory set up and used by the

11249

11250

to which the SDK is deployed.

11251

The <filename>populate_sdk_base</filename> class defines

11252

<filename>SDK_DEPLOY</filename> as follows:

11253

11254

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>

11267

The parent directory used by the OpenEmbedded build system

11268

when creating SDK output.

11269

The

11270

11271

class defines the variable as follows:

11272

11273

SDK_DIR = "${<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>}/sdk"

11274

</literallayout>

11275

<note>

11276

The <filename>SDK_DIR</filename> directory is a

11277

temporary directory as it is part of

11278

<filename>WORKDIR</filename>.

11279

The final output directory is

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11286

11287

<info>

11288

SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK."

</info>

11293

Controls whether or not shared state artifacts are copied

11294

into the extensible SDK.

11295

The default value of "full" copies all of the required

11296

shared state artifacts into the extensible SDK.

11297

The value "minimal" leaves these artifacts out of the

11298

SDK.

11299

<note>

11300

If you set the variable to "minimal", you need to

11301

ensure

11302

11303

is set in the SDK's configuration to enable the

11304

artifacts to be fetched as needed.

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11310

<glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm>

11311

<info>

11312

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>

11317

The manifest file for the host part of the SDK.

11318

This file lists all the installed packages that make up

11319

the host part of SDK.

11320

The file contains package information on a line-per-package

11321

basis as follows:

11322

11323

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

11331

11332

SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"

11333

</literallayout>

11334

The location is derived using the

and

variables.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11343

<glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm>

11344

<info>

11345

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>

11350

When set to "1", specifies to include the packagedata for

11351

all recipes in the "world" target in the extensible SDK.

11352

Including this data allows the

11353

<filename>devtool search</filename> command to find these

11354

recipes in search results, as well as allows the

11355

<filename>devtool add</filename> command to map

11356

dependencies more effectively.

11357

<note>

11358

Enabling the <filename>SDK_INCLUDE_PKGDATA</filename>

11359

variable significantly increases build time because

11360

all of world needs to be built.

11361

Enabling the variable also slightly increases the size

11362

of the extensible SDK.

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

11368

<glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm>

11369

<info>

11370

SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK."

</info>

11375

When set to "1", specifies to include the toolchain in the

11376

extensible SDK.

11377

Including the toolchain is useful particularly when

11378

11379

is set to "minimal" to keep the SDK reasonably small

11380

but you still want to provide a usable toolchain.

11381

For example, suppose you want to use the toolchain from an

11382

IDE (e.g. Eclipse) or from other tools and you do not

11383

want to perform additional steps to install the toolchain.

</para>

<para>

The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable

11388

defaults to "0" if <filename>SDK_EXT_TYPE</filename>

11389

is set to "minimal", and defaults to "1" if

11390

<filename>SDK_EXT_TYPE</filename> is set to "full".

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11395

<glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm>

11396

<info>

11397

SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration."

</info>

11402

A list of classes to remove from the

11403

11404

value globally within the extensible SDK configuration.

11405

The default value is "buildhistory icecc".

</para>

<para>

Some classes are not generally applicable within

11410

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>

11417

<info>

11418

SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration."

</info>

11423

A list of variables not allowed through from the build

11424

system configuration into the extensible SDK configuration.

11425

Usually, these are variables that are specific to the

11426

machine on which the build system is running and thus

11427

would be potentially problematic within the extensible SDK.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm>

11433

<info>

11434

SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration."

</info>

11439

A list of variables allowed through from the build system

11440

configuration into the extensible SDK configuration.

11441

This list overrides the variables specified using the

11442

11443

variable as well as any variables identified by automatic

11444

blacklisting due to the "/" character being found at the

11445

start of the value, which is usually indicative of being a

11446

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]

11452

11453

<info>

11454

SDK_NAME[doc] = "The base name for SDK output files."

</info>

11459

The base name for SDK output files.

11460

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>

11482

Specifies the operating system for which the SDK

11483

will be built.

11484

The default value is the value of

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>

11491

<info>

11492

SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output."

</info>

11497

The location used by the OpenEmbedded build system when

creating SDK output.

The

class defines the variable as follows:

11502

11503

SDK_OUTPUT = "${<link linkend='var-SDK_DIR'>SDK_DIR</link>}/image"

11504

</literallayout>

11505

<note>

11506

The <filename>SDK_OUTPUT</filename> directory is a

11507

temporary directory as it is part of

11508

<filename>WORKDIR</filename> by way of

11509

<filename>SDK_DIR</filename>.

11510

The final output directory is

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>

11518

<info>

11519

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>

11524

Specifies a list of architectures compatible with

11525

the SDK machine.

11526

This variable is set automatically and should not

11527

normally be hand-edited.

11528

Entries are separated using spaces and listed in order

11529

of priority.

11530

The default value for

11531

<filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch

11532

${SDK_ARCH}-${SDKPKGSUFFIX}".

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>

11538

<info>

11539

SDK_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the SDK."

</info>

11544

Specifies a list of functions to call once the

11545

OpenEmbedded build system has created the SDK.

11546

You can specify functions separated by semicolons:

11547

11548

SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass an SDK path to a command within a

11554

function, you can use

11555

<filename>${SDK_DIR}</filename>, which points to

11556

the parent directory used by the OpenEmbedded build system

11557

when creating SDK output.

11558

See the

11559

11560

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>

11566

<info>

11567

SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."

</info>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11572

The toolchain binary prefix used for

11573

<filename>nativesdk</filename> recipes.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11574

The OpenEmbedded build system uses the

11575

<filename>SDK_PREFIX</filename> value to set the

11576

11577

when building <filename>nativesdk</filename> recipes.

11578

The default value is "${SDK_SYS}-".

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11583

<glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm>

11584

<info>

11585

SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK."

</info>

11590

A list of shared state tasks added to the extensible SDK.

11591

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

11599

<filename>SDK_RECRDEP_TASKS</filename> variable, the

11600

above four tasks are always added to the SDK.

11601

To specify tasks beyond these four, you need to use

11602

the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g.

11603

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]

11610

11611

<info>

11612

SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built."

</info>

11617

Specifies the system, including the architecture and the

11618

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>

11635

<info>

11636

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>

11641

The manifest file for the target part of the SDK.

11642

This file lists all the installed packages that make up

11643

the target part of the SDK.

11644

The file contains package information on a line-per-package

11645

basis as follows:

11646

11647

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

11655

11656

SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"

11657

</literallayout>

11658

The location is derived using the

and

variables.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11667

<glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm>

11668

<info>

11669

SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation."

</info>

11674

A list of targets to install from shared state as part of

11675

the standard or extensible SDK installation.

11676

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

11682

internal variable and typically would not be changed.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm>

11688

<info>

11689

SDK_TITLE[doc] = "Specifies a title to be printed when running the SDK installer."

</info>

11694

Specifies a title to be printed when running the SDK

11695

installer.

11696

The <filename>SDK_TITLE</filename> variable defaults to

11697

"<replaceable>distro</replaceable> SDK" for the standard

11698

SDK and "<replaceable>distro</replaceable> Extensible SDK"

11699

for the extensible SDK, where

11700

<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>

11710

<info>

11711

SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK."

</info>

11716

An optional URL for an update server for the extensible

11717

SDK.

11718

If set, the value is used as the default update server when

11719

running <filename>devtool sdk-update</filename> within the

extensible SDK.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11725

<glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm>

11726

<info>

11727

SDK_VENDOR[doc] = "Specifies the name of the SDK vendor."

</info>

11732

Specifies the name of the SDK vendor.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_VERSION'><glossterm>SDK_VERSION</glossterm>

11738

<info>

11739

SDK_VERSION[doc] = "Specifies the version for the SDK."

</info>

11744

Specifies the version of the SDK.

11745

The distribution configuration file (e.g.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11746

<filename>/meta-poky/conf/distro/poky.conf</filename>)

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11747

defines the <filename>SDK_VERSION</filename> as follows:

11748

11749

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>

11764

<info>

11765

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>

11770

Equivalent to

11771

<filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.

11772

However, this variable applies to the SDK generated from an

11773

image using the following command:

11774

11775

$ bitbake -c populate_sdk <replaceable>imagename</replaceable>

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>

11782

<info>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11783

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]

11788

The machine for which the SDK is built.

11789

In other words, the SDK is built such that it

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11790

runs on the target you specify with the

11791

<filename>SDKMACHINE</filename> value.

11792

The value points to a corresponding

11793

<filename>.conf</filename> file under

11794

<filename>conf/machine-sdk/</filename>.

</para>

<para>

You can use "i686" and "x86_64" as possible values

11799

for this variable. The variable defaults to "i686"

11800

and is set in the local.conf file in the Build Directory.

SDKMACHINE ?= "i686"

</literallayout>

<note>

You cannot set the <filename>SDKMACHINE</filename>

11806

variable in your distribution configuration file.

11807

If you do, the configuration will not take affect.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>

11814

<info>

11815

SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system."

</info>

11820

Defines the path offered to the user for installation

11821

of the SDK that is generated by the OpenEmbedded build

11822

system.

11823

The path appears as the default location for installing

11824

the SDK when you run the SDK's installation script.

11825

You can override the offered path when you run the

script.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm>

11832

<info>

11833

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>

11838

The full path to the sysroot used for cross-compilation

11839

within an SDK as it will be when installed into the

default

</para>

</glossdef>

</glossentry>

<glossentry id='var-SECTION'><glossterm>SECTION</glossterm>

11847

<info>

11848

SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable."

</info>

11853

The section in which packages should be categorized.

11854

Package management utilities can make use of this variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>

11860

<info>

11861

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>

11866

Specifies the optimization flags passed to the C compiler

11867

when building for the target.

11868

The flags are passed through the default value of the

variable.

</para>

<para>

The <filename>SELECTED_OPTIMIZATION</filename> variable

11875

takes the value of

11876

<filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>

11877

unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".

11878

If that is the case, the value of

11879

<filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>

11885

<info>

11886

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>

11891

Defines a serial console (TTY) to enable using getty.

11892

Provide a value that specifies the baud rate followed by

11893

the TTY device name separated by a space.

11894

You cannot specify more than one TTY device:

11895

11896

SERIAL_CONSOLE = "115200 ttyS0"

11897

</literallayout>

11898

<note>

11899

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>

11910

<info>

11911

SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty."

</info>

11916

Defines the serial consoles (TTYs) to enable using getty.

11917

Provide a value that specifies the baud rate followed by

11918

the TTY device name separated by a semicolon.

11919

Use spaces to separate multiple devices:

11920

11921

SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>

11928

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

11929

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]

11934

Specifies serial consoles, which must be listed in

11935

11936

to check against <filename>/proc/console</filename>

11937

before enabling them using getty.

11938

This variable allows aliasing in the format:

11939

<device>:<alias>.

11940

If a device was listed as "sclp_line0"

11941

in <filename>/dev/</filename> and "ttyS0" was listed

11942

in <filename>/proc/console</filename>, you would do the

11943

following:

11944

11945

SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"

11946

</literallayout>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11947

This variable is currently only supported with SysVinit

11948

(i.e. not with systemd).

</para>

</glossdef>

</glossentry>

<glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>

11954

<info>

11955

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>

11960

A list of recipe dependencies that should not be used to

11961

determine signatures of tasks from one recipe when they

11962

depend on tasks from another recipe.

11963

For example:

11964

11965

SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"

</literallayout>

</para>

<para>

In this example, <filename>intone</filename> depends on

11971

<filename>mplayer2</filename>.

</para>

<para>

Use of this variable is one mechanism to remove dependencies

11976

that affect task signatures and thus force rebuilds when a

11977

recipe changes.

11978

<note><title>Caution</title>

11979

If you add an inappropriate dependency for a recipe

11980

relationship, the software might break during

11981

runtime if the interface of the second recipe was

11982

changed after the first recipe had been built.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>

11989

<info>

11990

SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change."

</info>

11995

A list of recipes that are completely stable and will

11996

never change.

11997

The ABI for the recipes in the list are presented by

11998

output from the tasks run to build the recipe.

11999

Use of this variable is one way to remove dependencies from

12000

one recipe on another that affect task signatures and

12001

thus force rebuilds when the recipe changes.

12002

<note><title>Caution</title>

12003

If you add an inappropriate variable to this list,

12004

the software might break at runtime if the

12005

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>

12013

<info>

12014

SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU."

</info>

12019

Specifies the number of bits for the target system CPU.

12020

The value should be either "32" or "64".

</para>

</glossdef>

</glossentry>

<glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>

12026

<info>

12027

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>

12032

Specifies the endian byte order of the target system.

12033

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]

12038

<glossentry id='var-SKIP_FILEDEPS'><glossterm>SKIP_FILEDEPS</glossterm>

12039

<info>

12040

SKIP_FILEDEPS[doc] = "Enables you to remove all files from

12041

the "Provides" section of an RPM package."

</info>

12046

Enables removal of all files from the "Provides" section of

12047

an RPM package.

12048

Removal of these files is required for packages containing

12049

prebuilt binaries and libraries such as

12050

<filename>libstdc++</filename> and

12051

<filename>glibc</filename>.

</para>

<para>

To enable file removal, set the variable to "1" in your

12056

<filename>conf/local.conf</filename> configuration file

12057

in your:

12058

<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]

12066

<glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>

12067

<info>

12068

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>

12073

Groups together machines based upon the same family

12074

of SOC (System On Chip).

12075

You typically set this variable in a common

12076

<filename>.inc</filename> file that you include in the

12077

configuration files of all the machines.

12078

<note>

12079

You must include

12080

<filename>conf/machine/include/soc-family.inc</filename>

12081

for this variable to appear in

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>

12089

<info>

12090

SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform."

</info>

12095

Defines the suffix for shared libraries used on the

12096

target platform.

12097

By default, this suffix is ".so.*" for all Linux-based

12098

systems and is defined in the

12099

<filename>meta/conf/bitbake.conf</filename> configuration

file.

</para>

<para>

You will see this variable referenced in the default values

12105

of <filename>FILES_${PN}</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>

12111

<info>

12112

SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform."

</info>

12117

Defines the suffix for the development symbolic link

12118

(symlink) for shared libraries on the target platform.

12119

By default, this suffix is ".so" for Linux-based

12120

systems and is defined in the

12121

<filename>meta/conf/bitbake.conf</filename> configuration

file.

</para>

<para>

You will see this variable referenced in the default values

12127

of <filename>FILES_${PN}-dev</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm>

12133

<info>

12134

SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks."

</info>

12139

When you are fetching files to create a mirror of sources

12140

(i.e. creating a source mirror), setting

12141

<filename>SOURCE_MIRROR_FETCH</filename> to "1" in your

12142

<filename>local.conf</filename> configuration file ensures

12143

the source for all recipes are fetched regardless of

12144

whether or not a recipe is compatible with the

12145

configuration.

12146

A recipe is considered incompatible with the currently

12147

configured machine when either or both the

variable and

variables specify compatibility with a machine other

12152

than that of the current machine or host.

12153

<note><title>Warning</title>

12154

Do not set the

12155

<filename>SOURCE_MIRROR_FETCH</filename> variable

12156

unless you are creating a source mirror.

12157

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>

12165

<info>

12166

SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI."

</info>

12171

Defines your own

12172

12173

from which to first fetch source before attempting to fetch

12174

from the upstream specified in

</para>

<para>

To use this variable, you must globally inherit the

12180

12181

class and then provide the URL to your mirrors.

12182

Here is the general syntax:

12183

12184

INHERIT += "own-mirrors"

12185

SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>"

12186

</literallayout>

12187

<note>

12188

You can specify only a single URL in

12189

<filename>SOURCE_MIRROR_URL</filename>.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>

12196

<info>

12197

SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/."

</info>

12202

Maps commonly used license names to their SPDX counterparts

12203

found in <filename>meta/files/common-licenses/</filename>.

12204

For the default <filename>SPDXLICENSEMAP</filename>

12205

mappings, see the

12206

<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>

12218

<info>

12219

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>

12224

A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the

12225

OpenEmbedded build system to create variants of recipes or packages.

12226

The list specifies the prefixes to strip off during certain circumstances

12227

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>

12239

The list of source files - local or remote.

12240

This variable tells the OpenEmbedded build system which bits

12241

to pull in for the build and how to pull them in.

12242

For example, if the recipe or append file only needs to

12243

fetch a tarball from the Internet, the recipe or

12244

append file uses a single <filename>SRC_URI</filename>

12245

entry.

12246

On the other hand, if the recipe or append file needs to

12247

fetch a tarball, apply two patches, and include a custom

12248

file, the recipe or append file would include four

12249

instances of the variable.

12250

</para>

12251

12252

<para>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12253

The following list explains the available URI protocols.

12254

URI protocols are highly dependent on particular BitBake

12255

Fetcher submodules.

12256

Depending on the fetcher BitBake uses, various URL

12257

parameters are employed.

12258

For specifics on the supported Fetchers, see the

12259

"<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"

12260

section in the BitBake User Manual.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12261

12262

12263

Fetches files, which are usually files shipped with

12264

the

12265

<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,

12266

from the local machine.

12267

The path is relative to the

12268

12269

variable.

12270

Thus, the build system searches, in order, from the

12271

following directories, which are assumed to be a

12272

subdirectories of the directory in which the

12273

recipe file (<filename>.bb</filename>) or

12274

append file (<filename>.bbappend</filename>)

resides:

The base recipe name without any special

12279

suffix or version numbers.

12280

</para></listitem>

12281

12282

<filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.

12283

The base recipe name and version but without

12284

any special package name suffix.

12285

</para></listitem>

12286

<listitem><para><emphasis>files -</emphasis>

12287

Files within a directory, which is named

12288

<filename>files</filename> and is also

12289

alongside the recipe or append file.

</para></listitem>

</itemizedlist>

<note>

If you want the build system to pick up files

12294

specified through a

12295

12296

statement from your append file, you need to be

12297

sure to extend the

12298

<filename>FILESPATH</filename>

12299

variable by also using the

12300

12301

variable from within your append file.

12302

</note>

12303

</para></listitem>

12304

<listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a

12305

Bazaar revision control repository.</para></listitem>

12306

<listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a

12307

Git revision control repository.</para></listitem>

12308

<listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from

12309

an OSC (OpenSUSE Build service) revision control repository.</para></listitem>

12310

<listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from

12311

a repo (Git) repository.</para></listitem>

12312

12313

Fetches files from a ClearCase repository.

12314

</para></listitem>

12315

<listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from

12316

the Internet using <filename>http</filename>.</para></listitem>

12317

<listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files

12318

from the Internet using <filename>https</filename>.</para></listitem>

12319

<listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files

12320

from the Internet using <filename>ftp</filename>.</para></listitem>

12321

<listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from

12322

a CVS revision control repository.</para></listitem>

12323

<listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from

12324

a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>

12325

<listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from

12326

a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>

12327

<listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from

12328

a secure shell.</para></listitem>

12329

<listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from

12330

a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>

</itemizedlist>

</para>

<para>

Standard and recipe-specific options for <filename>SRC_URI</filename> exist.

12336

Here are standard options:

12337

12338

<listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply

12339

the patch or not.

12340

The default action is to apply the patch.</para></listitem>

12341

<listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which

12342

striplevel to use when applying the patch.

12343

The default level is 1.</para></listitem>

12344

<listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies

12345

the directory in which the patch should be applied.

12346

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:

12353

12354

<listitem><para><emphasis><filename>mindate</filename> -</emphasis>

12355

Apply the patch only if

12356

12357

is equal to or greater than <filename>mindate</filename>.

12358

</para></listitem>

12359

<listitem><para><emphasis><filename>maxdate</filename> -</emphasis>

12360

Apply the patch only if <filename>SRCDATE</filename>

12361

is not later than <filename>mindate</filename>.

12362

</para></listitem>

12363

<listitem><para><emphasis><filename>minrev</filename> -</emphasis>

12364

Apply the patch only if <filename>SRCREV</filename>

12365

is equal to or greater than <filename>minrev</filename>.

12366

</para></listitem>

12367

<listitem><para><emphasis><filename>maxrev</filename> -</emphasis>

12368

Apply the patch only if <filename>SRCREV</filename>

12369

is not later than <filename>maxrev</filename>.

12370

</para></listitem>

12371

12372

Apply the patch only if <filename>SRCREV</filename>

12373

is equal to <filename>rev</filename>.

12374

</para></listitem>

12375

<listitem><para><emphasis><filename>notrev</filename> -</emphasis>

12376

Apply the patch only if <filename>SRCREV</filename>

12377

is not equal to <filename>rev</filename>.

</para></listitem>

</itemizedlist>

</para>

<para>

Here are some additional options worth mentioning:

12384

12385

<listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls

12386

whether or not to unpack the file if it is an archive.

12387

The default action is to unpack the file.</para></listitem>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12388

<listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file

12389

(or extracts its contents) into the specified

12390

subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

12391

when the Git fetcher is used.

12392

</para></listitem>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12393

<listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file

12394

(or extracts its contents) into the specified

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12395

subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

12396

when the local (<filename>file://</filename>)

12397

fetcher is used.

12398

</para></listitem>

12399

<listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file

12400

(or extracts its contents) into the specified

12401

subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

12402

when the CVS fetcher is used.

12403

</para></listitem>

12404

<listitem><para><emphasis><filename>subpath</filename> -</emphasis>

12405

Limits the checkout to a specific subpath of the

12406

tree when using the Git fetcher is used.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12407

</para></listitem>

12408

<listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a

12409

name to be used for association with <filename>SRC_URI</filename> checksums

12410

when you have more than one file specified in <filename>SRC_URI</filename>.

12411

</para></listitem>

12412

<listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies

12413

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>

12420

<info>

12421

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>

12426

By default, the OpenEmbedded build system automatically detects whether

12427

12428

contains files that are machine-specific.

12429

If so, the build system automatically changes

12430

<filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.

12431

Setting this variable to "0" disables this behavior.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>

12437

<info>

12438

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>

12443

The date of the source code used to build the package.

12444

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>

12450

<info>

12451

SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV."

</info>

12456

Returns the version string of the current package.

12457

This string is used to help define the value of

</para>

<para>

The <filename>SRCPV</filename> variable is defined in the

12463

<filename>meta/conf/bitbake.conf</filename> configuration

12464

file in the

12465

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

12466

as follows:

12467

12468

SRCPV = "${@bb.fetch2.get_srcrev(d)}"

</literallayout>

</para>

<para>

Recipes that need to define <filename>PV</filename> do so

12474

with the help of the <filename>SRCPV</filename>.

12475

For example, the <filename>ofono</filename> recipe

12476

(<filename>ofono_git.bb</filename>) located in

12477

<filename>meta/recipes-connectivity</filename> in the

12478

Source Directory defines <filename>PV</filename> as

12479

follows:

12480

12481

PV = "0.12-git${SRCPV}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>

12488

<info>

12489

SRCREV[doc] = "The revision of the source code used to build the package. This variable applies to Subversion, Git, Mercurial and Bazaar only."

</info>

12494

The revision of the source code used to build the package.

12495

This variable applies to Subversion, Git, Mercurial and

12496

Bazaar only.

12497

Note that if you want to build a fixed revision and you

12498

want to avoid performing a query on the remote repository

12499

every time BitBake parses your recipe, you should specify

12500

a <filename>SRCREV</filename> that is a

12501

full revision identifier and not just a tag.

</para>

<note>

For information on limitations when inheriting the latest

12506

revision of software using <filename>SRCREV</filename>,

12507

see the

12508

12509

variable description.

</note>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>

12515

<info>

12516

SSTATE_DIR[doc] = "The directory for the shared state cache."

</info>

12521

The directory for the shared state cache.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>

12527

<info>

12528

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>

12533

If set to "1", allows fetches from

12534

mirrors that are specified in

12535

12536

to work even when fetching from the network has been

12537

disabled by setting <filename>BB_NO_NETWORK</filename>

12538

to "1".

12539

Using the

12540

<filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>

12541

variable is useful if you have set

12542

<filename>SSTATE_MIRRORS</filename> to point to an

12543

internal server for your shared state cache, but

12544

you want to disable any other fetching from the network.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>

12550

<info>

12551

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>

12556

Configures the OpenEmbedded build system to search other

12557

mirror locations for prebuilt cache data objects before

12558

building out the data.

12559

This variable works like fetcher

12560

12561

and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>

12562

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

12568

as HTTP or FTP.

12569

The locations you specify need to contain the shared state

12570

cache (sstate-cache) results from previous builds.

12571

The sstate-cache you point to can also be from builds on

other machines.

</para>

<para>

If a mirror uses the same structure as

12577

12578

you need to add

12579

"PATH" at the end as shown in the examples below.

12580

The build system substitutes the correct path within the

12581

directory structure.

12582

12583

SSTATE_MIRRORS ?= "\

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12584

file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12585

file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>

12592

<info>

12593

STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host."

</info>

12598

Specifies the path to the <filename>/lib</filename>

12599

subdirectory of the sysroot directory for the

build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>

12606

<info>

12607

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>

12612

Specifies the path to the <filename>/lib</filename>

12613

subdirectory of the sysroot directory for the target

12614

for which the current recipe is being built

12615

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>

12621

<info>

12622

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>

12627

Specifies the path to the

12628

<filename>/usr/bin</filename> subdirectory of the

12629

sysroot directory for the target for which the current

12630

recipe is being built

12631

(<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>

12637

<info>

12638

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>

12643

Specifies the path to the directory containing binary

12644

configuration scripts.

12645

These scripts provide configuration information for

12646

other software that wants to make use of libraries or

12647

include files provided by the software associated with

12648

the script.

12649

<note>

12650

This style of build configuration has been largely

12651

replaced by <filename>pkg-config</filename>.

12652

Consequently, if <filename>pkg-config</filename>

12653

is supported by the library to which you are linking,

12654

it is recommended you use

12655

<filename>pkg-config</filename> instead of a

12656

provided configuration script.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>

12663

<info>

12664

STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host."

</info>

12669

Specifies the path to the

12670

<filename>/usr/bin</filename> subdirectory of the

12671

sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>

12677

<info>

12678

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>

12683

Specifies the path to the <filename>/usr/share</filename>

12684

subdirectory of the sysroot directory for the target

12685

for which the current recipe is being built

12686

(<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>

12692

<info>

12693

STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host."

</info>

12698

Specifies the path to the <filename>/usr/share</filename>

12699

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>

12705

<info>

12706

STAGING_DIR[doc] = "Specifies the path to the top-level sysroots directory (i.e. ${TMPDIR}/sysroots)."

</info>

12711

Specifies the path to the top-level sysroots directory

12712

(i.e.

12713

<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

12718

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>"

12725

section for more information.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12726

<note>

12727

Recipes should never write files directly under

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

12728

the <filename>STAGING_DIR</filename> directory because

12729

the OpenEmbedded build system

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12730

manages the directory automatically.

12731

Instead, files should be installed to

within your recipe's

task and then the OpenEmbedded build system will

12736

stage a subset of those files into the sysroot.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>

12743

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12744

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]

12749

Specifies the path to the sysroot directory for the system

12750

that the component is built to run on (the system that hosts

12751

the component).

12752

For most recipes, this sysroot is the one that the recipe's

12753

12754

task copies files into.

12755

Exceptions include <filename>-native</filename> recipes,

12756

where the <filename>do_populate_sysroot</filename> task

12757

instead uses

12758

12759

Depending on the type of recipe and the build target,

12760

<filename>STAGING_DIR_HOST</filename> can have the

12761

following values:

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12762

12763

<listitem><para>For recipes building for the target

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12764

machine, the value is

12765

"${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".

12766

</para></listitem>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

12767

<listitem><para>For native recipes building

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12768

for the build host, the value is empty given the

12769

assumption that when building for the build host,

12770

the build host's own directories should be used.

12771

12772

<filename>-native</filename> recipes are not

12773

installed into host paths like such as

12774

<filename>/usr</filename>.

12775

Rather, these recipes are installed into

12776

<filename>STAGING_DIR_NATIVE</filename>.

12777

When compiling <filename>-native</filename>

12778

recipes, standard build environment variables

such as

and

are set up so that both host paths and

12784

<filename>STAGING_DIR_NATIVE</filename> are

12785

searched for libraries and headers using, for

12786

example, GCC's <filename>-isystem</filename>

12787

option.</para>

12788

12789

<para>This emphasizes that the

12790

<filename>STAGING_DIR*</filename> variables

12791

should be viewed as input variables by tasks

such as

and

Having the real system root correspond to

12798

<filename>STAGING_DIR_HOST</filename> makes

12799

conceptual sense for

12800

<filename>-native</filename> recipes, as

12801

they make use of host headers and libraries.

12802

</para>

12803

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12804

</para></listitem>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

12805

<listitem><para>For native SDK

12806

recipes that build for the SDK

12807

(<filename>nativesdk</filename>), the value is

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12808

"${STAGING_DIR}/${<link linkend='var-MULTIMACH_HOST_SYS'>MULTIMACH_HOST_SYS</link>}".

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>

12816

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12817

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]

12822

Specifies the path to the sysroot directory used when

12823

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>

12829

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12830

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]

12835

Specifies the path to the sysroot used for the system for

12836

which the component generates code.

12837

For components that do not generate code, which is the

12838

majority, <filename>STAGING_DIR_TARGET</filename> is set

12839

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

12845

system but those binaries in turn generate code for

12846

another different system (e.g. cross-canadian recipes).

12847

Using terminology from GNU, the primary system is referred

12848

to as the "HOST" and the secondary, or different, system is

12849

referred to as the "TARGET".

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12850

Thus, the binaries run on the "HOST" system

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12851

and generate binaries for the "TARGET" system.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12852

The <filename>STAGING_DIR_HOST</filename> variable points

12853

to the sysroot used for the "HOST" system, while

12854

<filename>STAGING_DIR_TARGET</filename>

12855

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>

12861

<info>

12862

STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host."

</info>

12867

Specifies the path to the <filename>/etc</filename>

12868

subdirectory of the sysroot directory for the

build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>

12875

<info>

12876

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>

12881

Specifies the path to the <filename>/usr</filename>

12882

subdirectory of the sysroot directory for the target

12883

for which the current recipe is being built

12884

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>

12890

<info>

12891

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>

12896

Specifies the path to the

12897

<filename>/usr/include</filename> subdirectory of the

12898

sysroot directory for the target for which the current

12899

recipe being built

12900

(<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>

12906

<info>

12907

STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host."

</info>

12912

Specifies the path to the <filename>/usr/include</filename>

12913

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12918

<glossentry id='var-STAGING_KERNEL_BUILDDIR'><glossterm>STAGING_KERNEL_BUILDDIR</glossterm>

12919

<info>

12920

STAGING_KERNEL_BUILDDIR[doc] = "Points to the directory containing the kernel build artifacts."

</info>

12925

Points to the directory containing the kernel build

12926

artifacts.

12927

Recipes building software that needs to access kernel

12928

build artifacts

12929

(e.g. <filename>systemtap-uprobes</filename>) can look in

12930

the directory specified with the

12931

<filename>STAGING_KERNEL_BUILDDIR</filename> variable to

12932

find these artifacts after the kernel has been built.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12937

<glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>

12938

<info>

12939

STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules."

</info>

12944

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>

12951

<info>

12952

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>

12957

Specifies the path to the <filename>/usr/lib</filename>

12958

subdirectory of the sysroot directory for the target for

12959

which the current recipe is being built

12960

(<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>

12966

<info>

12967

STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host."

</info>

12972

Specifies the path to the <filename>/usr/lib</filename>

12973

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAMP'><glossterm>STAMP</glossterm>

12979

<info>

12980

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>

12985

Specifies the base path used to create recipe stamp files.

12986

The path to an actual stamp file is constructed by evaluating this

12987

string and then appending additional information.

12988

Currently, the default assignment for <filename>STAMP</filename>

12989

as set in the <filename>meta/conf/bitbake.conf</filename> file

12990

is:

12991

12992

STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"

</literallayout>

</para>

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12997

For information on how BitBake uses stamp files to determine

12998

if a task should be rerun, see the

12999

"<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]

13004

See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,

information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>

13016

<info>

13017

STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps."

</info>

13022

Specifies the base directory in which the OpenEmbedded

13023

build system places stamps.

13024

The default directory is

13025

<filename>${TMPDIR}/stamps</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STRIP'><glossterm>STRIP</glossterm>

13031

<info>

13032

STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)."

</info>

13037

The minimal command and arguments to run

13038

<filename>strip</filename>, which is used to strip

symbols.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>

13045

<info>

13046

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>

13051

The short (72 characters or less) summary of the binary package for packaging

13052

systems such as <filename>opkg</filename>, <filename>rpm</filename> or

13053

<filename>dpkg</filename>.

13054

By default, <filename>SUMMARY</filename> is used to define

13055

the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>

13056

variable if <filename>DESCRIPTION</filename> is not set

in the recipe.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>

13063

<info>

13064

SVNDIR[doc] = "The directory where Subversion checkouts will be stored."

</info>

13069

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>

13076

<info>

13077

SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console."

</info>

13082

Specifies the kernel boot default console.

13083

If you want to use a console other than the default,

13084

set this variable in your recipe as follows where "X" is

13085

the console number you want to use:

13086

13087

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>

13101

<info>

13102

SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file."

</info>

13107

Lists additional options to add to the syslinux file.

13108

You need to set this variable in your recipe.

13109

If you want to list multiple options, separate the options

13110

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>

13122

<info>

13123

SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off."

</info>

13128

Specifies the alternate serial port or turns it off.

13129

To turn off serial, set this variable to an empty string

13130

in your recipe.

13131

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>

13146

<info>

13147

SYSLINUX_SPLASH[doc] = "An .LSS file used as the background for the VGA boot menu when you are using the boot menu."

</info>

13152

An <filename>.LSS</filename> file used as the background

13153

for the VGA boot menu when you are using the boot menu.

13154

You need to set this variable in your recipe.

</para>

<para>

The

class checks for this variable and if found, the

13161

OpenEmbedded build system installs the splash screen.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>

13167

<info>

13168

SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument."

</info>

13173

Specifies the alternate console=tty... kernel boot argument.

13174

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>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

13188

<glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>

13189

<info>

13190

SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task."

</info>

13195

Directories that are staged into the sysroot by the

13196

13197

task.

13198

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>

13213

<info>

13214

SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task."

</info>

13219

Directories that are not staged into the sysroot by the

13220

13221

task.

13222

You can use this variable to exclude certain subdirectories

13223

of directories listed in

13224

13225

from staging.

13226

By default, the following directories are not staged:

13227

13228

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>

13243

<info>

13244

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>

13249

Extra directories staged into the sysroot by the

13250

13251

task for <filename>-native</filename> recipes, in addition

13252

to those specified in

13253

13254

By default, the following extra directories are staged:

13255

13256

SYSROOT_DIRS_NATIVE = " \

${bindir} \

${sbindir} \

${base_bindir} \

${base_sbindir} \

${libexecdir} \

${sysconfdir} \

${localstatedir} \

"

</literallayout>

<note>

Programs built by <filename>-native</filename> recipes

13268

run directly from the sysroot

13269

(<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>),

13270

which is why additional directories containing program

13271

executables and supporting files need to be staged.

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13277

<glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>

13278

<info>

13279

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>

13284

A list of functions to execute after files are staged into

13285

the sysroot.

13286

These functions are usually used to apply additional

13287

processing on the staged files, or to stage additional

files.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>

13294

<info>

13295

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>

13300

When inheriting the

13301

13302

class, this variable specifies whether the service you have

13303

specified in

13304

13305

should be started automatically or not.

13306

By default, the service is enabled to automatically start

13307

at boot time.

13308

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]

13323

<glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm>

13324

<info>

13325

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>

13330

When

13331

13332

is set to "systemd-boot", the

13333

<filename>SYSTEMD_BOOT_CFG</filename> variable specifies the

13334

configuration file that should be used.

13335

By default, the

13336

13337

class sets the <filename>SYSTEMD_BOOT_CFG</filename> as

13338

follows:

13339

13340

SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf"

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

13346

<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>

13352

<info>

13353

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>

13358

When

13359

13360

is set to "systemd-boot", the

13361

<filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies

13362

a list of entry files

13363

(<filename>*.conf</filename>) to be installed

13364

containing one boot entry per file.

13365

By default, the

13366

13367

class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as

13368

follows:

13369

13370

SYSTEMD_BOOT_ENTRIES ?= ""

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

13376

<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>

13382

<info>

13383

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>

13388

When

13389

13390

is set to "systemd-boot", the

13391

<filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies

13392

the boot menu timeout in seconds.

13393

By default, the

13394

13395

class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as

13396

follows:

13397

13398

SYSTEMD_BOOT_TIMEOUT ?= "10"

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

13404

<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]

13409

<glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>

13410

<info>

13411

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>

13416

When inheriting the

13417

13418

class, this variable locates the systemd unit files when

13419

they are not found in the main recipe's package.

13420

By default, the

13421

<filename>SYSTEMD_PACKAGES</filename> variable is set

13422

such that the systemd unit files are assumed to reside in

13423

the recipes main package:

13424

13425

SYSTEMD_PACKAGES ?= "${PN}"

</literallayout>

</para>

<para>

If these unit files are not in this recipe's main

13431

package, you need to use

13432

<filename>SYSTEMD_PACKAGES</filename> to list the package

13433

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>

13440

<info>

13441

SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package."

</info>

13446

When inheriting the

13447

13448

class, this variable specifies the systemd service name for

a package.

</para>

<para>

When you specify this file in your recipe, use a package

13454

name override to indicate the package to which the value

13455

applies.

13456

Here is an example from the connman recipe:

13457

13458

SYSTEMD_SERVICE_${PN} = "connman.service"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>

13465

<info>

13466

SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should be running a getty, the default is '1'."

</info>

13471

When using

13472

<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,

13473

specifies a space-separated list of the virtual terminals

13474

that should be running a

13475

<ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>

13476

(allowing login), assuming

is not set to "0".

</para>

<para>

The default value for

13483

<filename>SYSVINIT_ENABLED_GETTYS</filename> is "1"

13484

(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>

13500

This variable points to a directory were BitBake places

13501

temporary files, which consist mostly of task logs and

13502

scripts, when building a particular recipe.

13503

The variable is typically set as follows:

13504

13505

T = "${WORKDIR}/temp"

</literallayout>

</para>

<para>

The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

13511

is the directory into which BitBake unpacks and builds the

13512

recipe.

13513

The default <filename>bitbake.conf</filename> file sets this variable.</para>

13514

<para>The <filename>T</filename> variable is not to be confused with

13515

the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,

13516

which points to the root of the directory tree where BitBake

13517

places the output of an entire build.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>

13523

<info>

13524

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>

13529

The target machine's architecture.

13530

The OpenEmbedded build system supports many

13531

architectures.

13532

Here is an example list of architectures supported.

13533

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>

13556

<info>

13557

TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system."

</info>

13562

Specifies architecture-specific assembler flags for the

13563

target system.

13564

<filename>TARGET_AS_ARCH</filename> is initialized from

13565

13566

by default in the BitBake configuration file

13567

(<filename>meta/conf/bitbake.conf</filename>):

13568

13569

TARGET_AS_ARCH = "${TUNE_ASARGS}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>

13576

<info>

13577

TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system."

</info>

13582

Specifies architecture-specific C compiler flags for the

13583

target system.

13584

<filename>TARGET_CC_ARCH</filename> is initialized from

by default.

<note>

It is a common workaround to append

13589

13590

to <filename>TARGET_CC_ARCH</filename>

13591

in recipes that build software for the target that

13592

would not otherwise respect the exported

13593

<filename>LDFLAGS</filename> variable.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>

13600

<info>

13601

TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune."

</info>

13606

This is a specific kernel compiler flag for a CPU or

13607

Application Binary Interface (ABI) tune.

13608

The flag is used rarely and only for cases where a

13609

userspace

13610

13611

is not compatible with the kernel compilation.

13612

The <filename>TARGET_CC_KERNEL_ARCH</filename> variable

13613

allows the kernel (and associated modules) to use a

13614

different configuration.

13615

See the

13616

<filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>

13617

file in the

13618

<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>

13625

<info>

13626

TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS."

</info>

13631

Specifies the flags to pass to the C compiler when building

13632

for the target.

13633

When building in the target context,

13634

13635

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

13640

the

13641

13642

variable in the environment to the

13643

<filename>TARGET_CFLAGS</filename> value so that

13644

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>

13651

<info>

13652

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>

13657

Specifies the flags to pass to the C pre-processor

13658

(i.e. to both the C and the C++ compilers) when building

13659

for the target.

13660

When building in the target context,

13661

13662

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

13667

the

13668

13669

variable in the environment to the

13670

<filename>TARGET_CPPFLAGS</filename> value so that

13671

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>

13678

<info>

13679

TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target."

</info>

13684

Specifies the flags to pass to the C++ compiler when

13685

building for the target.

13686

When building in the target context,

13687

13688

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

13693

the

13694

13695

variable in the environment to the

13696

<filename>TARGET_CXXFLAGS</filename> value so that

13697

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>

13704

<info>

13705

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>

13710

Specifies the method for handling FPU code.

13711

For FPU-less targets, which include most ARM CPUs, the variable must be

13712

set to "soft".

13713

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>

13719

<info>

13720

TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system."

</info>

13725

Specifies architecture-specific linker flags for the

13726

target system.

13727

<filename>TARGET_LD_ARCH</filename> is initialized from

13728

13729

by default in the BitBake configuration file

13730

(<filename>meta/conf/bitbake.conf</filename>):

13731

13732

TARGET_LD_ARCH = "${TUNE_LDARGS}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>

13739

<info>

13740

TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target."

</info>

13745

Specifies the flags to pass to the linker when building

13746

for the target.

13747

When building in the target context,

13748

13749

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

13754

the

13755

13756

variable in the environment to the

13757

<filename>TARGET_LDFLAGS</filename> value so that

13758

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>

13765

<info>

13766

TARGET_OS[doc] = "Specifies the target's operating system."

</info>

13771

Specifies the target's operating system.

13772

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^]

13773

to "linux-musl" for <filename>musl</filename>.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13774

For ARM/EABI targets, there are also "linux-gnueabi" and

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

13775

"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>

13781

<info>

13782

TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools."

</info>

13787

Specifies the prefix used for the toolchain binary target

tools.

</para>

<para>

Depending on the type of recipe and the build target,

13793

<filename>TARGET_PREFIX</filename> is set as follows:

13794

13795

13796

For recipes building for the target machine,

13797

the value is

13798

"${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".

13799

</para></listitem>

13800

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

13801

For native recipes, the build system sets the

13802

variable to the value of

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13803

<filename>BUILD_PREFIX</filename>.

13804

</para></listitem>

13805

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

13806

For native SDK recipes

13807

(<filename>nativesdk</filename>), the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13808

build system sets the variable to the value of

13809

<filename>SDK_PREFIX</filename>.

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm>

13817

<info>

13818

TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."

</info>

13823

Specifies the system, including the architecture and the

13824

operating system, for which the build is occurring in

13825

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

13838

<filename>TARGET_SYS</filename> variable yourself.

</note>

</para>

<para>

Consider these two examples:

13844

13845

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

13846

Given a native recipe on a 32-bit, x86 machine

13847

running Linux, the value is "i686-linux".

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13848

</para></listitem>

13849

13850

Given a recipe being built for a little-endian,

13851

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>

13860

<info>

13861

TARGET_VENDOR[doc] = "The name of the target vendor."

</info>

13866

Specifies the name of the target vendor.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm>

13872

<info>

13873

TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."

</info>

13878

Specifies a suffix to be appended onto the

13879

13880

value.

13881

The suffix identifies the <filename>libc</filename> variant

13882

for building.

13883

When you are building for multiple variants with the same

13884

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,

13885

this mechanism ensures that output for different

13886

<filename>libc</filename> variants is kept separate to

13887

avoid potential conflicts.

</para>

<para>

In the <filename>defaultsetup.conf</filename> file, the

13892

default value of <filename>TCLIBCAPPEND</filename> is

13893

"-${TCLIBC}".

13894

However, distros such as poky, which normally only support

13895

one <filename>libc</filename> variant, set

13896

<filename>TCLIBCAPPEND</filename> to "" in their distro

13897

configuration file resulting in no suffix being applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>

13903

<info>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

13904

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>

13909

Specifies the GNU standard C library (<filename>libc</filename>)

13910

variant to use during the build process.

13911

This variable replaces <filename>POKYLIBC</filename>, which is no longer

supported.

</para>

<para>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

13916

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>

13922

<info>

13923

TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'."

</info>

13928

Specifies the toolchain selector.

13929

<filename>TCMODE</filename> controls the characteristics

13930

of the generated packages and images by telling the

13931

OpenEmbedded build system which toolchain profile to use.

13932

By default, the OpenEmbedded build system builds its own

13933

internal toolchain.

13934

The variable's default value is "default", which uses

13935

that internal toolchain.

13936

<note>

13937

If <filename>TCMODE</filename> is set to a value

13938

other than "default", then it is your responsibility

13939

to ensure that the toolchain is compatible with the

13940

default toolchain.

13941

Using older or newer versions of these components

13942

might cause build problems.

13943

See the

13944

<ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>

13945

for the specific components with which the toolchain

must be compatible.

</note>

</para>

<para>

The <filename>TCMODE</filename> variable is similar to

13952

13953

which controls the variant of the GNU standard C library

13954

(<filename>libc</filename>) used during the build process:

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

13955

<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

13960

external toolchain.

13961

One example is the Sourcery G++ Toolchain.

13962

The support for this toolchain resides in the separate

13963

<trademark class='registered'>Mentor Graphics</trademark>

13964

<filename>meta-sourcery</filename> layer at

13965

<ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.

</para>

<para>

The layer's <filename>README</filename> file contains

13970

information on how to use the Sourcery G++ Toolchain as

13971

an external toolchain.

13972

In summary, you must be sure to add the layer to your

13973

<filename>bblayers.conf</filename> file in front of the

13974

<filename>meta</filename> layer and then set the

13975

<filename>EXTERNAL_TOOLCHAIN</filename>

13976

variable in your <filename>local.conf</filename> file

13977

to the location in which you installed the toolchain.

</para>

<para>

The fundamentals used for this example apply to any

13982

external toolchain.

13983

You can use <filename>meta-sourcery</filename> as a

13984

template for adding support for other external toolchains.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>

13990

<info>

13991

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>

13996

The location the OpenEmbedded build system uses to export

13997

tests when the

13998

13999

variable is set to "1".

</para>

<para>

The <filename>TEST_EXPORT_DIR</filename> variable defaults

14004

to <filename>"${TMPDIR}/testimage/${PN}"</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>

14010

<info>

14011

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>

14016

Specifies to export the tests only.

14017

Set this variable to "1" if you do not want to run the

14018

tests but you want them to be exported in a manner that

14019

you to run them outside of the build system.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>

14025

<info>

14026

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>

14031

Automatically runs the series of automated tests for

14032

images when an image is successfully built.

</para>

<para>

These tests are written in Python making use of the

14037

<filename>unittest</filename> module, and the majority of

14038

them run commands on the target system over

14039

<filename>ssh</filename>.

14040

You can set this variable to "1" in your

14041

<filename>local.conf</filename> file in the

14042

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>

14043

to have the OpenEmbedded build system automatically run

14044

these tests after an image successfully builds:

TEST_IMAGE = "1"

</literallayout>

For more information on enabling, running, and writing

14049

these tests, see the

14050

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

14051

section in the Yocto Project Development Manual and the

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

14052

"<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>

14065

Holds the SSH log and the boot log for QEMU machines.

14066

The <filename>TEST_LOG_DIR</filename> variable defaults

14067

to <filename>"${WORKDIR}/testimage"</filename>.

14068

<note>

14069

Actual test results reside in the task log

14070

(<filename>log.do_testimage</filename>), which is in

14071

the <filename>${WORKDIR}/temp/</filename> directory.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>

14078

<info>

14079

TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test"

</info>

14084

For automated hardware testing, specifies the command to

14085

use to control the power of the target machine under test.

14086

Typically, this command would point to a script that

14087

performs the appropriate action (e.g. interacting

14088

with a web-enabled power strip).

14089

The specified command should expect to receive as the last

14090

argument "off", "on" or "cycle" specifying to power off,

14091

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>

14098

<info>

14099

TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD"

</info>

14104

For automated hardware testing, specifies additional

14105

arguments to pass through to the command specified in

14106

14107

Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>

14108

is optional.

14109

You can use it if you wish, for example, to separate the

14110

machine-specific and non-machine-specific parts of the

arguments.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>

14117

<info>

14118

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>

14123

The time in seconds allowed for an image to boot before

14124

automated runtime tests begin to run against an

14125

image.

14126

The default timeout period to allow the boot process to

14127

reach the login prompt is 500 seconds.

14128

You can specify a different value in the

14129

<filename>local.conf</filename> file.

</para>

<para>

For more information on testing images, see the

14134

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

14135

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>

14141

<info>

14142

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>

14147

For automated hardware testing, specifies the command

14148

to use to connect to the serial console of the target

14149

machine under test.

14150

This command simply needs to connect to the serial console

14151

and forward that connection to standard input and output

14152

as any normal terminal program does.

</para>

<para>

For example, to use the Picocom terminal program on

14157

serial device <filename>/dev/ttyUSB0</filename> at

14158

115200bps, you would set the variable as follows:

14159

14160

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>

14167

<info>

14168

TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD."

</info>

14173

For automated hardware testing, specifies additional

14174

arguments to pass through to the command specified in

14175

14176

Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>

14177

is optional.

14178

You can use it if you wish, for example, to separate the

14179

machine-specific and non-machine-specific parts of the

command.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>

14186

<info>

14187

TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected."

</info>

14192

The IP address of the build machine (host machine).

14193

This IP address is usually automatically detected.

14194

However, if detection fails, this variable needs to be set

14195

to the IP address of the build machine (i.e. where

14196

the build is taking place).

14197

<note>

14198

The <filename>TEST_SERVER_IP</filename> variable

14199

is only used for a small number of tests such as

14200

the "smart" test suite, which needs to download

14201

packages from <filename>DEPLOY_DIR/rpm</filename>.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>

14208

<info>

14209

TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine."

</info>

14214

Specifies the target controller to use when running tests

14215

against a test image.

14216

The default controller to use is "qemu":

TEST_TARGET = "qemu"

</literallayout>

</para>

<para>

A target controller is a class that defines how an

14224

image gets deployed on a target and how a target is started.

14225

A layer can extend the controllers by adding a module

14226

in the layer's <filename>/lib/oeqa/controllers</filename>

14227

directory and by inheriting the

14228

<filename>BaseTarget</filename> class, which is an abstract

14229

class that cannot be used as a value of

14230

<filename>TEST_TARGET</filename>.

</para>

<para>

You can provide the following arguments with

14235

<filename>TEST_TARGET</filename>:

14236

14237

<listitem><para><emphasis>"qemu" and "QemuTarget":</emphasis>

14238

Boots a QEMU image and runs the tests.

14239

See the

14240

"<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"

14241

section in the Yocto Project Development Manual for

14242

more information.

14243

</para></listitem>

14244

<listitem><para><emphasis>"simpleremote" and "SimpleRemoteTarget":</emphasis>

14245

Runs the tests on target hardware that is already

14246

up and running.

14247

The hardware can be on the network or it can be

14248

a device running an image on QEMU.

14249

You must also set

14250

14251

when you use "simpleremote" or "SimpleRemoteTarget".

14252

<note>

14253

This argument is defined in

14254

<filename>meta/lib/oeqa/targetcontrol.py</filename>.

14255

The small caps names are kept for compatibility

reasons.

</note>

</para></listitem>

<listitem><para><emphasis>"GummibootTarget":</emphasis>

14260

Automatically deploys and runs tests on an

14261

EFI-enabled machine that has a master image

14262

installed.

14263

<note>

14264

This argument is defined in

14265

<filename>meta/lib/oeqa/controllers/masterimage.py</filename>.

</note>

</para></listitem>

</itemizedlist>

</para>

<para>

For information on running tests on hardware, see the

14273

"<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"

14274

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>

14280

<info>

14281

TEST_TARGET_IP[doc] = "The IP address of your hardware under test."

</info>

14286

The IP address of your hardware under test.

14287

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"

14299

</literallayout>

14300

Specifying a port is useful when SSH is started on a

14301

non-standard port or in cases when your hardware under test

14302

is behind a firewall or network that is not directly

14303

accessible from your host and you need to do port address

translation.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>

14310

<info>

14311

TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing."

</info>

14316

An ordered list of tests (modules) to run against

14317

an image when performing automated runtime testing.

</para>

<para>

The OpenEmbedded build system provides a core set of tests

14322

that can be used against images.

14323

<note>

14324

Currently, there is only support for running these tests

14325

under QEMU.

14326

</note>

14327

Tests include <filename>ping</filename>,

14328

<filename>ssh</filename>, <filename>df</filename> among

14329

others.

14330

You can add your own tests to the list of tests by

14331

appending <filename>TEST_SUITES</filename> as follows:

14332

14333

TEST_SUITES_append = " <replaceable>mytest</replaceable>"

14334

</literallayout>

14335

Alternatively, you can provide the "auto" option to

14336

have all applicable tests run against the image.

14337

14338

TEST_SUITES_append = " auto"

14339

</literallayout>

14340

Using this option causes the build system to automatically

14341

run tests that are applicable to the image.

14342

Tests that are not applicable are skipped.

</para>

<para>

The order in which tests are run is important.

14347

Tests that depend on another test must appear later in the

14348

list than the test on which they depend.

14349

For example, if you append the list of tests with two

14350

tests (<filename>test_A</filename> and

14351

<filename>test_B</filename>) where

14352

<filename>test_B</filename> is dependent on

14353

<filename>test_A</filename>, then you must order the tests

14354

as follows:

14355

14356

TEST_SUITES = " test_A test_B"

</literallayout>

</para>

<para>

For more information on testing images, see the

14362

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

14363

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>

14369

<info>

14370

THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located."

</info>

14375

The directory in which the file BitBake is currently

14376

parsing is located.

14377

Do not manually set this variable.

</para>

</glossdef>

</glossentry>

<info>

TIME[doc] = "The time the build was started using HMS format."

</info>

14389

The time the build was started.

14390

Times appear using the hour, minute, and second (HMS)

14391

format (e.g. "140159" for one minute and fifty-nine

14392

seconds past 1400 hours).

</para>

</glossdef>

</glossentry>

<glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>

14398

<info>

14399

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>

14404

This variable is the base directory the OpenEmbedded

14405

build system uses for all build output and intermediate

14406

files (other than the shared state cache).

14407

By default, the <filename>TMPDIR</filename> variable points

14408

to <filename>tmp</filename> within the

14409

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

</para>

<para>

If you want to establish this directory in a location other

14414

than the default, you can uncomment and edit the following

14415

statement in the

14416

<filename>conf/local.conf</filename> file in the

14417

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:

14418

14419

#TMPDIR = "${TOPDIR}/tmp"

14420

</literallayout>

14421

An example use for this scenario is to set

14422

<filename>TMPDIR</filename> to a local disk, which does

14423

not use NFS, while having the Build Directory use NFS.

</para>

<para>

The filesystem used by <filename>TMPDIR</filename> must

14428

have standard filesystem semantics (i.e. mixed-case files

14429

are unique, POSIX file locking, and persistent inodes).

14430

Due to various issues with NFS and bugs in some

14431

implementations, NFS does not meet this minimum

14432

requirement.

14433

Consequently, <filename>TMPDIR</filename> cannot be on

NFS.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>

14440

<info>

14441

TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment."

</info>

14446

This variable lists packages the OpenEmbedded build system

14447

uses when building an SDK, which contains a

14448

cross-development environment.

14449

The packages specified by this variable are part of the

14450

toolchain set that runs on the

14451

14452

and each package should usually have the prefix

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14453

<filename>nativesdk-</filename>.

14454

For example, consider the following command when

14455

building an SDK:

14456

14457

$ bitbake -c populate_sdk <replaceable>imagename</replaceable>

14458

</literallayout>

14459

In this case, a default list of packages is set in this

14460

variable, but you can add additional packages to the list.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

14461

See the

14462

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"

14463

section in the Yocto Project Software Development Kit (SDK)

14464

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

14469

in the Yocto Project development environment, see the

14470

"<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"

14471

section.

14472

For information on setting up a cross-development

14473

environment, see the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14474

<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>

14480

<info>

14481

TOOLCHAIN_OUTPUTNAME[doc] = "Defines the name used for the toolchain output."

</info>

14486

This variable defines the name used for the toolchain

output.

The

class sets the

<filename>TOOLCHAIN_OUTPUTNAME</filename> variable as

14492

follows:

14493

14494

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>

14506

<info>

14507

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>

14512

This variable lists packages the OpenEmbedded build system

14513

uses when it creates the target part of an SDK

14514

(i.e. the part built for the target hardware), which

14515

includes libraries and headers.

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

14516

Use this variable to add individual packages to the

14517

part of the SDK that runs on the target.

14518

See the

14519

"<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"

14520

section in the Yocto Project Software Development Kit (SDK)

14521

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

14526

in the Yocto Project development environment, see the

14527

"<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"

14528

section.

14529

For information on setting up a cross-development

14530

environment, see the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14531

<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>

14537

<info>

14538

TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images."

</info>

14543

The top-level

14544

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

14545

BitBake automatically sets this variable when you

14546

initialize your build environment using either

or

</para>

</glossdef>

</glossentry>

<glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>

14555

<info>

14556

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>

14561

A sanitized version of

14562

14563

This variable is used where the architecture is needed in

14564

a value where underscores are not allowed, for example

14565

within package filenames.

14566

In this case, dash characters replace any underscore

14567

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>

14583

The GNU canonical architecture for a specific architecture

14584

(i.e. <filename>arm</filename>,

14585

<filename>armeb</filename>,

14586

<filename>mips</filename>,

14587

<filename>mips64</filename>, and so forth).

14588

BitBake uses this value to setup configuration.

</para>

<para>

<filename>TUNE_ARCH</filename> definitions are specific to

14593

a given architecture.

14594

The definitions can be a single static definition, or

14595

can be dynamically adjusted.

14596

You can see details for a given CPU family by looking at

14597

the architecture's <filename>README</filename> file.

14598

For example, the

14599

<filename>meta/conf/machine/include/mips/README</filename>

14600

file in the

14601

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

14602

provides information for <filename>TUNE_ARCH</filename>

14603

specific to the <filename>mips</filename> architecture.

</para>

<para>

<filename>TUNE_ARCH</filename> is tied closely to

14608

14609

which defines the target machine's architecture.

14610

The BitBake configuration file

14611

(<filename>meta/conf/bitbake.conf</filename>) sets

14612

<filename>TARGET_ARCH</filename> as follows:

14613

14614

TARGET_ARCH = "${TUNE_ARCH}"

</literallayout>

</para>

<para>

The following list, which is by no means complete since

14620

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>

14636

<info>

14637

TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system."

</info>

14642

Specifies architecture-specific assembler flags for

14643

the target system.

14644

The set of flags is based on the selected tune features.

14645

<filename>TUNE_ASARGS</filename> is set using

14646

the tune include files, which are typically under

14647

<filename>meta/conf/machine/include/</filename> and are

influenced through

For example, the

<filename>meta/conf/machine/include/x86/arch-x86.inc</filename>

14652

file defines the flags for the x86 architecture as follows:

14653

14654

TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"

14655

</literallayout>

14656

<note>

14657

Board Support Packages (BSPs) select the tune.

14658

The selected tune, in turn, affects the tune variables

14659

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>

14667

<info>

14668

TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system."

</info>

14673

Specifies architecture-specific C compiler flags for

14674

the target system.

14675

The set of flags is based on the selected tune features.

14676

<filename>TUNE_CCARGS</filename> is set using

14677

the tune include files, which are typically under

14678

<filename>meta/conf/machine/include/</filename> and are

influenced through

<note>

Board Support Packages (BSPs) select the tune.

14683

The selected tune, in turn, affects the tune variables

14684

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>

14692

<info>

14693

TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system."

</info>

14698

Specifies architecture-specific linker flags for

14699

the target system.

14700

The set of flags is based on the selected tune features.

14701

<filename>TUNE_LDARGS</filename> is set using

14702

the tune include files, which are typically under

14703

<filename>meta/conf/machine/include/</filename> and are

influenced through

For example, the

<filename>meta/conf/machine/include/x86/arch-x86.inc</filename>

14708

file defines the flags for the x86 architecture as follows:

14709

14710

TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"

14711

</literallayout>

14712

<note>

14713

Board Support Packages (BSPs) select the tune.

14714

The selected tune, in turn, affects the tune variables

14715

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>

14723

<info>

14724

TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor."

</info>

14729

Features used to "tune" a compiler for optimal use

14730

given a specific processor.

14731

The features are defined within the tune files and allow

14732

arguments (i.e. <filename>TUNE_*ARGS</filename>) to be

14733

dynamically generated based on the features.

</para>

<para>

The OpenEmbedded build system verifies the features

14738

to be sure they are not conflicting and that they are

supported.

</para>

<para>

The BitBake configuration file

14744

(<filename>meta/conf/bitbake.conf</filename>) defines

14745

<filename>TUNE_FEATURES</filename> as follows:

14746

14747

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>

14757

<info>

14758

TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages."

</info>

14763

The package architecture understood by the packaging

14764

system to define the architecture, ABI, and tuning of

14765

output packages.

14766

The specific tune is defined using the "_tune" override

14767

as follows:

14768

14769

TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>"

</literallayout>

</para>

<para>

These tune-specific package architectures are defined in

14775

the machine include files.

14776

Here is an example of the "core2-32" tuning as used

14777

in the

14778

<filename>meta/conf/machine/include/tune-core2.inc</filename>

14779

file:

14780

14781

TUNE_PKGARCH_tune-core2-32 = "core2-32"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>

14788

<info>

14789

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>

14794

An underlying Application Binary Interface (ABI) used by

14795

a particular tuning in a given toolchain layer.

14796

Providers that use prebuilt libraries can use the

14797

<filename>TUNEABI</filename>,

and

variables to check compatibility of tunings against their

14802

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>

14816

<info>

14817

TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST."

</info>

14822

If set, the OpenEmbedded system ignores the

14823

14824

variable.

14825

Providers that use prebuilt libraries can use the

14826

<filename>TUNEABI_OVERRIDE</filename>,

14827

<filename>TUNEABI_WHITELIST</filename>,

14828

and

14829

14830

variables to check compatibility of a tuning against their

14831

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>

14843

<info>

14844

TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed."

</info>

14849

A whitelist of permissible

14850

14851

values.

14852

If <filename>TUNEABI_WHITELIST</filename> is not set,

14853

all tunes are allowed.

14854

Providers that use prebuilt libraries can use the

14855

<filename>TUNEABI_WHITELIST</filename>,

14856

14857

and <filename>TUNEABI</filename> variables to check

14858

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>

14871

<info>

14872

TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature."

</info>

14877

Specifies CPU or Application Binary Interface (ABI)

14878

tuning features that conflict with <replaceable>feature</replaceable>.

</para>

<para>

Known tuning conflicts are specified in the machine include

14883

files in the

14884

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

14885

Here is an example from the

14886

<filename>meta/conf/machine/include/mips/arch-mips.inc</filename>

14887

include file that lists the "o32" and "n64" features as

14888

conflicting with the "n32" feature:

14889

14890

TUNECONFLICTS[n32] = "o32 n64"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm>

14897

<info>

14898

TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features."

</info>

14903

Specifies a valid CPU or Application Binary Interface (ABI)

14904

tuning feature.

14905

The specified feature is stored as a flag.

14906

Valid features are specified in the machine include files

14907

(e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).

14908

Here is an example from that file:

14909

14910

TUNEVALID[bigendian] = "Enable big-endian mode."

</literallayout>

</para>

<para>

See the machine include files in the

14916

<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>

14927

<info>

14928

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

14942

<filename>meta-fsl-arm</filename> layer.

14943

14944

UBOOT_CONFIG ??= "sd"

14945

UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"

14946

UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"

14947

UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"

14948

UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"

14949

</literallayout>

14950

In this example, "sd" is selected as the configuration

14951

of the possible four for the

14952

<filename>UBOOT_MACHINE</filename>.

14953

The "sd" configuration defines "mx6qsabreauto_config"

14954

as the value for <filename>UBOOT_MACHINE</filename>, while

14955

the "sdcard" specifies the

14956

<filename>IMAGE_FSTYPES</filename> to use for the U-boot

image.

</para>

<para>

For more information on how the

14962

<filename>UBOOT_CONFIG</filename> is handled, see the

14963

<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>

14970

<info>

14971

UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."

</info>

14976

Specifies the entry point for the U-Boot image.

14977

During U-Boot image creation, the

14978

<filename>UBOOT_ENTRYPOINT</filename> variable is passed

14979

as a command-line parameter to the

14980

<filename>uboot-mkimage</filename> utility.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>

14986

<info>

14987

UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image."

</info>

14992

Specifies the load address for the U-Boot image.

14993

During U-Boot image creation, the

14994

<filename>UBOOT_LOADADDRESS</filename> variable is passed

14995

as a command-line parameter to the

14996

<filename>uboot-mkimage</filename> utility.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>

15002

<info>

15003

UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image."

</info>

15008

Appends a string to the name of the local version of the

15009

U-Boot image.

15010

For example, assuming the version of the U-Boot image

15011

built was "2013.10, the full version string reported by

15012

U-Boot would be "2013.10-yocto" given the following

15013

statement:

15014

15015

UBOOT_LOCALVERSION = "-yocto"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>

15022

<info>

15023

UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image."

</info>

15028

Specifies the value passed on the

15029

<filename>make</filename> command line when building

15030

a U-Boot image.

15031

The value indicates the target platform configuration.

15032

You typically set this variable from the machine

15033

configuration file (i.e.

15034

<filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>).

</para>

<para>

Please see the "Selection of Processor Architecture and

15039

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>

15046

<info>

15047

UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile."

</info>

15052

Specifies the target called in the

15053

<filename>Makefile</filename>.

15054

The default target is "all".

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>

15060

<info>

15061

UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."

</info>

15066

Points to the generated U-Boot extension.

15067

For example, <filename>u-boot.sb</filename> has a

15068

<filename>.sb</filename> extension.

</para>

<para>

The default U-Boot extension is

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>

15079

<info>

15080

UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."

</info>

15085

Specifies the target used for building U-Boot.

15086

The target is passed directly as part of the "make" command

15087

(e.g. SPL and AIS).

15088

If you do not specifically set this variable, the

15089

OpenEmbedded build process passes and uses "all" for the

15090

target during the U-Boot building process.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UNKNOWN_CONFIGURE_WHITELIST'><glossterm>UNKNOWN_CONFIGURE_WHITELIST</glossterm>

15096

<info>

15097

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>

15102

Specifies a list of options that, if reported by the

15103

configure script as being invalid, should not generate a

warning during the

task.

Normally, invalid configure options are simply not passed

15108

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]

15112

However, common options, for example, exist that are passed

15113

to all configure scripts at a class level that might not

15114

be valid for some configure scripts.

15115

It follows that no benefit exists in seeing a warning about

15116

these options.

15117

For these cases, the options are added to

15118

<filename>UNKNOWN_CONFIGURE_WHITELIST</filename>.

</para>

<para>

The configure arguments check that uses

15123

<filename>UNKNOWN_CONFIGURE_WHITELIST</filename> is part

15124

of the

15125

15126

class and is only enabled if the recipe inherits the

class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>

15134

<info>

15135

UPDATERCPN[doc] = "Specifies the package that contains the initscript that is to be enabled."

</info>

15140

For recipes inheriting the

15141

15142

class, <filename>UPDATERCPN</filename> specifies

15143

the package that contains the initscript that is to be

enabled.

</para>

<para>

The default value is "${PN}".

15149

Given that almost all recipes that install initscripts

15150

package them in the main package for the recipe, you

15151

rarely need to set this variable in individual recipes.

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15156

<glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm>

15157

<info>

15158

UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository."

</info>

15163

When the

15164

15165

class is enabled globally, you can perform a per-recipe

15166

check for what the latest upstream source code version is

15167

by calling

15168

<filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.

15169

If the recipe source code is provided from Git

15170

repositories, the OpenEmbedded build system determines the

15171

latest upstream version by picking the latest tag from the

15172

list of all repository tags.

15173

You can use the

15174

<filename>UPSTREAM_CHECK_GITTAGREGEX</filename>

15175

variable to provide a regular expression to filter only the

15176

relevant tags should the default filter not work

15177

correctly.

15178

15179

UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm>

15186

<info>

15187

UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI."

</info>

15192

When the

15193

15194

class is enabled globally, use the

15195

<filename>UPSTREAM_CHECK_REGEX</filename> variable to

15196

specify a different regular expression instead of the

15197

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>

15208

<info>

15209

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>

15214

When the

15215

15216

class is enabled globally, you can perform a per-recipe

15217

check for what the latest upstream source code version is

15218

by calling <filename>bitbake -c checkpkg</filename>

15219

<replaceable>recipe</replaceable>.

15220

If the source code is provided from tarballs, the latest

15221

version is determined by fetching the directory listing

15222

where the tarball is and attempting to find a later tarball.

15223

When this approach does not work, you can use

15224

<filename>UPSTREAM_CHECK_URI</filename> to

15225

provide a different URI that contains the link to the

15226

latest tarball.

15227

15228

UPSTREAM_CHECK_URI = "recipe_url"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15234

<glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm>

15235

<info>

15236

USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population."

</info>

15241

Determines if <filename>devtmpfs</filename> is used for

15242

<filename>/dev</filename> population.

15243

The default value used for <filename>USE_DEVFS</filename>

15244

is "1" when no value is specifically set.

15245

Typically, you would set <filename>USE_DEVFS</filename>

15246

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>"

15253

section in the Yocto Project Development Manual for

15254

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>

15266

When using

15267

<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,

15268

determines whether or not to run a

15269

<ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>

15270

on any virtual terminals in order to enable logging in

15271

through those terminals.

</para>

<para>

The default value used for <filename>USE_VT</filename>

15276

is "1" when no default value is specifically set.

15277

Typically, you would set <filename>USE_VT</filename>

15278

to "0" in the machine configuration file for machines

15279

that do not have a graphical display attached and

15280

therefore do not need virtual terminal functionality.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>

15286

<info>

15287

USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features."

</info>

15292

A list of classes to globally inherit.

15293

These classes are used by the OpenEmbedded build system

15294

to enable extra features (e.g.

15295

<filename>buildstats</filename>,

15296

<filename>image-mklibs</filename>, and so forth).

</para>

<para>

The default list is set in your

15301

<filename>local.conf</filename> file:

15302

15303

USER_CLASSES ?= "buildstats image-mklibs image-prelink"

15304

</literallayout>

15305

For more information, see

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

15306

<filename>meta-poky/conf/local.conf.sample</filename> in

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15307

the

15308

<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>

15314

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15315

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]

15320

If set to "error", forces the OpenEmbedded build system to

15321

produce an error if the user identification

15322

(<filename>uid</filename>) and group identification

15323

(<filename>gid</filename>) values are not defined

15324

in <filename>files/passwd</filename>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15325

and <filename>files/group</filename> files.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15326

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

15331

apply <filename>uid</filename> and

15332

<filename>gid</filename> values.

15333

Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>

15334

variable is by default not set.

15335

If you plan on using statically assigned

15336

15337

values, you should set

15338

the <filename>USERADD_ERROR_DYNAMIC</filename> variable in

15339

your <filename>local.conf</filename> file as

15340

follows:

15341

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15342

USERADD_ERROR_DYNAMIC = "error"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15343

</literallayout>

15344

Overriding the default behavior implies you are going to

15345

also take steps to set static <filename>uid</filename> and

15346

<filename>gid</filename> values through use of the

and

variables.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>

15357

<info>

15358

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>

15363

Specifies a password file to use for obtaining static

15364

group identification (<filename>gid</filename>) values

15365

when the OpenEmbedded build system adds a group to the

15366

system during package installation.

</para>

<para>

When applying static group identification

15371

(<filename>gid</filename>) values, the OpenEmbedded build

15372

system looks in

15373

15374

for a <filename>files/group</filename> file and then applies

15375

those <filename>uid</filename> values.

15376

Set the variable as follows in your

15377

<filename>local.conf</filename> file:

15378

15379

USERADD_GID_TABLES = "files/group"

</literallayout>

</para>

<note>

Setting the

variable to "useradd-staticids" causes the build system

15387

to use static <filename>gid</filename> values.

</note>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>

15393

<info>

15394

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

15403

require users and/or groups to be added.

</para>

<para>

You must set this variable if the recipe inherits the

15408

class.

15409

For example, the following enables adding a user for the

15410

main package in a recipe:

15411

15412

USERADD_PACKAGES = "${PN}"

15413

</literallayout>

15414

<note>

15415

If follows that if you are going to use the

15416

<filename>USERADD_PACKAGES</filename> variable,

15417

you need to set one or more of the

or

variables.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>

15430

<info>

15431

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

15440

to the <filename>useradd</filename> command

15441

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>

15447

recipe:

15448

15449

USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \

15450

--no-create-home --shell /bin/false \

15451

--user-group messagebus"

15452

</literallayout>

15453

For information on the standard Linux shell command

15454

<filename>useradd</filename>, see

15455

<ulink url='http://linux.die.net/man/8/useradd'></ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>

15461

<info>

15462

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>

15467

Specifies a password file to use for obtaining static

15468

user identification (<filename>uid</filename>) values

15469

when the OpenEmbedded build system adds a user to the

15470

system during package installation.

</para>

<para>

When applying static user identification

15475

(<filename>uid</filename>) values, the OpenEmbedded build

15476

system looks in

15477

15478

for a <filename>files/passwd</filename> file and then applies

15479

those <filename>uid</filename> values.

15480

Set the variable as follows in your

15481

<filename>local.conf</filename> file:

15482

15483

USERADD_UID_TABLES = "files/passwd"

</literallayout>

</para>

<note>

Setting the

variable to "useradd-staticids" causes the build system

15491

to use static <filename>uid</filename> values.

</note>

</glossdef>

</glossentry>

<glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>

15497

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15498

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>

15503

When set to "useradd-staticids", causes the

15504

OpenEmbedded build system to base all user and group

15505

additions on a static

15506

<filename>passwd</filename> and

15507

<filename>group</filename> files found in

</para>

<para>

To use static user identification (<filename>uid</filename>)

15513

and group identification (<filename>gid</filename>)

15514

values, set the variable

15515

as follows in your <filename>local.conf</filename> file:

15516

15517

USERADDEXTENSION = "useradd-staticids"

15518

</literallayout>

15519

<note>

15520

Setting this variable to use static

15521

15522

values causes the OpenEmbedded build system to employ

15523

the

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

15524

Patrick Williams