Blame - import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml - stefanberger/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>

2276

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

</info>

2281

Identifies the initial RAM disk (initramfs) source files.

2282

The OpenEmbedded build system receives and uses

2283

this kernel Kconfig variable as an environment variable.

2284

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

</para>

<para>

The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be

2289

either a single cpio archive with a

2290

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

2291

space-separated list of directories and files for building

2292

the initramfs image.

2293

A cpio archive should contain a filesystem archive

2294

to be used as an initramfs image.

2295

Directories should contain a filesystem layout to be

2296

included in the initramfs image.

2297

Files should contain entries according to the format

2298

described by the

2299

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

kernel tree.

</para>

<para>

If you specify multiple directories and files, the

2305

initramfs image will be the aggregate of all of them.

</para>

</glossdef>

</glossentry>

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

2311

<info>

2312

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>

2317

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

2318

to the current build.

2319

This variable is used by the Autotools utilities when running

2320

<filename>configure</filename>.

</para>

</glossdef>

</glossentry>

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

2326

<info>

2327

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

</info>

2332

The minimal arguments for GNU configure.

</para>

</glossdef>

</glossentry>

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

2338

<info>

2339

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

2348

be in conflict should the recipe

2349

be built.

2350

In other words, if the

2351

<filename>CONFLICT_DISTRO_FEATURES</filename> variable

2352

lists a feature that also appears in

2353

<filename>DISTRO_FEATURES</filename> within the

2354

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>

2367

If set to "1" along with the

2368

2369

variable, the OpenEmbedded build system copies

2370

into the image the license files, which are located in

2371

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

2372

for each package.

2373

The license files are placed

Patrick Williams

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

[diff] [blame]

2374

in directories within the image itself during build time.

2375

<note>

2376

The <filename>COPY_LIC_DIRS</filename> does not

2377

offer a path for adding licenses for newly installed

2378

packages to an image, which might be most suitable

2379

for read-only filesystems that cannot be upgraded.

2380

See the

2381

2382

variable for additional information.

2383

You can also reference the

2384

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

2385

section in the Yocto Project Development Manual for

2386

information on providing license text.

2387

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

2393

<info>

2394

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>

2399

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

2400

the license manifest for the image to

2401

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

Patrick Williams

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

[diff] [blame]

2402

within the image itself during build time.

2403

<note>

2404

The <filename>COPY_LIC_MANIFEST</filename> does not

2405

offer a path for adding licenses for newly installed

2406

packages to an image, which might be most suitable

2407

for read-only filesystems that cannot be upgraded.

2408

See the

2409

2410

variable for additional information.

2411

You can also reference the

2412

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

2413

section in the Yocto Project Development Manual for

2414

information on providing license text.

2415

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

2421

<info>

2422

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>

2427

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

2428

You should only set this variable in the

2429

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

2430

in the

2431

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

2441

<info>

2442

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

</info>

2447

Specifies the parent directory of the OpenEmbedded

2448

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

</para>

<para>

It is an important distinction that

2453

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

2454

layer and not the layer itself.

2455

Consider an example where you have cloned the Poky Git

2456

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

2457

name for your local copy of the repository.

2458

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

2459

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

2460

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

layer.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

2466

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

2467

<info>

2468

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

</info>

2473

Lists files from the

2474

2475

directory that should be copied other than the layers

2476

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

2477

The <filename>COREBASE_FILES</filename> variable exists

2478

for the purpose of copying metadata from the

2479

OpenEmbedded build system into the extensible

SDK.

</para>

<para>

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

2485

is needed because it typically contains build

2486

directories and other files that should not normally

2487

be copied into the extensible SDK.

2488

Consequently, the value of

2489

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

2490

only copy the files that are actually needed.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

2495

2496

<info>

2497

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

</info>

2502

The minimal command and arguments used to run the C

preprocessor.

</para>

</glossdef>

</glossentry>

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

2509

<info>

2510

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

</info>

2515

Specifies the flags to pass to the C pre-processor

2516

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

2517

This variable is exported to an environment

2518

variable and thus made visible to the software being

2519

built during the compilation step.

</para>

<para>

Default initialization for <filename>CPPFLAGS</filename>

2524

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

2533

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

2538

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

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

2546

<info>

2547

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

</info>

2552

The toolchain binary prefix for the target tools.

2553

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

same as the

variable.

<note>

The OpenEmbedded build system sets the

2559

<filename>CROSS_COMPILE</filename> variable only in

2560

certain contexts (e.g. when building for kernel

2561

and kernel module recipes).

</note>

</para>

</glossdef>

</glossentry>

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

2568

<info>

2569

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

</info>

2574

The directory in which files checked out under the

2575

CVS system are stored.

</para>

</glossdef>

</glossentry>

<info>

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

</info>

2587

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

compiler.

</para>

</glossdef>

</glossentry>

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

2594

<info>

2595

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

</info>

2600

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

2601

This variable is exported to an environment

2602

variable and thus made visible to the software being

2603

built during the compilation step.

</para>

<para>

Default initialization for <filename>CXXFLAGS</filename>

2608

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

2617

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

Patrick Williams

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

[diff] [blame]

2622

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

2640

The destination directory.

2641

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

2642

where components are installed by the

2643

2644

task.

2645

This location defaults to:

2646

Patrick Williams

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

[diff] [blame]

2647

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

Patrick Williams

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

[diff] [blame]

2648

</literallayout>

Patrick Williams

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

[diff] [blame]

2649

<note><title>Caution</title>

2650

Tasks that read from or write to this directory should

2651

run under

2652

2653

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

2665

The date the build was started.

2666

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

2667

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

</para>

</glossdef>

</glossentry>

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

2673

<info>

2674

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

</info>

2679

The date and time on which the current build started.

2680

The format is suitable for timestamps.

</para>

</glossdef>

</glossentry>

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

2686

<info>

2687

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

</info>

2692

When the

2693

2694

class is inherited, which is the default behavior,

2695

<filename>DEBIAN_NOAUTONAME</filename> specifies a

2696

particular package should not be renamed according to

2697

Debian library package naming.

2698

You must use the package name as an override when you

2699

set this variable.

2700

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

2701

recipe:

2702

2703

DEBIAN_NOAUTONAME_fontconfig-utils = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

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

2710

<info>

2711

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

</info>

2716

When the

2717

2718

class is inherited, which is the default behavior,

2719

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

2720

library name for an individual package.

2721

Overriding the library name in these cases is rare.

2722

You must use the package name as an override when you

2723

set this variable.

2724

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

2725

recipe:

2726

2727

DEBIANNAME_${PN} = "dbus-1"

</literallayout>

</para>

</glossdef>

</glossentry>

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

2734

<info>

2735

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

</info>

2740

Specifies to build packages with debugging information.

2741

This influences the value of the

2742

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

variable.

</para>

</glossdef>

</glossentry>

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

2749

<info>

2750

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>

2755

The options to pass in

2756

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

2757

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

2758

a system for debugging.

2759

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

</para>

</glossdef>

</glossentry>

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

2765

<info>

2766

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

</info>

2771

Specifies a weak bias for recipe selection priority.

</para>

<para>

The most common usage of this is variable is to set

2776

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

2777

piece of software.

2778

Using the variable in this way causes the stable version

2779

of the recipe to build by default in the absence of

2780

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

2781

being used to build the development version.

</para>

<note>

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

2786

is weak and is overridden by

2787

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

2788

if that variable is different between two layers

2789

that contain different versions of the same recipe.

</note>

</glossdef>

</glossentry>

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

2795

<info>

2796

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

</info>

2801

The default CPU and Application Binary Interface (ABI)

2802

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

2803

system.

2804

The <filename>DEFAULTTUNE</filename> helps define

</para>

<para>

The default tune is either implicitly or explicitly set

2810

by the machine

2811

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

2812

However, you can override the setting using available tunes

as defined with

</para>

</glossdef>

</glossentry>

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

2820

<info>

2821

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]

2826

Lists a recipe's build-time dependencies.

2827

These are dependencies on other recipes whose

2828

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

2829

by the recipe at build time.

Patrick Williams

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

[diff] [blame]

2830

</para>

2831

2832

<para>

Patrick Williams

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

[diff] [blame]

2833

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

2834

that contains the following assignment:

Patrick Williams

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

[diff] [blame]

2835

Patrick Williams

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

[diff] [blame]

2836

DEPENDS = "bar"

Patrick Williams

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

[diff] [blame]

2837

</literallayout>

Patrick Williams

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

[diff] [blame]

2838

The practical effect of the previous assignment is that

2839

all files installed by bar will be available in the

2840

appropriate staging sysroot, given by the

2841

2842

variables, by the time the

Patrick Williams

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

[diff] [blame]

2843

Patrick Williams

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

[diff] [blame]

2844

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

2845

This mechanism is implemented by having

2846

<filename>do_configure</filename> depend on the

Patrick Williams

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

[diff] [blame]

2847

Patrick Williams

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

[diff] [blame]

2848

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

2849

through a

2850

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

2856

<filename>STAGING_DIR_HOST</filename> explicitly.

2857

The standard classes and build-related variables are

2858

configured to automatically use the appropriate staging

2859

sysroots.

2860

</note>

2861

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

2862

be used to add utilities that run on the build machine

2863

during the build.

2864

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

2865

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

2866

the following:

2867

2868

DEPENDS = "codegen-native"

2869

</literallayout>

2870

For more information, see the

class and the

variable.

<note>

<title>Notes</title>

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

2880

recipe names.

2881

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

2882

2883

names, which usually match recipe names.

2884

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

2885

<filename>DEPENDS</filename> does not make

2886

sense.

2887

Use "foo" instead, as this will put files

2888

from all the packages that make up

2889

<filename>foo</filename>, which includes

2890

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

the sysroot.

</para></listitem>

One recipe having another recipe in

2895

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

2896

add any runtime dependencies between the

2897

packages produced by the two recipes.

2898

However, as explained in the

2899

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

2900

section, runtime dependencies will often be

2901

added automatically, meaning

2902

<filename>DEPENDS</filename> alone is

2903

sufficient for most recipes.

</para></listitem>

Counterintuitively,

<filename>DEPENDS</filename> is often necessary

2908

even for recipes that install precompiled

2909

components.

2910

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

2911

is a precompiled library that links against

2912

<filename>libbar</filename>, then

2913

linking against <filename>libfoo</filename>

2914

requires both <filename>libfoo</filename>

2915

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

2916

in the sysroot.

2917

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

2918

recipe that installs <filename>libfoo</filename>

2919

to the recipe that installs

2920

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

2921

fail to link against

2922

<filename>libfoo</filename>.

2923

</para></listitem>

2924

</itemizedlist>

2925

</note>

Patrick Williams

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

[diff] [blame]

</para>

<para>

For information on runtime dependencies, see the

2930

2931

variable.

Patrick Williams

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

[diff] [blame]

2932

You can also see the

2933

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

2934

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

2935

sections in the BitBake User Manual for additional

2936

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>

2942

<info>

2943

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>

2948

Points to the general area that the OpenEmbedded build

2949

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

2950

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

2951

By default, this directory resides within the

2952

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

2953

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

</para>

<para>

For more information on the structure of the Build

2958

Directory, see

2959

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

2960

section.

2961

For more detail on the contents of the

2962

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

2963

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

2964

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

2965

and

2966

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

sections.

</para>

</glossdef>

</glossentry>

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

2973

<info>

2974

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>

2979

Points to the area that the OpenEmbedded build system uses

2980

to place Debian packages that are ready to be used outside

2981

of the build system.

2982

This variable applies only when

2983

2984

contains "package_deb".

</para>

<para>

The BitBake configuration file initially defines the

2989

<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

3002

the

3003

3004

task writes Debian packages into the appropriate folder.

3005

For more information on how packaging works, see the

3006

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

section.

</para>

</glossdef>

</glossentry>

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

3013

<info>

3014

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>

3019

Points to the area that the OpenEmbedded build system uses

3020

to place images and other associated output files that are

3021

ready to be deployed onto the target machine.

3022

The directory is machine-specific as it contains the

3023

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

3024

By default, this directory resides within the

3025

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

3026

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

</para>

<para>

For more information on the structure of the Build

3031

Directory, see

3032

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

3033

section.

3034

For more detail on the contents of the

3035

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

3036

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

3037

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

sections.

</para>

</glossdef>

</glossentry>

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

3044

<info>

3045

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>

3050

Points to the area that the OpenEmbedded build system uses

3051

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

3052

the build system.

3053

This variable applies only when

3054

3055

contains "package_ipk".

</para>

<para>

The BitBake configuration file initially defines this

3060

variable as a sub-folder of

3061

3062

3063

DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"

</literallayout>

</para>

<para>

The

class uses the

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

3072

the

3073

3074

task writes IPK packages into the appropriate folder.

3075

For more information on how packaging works, see the

3076

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

section.

</para>

</glossdef>

</glossentry>

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

3083

<info>

3084

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>

3089

Points to the area that the OpenEmbedded build system uses

3090

to place RPM packages that are ready to be used outside

3091

of the build system.

3092

This variable applies only when

3093

3094

contains "package_rpm".

</para>

<para>

The BitBake configuration file initially defines this

3099

variable as a sub-folder of

3100

3101

3102

DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"

</literallayout>

</para>

<para>

The

class uses the

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

3111

the

3112

3113

task writes RPM packages into the appropriate folder.

3114

For more information on how packaging works, see the

3115

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

section.

</para>

</glossdef>

</glossentry>

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

3122

<info>

3123

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>

3128

Points to the area that the OpenEmbedded build system uses

3129

to place tarballs that are ready to be used outside of

3130

the build system.

3131

This variable applies only when

3132

3133

contains "package_tar".

</para>

<para>

The BitBake configuration file initially defines this

3138

variable as a sub-folder of

3139

3140

3141

DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"

</literallayout>

</para>

<para>

The

class uses the

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

3150

the

3151

3152

task writes TAR packages into the appropriate folder.

3153

For more information on how packaging works, see the

3154

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

section.

</para>

</glossdef>

</glossentry>

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

3161

<info>

3162

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

</info>

3167

When inheriting the

3168

3169

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

3170

temporary work area for deployed files that is set in the

3171

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

3172

3173

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

</literallayout>

</para>

<para>

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

3179

should copy files to be deployed into

3180

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

3181

care of copying them into

afterwards.

</para>

</glossdef>

</glossentry>

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

3189

<info>

3190

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

</info>

3195

The package description used by package managers.

3196

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

the value of the

variable.

</para>

</glossdef>

</glossentry>

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

3205

<info>

3206

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

</info>

3211

A 32-bit MBR disk signature used by

3212

<filename>directdisk</filename> images.

</para>

<para>

By default, the signature is set to an automatically

3217

generated random value that allows the OpenEmbedded

3218

build system to create a boot loader.

3219

You can override the signature in the image recipe

3220

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

3221

8-digit hex string.

3222

You might want to override

3223

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

3224

signature to remain constant between image builds.

</para>

<para>

When using Linux 3.8 or later, you can use

3229

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

3230

by UUID to allow the kernel to locate the root device

3231

even if the device name changes due to differences in

3232

hardware configuration.

Patrick Williams

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

[diff] [blame]

3233

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

Patrick Williams

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

[diff] [blame]

3234

as follows:

3235

Patrick Williams

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

[diff] [blame]

3236

ROOT_VM ?= "root=/dev/sda2"

Patrick Williams

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

[diff] [blame]

3237

</literallayout>

3238

However, you can change this to locate the root device

3239

using the disk signature instead:

3240

Patrick Williams

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

[diff] [blame]

3241

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

3247

<filename>DISK_SIGNATURE</filename> variable in your

3248

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

3249

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

3250

changing for each build.

3251

You might find this useful when you want to upgrade the

3252

root filesystem on a device without having to recreate or

3253

modify the master boot record.

</para>

</glossdef>

</glossentry>

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

3259

<info>

3260

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

</info>

3265

The short name of the distribution.

3266

This variable corresponds to a distribution

3267

configuration file whose root name is the same as the

3268

variable's argument and whose filename extension is

3269

<filename>.conf</filename>.

3270

For example, the distribution configuration file for the

3271

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

3272

and resides in the

Patrick Williams

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

[diff] [blame]

3273

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

Patrick Williams

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

[diff] [blame]

3274

the

3275

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

</para>

<para>

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

3280

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

DISTRO = "poky"

</literallayout>

</para>

<para>

Distribution configuration files are located in a

3288

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

3289

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

3290

that contains the distribution configuration.

3291

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

3292

spaces, and is typically all lower-case.

3293

<note>

3294

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

3295

of default configurations are used, which are specified

3296

within

3297

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

3298

also in the Source Directory.

</note>

</para>

</glossdef>

</glossentry>

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

3305

<info>

3306

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

</info>

3311

Specifies a codename for the distribution being built.

</para>

</glossdef>

</glossentry>

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

3317

<info>

3318

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>

3323

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

3324

This variable takes affect through

3325

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

3326

variable only really applies to the more full-featured

3327

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

3328

You can use this variable to keep distro policy out of

3329

generic images.

3330

As with all other distro variables, you set this variable

3331

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

</para>

</glossdef>

</glossentry>

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

3337

<info>

3338

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>

3343

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

3344

if the packages exist.

3345

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

3346

The list of packages are automatically installed but you can

remove them.

</para>

</glossdef>

</glossentry>

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

3353

<info>

3354

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

</info>

3359

The software support you want in your distribution for

3360

various features.

3361

You define your distribution features in the distribution

configuration file.

</para>

<para>

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

3367

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

3368

appropriate option supplied to the configure script

3369

during the

3370

3371

task for recipes that optionally support the feature.

3372

For example, specifying "x11" in

3373

<filename>DISTRO_FEATURES</filename>, causes

3374

every piece of software built for the target that can

3375

optionally support X11 to have its X11 support enabled.

</para>

<para>

Two more examples are Bluetooth and NFS support.

3380

For a more complete list of features that ships with the

3381

Yocto Project and that you can provide with this variable,

3382

see the

3383

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

section.

</para>

</glossdef>

</glossentry>

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

3390

<info>

3391

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>

3396

Features to be added to

3397

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

3398

if not also present in

3399

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

3404

It is not intended to be user-configurable.

3405

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

3406

being backfilled for all distro configurations.

3407

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>

3414

<info>

3415

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>

3420

Features from

3421

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

3422

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

3423

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

3424

during the build.

3425

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>

3432

<info>

3433

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

</info>

3438

A convenience variable that gives you the default

3439

list of distro features with the exception of any

3440

features specific to the C library

3441

(<filename>libc</filename>).

</para>

<para>

When creating a custom distribution, you might find it

3446

useful to be able to reuse the default

3447

3448

options without the need to write out the full set.

3449

Here is an example that uses

3450

<filename>DISTRO_FEATURES_DEFAULT</filename> from a

3451

custom distro configuration file:

3452

3453

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

3460

<info>

3461

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

</info>

3466

A convenience variable that specifies the list of distro

3467

features that are specific to the C library

3468

(<filename>libc</filename>).

3469

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

3470

control which features are enabled at during the build

3471

within the C library itself.

</para>

</glossdef>

</glossentry>

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

3477

<info>

3478

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

</info>

3483

The long name of the distribution.

</para>

</glossdef>

</glossentry>

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

3489

<info>

3490

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

</info>

3495

The version of the distribution.

</para>

</glossdef>

</glossentry>

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

3501

<info>

Patrick Williams

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

[diff] [blame]

3502

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]

3507

A colon-separated list of overrides specific to the

3508

current distribution.

3509

By default, this list includes the value of

</para>

<para>

You can extend <filename>DISTROOVERRIDES</filename>

3515

to add extra overrides that should apply to

the distribution.

</para>

<para>

The underlying mechanism behind

3521

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

3522

is included in the default value of

3523

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>

3535

The central download directory used by the build process to

3536

store downloads.

3537

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

3538

suitable for mirroring for everything except Git

3539

repositories.

3540

If you want tarballs of Git repositories, use the

variable.

</para>

<para>

You can set this directory by defining the

3547

<filename>DL_DIR</filename> variable in the

3548

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

3549

This directory is self-maintaining and you should not have

3550

to touch it.

3551

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

3552

in the

3553

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

3554

3555

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

3556

</literallayout>

3557

To specify a different download directory, simply remove

3558

the comment from the line and provide your directory.

</para>

<para>

During a first build, the system downloads many different

3563

source code tarballs from various upstream projects.

3564

Downloading can take a while, particularly if your network

3565

connection is slow.

3566

Tarballs are all stored in the directory defined by

3567

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

3568

first to find source tarballs.

3569

<note>

3570

When wiping and rebuilding, you can preserve this

3571

directory to speed up this part of subsequent

builds.

</note>

</para>

<para>

You can safely share this directory between multiple builds

3578

on the same development machine.

3579

For additional information on how the build process gets

3580

source files when working behind a firewall or proxy server,

3581

see this specific question in the

3582

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

3583

chapter.

Patrick Williams

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

[diff] [blame]

3584

You can also refer to the

3585

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

3586

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>

3592

<info>

3593

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>

3598

When inheriting the

3599

3600

class, this variable sets the compression policy used when

3601

the OpenEmbedded build system compresses man pages and info

3602

pages.

3603

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

3604

Other policies available are xz and bz2.

</para>

<para>

For information on policies and on how to use this

3609

variable, see the comments in the

3610

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

</para>

</glossdef>

</glossentry>

</glossdiv>

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

3620

<info>

3621

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>

3626

When building bootable images (i.e. where

3627

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

3628

is in

3629

3630

the <filename>EFI_PROVIDER</filename> variable specifies

3631

the EFI bootloader to use.

Patrick Williams

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

[diff] [blame]

3632

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]

3638

Patrick Williams

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

[diff] [blame]

3639

class for more information.

</para>

</glossdef>

</glossentry>

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

3645

<info>

3646

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>

3651

Variable that controls which locales for

3652

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

3653

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>

3660

<info>

3661

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>

3666

When used with the

3667

3668

class, specifies the path used for storing the debug files

3669

created by the

3670

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

3671

which allows you to submit build errors you encounter to a

3672

central database.

3673

By default, the value of this variable is

3674

<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

3679

you want the error reporting tool to store the debug files

3680

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

3681

3682

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

3689

<info>

3690

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

</info>

3695

Specifies the quality assurance checks whose failures are

3696

reported as errors by the OpenEmbedded build system.

3697

You set this variable in your distribution configuration

3698

file.

3699

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

3700

see the

3701

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

3707

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

3708

<info>

3709

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

</info>

3714

Triggers the OpenEmbedded build system's shared libraries

3715

resolver to exclude an entire package when scanning for

3716

shared libraries.

3717

<note>

3718

The shared libraries resolver's functionality results

3719

in part from the internal function

3720

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

the

task.

You should be aware that the shared libraries resolver

3725

might implicitly define some dependencies between

3726

packages.

3727

</note>

3728

The <filename>EXCLUDE_FROM_SHLIBS</filename> variable is

3729

similar to the

3730

3731

variable, which excludes a package's particular libraries

3732

only and not the whole package.

</para>

<para>

Use the

<filename>EXCLUDE_FROM_SHLIBS</filename> variable by

3738

setting it to "1" for a particular package:

3739

3740

EXCLUDE_FROM_SHLIBS = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

3746

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

3747

<info>

3748

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

</info>

3753

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

3754

<filename>bitbake world</filename>).

3755

During world builds, BitBake locates, parses and builds all

3756

recipes found in every layer exposed in the

3757

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

</para>

<para>

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

3762

set the variable to "1" in the recipe.

</para>

<note>

Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>

3767

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

3768

dependencies of other recipes.

3769

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

3770

only ensures that the recipe is not explicitly added

3771

to the list of build targets in a world build.

</note>

</glossdef>

</glossentry>

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

3777

<info>

3778

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>

3783

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

3784

version based on the recipe's

3785

3786

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

3787

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

3788

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

3789

becomes "1_").

3790

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

3791

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

3792

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

3793

variable for an example.

</para>

</glossdef>

</glossentry>

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

3799

<info>

3800

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

</info>

3805

The full package version specification as it appears on the

3806

final packages produced by a recipe.

3807

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

3808

dependency to the exact same version of another package

3809

in the same recipe:

3810

3811

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

</literallayout>

</para>

<para>

The dependency relationships are intended to force the

3817

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>

3824

<info>

3825

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

</info>

3830

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

3831

variable indicates that these tools are not in the

source tree.

</para>

<para>

When kernel tools are available in the tree, they are

3837

preferred over any externally installed tools.

3838

Setting the <filename>EXTERNAL_KERNEL_TOOLS</filename>

3839

variable tells the OpenEmbedded build system to prefer

3840

the installed external tools.

3841

See the

3842

3843

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

3844

the variable is used.

</para>

</glossdef>

</glossentry>

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

3850

<info>

3851

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

</info>

3856

When inheriting the

3857

3858

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

3859

outside of the OpenEmbedded build system.

3860

When set, this variable sets the

3861

3862

variable, which is what the OpenEmbedded build system uses

3863

to locate unpacked recipe source code.

</para>

<para>

For more information on

3868

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

3869

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

3870

section.

3871

You can also find information on how to use this variable

3872

in the

3873

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

3874

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

3880

<info>

3881

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>

3886

When inheriting the

3887

3888

class, this variable points to the directory in which the

3889

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

3890

OpenEmbedded build system.

3891

When set, this variable sets the

3892

3893

variable, which is what the OpenEmbedded build system uses

3894

to locate the Build Directory.

</para>

<para>

For more information on

3899

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

3900

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

3901

section.

3902

You can also find information on how to use this variable

3903

in the

3904

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

3905

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

3911

<info>

3912

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

</info>

3917

For recipes inheriting the

3918

3919

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

3920

specify extra options to pass to the

3921

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

3934

<info>

3935

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>

3940

A list of additional features to include in an image.

3941

When listing more than one feature, separate them with

a space.

</para>

<para>

Typically, you configure this variable in your

3947

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

3948

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

3949

Although you can use this variable from within a recipe,

3950

best practices dictate that you do not.

3951

<note>

3952

To enable primary features from within the image

recipe, use the

variable.

</note>

</para>

<para>

Here are some examples of features you can add:

3961

3962

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

3963

including symbol information for debugging and

3964

profiling.

3965

3966

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

3967

For example, allows root logins without

3968

passwords and enables post-installation

3969

logging. See the 'allow-empty-password'

3970

and 'post-install-logging' features in

3971

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

3972

more information.

3973

3974

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

3975

This is useful if you want to develop against

3976

the libraries in the image.

3977

3978

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

3979

filesystem is read-only. See the

3980

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

3981

section in the Yocto Project

3982

Development Manual for more

3983

information

3984

3985

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

3986

strace.

3987

Patrick Williams

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

[diff] [blame]

3988

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

3989

pkgconfig and so forth.

3990

3991

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

3992

ts_print, aplay, arecord and so

forth.

</literallayout>

</para>

<para>

For a complete list of image features that ships with the

4000

Yocto Project, see the

4001

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

section.

</para>

<para>

For an example that shows how to customize your image by

4007

using this variable, see the

4008

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

4009

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

4015

<info>

4016

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>

4021

Specifies additional options for the image

4022

creation command that has been specified in

4023

4024

When setting this variable, you should

4025

use an override for the associated type.

4026

Here is an example:

4027

4028

EXTRA_IMAGECMD_ext3 ?= "-i 4096"

</literallayout>

</para>

</glossdef>

</glossentry>

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

4035

<info>

4036

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>

4041

A list of recipes to build that do not provide packages

4042

for installing into the root filesystem.

</para>

<para>

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

4047

needed in the root filesystem.

4048

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

4049

list these recipes and thus specify the dependencies.

4050

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

</para>

<note>

To add packages to the root filesystem, see the various

4055

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

4056

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

variables.

</note>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

4062

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

4063

<info>

4064

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

</info>

4069

A list of subdirectories of

4070

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

4071

added to the beginning of the environment variable

4072

<filename>PATH</filename>.

4073

As an example, the following prepends

4074

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

4075

to <filename>PATH</filename>:

4076

4077

EXTRANATIVEPATH = "foo bar"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

4083

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

4084

<info>

4085

EXTRA_OECMAKE[doc] = "Additional cmake options."

</info>

4090

Additional <filename>cmake</filename> options.

</para>

</glossdef>

</glossentry>

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

4096

<info>

4097

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

</info>

4102

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

Patrick Williams

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

[diff] [blame]

4103

See

4104

4105

for additional information on passing configure script

4106

options.

Patrick Williams

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

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

4112

<info>

4113

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

</info>

4118

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

4119

</para>

Patrick Williams

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

[diff] [blame]

4120

4121

<para>

4122

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

4123

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

4124

GNU options.

4125

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

4133

flags.

4134

</para>

Patrick Williams

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

[diff] [blame]

</glossdef>

</glossentry>

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

4139

<info>

4140

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>

4145

When inheriting the

4146

4147

class, this variable specifies additional configuration

4148

options you want to pass to the

4149

<filename>scons</filename> command line.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

4154

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

4155

<info>

4156

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

</info>

4161

When inheriting the

4162

4163

class, this variable provides image level user and group

4164

operations.

4165

This is a more global method of providing user and group

4166

configuration as compared to using the

4167

4168

class, which ties user and group configurations to a

specific recipe.

</para>

<para>

The set list of commands you can configure using the

4174

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

4175

<filename>extrausers</filename> class.

4176

These commands map to the normal Unix commands of the same

4177

names:

4178

4179

# EXTRA_USERS_PARAMS = "\

4180

# useradd -p '' tester; \

4181

# groupadd developers; \

4182

# userdel nobody; \

4183

# groupdel -g video; \

4184

# groupmod -g 1020 developers; \

4185

# usermod -s /bin/sh tester; \

# "

</literallayout>

</para>

</glossdef>

</glossentry>

</glossdiv>

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

4197

<info>

4198

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>

4203

Defines one or more packages to include in an image when

4204

a specific item is included in

4205

4206

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

4207

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

4208

Here is an example:

4209

4210

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

</literallayout>

</para>

<para>

In this example, if "widget" were added to

4216

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

4217

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

4218

<note>

4219

Packages installed by features defined through

4220

<filename>FEATURE_PACKAGES</filename> are often package

4221

groups.

4222

While similarly named, you should not confuse the

4223

<filename>FEATURE_PACKAGES</filename> variable with

4224

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>

4232

<info>

4233

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>

4238

Points to the base URL of the server and location within

4239

the document-root that provides the metadata and

4240

packages required by OPKG to support runtime package

4241

management of IPK packages.

4242

You set this variable in your

4243

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

</para>

<para>

Consider the following example:

4248

4249

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

4250

</literallayout>

4251

This example assumes you are serving your packages over

4252

HTTP and your databases are located in a directory

4253

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

4254

your HTTP server's document-root.

4255

In this case, the OpenEmbedded build system generates a set

4256

of configuration files for you in your target that work

with the feed.

</para>

</glossdef>

</glossentry>

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

4263

<info>

Patrick Williams

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

[diff] [blame]

4264

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]

4269

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

4278

package name override that identifies the resulting package.

4279

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

4280

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]

4284

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

4290

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

4291

to use appropriate path variables.

4292

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

4293

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

4294

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

4295

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

4296

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

4297

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

4298

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

Patrick Williams

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

[diff] [blame]

4299

You will also find the default values of the various

4300

<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

4305

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

4306

know they should not be overwritten during the package

4307

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

4308

can identify these files so that the PMS will not

overwrite them.

See the

variable for information on how to identify these files to

4313

the PMS.

4314

</para>

Patrick Williams

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

[diff] [blame]

</glossdef>

</glossentry>

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

4319

<info>

4320

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

</info>

4325

Defines the file specification to match

4326

4327

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

4328

defines the full path name of the development symbolic link

4329

(symlink) for shared libraries on the target platform.

</para>

<para>

The following statement from the

4334

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

4335

4336

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

4343

<info>

4344

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>

4349

Extends the search path the OpenEmbedded build system uses

4350

when looking for files and patches as it processes recipes

4351

and append files.

4352

The default directories BitBake uses when it processes

4353

recipes are initially defined by the

4354

4355

variable.

4356

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

4357

by using <filename>FILESEXTRAPATHS</filename>.

</para>

<para>

Best practices dictate that you accomplish this by using

4362

<filename>FILESEXTRAPATHS</filename> from within a

4363

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

4364

paths as follows:

4365

4366

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

4367

</literallayout>

4368

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

4369

in a directory that has the same name as the corresponding

4370

append file.

4371

<note>

4372

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

4373

be sure to use the immediate expansion

4374

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

4375

Immediate expansion makes sure that BitBake evaluates

4376

4377

at the time the directive is encountered rather than at

4378

some later time when expansion might result in a

4379

directory that does not contain the files you need.

4380

</para>

4381

<para>Also, include the trailing separating colon

4382

character if you are prepending.

4383

The trailing colon character is necessary because you

4384

are directing BitBake to extend the path by prepending

4385

directories to the search path.</para>

4386

</note>

4387

Here is another common use:

4388

4389

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

4390

</literallayout>

4391

In this example, the build system extends the

4392

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

4393

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

4394

same directory as the corresponding append file.

</para>

<para>

Here is a final example that specifically adds three paths:

4399

4400

FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"

</literallayout>

</para>

<para>

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

4406

files, you allow multiple append files that reside in

4407

different layers but are used for the same recipe to

4408

correctly extend the path.

</para>

</glossdef>

</glossentry>

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

4414

<info>

4415

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

</info>

4420

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

4421

used by the OpenEmbedded build system for creating

4422

4423

You can find more information on how overrides are handled

4424

in the

4425

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

</para>

<para>

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

4430

variable is defined as:

4431

4432

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

</literallayout>

<note>

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

4437

variable.

4438

The values match up with expected overrides and are

4439

used in an expected manner by the build system.

</note>

</para>

</glossdef>

</glossentry>

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

4446

<info>

4447

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>

4452

The default set of directories the OpenEmbedded build system

4453

uses when searching for patches and files.

4454

During the build process, BitBake searches each directory in

4455

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

4456

looking for files and patches specified by each

4457

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

</para>

<para>

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

4462

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

4463

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

4464

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

4465

4466

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

4467

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

4468

</literallayout>

4469

<note>

4470

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

4471

variable.

4472

If you want the build system to look in directories

4473

other than the defaults, extend the

4474

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

variable.

</note>

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

4479

directories do not map to directories in custom layers

4480

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

4481

are used.

4482

If you want the build system to find patches or files

4483

that reside with your append files, you need to extend

4484

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

the

variable.

</para>

</glossdef>

</glossentry>

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

4493

<info>

4494

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

</info>

4499

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

4500

your configuration for the packaging process.

4501

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

4502

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

4503

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

4509

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

4510

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

4511

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

4512

layer or the distro's layer.

</para>

<para>

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

4517

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

4518

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

4519

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

4520

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

4521

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,

4527

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

</para>

</glossdef>

</glossentry>

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

4533

<info>

4534

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>

4539

When inheriting the

4540

4541

class, this variable specifies the runtime dependencies

4542

for font packages.

4543

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

4544

is set to "fontconfig-utils".

</para>

</glossdef>

</glossentry>

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

4550

<info>

4551

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>

4556

When inheriting the

4557

4558

class, this variable identifies packages containing font

4559

files that need to be cached by Fontconfig.

4560

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

4561

that fonts are in the recipe's main package

4562

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

4563

Use this variable if fonts you need are in a package

4564

other than that main package.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

4569

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

4570

<info>

4571

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

</info>

4576

Forces the removal of the packages listed in

4577

<filename>ROOTFS_RO_UNNEEDED</filename> during the

4578

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]

4588

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

4589

<info>

4590

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>

4595

The options to pass in

4596

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

4597

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

4598

when compiling an optimized system.

4599

This variable defaults to

4600

"-O2 -pipe ${DEBUG_FLAGS}".

</para>

</glossdef>

</glossentry>

</glossdiv>

<info>

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

</info>

4615

The minimal command and arguments to run the GNU Debugger.

</para>

</glossdef>

</glossentry>

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

4621

<info>

4622

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

</info>

4627

The directory in which a local copy of a Git repository

4628

is stored when it is cloned.

</para>

</glossdef>

</glossentry>

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

4634

<info>

4635

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>

4640

Specifies the list of GLIBC locales to generate should you

4641

not wish generate all LIBC locals, which can be time

4642

consuming.

4643

<note>

4644

If you specifically remove the locale

4645

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

appropriately.

</note>

</para>

<para>

You can set <filename>GLIBC_GENERATE_LOCALES</filename>

4653

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

4654

By default, all locales are generated.

4655

4656

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

</literallayout>

</para>

</glossdef>

</glossentry>

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

4663

<info>

4664

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

4673

to the <filename>groupadd</filename> command

4674

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>

4680

recipe:

4681

4682

GROUPADD_PARAM_${PN} = "-r netdev"

4683

</literallayout>

4684

For information on the standard Linux shell command

4685

<filename>groupadd</filename>, see

4686

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

</para>

</glossdef>

</glossentry>

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

4692

<info>

4693

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

4702

to the <filename>groupmems</filename> command

4703

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

4704

package is installed.

</para>

<para>

For information on the standard Linux shell command

4709

<filename>groupmems</filename>, see

4710

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

</para>

</glossdef>

</glossentry>

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

4716

<info>

4717

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

</info>

4722

Configures the GNU GRand Unified Bootloader (GRUB) to have

4723

graphics and serial in the boot menu.

4724

Set this variable to "1" in your

4725

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

4726

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>

4745

Additional options to add to the GNU GRand Unified

4746

Bootloader (GRUB) configuration.

4747

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

4748

separate multiple options.

</para>

<para>

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

4753

See the

4754

4755

class for more information on how this variable is used.

</para>

</glossdef>

</glossentry>

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

4761

<info>

4762

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

</info>

4767

Specifies the timeout before executing the default

4768

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

Bootloader (GRUB).

</para>

<para>

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

4774

See the

4775

4776

class for more information on how this variable is used.

</para>

</glossdef>

</glossentry>

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

4782

<info>

4783

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>

4788

When inheriting the

4789

4790

class, this variable specifies the packages that contain the

4791

GTK+ input method modules being installed when the modules

4792

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>

4802

<info>

4803

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

</info>

4808

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>

4822

The name of the target architecture, which is normally

4823

the same as

4824

4825

The OpenEmbedded build system supports many

4826

architectures.

4827

Here is an example list of architectures supported.

4828

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>

4850

Specifies architecture-specific compiler flags that are

4851

passed to the C compiler.

</para>

<para>

Default initialization for <filename>HOST_CC_ARCH</filename>

4856

varies depending on what is being built:

when building for the target

4861

</para></listitem>

4862

4863

<filename>BUILD_CC_ARCH</filename>

4864

when building for the build host (i.e.

Patrick Williams

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

[diff] [blame]

4865

<filename>-native</filename>)

Patrick Williams

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

[diff] [blame]

4866

</para></listitem>

4867

4868

<filename>BUILDSDK_CC_ARCH</filename>

4869

when building for an SDK (i.e.

Patrick Williams

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

[diff] [blame]

4870

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

4884

Specifies the name of the target operating system, which

4885

is normally the same as the

4886

4887

The variable can be set to "linux" for <filename>glibc</filename>-based systems and

4888

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

4889

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

4890

"linux-uclibc-gnueabi" values possible.

</para>

</glossdef>

</glossentry>

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

4896

<info>

4897

HOST_PREFIX[doc] = "The prefix for the cross compile toolchain. Normally same as the TARGET_PREFIX."

</info>

4902

Specifies the prefix for the cross-compile toolchain.

4903

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

4916

Specifies the system, including the architecture and the

4917

operating system, for which the build is occurring

4918

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:

4936

4937

<listitem><para>Given a native recipe on a 32-bit

4938

x86 machine running Linux, the value is

4939

"i686-linux".

4940

</para></listitem>

4941

<listitem><para>Given a recipe being built for a

4942

little-endian MIPS target running Linux,

4943

the value might be "mipsel-linux".

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

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

4951

<info>

4952

HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR."

</info>

4957

Specifies the name of the vendor.

4958

<filename>HOST_VENDOR</filename> is normally the same as

</para>

</glossdef>

</glossentry>

</glossdiv>

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

4969

<info>

4970

ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function."

</info>

4975

Disables or enables the <filename>icecc</filename>

4976

(Icecream) function.

4977

For more information on this function and best practices

4978

for using this variable, see the

4979

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

section.

</para>

<para>

Setting this variable to "1" in your

4985

<filename>local.conf</filename> disables the function:

4986

4987

ICECC_DISABLED ??= "1"

4988

</literallayout>

4989

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>

4998

<info>

4999

ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide."

</info>

5004

Points to the <filename>icecc-create-env</filename> script

5005

that you provide.

5006

This variable is used by the

5007

5008

class.

5009

You set this variable in your

5010

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

</para>

<para>

If you do not point to a script that you provide, the

5015

OpenEmbedded build system uses the default script provided

5016

by the <filename>icecc-create-env.bb</filename> recipe,

5017

which is a modified version and not the one that comes with

5018

<filename>icecc</filename>.

</para>

</glossdef>

</glossentry>

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

5024

<info>

5025

ICECC_PARALLEL_MAKE[doc] = "Extra options passed to the make command during the do_compile task that specify parallel compilation."

</info>

5030

Extra options passed to the <filename>make</filename>

5031

command during the

5032

5033

task that specify parallel compilation.

5034

This variable usually takes the form of

5035

"-j <replaceable>x</replaceable>", where

5036

<replaceable>x</replaceable> represents the maximum

5037

number of parallel threads <filename>make</filename> can

5038

run.

5039

<note>

5040

The options passed affect builds on all enabled

5041

machines on the network, which are machines running the

5042

<filename>iceccd</filename> daemon.

</note>

</para>

<para>

If your enabled machines support multiple cores,

5048

coming up with the maximum number of parallel threads

5049

that gives you the best performance could take some

5050

experimentation since machine speed, network lag,

5051

available memory, and existing machine loads can all

5052

affect build time.

5053

Consequently, unlike the

5054

5055

variable, there is no rule-of-thumb for setting

5056

<filename>ICECC_PARALLEL_MAKE</filename> to achieve

optimal performance.

</para>

<para>

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

5062

the build system does not use it (i.e. the system does

5063

not detect and assign the number of cores as is done with

5064

<filename>PARALLEL_MAKE</filename>).

</para>

</glossdef>

</glossentry>

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

5070

<info>

5071

ICECC_PATH[doc] = "The location of the icecc binary."

</info>

5076

The location of the <filename>icecc</filename> binary.

5077

You can set this variable in your

5078

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

5079

If your <filename>local.conf</filename> file does not define

5080

this variable, the

5081

5082

class attempts to define it by locating

5083

<filename>icecc</filename> using <filename>which</filename>.

</para>

</glossdef>

</glossentry>

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

5089

<info>

5090

ICECC_USER_CLASS_BL[doc] = "Identifies user classes that you do not want the Icecream distributed compile support to consider."

</info>

5095

Identifies user classes that you do not want the

5096

Icecream distributed compile support to consider.

5097

This variable is used by the

5098

5099

class.

5100

You set this variable in your

5101

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

</para>

<para>

When you list classes using this variable, you are

5106

"blacklisting" them from distributed compilation across

5107

remote hosts.

5108

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>

5115

<info>

5116

ICECC_USER_PACKAGE_BL[doc] = "Identifies user recipes that you do not want the Icecream distributed compile support to consider."

</info>

5121

Identifies user recipes that you do not want the

5122

Icecream distributed compile support to consider.

5123

This variable is used by the

5124

5125

class.

5126

You set this variable in your

5127

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

</para>

<para>

When you list packages using this variable, you are

5132

"blacklisting" them from distributed compilation across

5133

remote hosts.

5134

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>

5141

<info>

5142

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>

5147

Identifies user recipes that use an empty

5148

5149

variable that you want to force remote distributed

5150

compilation on using the Icecream distributed compile

5151

support.

5152

This variable is used by the

5153

5154

class.

5155

You set this variable in your

5156

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

</para>

</glossdef>

</glossentry>

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

5162

<info>

5163

IMAGE_BASENAME[doc] = "The base name of image output files."

</info>

5168

The base name of image output files.

5169

This variable defaults to the recipe name

5170

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

5176

<info>

5177

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>

5182

A space-separated list of files installed into the

5183

boot partition when preparing an image using the

5184

<filename>wic</filename> tool with the

5185

<filename>bootimg-partition</filename> source

5186

plugin.

5187

By default, the files are installed under

5188

the same name as the source files.

5189

To change the installed name, separate it from the

5190

original name with a semi-colon (;).

5191

Source files need to be located in

5192

5193

Here are two examples:

5194

5195

5196

IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"

5197

IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"

</literallayout>

</para>

<para>

Alternatively, source files can be picked up using

5203

a glob pattern.

5204

In this case, the destination file

5205

will have the same name as the base name of the source file

5206

path.

5207

To install files into a directory within the

5208

target location, pass its name after a semi-colon

5209

(;).

5210

Here are two examples:

5211

5212

IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"

5213

IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"

5214

</literallayout>

5215

The first example installs all files from

5216

<filename>${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles</filename>

5217

into the root of the target partition.

5218

The second example installs the same files into a

5219

<filename>boot</filename> directory within the

target partition.

</para>

</glossdef>

</glossentry>

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

5226

<info>

5227

IMAGE_CLASSES[doc] = "A list of classes that all images should inherit."

</info>

5232

A list of classes that all images should inherit.

5233

You typically use this variable to specify the list of

5234

classes that register the different types of images

5235

the OpenEmbedded build system creates.

</para>

<para>

The default value for <filename>IMAGE_CLASSES</filename> is

5240

<filename>image_types</filename>.

5241

You can set this variable in your

5242

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

configuration file.

</para>

<para>

For more information, see

5248

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

5249

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

</para>

</glossdef>

</glossentry>

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

5255

<info>

5256

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>

5261

Specifies the command to create the image file for a

5262

specific image type, which corresponds to the value set

5263

set in

5264

5265

(e.g. <filename>ext3</filename>,

5266

<filename>btrfs</filename>, and so forth).

5267

When setting this variable, you should use

5268

an override for the associated type.

5269

Here is an example:

5270

5271

IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \

5272

--faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \

${EXTRA_IMAGECMD}"

</literallayout>

</para>

<para>

You typically do not need to set this variable unless

5279

you are adding support for a new image type.

5280

For more examples on how to set this variable, see the

5281

5282

class file, which is

5283

<filename>meta/classes/image_types.bbclass</filename>.

</para>

</glossdef>

</glossentry>

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

5289

<info>

5290

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>

5295

Specifies one or more files that contain custom device

5296

tables that are passed to the

5297

<filename>makedevs</filename> command as part of creating

5298

an image.

5299

These files list basic device nodes that should be

5300

created under <filename>/dev</filename> within the image.

5301

If <filename>IMAGE_DEVICE_TABLES</filename> is not set,

5302

<filename>files/device_table-minimal.txt</filename> is

5303

used, which is located by

5304

5305

For details on how you should write device table files,

5306

see <filename>meta/files/device_table-minimal.txt</filename>

as an example.

</para>

</glossdef>

</glossentry>

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

5313

<info>

5314

IMAGE_FEATURES[doc] = "The primary list of features to include in an image. Configure this variable in an image recipe."

</info>

5319

The primary list of features to include in an image.

5320

Typically, you configure this variable in an image recipe.

5321

Although you can use this variable from your

5322

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

5323

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

5324

best practices dictate that you do not.

5325

<note>

5326

To enable extra features from outside the image recipe,

5327

use the

5328

<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

5334

Project, see the

5335

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

section.

</para>

<para>

For an example that shows how to customize your image by

5341

using this variable, see the

5342

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

5343

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

5349

<info>

5350

IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created."

</info>

5355

Specifies the formats the OpenEmbedded build system uses

5356

during the build when creating the root filesystem.

5357

For example, setting <filename>IMAGE_FSTYPES</filename>

5358

as follows causes the build system to create root

5359

filesystems using two formats: <filename>.ext3</filename>

5360

and <filename>.tar.bz2</filename>:

5361

5362

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>

5374

inside an image recipe, be sure that you do so prior to the

5375

"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

5381

possible to update its contents using

5382

<filename>_append</filename> or

5383

<filename>_prepend</filename>. To add one or more

5384

additional options to this variable the

5385

<filename>+=</filename> operator must be used.

</note>

</glossdef>

</glossentry>

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

5391

<info>

5392

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>

5397

Specifies the packages to install into an image.

5398

The <filename>IMAGE_INSTALL</filename> variable is a

5399

mechanism for an image recipe and you should use it

5400

with care to avoid ordering issues.

<note>

When working with an

image, do not use the <filename>IMAGE_INSTALL</filename>

5405

variable to specify packages for installation.

5406

Instead, use the

5407

5408

variable, which allows the initial RAM disk (initramfs)

5409

recipe to use a fixed set of packages and not be

5410

affected by <filename>IMAGE_INSTALL</filename>.

</note>

</para>

<para>

Image recipes set <filename>IMAGE_INSTALL</filename>

5416

to specify the packages to install into an image through

5417

<filename>image.bbclass</filename>.

5418

Additionally, "helper" classes exist, such as

5419

<filename>core-image.bbclass</filename>, that can take

5420

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

5421

lists and turn these into auto-generated entries in

5422

<filename>IMAGE_INSTALL</filename> in addition to its

default contents.

</para>

<para>

Using <filename>IMAGE_INSTALL</filename> with the

5428

<filename>+=</filename> operator from the

5429

<filename>/conf/local.conf</filename> file or from within

5430

an image recipe is not recommended as it can cause ordering

5431

issues.

5432

Since <filename>core-image.bbclass</filename> sets

5433

<filename>IMAGE_INSTALL</filename> to a default value using

5434

the <filename>?=</filename> operator, using a

5435

<filename>+=</filename> operation against

5436

<filename>IMAGE_INSTALL</filename> will result in

5437

unexpected behavior when used in

5438

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

5439

Furthermore, the same operation from within an image

5440

recipe may or may not succeed depending on the specific

5441

situation.

5442

In both these cases, the behavior is contrary to how most

5443

users expect the <filename>+=</filename> operator to work.

</para>

<para>

When you use this variable, it is best to use it as follows:

5448

5449

IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"

5450

</literallayout>

5451

Be sure to include the space between the quotation character

5452

and the start of the package name or names.

</para>

</glossdef>

</glossentry>

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

5458

<info>

5459

IMAGE_LINGUAS[doc] = "Specifies the list of locales to install into the image during the root filesystem construction process."

</info>

5464

Specifies the list of locales to install into the image

5465

during the root filesystem construction process.

5466

The OpenEmbedded build system automatically splits locale

5467

files, which are used for localization, into separate

5468

packages.

5469

Setting the <filename>IMAGE_LINGUAS</filename> variable

5470

ensures that any locale packages that correspond to packages

5471

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

5481

Portuguese and German locale files that correspond to

5482

packages in the image are installed (i.e.

5483

<filename>*-locale-pt-br</filename>

5484

and <filename>*-locale-de-de</filename> as well as

5485

<filename>*-locale-pt</filename>

5486

and <filename>*-locale-de</filename>, since some software

5487

packages only provide locale files by language and not by

5488

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>

5500

<info>

5501

IMAGE_MANIFEST[doc] = "The manifest file for the image. This file lists all the installed packages that make up the image."

</info>

5506

The manifest file for the image.

5507

This file lists all the installed packages that make up

5508

the image.

5509

The file contains package information on a line-per-package

5510

basis as follows:

5511

5512

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

5520

5521

IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"

5522

</literallayout>

5523

The location is derived using the

and

variables.

You can find information on how the image

5529

is created in the

5530

"<link linkend='image-generation-dev-environment'>Image Generation</link>"

section.

</para>

</glossdef>

</glossentry>

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

5537

<info>

5538

IMAGE_NAME[doc] = "The name of the output image files minus the extension."

</info>

5543

The name of the output image files minus the extension.

5544

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>

5558

<info>

5559

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>

5564

Defines a multiplier that the build system applies to the initial image

5565

size for cases when the multiplier times the returned disk usage value

5566

for the image is greater than the sum of

5567

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

5568

and

5569

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

5570

The result of the multiplier applied to the initial image size creates

5571

free disk space in the image as overhead.

5572

By default, the build process uses a multiplier of 1.3 for this variable.

5573

This default value results in 30% free disk space added to the image when this

5574

method is used to determine the final generated image size.

5575

You should be aware that post install scripts and the package management

5576

system uses disk space inside this overhead area.

5577

Consequently, the multiplier does not produce an image with

5578

all the theoretical free disk space.

5579

See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>

5580

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

5585

and allows for basic post installs while still leaving a small amount of

5586

free disk space.

5587

If 30% free space is inadequate, you can increase the default value.

5588

For example, the following setting gives you 50% free space added to the image:

5589

5590

IMAGE_OVERHEAD_FACTOR = "1.5"

</literallayout>

</para>

<para>

Alternatively, you can ensure a specific amount of free disk space is added

5596

to the image by using the

5597

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

5604

<info>

5605

IMAGE_PKGTYPE[doc] = "Defines the package type (DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system."

</info>

5610

Defines the package type (DEB, RPM, IPK, or TAR) used

5611

by the OpenEmbedded build system.

5612

The variable is defined appropriately by the

or

class.

<note><title>Warning</title>

5620

The <filename>package_tar</filename> class is broken

5621

and is not supported.

5622

It is recommended that you do not use it.

</note>

</para>

<para>

The

Patrick Williams

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

[diff] [blame]

5628

Patrick Williams

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

[diff] [blame]

5629

and

5630

5631

classes use the <filename>IMAGE_PKGTYPE</filename> for

5632

packaging up images and SDKs.

</para>

<para>

You should not set the <filename>IMAGE_PKGTYPE</filename>

5637

manually.

5638

Rather, the variable is set indirectly through the

appropriate

class using the

variable.

The OpenEmbedded build system uses the first package type

5645

(e.g. DEB, RPM, or IPK) that appears with the variable

5646

<note>

5647

Files using the <filename>.tar</filename> format are

5648

never used as a substitute packaging format for DEB,

5649

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>

5656

<info>

5657

IMAGE_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the final image output files."

</info>

5662

Specifies a list of functions to call once the

5663

OpenEmbedded build system has created the final image

5664

output files.

5665

You can specify functions separated by semicolons:

5666

5667

IMAGE_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

5673

within the function, you can use

5674

<filename>${IMAGE_ROOTFS}</filename>, which points to

5675

the directory that becomes the root filesystem image.

Patrick Williams

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

[diff] [blame]

5676

See the

5677

5678

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>

5684

<info>

5685

IMAGE_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the final image output files."

</info>

5690

Specifies a list of functions to call before the

5691

OpenEmbedded build system has created the final image

5692

output files.

5693

You can specify functions separated by semicolons:

5694

5695

IMAGE_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

5701

within the function, you can use

5702

<filename>${IMAGE_ROOTFS}</filename>, which points to

5703

the directory that becomes the root filesystem image.

Patrick Williams

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

[diff] [blame]

5704

See the

5705

5706

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>

5712

<info>

5713

IMAGE_ROOTFS[doc] = "The location of the root filesystem while it is under construction (i.e. during do_rootfs)."

</info>

5718

The location of the root filesystem while it is under

5719

construction (i.e. during the

5720

5721

task).

5722

This variable is not configurable.

Do not change it.

</para>

</glossdef>

</glossentry>

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

5729

<info>

5730

IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes."

</info>

5735

Specifies the alignment for the output image file in

5736

Kbytes.

5737

If the size of the image is not a multiple of

5738

this value, then the size is rounded up to the nearest

5739

multiple of the value.

5740

The default value is "1".

5741

See

5742

5743

for additional information.

</para>

</glossdef>

</glossentry>

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

5749

<info>

5750

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>

5755

Defines additional free disk space created in the image in Kbytes.

5756

By default, this variable is set to "0".

5757

This free disk space is added to the image after the build system determines

5758

the image size as described in

5759

<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

5764

specific amount of free disk space is available on a device after an image

5765

is installed and running.

5766

For example, to be sure 5 Gbytes of free disk space is available, set the

5767

variable as follows:

5768

5769

IMAGE_ROOTFS_EXTRA_SPACE = "5242880"

</literallayout>

</para>

<para>

For example, the Yocto Project Build Appliance specifically requests 40 Gbytes

5775

of extra space with the line:

5776

5777

IMAGE_ROOTFS_EXTRA_SPACE = "41943040"

</literallayout>

</para>

</glossdef>

</glossentry>

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

5784

<info>

5785

IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image."

</info>

5790

Defines the size in Kbytes for the generated image.

5791

The OpenEmbedded build system determines the final size for the generated

5792

image using an algorithm that takes into account the initial disk space used

5793

for the generated image, a requested size for the image, and requested

5794

additional free disk space to be added to the image.

5795

Programatically, the build system determines the final size of the

5796

generated image as follows:

5797

5798

if (image-du * overhead) < rootfs-size:

5799

internal-rootfs-size = rootfs-size + xspace

5800

else:

5801

internal-rootfs-size = (image-du * overhead) + xspace

where:

image-du = Returned value of the du command on

5806

the image.

5807

5808

overhead = IMAGE_OVERHEAD_FACTOR

5809

5810

rootfs-size = IMAGE_ROOTFS_SIZE

5811

5812

internal-rootfs-size = Initial root filesystem

5813

size before any modifications.

5814

5815

xspace = IMAGE_ROOTFS_EXTRA_SPACE

</literallayout>

</para>

<para>

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

5821

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

5822

variables for related information.

5823

<!-- In the above example, <filename>overhead</filename> is defined by the

5824

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

5825

variable, <filename>xspace</filename> is defined by the

5826

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

5827

variable, and <filename>du</filename> is the results of the disk usage command

5828

on the initially generated image. -->

</para>

</glossdef>

</glossentry>

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

5834

<info>

5835

IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another."

</info>

5840

Specifies a dependency from one image type on another.

5841

Here is an example from the

class:

IMAGE_TYPEDEP_live = "ext3"

</literallayout>

</para>

<para>

In the previous example, the variable ensures that when

5851

"live" is listed with the

5852

5853

variable, the OpenEmbedded build system produces an

5854

<filename>ext3</filename> image first since one of the

5855

components of the live

5856

image is an <filename>ext3</filename>

5857

formatted partition containing the root

filesystem.

</para>

</glossdef>

</glossentry>

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

5864

<info>

5865

IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default."

</info>

5870

Specifies the complete list of supported image types

5871

by default:

5872

Patrick Williams

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

[diff] [blame]

5873

btrfs

Patrick Williams

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

[diff] [blame]

5874

cpio

5875

cpio.gz

Patrick Williams

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

[diff] [blame]

5876

cpio.lz4

Patrick Williams

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

[diff] [blame]

5877

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]

5906

vdi

5907

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

5917

<filename>meta/classes/image_types*.bbclass</filename>

5918

in the

5919

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

5931

Helps define the recipe revision for recipes that share

5932

a common <filename>include</filename> file.

5933

You can think of this variable as part of the recipe revision

5934

as set from within an include file.

</para>

<para>

Suppose, for example, you have a set of recipes that

5939

are used across several projects.

5940

And, within each of those recipes the revision

5941

(its <link linkend='var-PR'><filename>PR</filename></link>

5942

value) is set accordingly.

5943

In this case, when the revision of those recipes changes,

5944

the burden is on you to find all those recipes and

5945

be sure that they get changed to reflect the updated

5946

version of the recipe.

5947

In this scenario, it can get complicated when recipes

5948

that are used in many places and provide common functionality

5949

are upgraded to a new revision.

</para>

<para>

A more efficient way of dealing with this situation is

5954

to set the <filename>INC_PR</filename> variable inside

5955

the <filename>include</filename> files that the recipes

5956

share and then expand the <filename>INC_PR</filename>

5957

variable within the recipes to help

5958

define the recipe revision.

</para>

<para>

The following provides an example that shows how to use

5963

the <filename>INC_PR</filename> variable

5964

given a common <filename>include</filename> file that

5965

defines the variable.

5966

Once the variable is defined in the

5967

<filename>include</filename> file, you can use the

5968

variable to set the <filename>PR</filename> values in

5969

each recipe.

5970

You will notice that when you set a recipe's

5971

<filename>PR</filename> you can provide more granular

5972

revisioning by appending values to the

5973

<filename>INC_PR</filename> variable:

5974

5975

recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"

5976

recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"

5977

recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"

5978

recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"

5979

</literallayout>

5980

The first line of the example establishes the baseline

5981

revision to be used for all recipes that use the

5982

<filename>include</filename> file.

5983

The remaining lines in the example are from individual

5984

recipes and show how the <filename>PR</filename> value

is set.

</para>

</glossdef>

</glossentry>

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

5991

<info>

5992

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>

5997

Specifies a space-separated list of license names

5998

(as they would appear in

5999

6000

that should be excluded from the build.

6001

Recipes that provide no alternatives to listed incompatible

6002

licenses are not built.

6003

Packages that are individually licensed with the specified

6004

incompatible licenses will be deleted.

</para>

<note>

This functionality is only regularly tested using

6009

the following setting:

6010

6011

INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"

6012

</literallayout>

6013

Although you can use other settings, you might be required

6014

to remove dependencies on or provide alternatives to

6015

components that are required to produce a functional system

image.

</note>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

6021

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

6022

<info>

6023

INHERIT[doc] = "Causes the named class to be inherited at this point during parsing. The variable is only valid in configuration files."

</info>

6028

Causes the named class to be inherited at

6029

this point during parsing.

6030

The variable is only valid in configuration files.

</para>

</glossdef>

</glossentry>

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

6036

<info>

6037

INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable."

</info>

6042

Lists classes that will be inherited at the

6043

distribution level.

6044

It is unlikely that you want to edit this variable.

</para>

<para>

The default value of the variable is set as follows in the

6049

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

6050

file:

6051

6052

INHERIT_DISTRO ?= "debian devshell sstate license"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

6058

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

6059

<info>

6060

INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS."

</info>

6065

Prevents the default dependencies, namely the C compiler

6066

and standard C library (libc), from being added to

6067

6068

This variable is usually used within recipes that do not

6069

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>

6080

<info>

Patrick Williams

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

[diff] [blame]

6081

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>

6086

Prevents the OpenEmbedded build system from splitting

6087

out debug information during packaging.

6088

By default, the build system splits out debugging

6089

information during the

6090

6091

task.

6092

For more information on how debug information is split out,

see the

variable.

</para>

<para>

To prevent the build system from splitting out

6100

debug information during packaging, set the

6101

<filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable

6102

as follows:

6103

6104

INHIBIT_PACKAGE_DEBUG_SPLIT = "1"

</literallayout>

</para>

</glossdef>

</glossentry>

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

6111

<info>

6112

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]

6117

If set to "1", causes the build to not strip binaries in

6118

resulting packages and prevents the

6119

<filename>-dbg</filename> package from containing the

source files.

</para>

<para>

By default, the OpenEmbedded build system strips

6125

binaries and puts the debugging symbols into

6126

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

6127

Consequently, you should not set

6128

<filename>INHIBIT_PACKAGE_STRIP</filename> when you plan

6129

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]

6134

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

6135

<info>

6136

INITRAMFS_FSTYPES[doc] = "Defines the format for the output image of an initial RAM disk (initramfs), which is used during boot."

</info>

6141

Defines the format for the output image of an initial

6142

RAM disk (initramfs), which is used during boot.

6143

Supported formats are the same as those supported by the

6144

6145

variable.

6146

</para>

Patrick Williams

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

[diff] [blame]

6147

6148

<para>

6149

The default value of this variable, which is set in the

6150

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

6151

file in the

6152

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

6153

is "cpio.gz".

6154

The Linux kernel's initramfs mechanism, as opposed to the

6155

initial RAM disk

6156

<ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>

6157

mechanism, expects an optionally compressed cpio

6158

archive.

6159

</para>

Patrick Williams

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

[diff] [blame]

</glossdef>

</glossentry>

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

6164

<info>

Patrick Williams

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

[diff] [blame]

6165

INITRAMFS_IMAGE[doc] = "Specifies the PROVIDES name of an image recipe that is used to build an initial RAM disk (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]

6170

Specifies the

6171

6172

name of an image recipe that is used to build an initial

6173

RAM disk (initramfs) image.

6174

An initramfs provides a temporary root filesystem used for

6175

early system initialization (e.g. loading of modules

6176

needed to locate and mount the "real" root filesystem).

6177

The specified recipe is added as a dependency of the root

6178

filesystem recipe (e.g.

6179

<filename>core-image-sato</filename>).

6180

See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename>

6181

recipe in the

6182

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

6183

for an example initramfs recipe.

6184

To select this recipe to provide the initramfs,

6185

set <filename>INITRAMFS_IMAGE</filename> to

6186

"core-image-minimal-initramfs".

6187

<note>

6188

The initramfs image recipe should set

to

</note>

Patrick Williams

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

[diff] [blame]

6193

</para>

6194

6195

<para>

Patrick Williams

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

[diff] [blame]

6196

You can also find more information by referencing the

6197

<filename>meta/poky/conf/local.conf.sample.extended</filename>

6198

configuration file in the

6199

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

6200

the

6201

6202

class, and the

Patrick Williams

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

[diff] [blame]

6203

Patrick Williams

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

[diff] [blame]

6204

class to see how to use the

6205

<filename>INITRAMFS_IMAGE</filename> variable.

Patrick Williams

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

[diff] [blame]

6206

</para>

6207

6208

<para>

Patrick Williams

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

[diff] [blame]

6209

If <filename>INITRAMFS_IMAGE</filename> is empty, which is

6210

the default, then no initramfs is built.

</para>

<para>

Finally, for more information you can also see the

6215

6216

variable, which allows the generated image to be bundled

6217

inside the kernel image.

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>

6223

<info>

Patrick Williams

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

[diff] [blame]

6224

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 disk (initramfs)."

Patrick Williams

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

[diff] [blame]

</info>

6229

Controls whether or not the image recipe specified by

6230

Patrick Williams

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

[diff] [blame]

6231

is run through an extra pass

6232

(<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)

6233

during kernel compilation in order to build a single binary

6234

that contains both the kernel image and the initial RAM disk

6235

(initramfs).

6236

This makes use of the

kernel feature.

<note>

Using an extra compilation pass to bundle the initramfs

6241

avoids a circular dependency between the kernel recipe and

6242

the initramfs recipe should the initramfs include kernel

6243

modules.

6244

Should that be the case, the initramfs recipe depends on

6245

the kernel for the kernel modules, and the kernel depends

6246

on the initramfs recipe since the initramfs is bundled

6247

inside the kernel image.

6248

</note>

Patrick Williams

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

[diff] [blame]

</para>

<para>

The combined binary is deposited into the

6253

<filename>tmp/deploy</filename> directory, which is part

6254

of the

6255

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

6256

</para>

6257

6258

<para>

Patrick Williams

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

[diff] [blame]

6259

Setting the variable to "1" in a configuration file causes the

6260

OpenEmbedded build system to generate a kernel image with the

6261

initramfs specified in

6262

6263

bundled within:

Patrick Williams

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

[diff] [blame]

6264

6265

INITRAMFS_IMAGE_BUNDLE = "1"

</literallayout>

By default, the

class sets this variable to a null string as follows:

6270

Patrick Williams

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

[diff] [blame]

6271

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

6276

a configuration file.

6277

You cannot set the variable in a recipe file.

6278

</note>

6279

See the

Patrick Williams

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

[diff] [blame]

6280

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

6281

file for additional information.

</para>

</glossdef>

</glossentry>

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

6287

<info>

6288

INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)."

</info>

6293

Indicates list of filesystem images to concatenate and use

6294

as an initial RAM disk (<filename>initrd</filename>).

</para>

<para>

The <filename>INITRD</filename> variable is an optional

6299

variable used with the

Patrick Williams

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

[diff] [blame]

6300

Patrick Williams

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

[diff] [blame]

class.

</para>

</glossdef>

</glossentry>

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

6307

<info>

6308

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>

6313

When building a "live" bootable image (i.e. when

6314

6315

contains "live"), <filename>INITRD_IMAGE</filename>

6316

specifies the image recipe that should be built

6317

to provide the initial RAM disk image.

6318

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>

6330

<info>

6331

INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d."

</info>

6336

The filename of the initialization script as installed to

6337

<filename>${sysconfdir}/init.d</filename>.

</para>

<para>

This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.

6342

The variable is mandatory.

</para>

</glossdef>

</glossentry>

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

6348

<info>

6349

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>

6354

A list of the packages that contain initscripts.

6355

If multiple packages are specified, you need to append the package name

6356

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

6361

The variable is optional and defaults to the

</para>

</glossdef>

</glossentry>

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

6368

<info>

6369

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>

6374

Specifies the options to pass to <filename>update-rc.d</filename>.

6375

Here is an example:

6376

6377

INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."

</literallayout>

</para>

<para>

In this example, the script has a runlevel of 99,

6383

starts the script in initlevels 2 and 5, and

6384

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

6397

to the <filename>update-rc.d</filename> command.

6398

For more information on valid parameters, please see the

6399

<filename>update-rc.d</filename> manual page at

6400

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

6406

<info>

6407

INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe."

</info>

6412

Specifies the QA checks to skip for a specific package

6413

within a recipe.

6414

For example, to skip the check for symbolic link

6415

<filename>.so</filename> files in the main package of a

6416

recipe, add the following to the recipe.

6417

The package name override must be used, which in this

6418

example is <filename>${PN}</filename>:

6419

6420

INSANE_SKIP_${PN} += "dev-so"

</literallayout>

</para>

<para>

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

6426

section for a list of the valid QA checks you can

6427

specify using this variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

6432

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

6433

<info>

6434

INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file."

</info>

6439

By default, the <filename>tzdata</filename> recipe packages

6440

an <filename>/etc/timezone</filename> file.

6441

Set the <filename>INSTALL_TIMEZONE_FILE</filename>

6442

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]

6448

6449

<info>

6450

IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image."

</info>

6455

When the IPK backend is in use and package management

6456

is enabled on the target, you can use this variable to

6457

set up <filename>opkg</filename> in the target image

6458

to point to package feeds on a nominated server.

6459

Once the feed is established, you can perform

6460

installations or upgrades using the package manager

at runtime.

</para>

</glossdef>

</glossentry>

<!--

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

6468

6469

<para>

6470

An environment variable that defines the directory where

6471

post installation hooks are installed for the

6472

post install environment.

6473

This variable is fixed as follows:

6474

6475

${WORKDIR}/intercept_scripts

</literallayout>

</para>

<para>

After installation of a target's root filesystem,

6481

post installation scripts, which are essentially bash scripts,

6482

are all executed just a single time.

6483

Limiting execution of these scripts minimizes installation

6484

time that would be lengthened due to certain packages

6485

triggering redundant operations.

6486

For example, consider the installation of font packages

6487

as a common example.

6488

Without limiting the execution of post installation scripts,

6489

all font directories would be rescanned to create the

6490

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>

6509

<info>

6510

KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions."

</info>

6515

Defines the kernel architecture used when assembling

6516

the configuration.

6517

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

6530

<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.

</para>

</glossdef>

</glossentry>

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

6536

<info>

6537

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>

6542

A regular expression used by the build process to explicitly

6543

identify the kernel branch that is validated, patched,

6544

and configured during a build.

6545

You must set this variable to ensure the exact kernel

6546

branch you want is being used by the build process.

</para>

<para>

Values for this variable are set in the kernel's recipe

6551

file and the kernel's append file.

6552

For example, if you are using the Yocto Project kernel that

6553

is based on the Linux 3.14 kernel, the kernel recipe file

6554

is the

6555

<filename>meta/recipes-kernel/linux/linux-yocto_3.14.bb</filename>

6556

file.

6557

Following is an example for a kernel recipe file:

6558

6559

KBRANCH ?= "standard/base"

</literallayout>

</para>

<para>

This variable is also used from the kernel's append file

6565

to identify the kernel branch specific to a particular

6566

machine or target hardware.

6567

The kernel's append file is located in the BSP layer for

6568

a given machine.

6569

For example, the kernel append file for the Emenlow BSP is in the

6570

<filename>meta-intel</filename> Git repository and is named

6571

<filename>meta-emenlow/recipes-kernel/linux/linux-yocto_3.14.bbappend</filename>.

6572

Here are the related statements from the append file:

6573

6574

COMPATIBLE_MACHINE_emenlow-noemgd = "emenlow-noemgd"

6575

KMACHINE_emenlow-noemgd = "emenlow"

6576

KBRANCH_emenlow-noemgd = "standard/base"

6577

KERNEL_FEATURES_append_emenlow-noemgd = " features/drm-gma500/drm-gma500.scc"

6578

</literallayout>

6579

The <filename>KBRANCH</filename> statement identifies

6580

the kernel branch to use when building for the Emenlow

BSP.

</para>

</glossdef>

</glossentry>

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

6587

<info>

6588

KBUILD_DEFCONFIG[doc] = "Specifies an "in-tree" kernel configuration file for use during a kernel build."

</info>

6593

When used with the

6594

6595

class, specifies an "in-tree" kernel configuration file

6596

for use during a kernel build.

</para>

<para>

Typically, when using a <filename>defconfig</filename> to

6601

configure a kernel during a build, you place the

6602

file in your layer in the same manner as you would

6603

patch files and configuration fragment files (i.e.

6604

"out-of-tree").

6605

However, if you want to use a <filename>defconfig</filename>

6606

file that is part of the kernel tree (i.e. "in-tree"),

6607

you can use the

6608

<filename>KBUILD_DEFCONFIG</filename> variable to point

6609

to the <filename>defconfig</filename> file.

</para>

<para>

To use the variable, set it in the append file for your

6614

kernel recipe using the following form:

6615

6616

KBUILD_DEFCONFIG_<link linkend='var-KMACHINE'>KMACHINE</link> ?= <replaceable>defconfig_file</replaceable>

6617

</literallayout>

6618

Here is an example from a "raspberrypi2"

6619

<filename>KMACHINE</filename> build that uses a

6620

<filename>defconfig</filename> file named

6621

"bcm2709_defconfig":

6622

6623

KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"

6624

</literallayout>

6625

As an alternative, you can use the following within your

6626

append file:

6627

6628

KBUILD_DEFCONFIG_pn-linux-yocto ?= <replaceable>defconfig_file</replaceable>

6629

</literallayout>

6630

For more information on how to use the

6631

<filename>KBUILD_DEFCONFIG</filename> variable, see the

6632

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

6638

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

6639

<info>

6640

KERNEL_ALT_IMAGETYPE[doc] = "Specifies an alternate kernel image type for creation."

</info>

6645

Specifies an alternate kernel image type for creation in

6646

addition to the kernel image type specified using the

variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

6653

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

6654

<info>

6655

KERNEL_CLASSES[doc] = "A list of classes defining kernel image types that kernel class should inherit."

</info>

6660

A list of classes defining kernel image types that the

6661

6662

class should inherit.

6663

You typically append this variable to enable extended image

6664

types.

6665

An example is the "kernel-fitimage", which enables

6666

fitImage support and resides in

6667

<filename>meta/classes/kernel-fitimage.bbclass</filename>.

6668

You can register custom kernel image types with the

6669

<filename>kernel</filename> class using this variable.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

6674

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

6675

<info>

6676

KERNEL_DEVICETREE[doc] = "Specifies the name of the generated Linux kernel device tree (i.e. the <filename>.dtb</filename>) file."

</info>

6681

Specifies the name of the generated Linux kernel device tree

6682

(i.e. the <filename>.dtb</filename>) file.

6683

<note>

6684

Legacy support exists for specifying the full path

6685

to the device tree.

6686

However, providing just the <filename>.dtb</filename>

6687

file is preferred.

6688

</note>

6689

In order to use this variable, you must have the include

6690

files in your kernel recipe:

6691

6692

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]

6702

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

6703

<info>

6704

KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel."

</info>

6709

Specifies additional <filename>make</filename>

6710

command-line arguments the OpenEmbedded build system

6711

passes on when compiling the kernel.

</para>

</glossdef>

</glossentry>

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

6717

<info>

6718

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>

6723

Includes additional metadata from the Yocto Project kernel Git repository.

6724

In the OpenEmbedded build system, the default Board Support Packages (BSPs)

6725

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

6726

is provided through

6727

the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>

6728

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

6729

You can use the <filename>KERNEL_FEATURES</filename> variable to further

6730

add metadata for all BSPs.

</para>

<para>

The metadata you add through this variable includes config fragments and

6735

features descriptions,

6736

which usually includes patches as well as config fragments.

6737

You typically override the <filename>KERNEL_FEATURES</filename> variable

6738

for a specific machine.

6739

In this way, you can provide validated, but optional, sets of kernel

6740

configurations and features.

</para>

<para>

For example, the following adds <filename>netfilter</filename> to all

6745

the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>

6746

machine:

6747

6748

# Add netfilter to all linux-yocto kernels

6749

KERNEL_FEATURES="features/netfilter/netfilter.scc"

6750

6751

# Add sound support to the qemux86 machine

6752

KERNEL_FEATURES_append_qemux86=" cfg/sound.scc"

6753

</literallayout></para>

</glossdef>

</glossentry>

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

6758

<info>

6759

KERNEL_IMAGE_BASE_NAME[doc] = "The base name of the kernel image."

</info>

6764

The base name of the kernel image.

6765

This variable is set in the

as follows:

KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"

</literallayout>

</para>

<para>

See the

and

variables for additional information.

</para>

</glossdef>

</glossentry>

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

6788

<info>

6789

KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."

</info>

6794

Specifies the maximum size of the kernel image file in

6795

kilobytes.

6796

If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,

6797

the size of the kernel image file is checked against

6798

the set value during the

6799

6800

task.

6801

The task fails if the kernel image file is larger than

the setting.

</para>

<para>

<filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for

6807

target devices that have a limited amount of space in

6808

which the kernel image must be stored.

</para>

<para>

By default, this variable is not set, which means the

6813

size of the kernel image is not checked.

</para>

</glossdef>

</glossentry>

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

6819

<info>

6820

KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."

</info>

6825

The type of kernel to build for a device, usually set by the

6826

machine configuration files and defaults to "zImage".

6827

This variable is used

6828

when building the kernel and is passed to <filename>make</filename> as the target to

6829

build.

6830

</para>

Patrick Williams

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

[diff] [blame]

6831

6832

<para>

6833

If you want to build an alternate kernel image type, use the

6834

6835

variable.

6836

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

6841

<info>

6842

KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot"

</info>

6847

Lists kernel modules that need to be auto-loaded during

6848

boot.

6849

<note>

6850

This variable replaces the deprecated

variable.

</note>

</para>

<para>

You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename>

6858

variable anywhere that it can be

6859

recognized by the kernel recipe or by an out-of-tree kernel

6860

module recipe (e.g. a machine configuration file, a

6861

distribution configuration file, an append file for the

6862

recipe, or the recipe itself).

</para>

<para>

Specify it as follows:

6867

6868

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

6874

the OpenEmbedded build system to populate the

6875

<filename>/etc/modules-load.d/modname.conf</filename>

6876

file with the list of modules to be auto-loaded on boot.

6877

The modules appear one-per-line in the file.

6878

Here is an example of the most common use case:

6879

6880

KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>"

</literallayout>

</para>

<para>

For information on how to populate the

6886

<filename>modname.conf</filename> file with

6887

<filename>modprobe.d</filename> syntax lines, see the

variable.

</para>

</glossdef>

</glossentry>

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

6895

<info>

6896

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>

6901

Provides a list of modules for which the OpenEmbedded

6902

build system expects to find

6903

<filename>module_conf_</filename><replaceable>modname</replaceable>

6904

values that specify configuration for each of the modules.

6905

For information on how to provide those module

6906

configurations, see the

variable.

</para>

</glossdef>

</glossentry>

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

6914

<info>

6915

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>

6920

The location of the kernel sources.

6921

This variable is set to the value of the

within the

class.

For information on how this variable is used, see the

6927

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

6933

used to build modules, the OpenEmbedded build system also

6934

recognizes and uses the

6935

6936

variable, which is identical to the

6937

<filename>KERNEL_PATH</filename> variable.

6938

Both variables are common variables used by external

6939

Makefiles to point to the kernel source directory.

</para>

</glossdef>

</glossentry>

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

6945

<info>

6946

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>

6951

The location of the kernel sources.

6952

This variable is set to the value of the

within the

class.

For information on how this variable is used, see the

6958

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

6964

used to build modules, the OpenEmbedded build system also

6965

recognizes and uses the

6966

6967

variable, which is identical to the

6968

<filename>KERNEL_SRC</filename> variable.

6969

Both variables are common variables used by external

6970

Makefiles to point to the kernel source directory.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

6975

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

6976

<info>

6977

KERNEL_VERSION[doc] = "Specifies the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources."

</info>

6982

Specifies the version of the kernel as extracted from

6983

<filename>version.h</filename> or

6984

<filename>utsrelease.h</filename> within the kernel sources.

6985

Effects of setting this variable do not take affect until

6986

the kernel has been configured.

6987

Consequently, attempting to refer to this variable in

6988

contexts prior to configuration will not work.

</para>

</glossdef>

</glossentry>

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

6994

<info>

6995

KERNELDEPMODDEPEND[doc] = "Specifies whether or not to use the data referenced through the PKGDATA_DIR directory."

</info>

7000

Specifies whether the data referenced through

7001

7002

is needed or not.

7003

The <filename>KERNELDEPMODDEPEND</filename> does not

7004

control whether or not that data exists,

7005

but simply whether or not it is used.

7006

If you do not need to use the data, set the

7007

<filename>KERNELDEPMODDEPEND</filename> variable in your

7008

<filename>initramfs</filename> recipe.

7009

Setting the variable there when the data is not needed

7010

avoids a potential dependency loop.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

7015

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

7016

<info>

7017

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>

7022

Provides a short description of a configuration fragment.

7023

You use this variable in the <filename>.scc</filename>

7024

file that describes a configuration fragment file.

7025

Here is the variable used in a file named

7026

<filename>smp.scc</filename> to describe SMP being

7027

enabled:

7028

7029

define KFEATURE_DESCRIPTION "Enable SMP"

</literallayout>

</para>

</glossdef>

</glossentry>

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

7036

<info>

7037

KMACHINE[doc] = "The machine as known by the kernel."

</info>

7042

The machine as known by the kernel.

7043

Sometimes the machine name used by the kernel does not

7044

match the machine name used by the OpenEmbedded build

7045

system.

7046

For example, the machine name that the OpenEmbedded build

7047

system understands as

7048

<filename>core2-32-intel-common</filename> goes by a

7049

different name in the Linux Yocto kernel.

7050

The kernel understands that machine as

7051

<filename>intel-core2-32</filename>.

7052

For cases like these, the <filename>KMACHINE</filename>

7053

variable maps the kernel machine name to the OpenEmbedded

7054

build system machine name.

</para>

<para>

These mappings between different names occur in the

7059

Yocto Linux Kernel's <filename>meta</filename> branch.

7060

As an example take a look in the

7061

<filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename>

7062

file:

7063

7064

LINUX_VERSION_core2-32-intel-common = "3.19.0"

7065

COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"

7066

SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"

7067

SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"

7068

KMACHINE_core2-32-intel-common = "intel-core2-32"

7069

KBRANCH_core2-32-intel-common = "standard/base"

7070

KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"

7071

</literallayout>

7072

The <filename>KMACHINE</filename> statement says that

7073

the kernel understands the machine name as

7074

"intel-core2-32".

7075

However, the OpenEmbedded build system understands the

7076

machine as "core2-32-intel-common".

</para>

</glossdef>

</glossentry>

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

7083

<info>

7084

KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration."

</info>

7089

Defines the kernel type to be used in assembling the

7090

configuration.

7091

The linux-yocto recipes define "standard", "tiny",

7092

and "preempt-rt" kernel types.

7093

See the

7094

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"

7095

section in the Yocto Project Linux Kernel Development

7096

Manual for more information on kernel types.

</para>

<para>

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

7101

<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.

7102

The value you use must match the value used for the

7103

7104

value used by the kernel recipe.

</para>

</glossdef>

</glossentry>

</glossdiv>

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

7113

<info>

7114

LABELS[doc] = "Provides a list of targets for automatic configuration."

</info>

7119

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>

7131

<info>

7132

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>

7137

Lists the layers that this recipe depends upon, separated by spaces.

7138

Optionally, you can specify a specific layer version for a dependency

7139

by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"

7140

to be compared against

7141

7142

in this case).

7143

An error will be produced if any dependency is missing or

7144

the version numbers do not match exactly (if specified).

7145

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

7146

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

7147

<filename>LAYERDEPENDS_mylayer</filename>).

</para>

</glossdef>

</glossentry>

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

7153

<info>

7154

LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer."

</info>

7159

When used inside the <filename>layer.conf</filename> configuration

7160

file, this variable provides the path of the current layer.

7161

This variable is not available outside of <filename>layer.conf</filename>

7162

and references are expanded immediately when parsing of the file completes.

</para>

</glossdef>

</glossentry>

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

7168

<info>

7169

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>

7174

Optionally specifies the version of a layer as a single number.

7175

You can use this within

7176

7177

for another layer in order to depend on a specific version

7178

of the layer.

7179

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

7180

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

7181

<filename>LAYERVERSION_mylayer</filename>).

</para>

</glossdef>

</glossentry>

<info>

LD[doc] = "Minimal command and arguments to run the linker."

</info>

7193

The minimal command and arguments used to run the

linker.

</para>

</glossdef>

</glossentry>

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

7200

<info>

7201

LDFLAGS[doc] = "Specifies the flags to pass to the linker."

</info>

7206

Specifies the flags to pass to the linker.

7207

This variable is exported to an environment

7208

variable and thus made visible to the software being

7209

built during the compilation step.

</para>

<para>

Default initialization for <filename>LDFLAGS</filename>

7214

varies depending on what is being built:

when building for the target

</para></listitem>

when building for the build host (i.e.

7223

<filename>-native</filename>)

</para></listitem>

when building for an SDK (i.e.

7228

<filename>nativesdk-</filename>)

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

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

7236

<info>

7237

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>

7242

Specifies the lead (or primary) compiled library file

7243

(<filename>.so</filename>) that the

7244

7245

class applies its naming policy to given a recipe that

7246

packages multiple libraries.

</para>

<para>

This variable works in conjunction with the

7251

<filename>debian</filename> class.

</para>

</glossdef>

</glossentry>

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

7257

<info>

7258

LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code."

</info>

7263

Checksums of the license text in the recipe source code.

</para>

<para>

This variable tracks changes in license text of the source

7268

code files.

7269

If the license text is changed, it will trigger a build

7270

failure, which gives the developer an opportunity to review any

license change.

</para>

<para>

This variable must be defined for all recipes (unless

7276

7277

is set to "CLOSED").</para>

7278

<para>For more information, see the

7279

"<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>

7280

Tracking License Changes</link>" section.

</para>

</glossdef>

</glossentry>

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

7286

<info>

7287

LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &, '|', and parentheses can be used."

</info>

7292

The list of source licenses for the recipe.

7293

Follow these rules:

7294

7295

<listitem><para>Do not use spaces within individual

7296

license names.</para></listitem>

7297

<listitem><para>Separate license names using

7298

| (pipe) when there is a choice between licenses.

7299

</para></listitem>

7300

<listitem><para>Separate license names using

7301

& (ampersand) when multiple licenses exist

7302

that cover different parts of the source.

7303

</para></listitem>

7304

<listitem><para>You can use spaces between license

7305

names.</para></listitem>

7306

<listitem><para>For standard licenses, use the names

7307

of the files in

7308

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

7309

or the

7310

7311

flag names defined in

7312

<filename>meta/conf/licenses.conf</filename>.

</para></listitem>

</itemizedlist>

</para>

<para>

Here are some examples:

7319

7320

LICENSE = "LGPLv2.1 | GPLv3"

7321

LICENSE = "MPL-1 & LGPLv2.1"

7322

LICENSE = "GPLv2+"

7323

</literallayout>

7324

The first example is from the recipes for Qt, which the user

7325

may choose to distribute under either the LGPL version

7326

2.1 or GPL version 3.

7327

The second example is from Cairo where two licenses cover

7328

different parts of the source code.

7329

The final example is from <filename>sysstat</filename>,

7330

which presents a single license.

</para>

<para>

You can also specify licenses on a per-package basis to

7335

handle situations where components of the output have

7336

different licenses.

7337

For example, a piece of software whose code is

7338

licensed under GPLv2 but has accompanying documentation

7339

licensed under the GNU Free Documentation License 1.2 could

7340

be specified as follows:

7341

7342

LICENSE = "GFDL-1.2 & GPLv2"

7343

LICENSE_${PN} = "GPLv2"

7344

LICENSE_${PN}-doc = "GFDL-1.2"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

7350

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

7351

<info>

7352

LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."

</info>

7357

Setting <filename>LICENSE_CREATE_PACKAGE</filename>

7358

to "1" causes the OpenEmbedded build system to create

7359

an extra package (i.e.

7360

<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)

7361

for each recipe and to add those packages to the

</para>

<para>

The <filename>${PN}-lic</filename> package installs a

7367

directory in <filename>/usr/share/licenses</filename>

7368

named <filename>${PN}</filename>, which is the recipe's

7369

base name, and installs files in that directory that

7370

contain license and copyright information (i.e. copies of

7371

the appropriate license files from

7372

<filename>meta/common-licenses</filename> that match the

7373

licenses specified in the

7374

7375

variable of the recipe metadata and copies of files marked

7376

in

7377

7378

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

7388

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

7393

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

7394

<info>

7395

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>

7400

Specifies additional flags for a recipe you must

7401

whitelist through

7402

7403

in order to allow the recipe to be built.

7404

When providing multiple flags, separate them with

spaces.

</para>

<para>

This value is independent of

7410

7411

and is typically used to mark recipes that might

7412

require additional licenses in order to be used in a

7413

commercial product.

7414

For more information, see the

7415

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

7422

<info>

7423

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>

7428

Lists license flags that when specified in

7429

7430

within a recipe should not prevent that recipe from being

7431

built.

7432

This practice is otherwise known as "whitelisting"

7433

license flags.

7434

For more information, see the

section.

</para>

</glossdef>

</glossentry>

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

7442

<info>

7443

LICENSE_PATH[doc] = "Path to additional licenses used during the build."

</info>

7448

Path to additional licenses used during the build.

7449

By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>

7450

to define the directory that holds common license text used during the build.

7451

The <filename>LICENSE_PATH</filename> variable allows you to extend that

7452

location to other areas that have additional licenses:

7453

7454

LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>"

</literallayout>

</para>

</glossdef>

</glossentry>

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

7461

<info>

7462

LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration."

</info>

7467

Defines the kernel type to be used in assembling the

7468

configuration.

7469

The linux-yocto recipes define "standard", "tiny", and

7470

"preempt-rt" kernel types.

7471

See the

7472

"<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"

7473

section in the Yocto Project Linux Kernel Development

7474

Manual for more information on kernel types.

</para>

<para>

If you do not specify a

7479

<filename>LINUX_KERNEL_TYPE</filename>, it defaults to

"standard".

Together with

the <filename>LINUX_KERNEL_TYPE</filename> variable

7484

defines the search

7485

arguments used by the kernel tools to find the appropriate

7486

description within the kernel

7487

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

7488

with which to build out the sources and configuration.

</para>

</glossdef>

</glossentry>

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

7494

<info>

7495

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>

7500

The Linux version from <filename>kernel.org</filename>

7501

on which the Linux kernel image being built using the

7502

OpenEmbedded build system is based.

7503

You define this variable in the kernel recipe.

7504

For example, the <filename>linux-yocto-3.4.bb</filename>

7505

kernel recipe found in

7506

<filename>meta/recipes-kernel/linux</filename>

7507

defines the variables as follows:

7508

7509

LINUX_VERSION ?= "3.4.24"

</literallayout>

</para>

<para>

The <filename>LINUX_VERSION</filename> variable is used to

7515

define <link linkend='var-PV'><filename>PV</filename></link>

7516

for the recipe:

7517

7518

PV = "${LINUX_VERSION}+git${SRCPV}"

</literallayout>

</para>

</glossdef>

</glossentry>

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

7525

<info>

7526

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>

7531

A string extension compiled into the version

7532

string of the Linux kernel built with the OpenEmbedded

7533

build system.

7534

You define this variable in the kernel recipe.

7535

For example, the linux-yocto kernel recipes all define

7536

the variable as follows:

7537

7538

LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"

</literallayout>

</para>

<para>

Defining this variable essentially sets the

7544

Linux kernel configuration item

7545

<filename>CONFIG_LOCALVERSION</filename>, which is visible

7546

through the <filename>uname</filename> command.

7547

Here is an example that shows the extension assuming it

7548

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>

7564

Specifies the directory to which the OpenEmbedded build

7565

system writes overall log files.

7566

The default directory is <filename>${TMPDIR}/log</filename>.

</para>

<para>

For the directory containing logs specific to each task,

7571

see the <link linkend='var-T'><filename>T</filename></link>

variable.

</para>

</glossdef>

</glossentry>

</glossdiv>

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

7582

<info>

7583

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>

7588

Specifies the target device for which the image is built.

7589

You define <filename>MACHINE</filename> in the

7590

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

7591

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

7592

By default, <filename>MACHINE</filename> is set to

7593

"qemux86", which is an x86-based architecture machine to

7594

be emulated using QEMU:

MACHINE ?= "qemux86"

</literallayout>

</para>

<para>

The variable corresponds to a machine configuration file of the

7602

same name, through which machine-specific configurations are set.

7603

Thus, when <filename>MACHINE</filename> is set to "qemux86" there

7604

exists the corresponding <filename>qemux86.conf</filename> machine

7605

configuration file, which can be found in the

7606

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

7607

in <filename>meta/conf/machine</filename>.

</para>

<para>

The list of machines supported by the Yocto Project as

7612

shipped include the following:

7613

7614

MACHINE ?= "qemuarm"

7615

MACHINE ?= "qemuarm64"

7616

MACHINE ?= "qemumips"

7617

MACHINE ?= "qemumips64"

7618

MACHINE ?= "qemuppc"

7619

MACHINE ?= "qemux86"

7620

MACHINE ?= "qemux86-64"

7621

MACHINE ?= "genericx86"

7622

MACHINE ?= "genericx86-64"

7623

MACHINE ?= "beaglebone"

7624

MACHINE ?= "mpc8315e-rdb"

7625

MACHINE ?= "edgerouter"

7626

</literallayout>

7627

The last five are Yocto Project reference hardware boards, which

7628

are provided in the <filename>meta-yocto-bsp</filename> layer.

7629

<note>Adding additional Board Support Package (BSP) layers

7630

to your configuration adds new possible settings for

7631

<filename>MACHINE</filename>.

</note>

</para>

</glossdef>

</glossentry>

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

7638

<info>

7639

MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH."

</info>

7644

Specifies the name of the machine-specific architecture.

7645

This variable is set automatically from

or

You should not hand-edit the

7650

<filename>MACHINE_ARCH</filename> variable.

</para>

</glossdef>

</glossentry>

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

7656

<info>

7657

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>

7662

A list of required machine-specific packages to install as part of

7663

the image being built.

7664

The build process depends on these packages being present.

7665

Furthermore, because this is a "machine essential" variable, the list of

7666

packages are essential for the machine to boot.

7667

The impact of this variable affects images based on

7668

<filename>packagegroup-core-boot</filename>,

7669

including the <filename>core-image-minimal</filename> image.

</para>

<para>

This variable is similar to the

7674

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

7675

variable with the exception that the image being built has a build

7676

dependency on the variable's list of packages.

7677

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

7682

<filename>example-init</filename> to be run during boot to initialize the hardware.

7683

In this case, you would use the following in the machine's

7684

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

7685

7686

MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"

</literallayout>

</para>

</glossdef>

</glossentry>

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

7693

<info>

7694

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>

7699

A list of recommended machine-specific packages to install as part of

7700

the image being built.

7701

The build process does not depend on these packages being present.

7702

However, because this is a "machine essential" variable, the list of

7703

packages are essential for the machine to boot.

7704

The impact of this variable affects images based on

7705

<filename>packagegroup-core-boot</filename>,

7706

including the <filename>core-image-minimal</filename> image.

</para>

<para>

This variable is similar to the

7711

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

7712

variable with the exception that the image being built does not have a build

7713

dependency on the variable's list of packages.

7714

In other words, the image will still build if a package in this list is not found.

7715

Typically, this variable is used to handle essential kernel modules, whose

7716

functionality may be selected to be built into the kernel rather than as a module,

7717

in which case a package will not be produced.

</para>

<para>

Consider an example where you have a custom kernel where a specific touchscreen

7722

driver is required for the machine to be usable.

7723

However, the driver can be built as a module or

7724

into the kernel depending on the kernel configuration.

7725

If the driver is built as a module, you want it to be installed.

7726

But, when the driver is built into the kernel, you still want the

7727

build to succeed.

7728

This variable sets up a "recommends" relationship so that in the latter case,

7729

the build will not fail due to the missing package.

7730

To accomplish this, assuming the package for the module was called

7731

<filename>kernel-module-ab123</filename>, you would use the

7732

following in the machine's <filename>.conf</filename> configuration

7733

file:

7734

7735

MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"

7736

</literallayout>

Patrick Williams

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

[diff] [blame]

7737

<note>

7738

In this example, the

7739

<filename>kernel-module-ab123</filename> recipe

7740

needs to explicitly set its

7741

7742

variable to ensure that BitBake does not use the

7743

kernel recipe's

7744

7745

variable to satisfy the dependency.

7746

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

7751

or touchscreen drivers (depending on the machine).

</para>

</glossdef>

</glossentry>

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

7757

<info>

7758

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>

7763

A list of machine-specific packages to install as part of the

7764

image being built that are not essential for the machine to boot.

7765

However, the build process for more fully-featured images

7766

depends on the packages being present.

</para>

<para>

This variable affects all images based on

7771

<filename>packagegroup-base</filename>, which does not include the

7772

<filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>

images.

</para>

<para>

The variable is similar to the

7778

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

7779

variable with the exception that the image being built has a build

7780

dependency on the variable's list of packages.

7781

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

7786

essential for the machine to boot the image.

7787

However, if you are building a more fully-featured image, you want to enable

7788

the WiFi.

7789

The package containing the firmware for the WiFi hardware is always

7790

expected to exist, so it is acceptable for the build process to depend upon

7791

finding the package.

7792

In this case, assuming the package for the firmware was called

7793

<filename>wifidriver-firmware</filename>, you would use the following in the

7794

<filename>.conf</filename> file for the machine:

7795

7796

MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"

</literallayout>

</para>

</glossdef>

</glossentry>

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

7803

<info>

7804

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>

7809

A list of machine-specific packages to install as part of the

7810

image being built that are not essential for booting the machine.

7811

The image being built has no build dependency on this list of packages.

</para>

<para>

This variable affects only images based on

7816

<filename>packagegroup-base</filename>, which does not include the

7817

<filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>

images.

</para>

<para>

This variable is similar to the

7823

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

7824

variable with the exception that the image being built does not have a build

7825

dependency on the variable's list of packages.

7826

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

7831

For the machine to boot the image.

7832

However, if you are building a more fully-featured image, you want to enable

7833

WiFi.

7834

In this case, the package containing the WiFi kernel module will not be produced

7835

if the WiFi driver is built into the kernel, in which case you still want the

7836

build to succeed instead of failing as a result of the package not being found.

7837

To accomplish this, assuming the package for the module was called

7838

<filename>kernel-module-examplewifi</filename>, you would use the

7839

following in the <filename>.conf</filename> file for the machine:

7840

7841

MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"

</literallayout>

</para>

</glossdef>

</glossentry>

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

7848

<info>

7849

MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports."

</info>

7854

Specifies the list of hardware features the

7855

7856

of supporting.

7857

For related information on enabling features, see the

and

variables.

</para>

<para>

For a list of hardware features supported by the Yocto

7867

Project as shipped, see the

7868

"<link linkend='ref-features-machine'>Machine Features</link>"

section.

</para>

</glossdef>

</glossentry>

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

7875

<info>

7876

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>

7881

Features to be added to

7882

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

7883

if not also present in

7884

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

7889

It is not intended to be user-configurable.

7890

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

7891

being backfilled for all machine configurations.

7892

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>

7899

<info>

7900

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>

7905

Features from

7906

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

7907

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

7908

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

7909

during the build.

7910

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

more information.

</para>

</glossdef>

</glossentry>

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

7917

<info>

Patrick Williams

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

[diff] [blame]

7918

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]

7923

A colon-separated list of overrides that apply to the

7924

current machine.

7925

By default, this list includes the value of

7926

Patrick Williams

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

[diff] [blame]

7927

</para>

7928

7929

<para>

Patrick Williams

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

[diff] [blame]

7930

You can extend <filename>MACHINEOVERRIDES</filename>

7931

to add extra overrides that should apply to a machine.

7932

For example, all machines emulated in QEMU (e.g.

7933

<filename>qemuarm</filename>, <filename>qemux86</filename>,

7934

and so forth) include a file named

7935

<filename>meta/conf/machine/include/qemu.inc</filename>

7936

that prepends the following override to

7937

<filename>MACHINEOVERRIDES</filename>:

Patrick Williams

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

[diff] [blame]

7938

Patrick Williams

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

[diff] [blame]

7939

MACHINEOVERRIDES =. "qemuall:"

Patrick Williams

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

[diff] [blame]

7940

</literallayout>

Patrick Williams

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

[diff] [blame]

7941

This override allows variables to be overriden for all

7942

machines emulated in QEMU, like in the following example

7943

from the <filename>connman-conf</filename> recipe:

7944

7945

SRC_URI_append_qemuall = "file://wired.config \

file://wired-setup \

"

</literallayout>

The underlying mechanism behind

7950

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

7951

included in the default value of

7952

Patrick Williams

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

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

7958

<info>

7959

MAINTAINER[doc] = "The email address of the distribution maintainer."

</info>

7964

The email address of the distribution maintainer.

</para>

</glossdef>

</glossentry>

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

7970

<info>

7971

MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."

</info>

7976

Specifies additional paths from which the OpenEmbedded

7977

build system gets source code.

7978

When the build system searches for source code, it first

7979

tries the local download directory.

7980

If that location fails, the build system tries locations

7981

defined by

7982

7983

the upstream source, and then locations specified by

7984

<filename>MIRRORS</filename> in that order.

</para>

<para>

Assuming your distribution

7989

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

7990

is "poky", the default value for

7991

<filename>MIRRORS</filename> is defined in the

7992

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

Patrick Williams

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

[diff] [blame]

7993

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

7999

<info>

8000

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>

8005

Specifies a prefix has been added to

8006

8007

of a recipe or package, such as a Multilib version.

8008

The variable is used in places where the prefix needs to be

8009

added to or removed from a the name (e.g. the

8010

8011

<filename>MLPREFIX</filename> gets set when a prefix has been

8012

added to <filename>PN</filename>.

Patrick Williams

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

[diff] [blame]

8013

<note>

8014

The "ML" in <filename>MLPREFIX</filename> stands for

8015

"MultiLib".

8016

This representation is historical and comes from

8017

a time when <filename>nativesdk</filename> was a suffix

8018

rather than a prefix on the recipe name.

8019

When <filename>nativesdk</filename> was turned into a

8020

prefix, it made sense to set

8021

<filename>MLPREFIX</filename> for it as well.

</note>

</para>

<para>

To help understand when <filename>MLPREFIX</filename>

8027

might be needed, consider when

8028

8029

is used to provide a <filename>nativesdk</filename> version

8030

of a recipe in addition to the target version.

8031

If that recipe declares build-time dependencies on tasks in

8032

other recipes by using

8033

8034

then a dependency on "foo" will automatically get rewritten

8035

to a dependency on "nativesdk-foo".

8036

However, dependencies like the following will not get

8037

rewritten automatically:

8038

8039

do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo"

8040

</literallayout>

8041

If you want such a dependency to also get transformed,

8042

you can do the following:

8043

8044

do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo"

8045

</literallayout>

Patrick Williams

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

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

8051

<info>

8052

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>

8057

This variable has been replaced by the

8058

<filename>KERNEL_MODULE_AUTOLOAD</filename> variable.

8059

You should replace all occurrences of

8060

<filename>module_autoload</filename> with additions to

8061

<filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:

8062

8063

module_autoload_rfcomm = "rfcomm"

</literallayout>

</para>

<para>

should now be replaced with:

8069

8070

KERNEL_MODULE_AUTOLOAD += "rfcomm"

</literallayout>

See the

variable for more information.

</para>

</glossdef>

</glossentry>

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

8080

<info>

8081

module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file."

</info>

8086

Specifies

8087

<ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>

8088

syntax lines for inclusion in the

8089

<filename>/etc/modprobe.d/modname.conf</filename> file.

</para>

<para>

You can use this variable anywhere that it can be

8094

recognized by the kernel recipe or out-of-tree kernel

8095

module recipe (e.g. a machine configuration file, a

8096

distribution configuration file, an append file for the

8097

recipe, or the recipe itself).

8098

If you use this variable, you must also be sure to list

8099

the module name in the

variable.

</para>

<para>

Here is the general syntax:

8106

8107

module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>"

8108

</literallayout>

8109

You must use the kernel module name override.

</para>

<para>

Run <filename>man modprobe.d</filename> in the shell to

8114

find out more information on the exact syntax

8115

you want to provide with <filename>module_conf</filename>.

</para>

<para>

Including <filename>module_conf</filename> causes the

8120

OpenEmbedded build system to populate the

8121

<filename>/etc/modprobe.d/modname.conf</filename>

8122

file with <filename>modprobe.d</filename> syntax lines.

8123

Here is an example that adds the options

8124

8125

to a module named <filename>mymodule</filename>:

8126

8127

module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"

</literallayout>

</para>

<para>

For information on how to specify kernel modules to

8133

auto-load on boot, see the

variable.

</para>

</glossdef>

</glossentry>

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

8141

<info>

8142

MODULE_IMAGE_BASE_NAME[doc] = "The base name of the kernel modules tarball."

</info>

8147

The base name of the kernel modules tarball.

8148

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>

8170

<info>

8171

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>

8176

Controls creation of the <filename>modules-*.tgz</filename>

8177

file.

8178

Set this variable to "0" to disable creation of this

8179

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]

8185

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

8186

<info>

8187

MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories."

</info>

8192

Serves the same purpose as

8193

8194

but for the "HOST" system, in situations that involve a

8195

"HOST" and a "TARGET" system.

8196

See the

8197

8198

variable for more information.

</para>

<para>

The default value of this variable is:

8203

8204

${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS}

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

8210

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

8211

<info>

8212

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]

8217

Uniquely identifies the type of the target system for

8218

which packages are being built.

8219

This variable allows output for different types of target

8220

systems to be put into different subdirectories of the same

output directory.

</para>

<para>

The default value of this variable is:

8226

8227

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

8238

8239

is the corresponding variable for the host system in

8240

situations that involve a "HOST" and a "TARGET" system.

8241

See the

8242

8243

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>

8253

<info>

8254

NATIVELSBSTRING[doc] = "A string identifying the host distribution."

</info>

8259

A string identifying the host distribution.

8260

Strings consist of the host distributor ID

8261

followed by the release, as reported by the

8262

<filename>lsb_release</filename> tool

8263

or as read from <filename>/etc/lsb-release</filename>.

8264

For example, when running a build on Ubuntu 12.10, the value

8265

is "Ubuntu-12.10".

8266

If this information is unable to be determined, the value

8267

resolves to "Unknown".

</para>

<para>

This variable is used by default to isolate native shared

8272

state packages for different distributions (e.g. to avoid

8273

problems with <filename>glibc</filename> version

8274

incompatibilities).

8275

Additionally, the variable is checked against

8276

8277

if that variable is set.

</para>

</glossdef>

</glossentry>

<info>

NM[doc] = "Minimal command and arguments to run 'nm'."

</info>

8289

The minimal command and arguments to run

8290

<filename>nm</filename>.

</para>

</glossdef>

</glossentry>

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

8296

<info>

8297

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>

8302

Prevents installation of all "recommended-only" packages.

8303

Recommended-only packages are packages installed only

through the

variable).

Setting the <filename>NO_RECOMMENDATIONS</filename> variable

8308

to "1" turns this feature on:

8309

8310

NO_RECOMMENDATIONS = "1"

</literallayout>

</para>

<para>

You can set this variable globally in your

8316

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

8317

a specific image recipe by using the recipe name override:

8318

8319

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

8325

packages using this variable and some other packages are

8326

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

8327

8328

variable), the OpenEmbedded build system ignores your

8329

request and will install the packages to avoid dependency

8330

errors.

8331

<note>

8332

Some recommended packages might be required for certain

8333

system functionality, such as kernel modules.

8334

It is up to you to add packages with the

variable.

</note>

</para>

<para>

Support for this variable exists only when using the

8342

IPK and RPM packaging backend.

8343

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>

8357

<info>

8358

NOHDD[doc] = "Causes the OpenEmbedded build system to skip building the .hddimg image."

</info>

8363

Causes the OpenEmbedded build system to skip building the

8364

<filename>.hddimg</filename> image.

8365

The <filename>NOHDD</filename> variable is used with the

Patrick Williams

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

[diff] [blame]

8366

Patrick Williams

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

[diff] [blame]

8367

class.

8368

Set the variable to "1" to prevent the

8369

<filename>.hddimg</filename> image from being built.

</para>

</glossdef>

</glossentry>

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

8375

<info>

8376

NOISO[doc] = "Causes the OpenEmbedded build system to skip building the ISO image."

</info>

8381

Causes the OpenEmbedded build system to skip building the

8382

ISO image.

8383

The <filename>NOISO</filename> variable is used with the

Patrick Williams

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

[diff] [blame]

8384

Patrick Williams

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

[diff] [blame]

8385

class.

8386

Set the variable to "1" to prevent the ISO image from

8387

being built.

8388

To enable building an ISO image, set the variable to "0".

</para>

</glossdef>

</glossentry>

</glossdiv>

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

8398

<info>

8399

OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'."

</info>

8404

The minimal command and arguments to run

8405

<filename>objcopy</filename>.

</para>

</glossdef>

</glossentry>

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

8411

<info>

8412

OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'."

</info>

8417

The minimal command and arguments to run

8418

<filename>objdump</filename>.

</para>

</glossdef>

</glossentry>

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

8424

<info>

8425

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.

8434

The sed command alters any paths in configuration scripts

8435

that have been set up during compilation.

8436

Inheriting this class results in all paths in these scripts

8437

being changed to point into the

8438

<filename>sysroots/</filename> directory so that all builds

8439

that use the script will use the correct directories

8440

for the cross compiling layout.

</para>

<para>

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

8445

in the

8446

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

8447

for details on how this class applies these additional

8448

sed command arguments.

8449

For general information on the

8450

<filename>binconfig.bbclass</filename> class, see the

8451

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

8458

<info>

8459

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>

8464

An internal variable used to tell the OpenEmbedded build

8465

system what Python modules to import for every Python

8466

function run by the system.

</para>

<note>

Do not set this variable.

8471

It is for internal use only.

</note>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

8476

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

8477

<info>

8478

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>

8483

The name of the build environment setup script for the

8484

purposes of setting up the environment within the

8485

extensible SDK.

8486

The default value is "oe-init-build-env".

</para>

<para>

If you use a custom script to set up your build

8491

environment, set the

8492

<filename>OE_INIT_ENV_SCRIPT</filename> variable to its

name.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

8498

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

8499

<info>

8500

OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system."

</info>

8505

Controls how the OpenEmbedded build system spawns

8506

interactive terminals on the host development system

8507

(e.g. using the BitBake command with the

8508

<filename>-c devshell</filename> command-line option).

8509

For more information, see the

8510

"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section

8511

in the Yocto Project Development Manual.

</para>

<para>

You can use the following values for the

8516

<filename>OE_TERMINAL</filename> variable:

auto

gnome

xfce

rxvt

screen

konsole

none

</literallayout>

</para>

</glossdef>

</glossentry>

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

8531

<info>

8532

OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced."

</info>

8537

The directory from which the top-level build environment

8538

setup script is sourced.

8539

The Yocto Project makes two top-level build environment

8540

setup scripts available:

and

When you run one of these scripts, the

8545

<filename>OEROOT</filename> variable resolves to the

8546

directory that contains the script.

</para>

<para>

For additional information on how this variable is used,

8551

see the initialization scripts.

</para>

</glossdef>

</glossentry>

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

8557

<info>

8558

OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support."

</info>

8563

Declares the oldest version of the Linux kernel that the

8564

produced binaries must support.

8565

This variable is passed into the build of the Embedded

8566

GNU C Library (<filename>glibc</filename>).

</para>

<para>

The default for this variable comes from the

8571

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

8572

file.

8573

You can override this default by setting the variable

8574

in a custom distribution configuration file.

</para>

</glossdef>

</glossentry>

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

8580

<info>

Patrick Williams

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

[diff] [blame]

8581

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]

8586

A colon-separated list of overrides that currently apply.

8587

Overrides are a BitBake mechanism that allows variables to

8588

be selectively overridden at the end of parsing.

8589

The set of overrides in <filename>OVERRIDES</filename>

8590

represents the "state" during building, which includes

8591

the current recipe being built, the machine for which

8592

it is being built, and so forth.

</para>

<para>

As an example, if the string "an-override" appears as an

8597

element in the colon-separated list in

8598

<filename>OVERRIDES</filename>, then the following

8599

assignment will override <filename>FOO</filename> with the

8600

value "overridden" at the end of parsing:

8601

8602

FOO_an-override = "overridden"

8603

</literallayout>

8604

See the

Patrick Williams

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

[diff] [blame]

8605

"<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"

Patrick Williams

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

[diff] [blame]

8606

section in the BitBake User Manual for more information on

8607

the overrides mechanism.

</para>

<para>

The default value of <filename>OVERRIDES</filename>

8612

includes the values of the

and

variables.

Another important override included by default is

8619

<filename>pn-${PN}</filename>.

8620

This override allows variables to be set for a single

8621

recipe within configuration (<filename>.conf</filename>)

files.

Here is an example:

FOO_pn-myrecipe = "myrecipe-specific value"

8626

</literallayout>

8627

8628

An easy way to see what overrides apply is to search for

8629

<filename>OVERRIDES</filename> in the output of the

8630

<filename>bitbake -e</filename> command.

8631

See the

8632

"<link linkend='usingpoky-debugging-viewing-variable-values'>Viewing Variable Values</link>"

8633

section for more information.

8634

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

8649

The recipe name and version.

8650

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

${PN}-${PV}

</literallayout>

</para>

</glossdef>

</glossentry>

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

8659

<info>

8660

PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."

</info>

8665

The architecture of the resulting package or packages.

</para>

<para>

By default, the value of this variable is set to

8670

8671

when building for the target,

8672

<filename>BUILD_ARCH</filename> when building for the

8673

build host and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building

8674

for the SDK.

8675

However, if your recipe's output packages are built

8676

specific to the target machine rather than general for

8677

the architecture of the machine, you should set

8678

<filename>PACKAGE_ARCH</filename> to the value of

8679

8680

in the recipe as follows:

8681

8682

PACKAGE_ARCH = "${MACHINE_ARCH}"

</literallayout>

</para>

</glossdef>

</glossentry>

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

8689

<info>

8690

PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority."

</info>

8695

Specifies a list of architectures compatible with

8696

the target machine.

8697

This variable is set automatically and should not

8698

normally be hand-edited.

8699

Entries are separated using spaces and listed in order

8700

of priority.

8701

The default value for

8702

<filename>PACKAGE_ARCHS</filename> is "all any noarch

8703

${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".

</para>

</glossdef>

</glossentry>

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

8709

<info>

8710

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>

8715

Enables easily adding packages to

8716

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

8717

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

8718

so that those added packages can pick up files that would normally be

8719

included in the default package.

</para>

</glossdef>

</glossentry>

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

8725

<info>

8726

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>

8731

This variable, which is set in the

8732

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

8733

the <filename>conf</filename> folder of the

8734

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

8735

specifies the package manager the OpenEmbedded build system

8736

uses when packaging data.

</para>

<para>

You can provide one or more of the following arguments for

8741

the variable:

8742

8743

PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"

8744

</literallayout>

8745

<note><title>Warning</title>

8746

While it is a legal option, the

8747

<filename>package_tar</filename> class is broken

8748

and is not supported.

8749

It is recommended that you do not use it.

8750

</note>

8751

The build system uses only the first argument in the list

8752

as the package manager when creating your image or SDK.

8753

However, packages will be created using any additional

8754

packaging classes you specify.

8755

For example, if you use the following in your

8756

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

8757

8758

PACKAGE_CLASSES ?= "package_ipk"

8759

</literallayout>

8760

The OpenEmbedded build system uses the IPK package manager

8761

to create your image or SDK.

</para>

<para>

For information on packaging and build performance effects

8766

as a result of the package manager in use, see the

8767

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

8774

<info>

8775

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>

8780

Determines how to split up the binary and debug information

8781

when creating <filename>*-dbg</filename> packages to be

8782

used with the GNU Project Debugger (GDB).

</para>

<para>

With the

<filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,

8788

you can control where debug information, which can include

8789

or exclude source files, is stored:

8790

8791

8792

".debug": Debug symbol files are placed next

8793

to the binary in a <filename>.debug</filename>

8794

directory on the target.

8795

For example, if a binary is installed into

8796

<filename>/bin</filename>, the corresponding debug

8797

symbol files are installed in

8798

<filename>/bin/.debug</filename>.

8799

Source files are placed in

8800

<filename>/usr/src/debug</filename>.

8801

This is the default behavior.

8802

</para></listitem>

8803

8804

"debug-file-directory": Debug symbol files are

8805

placed under <filename>/usr/lib/debug</filename>

8806

on the target, and separated by the path from where

8807

the binary is installed.

8808

For example, if a binary is installed in

8809

<filename>/bin</filename>, the corresponding debug

8810

symbols are installed in

8811

<filename>/usr/lib/debug/bin</filename>.

8812

Source files are placed in

8813

<filename>/usr/src/debug</filename>.

8814

</para></listitem>

8815

8816

"debug-without-src": The same behavior as

8817

".debug" previously described with the exception

8818

that no source files are installed.

</para></listitem>.

</itemizedlist>

</para>

<para>

You can find out more about debugging using GDB by reading

8825

the

8826

"<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"

8827

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

8832

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

8833

<info>

8834

PACKAGE_EXCLUDE_COMPLEMENTARY[doc] = "Prevents specific packages from being installed when you are installing complementary packages."

</info>

8839

Prevents specific packages from being installed when

8840

you are installing complementary packages.

</para>

<para>

You might find that you want to prevent installing certain

8845

packages when you are installing complementary packages.

8846

For example, if you are using

8847

8848

to install <filename>dev-pkgs</filename>, you might not want

8849

to install all packages from a particular multilib.

8850

If you find yourself in this situation, you can use the

8851

<filename>PACKAGE_EXCLUDE_COMPLEMENTARY</filename> variable

8852

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]

8858

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

8859

<info>

8860

PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated."

</info>

8865

Lists packages that should not be installed into an image.

8866

For example:

8867

8868

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

8874

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

8875

a specific image recipe by using the recipe name override:

8876

8877

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

</literallayout>

</para>

<para>

If you choose to not install

8883

a package using this variable and some other package is

8884

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

8885

8886

variable), the OpenEmbedded build system generates a fatal

8887

installation error.

8888

Because the build system halts the process with a fatal

8889

error, you can use the variable with an iterative

8890

development process to remove specific components from a

system.

</para>

<para>

Support for this variable exists only when using the

8896

IPK and RPM packaging backend.

8897

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>

8911

<info>

8912

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>

8917

Specifies the list of architectures compatible with the device CPU.

8918

This variable is useful when you build for several different devices that use

8919

miscellaneous processors such as XScale and ARM926-EJS.

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

8924

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

8925

<info>

8926

PACKAGE_FEED_ARCHS[doc] = "Specifies user-defined package architectures when constructing package feed URIs."

</info>

8931

Specifies the package architectures used as part of the

8932

package feed URIs during the build.

8933

The <filename>PACKAGE_FEED_ARCHS</filename> variable is

8934

appended to the final package feed URI, which is constructed

using the

and

variables.

</para>

<para>

Consider the following example where the

8944

<filename>PACKAGE_FEED_URIS</filename>,

8945

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

8946

<filename>PACKAGE_FEED_ARCHS</filename> variables are

8947

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

8948

8949

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

8950

https://example.com/packagerepos/updates"

8951

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

8952

PACKAGE_FEED_ARCHS = "all core2-64"

8953

</literallayout>

8954

Given these settings, the resulting package feeds are

8955

as follows:

8956

8957

https://example.com/packagerepos/release/rpm/all

8958

https://example.com/packagerepos/release/rpm/core2-64

8959

https://example.com/packagerepos/release/rpm-dev/all

8960

https://example.com/packagerepos/release/rpm-dev/core2-64

8961

https://example.com/packagerepos/updates/rpm/all

8962

https://example.com/packagerepos/updates/rpm/core2-64

8963

https://example.com/packagerepos/updates/rpm-dev/all

8964

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>

8971

<info>

8972

PACKAGE_FEED_BASE_PATHS[doc] = "Specifies base path used when constructing package feed URIs."

</info>

8977

Specifies the base path used when constructing package feed

8978

URIs.

8979

The <filename>PACKAGE_FEED_BASE_PATHS</filename> variable

8980

makes up the middle portion of a package feed URI used

8981

by the OpenEmbedded build system.

8982

The base path lies between the

and

variables.

</para>

<para>

Consider the following example where the

8991

<filename>PACKAGE_FEED_URIS</filename>,

8992

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

8993

<filename>PACKAGE_FEED_ARCHS</filename> variables are

8994

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

8995

8996

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

8997

https://example.com/packagerepos/updates"

8998

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

8999

PACKAGE_FEED_ARCHS = "all core2-64"

9000

</literallayout>

9001

Given these settings, the resulting package feeds are

9002

as follows:

9003

9004

https://example.com/packagerepos/release/rpm/all

9005

https://example.com/packagerepos/release/rpm/core2-64

9006

https://example.com/packagerepos/release/rpm-dev/all

9007

https://example.com/packagerepos/release/rpm-dev/core2-64

9008

https://example.com/packagerepos/updates/rpm/all

9009

https://example.com/packagerepos/updates/rpm/core2-64

9010

https://example.com/packagerepos/updates/rpm-dev/all

9011

https://example.com/packagerepos/updates/rpm-dev/core2-64

</literallayout>

</para>

</glossdef>

</glossentry>

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

9018

<info>

9019

PACKAGE_FEED_URIS[doc] = "Specifies the front portion of the package feed URI used by the OpenEmbedded build system."

</info>

9024

Specifies the front portion of the package feed URI

9025

used by the OpenEmbedded build system.

9026

Each final package feed URI is comprised of

9027

<filename>PACKAGE_FEED_URIS</filename>,

and

variables.

</para>

<para>

Consider the following example where the

9036

<filename>PACKAGE_FEED_URIS</filename>,

9037

<filename>PACKAGE_FEED_BASE_PATHS</filename>, and

9038

<filename>PACKAGE_FEED_ARCHS</filename> variables are

9039

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

9040

9041

PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \

9042

https://example.com/packagerepos/updates"

9043

PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"

9044

PACKAGE_FEED_ARCHS = "all core2-64"

9045

</literallayout>

9046

Given these settings, the resulting package feeds are

9047

as follows:

9048

9049

https://example.com/packagerepos/release/rpm/all

9050

https://example.com/packagerepos/release/rpm/core2-64

9051

https://example.com/packagerepos/release/rpm-dev/all

9052

https://example.com/packagerepos/release/rpm-dev/core2-64

9053

https://example.com/packagerepos/updates/rpm/all

9054

https://example.com/packagerepos/updates/rpm/core2-64

9055

https://example.com/packagerepos/updates/rpm-dev/all

9056

https://example.com/packagerepos/updates/rpm-dev/core2-64

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

9062

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

9063

<info>

9064

PACKAGE_GROUP[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES."

</info>

9069

The <filename>PACKAGE_GROUP</filename> variable has been

9070

renamed to

9071

9072

See the variable description for

9073

<filename>FEATURE_PACKAGES</filename> for information.

</para>

<para>

If if you use the <filename>PACKAGE_GROUP</filename>

9078

variable, the OpenEmbedded build system issues a warning

message.

</para>

</glossdef>

</glossentry>

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

9085

<info>

9086

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>

9091

The final list of packages passed to the package manager

9092

for installation into the image.

</para>

<para>

Because the package manager controls actual installation

9097

of all packages, the list of packages passed using

9098

<filename>PACKAGE_INSTALL</filename> is not the final list

9099

of packages that are actually installed.

9100

This variable is internal to the image construction

9101

code.

9102

Consequently, in general, you should use the

9103

9104

variable to specify packages for installation.

9105

The exception to this is when working with

the

image.

When working with an initial RAM disk (initramfs)

9110

image, use the <filename>PACKAGE_INSTALL</filename>

variable.

</para>

</glossdef>

</glossentry>

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

9117

<info>

9118

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>

9123

Specifies a list of packages the OpenEmbedded build

9124

system attempts to install when creating an image.

9125

If a listed package fails to install, the build system

9126

does not generate an error.

9127

This variable is generally not user-defined.

</para>

</glossdef>

</glossentry>

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

9133

<info>

9134

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>

9139

Specifies a list of functions run to pre-process the

9140

9141

directory prior to splitting the files out to individual

packages.

</para>

</glossdef>

</glossentry>

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

9148

<info>

9149

PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis."

</info>

9154

This variable provides a means of enabling or disabling

9155

features of a recipe on a per-recipe basis.

9156

<filename>PACKAGECONFIG</filename> blocks are defined

9157

in recipes when you specify features and then arguments

9158

that define feature behaviors.

9159

Here is the basic block structure:

9160

9161

PACKAGECONFIG ??= "f1 f2 f3 ..."

9162

PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"

9163

PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"

9164

PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"

</literallayout>

</para>

<para>

The <filename>PACKAGECONFIG</filename>

9170

variable itself specifies a space-separated list of the

9171

features to enable.

9172

Following the features, you can determine the behavior of

9173

each feature by providing up to four order-dependent

9174

arguments, which are separated by commas.

9175

You can omit any argument you like but must retain the

9176

separating commas.

9177

The order is important and specifies the following:

9178

9179

<listitem><para>Extra arguments

9180

that should be added to the configure script

9181

argument list

Patrick Williams

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

[diff] [blame]

9182

(<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>

9183

or

9184

Patrick Williams

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

[diff] [blame]

9185

if the feature is enabled.</para></listitem>

9186

<listitem><para>Extra arguments

9187

that should be added to <filename>EXTRA_OECONF</filename>

Patrick Williams

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

[diff] [blame]

9188

or <filename>PACKAGECONFIG_CONFARGS</filename>

Patrick Williams

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

[diff] [blame]

9189

if the feature is disabled.

9190

</para></listitem>

9191

<listitem><para>Additional build dependencies

9192

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

9193

that should be added if the feature is enabled.

9194

</para></listitem>

9195

<listitem><para>Additional runtime dependencies

9196

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

9197

that should be added if the feature is enabled.

</para></listitem>

</orderedlist>

</para>

<para>

Consider the following

9204

<filename>PACKAGECONFIG</filename> block taken from the

9205

<filename>librsvg</filename> recipe.

9206

In this example the feature is <filename>croco</filename>,

9207

which has three arguments that determine the feature's

9208

behavior.

9209

9210

PACKAGECONFIG ??= "croco"

9211

PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"

9212

</literallayout>

9213

The <filename>--with-croco</filename> and

9214

<filename>libcroco</filename> arguments apply only if

9215

the feature is enabled.

9216

In this case, <filename>--with-croco</filename> is

9217

added to the configure script argument list and

9218

<filename>libcroco</filename> is added to

9219

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

9220

On the other hand, if the feature is disabled say through

9221

a <filename>.bbappend</filename> file in another layer, then

9222

the second argument <filename>--without-croco</filename> is

9223

added to the configure script rather than

9224

<filename>--with-croco</filename>.

</para>

<para>

The basic <filename>PACKAGECONFIG</filename> structure

9229

previously described holds true regardless of whether you

9230

are creating a block or changing a block.

9231

When creating a block, use the structure inside your

recipe.

</para>

<para>

If you want to change an existing

9237

<filename>PACKAGECONFIG</filename> block, you can do so

9238

one of two ways:

9239

9240

<listitem><para><emphasis>Append file:</emphasis>

9241

Create an append file named

9242

<replaceable>recipename</replaceable><filename>.bbappend</filename>

9243

in your layer and override the value of

9244

<filename>PACKAGECONFIG</filename>.

9245

You can either completely override the variable:

9246

9247

PACKAGECONFIG="f4 f5"

9248

</literallayout>

9249

Or, you can just append the variable:

9250

9251

PACKAGECONFIG_append = " f4"

9252

</literallayout></para></listitem>

9253

<listitem><para><emphasis>Configuration file:</emphasis>

9254

This method is identical to changing the block

9255

through an append file except you edit your

9256

<filename>local.conf</filename> or

9257

<filename><replaceable>mydistro</replaceable>.conf</filename> file.

9258

As with append files previously described,

9259

you can either completely override the variable:

9260

9261

PACKAGECONFIG_pn-<replaceable>recipename</replaceable>="f4 f5"

9262

</literallayout>

9263

Or, you can just amend the variable:

9264

9265

PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4"

9266

</literallayout></para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

Patrick Williams

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

[diff] [blame]

9272

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

9273

<info>

9274

PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from PACKAGECONFIG."

</info>

9279

A space-separated list of configuration options generated

from the

setting.

This list of options helps other classes and

9284

recipes take advantage of the

9285

<filename>PACKAGECONFIG</filename> mechanism without

9286

having to include options from

</para>

<para>

To illustrate how to use

9292

<filename>PACKAGECONFIG_CONFARGS</filename>, consider the

9293

following example:

9294

9295

PACKAGECONFIG_CONFARGS = " \

9296

-prefix ${prefix} \

9297

-sysroot ${STAGING_DIR_NATIVE} \

-no-gcc-sysroot

"

</literallayout>

In the previous example,

9302

<filename>PACKAGECONFIG_CONFARGS</filename> is set with

9303

three configuration options that can be passed using the

9304

<filename>PACKAGECONFIG</filename> mechanism, thus

9305

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]

9316

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

9317

<info>

9318

PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe."

</info>

9323

For recipes inheriting the

9324

9325

class, setting

9326

<filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to

9327

"1" specifies that the normal complementary packages

9328

(i.e. <filename>-dev</filename>,

9329

<filename>-dbg</filename>, and so forth) should not be

9330

automatically created by the

9331

<filename>packagegroup</filename> recipe, which is the

default behavior.

</para>

</glossdef>

</glossentry>

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

9338

<info>

9339

PACKAGES[doc] = "The list of packages to be created from the recipe."

</info>

9344

The list of packages to be created from the recipe.

9345

The default value is the following:

9346

9347

${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}

9348

</literallayout>

9349

</para>

Patrick Williams

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

[diff] [blame]

9350

9351

<para>

9352

During packaging, the

9353

9354

task goes through <filename>PACKAGES</filename> and uses

9355

the

9356

9357

variable corresponding to each package to assign files to

9358

the package.

9359

If a file matches the <filename>FILES</filename> variable

9360

for more than one package in <filename>PACKAGES</filename>,

9361

it will be assigned to the earliest (leftmost) package.

</para>

<para>

Packages in the variable's list that are empty (i.e. where

9366

none of the patterns in

9367

<filename>FILES_</filename><replaceable>pkg</replaceable>

9368

match any files installed by the

9369

9370

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>

9379

<info>

9380

PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes."

</info>

9385

A promise that your recipe satisfies runtime dependencies

9386

for optional modules that are found in other recipes.

9387

<filename>PACKAGES_DYNAMIC</filename>

9388

does not actually satisfy the dependencies, it only states that

9389

they should be satisfied.

9390

For example, if a hard, runtime dependency

9391

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

9392

of another package is satisfied

9393

at build time through the <filename>PACKAGES_DYNAMIC</filename>

9394

variable, but a package with the module name is never actually

9395

produced, then the other package will be broken.

9396

Thus, if you attempt to include that package in an image,

9397

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

9405

occur and the package that is not created is valid

9406

without the dependency being satisfied, then you should use

9407

9408

(a soft runtime dependency) instead of

9409

<filename>RDEPENDS</filename>.

</para>

<para>

For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>

9414

variable when you are splitting packages, see the

9415

"<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section

9416

in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

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

9422

<info>

9423

PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages."

</info>

9428

Specifies a list of functions run to perform additional

9429

splitting of files into individual packages.

9430

Recipes can either prepend to this variable or prepend

9431

to the <filename>populate_packages</filename> function

9432

in order to perform additional package splitting.

9433

In either case, the function should set

and other packaging variables appropriately in order to

9438

perform the desired splitting.

</para>

</glossdef>

</glossentry>

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

9444

<info>

9445

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>

9450

Extra options passed to the <filename>make</filename>

9451

command during the

9452

9453

task in order to specify parallel compilation on the local

9454

build host.

9455

This variable is usually in the form "-j <replaceable>x</replaceable>",

9456

where <replaceable>x</replaceable> represents the maximum

9457

number of parallel threads <filename>make</filename> can

9458

run.

Patrick Williams

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

[diff] [blame]

9459

<note><title>Caution</title>

9460

In order for <filename>PARALLEL_MAKE</filename> to be

9461

effective, <filename>make</filename> must be called

9462

with

9463

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

9464

An easy way to ensure this is to use the

9465

<filename>oe_runmake</filename> function.

9466

</note>

Patrick Williams

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

[diff] [blame]

</para>

<para>

By default, the OpenEmbedded build system automatically

9471

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

9472

build system uses.

9473

<note>

9474

If the software being built experiences dependency

9475

issues during the <filename>do_compile</filename>

9476

task that result in race conditions, you can clear

9477

the <filename>PARALLEL_MAKE</filename> variable within

9478

the recipe as a workaround.

9479

For information on addressing race conditions, see the

9480

"<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"

9481

section in the Yocto Project Development Manual.

9482

</note>

9483

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

9484

have to override this variable to gain optimal parallelism

9485

during builds.

9486

However, if you have very large systems that employ

9487

multiple physical CPUs, you might want to make sure the

9488

<filename>PARALLEL_MAKE</filename> variable is not

9489

set higher than "-j 20".

</para>

<para>

For more information on speeding up builds, see the

9494

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

section.

</para>

</glossdef>

</glossentry>

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

9501

<info>

9502

PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation."

</info>

9507

Extra options passed to the

9508

<filename>make install</filename> command during the

9509

9510

task in order to specify parallel installation.

9511

This variable defaults to the value of

9512

Patrick Williams

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

[diff] [blame]

9513

<note><title>Notes and Cautions</title>

9514

<para>In order for <filename>PARALLEL_MAKEINST</filename>

9515

to be

9516

effective, <filename>make</filename> must be called

9517

with

9518

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

9519

An easy way to ensure this is to use the

9520

<filename>oe_runmake</filename> function.</para>

9521

9522

<para>If the software being built experiences

9523

dependency issues during the

Patrick Williams

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

[diff] [blame]

9524

<filename>do_install</filename> task that result in

9525

race conditions, you can clear the

9526

<filename>PARALLEL_MAKEINST</filename> variable within

9527

the recipe as a workaround.

9528

For information on addressing race conditions, see the

9529

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

9530

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>

9537

<info>

9538

PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution."

</info>

9543

Determines the action to take when a patch fails.

9544

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

9550

when the OpenEmbedded build system cannot successfully

9551

apply a patch.

9552

Setting the value to "user" causes the build system to

9553

launch a shell and places you in the right location so that

9554

you can manually resolve the conflicts.

</para>

<para>

Set this variable in your

9559

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

</para>

</glossdef>

</glossentry>

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

9565

<info>

9566

PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch."

</info>

9571

Specifies the utility used to apply patches for a recipe

during the

task.

You can specify one of three utilities: "patch", "quilt", or

9576

"git".

9577

The default utility used is "quilt" except for the

9578

quilt-native recipe itself.

9579

Because the quilt tool is not available at the

9580

time quilt-native is being patched, it uses "patch".

</para>

<para>

If you wish to use an alternative patching tool, set the

9585

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>

9602

The epoch of the recipe.

9603

By default, this variable is unset.

9604

The variable is used to make upgrades possible when the

9605

versioning scheme changes in some backwards incompatible

9606

way.

9607

</para>

Patrick Williams

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

[diff] [blame]

9608

9609

<para>

9610

<filename>PE</filename> is the default value of the

9611

9612

variable.

9613

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

9624

Specifies the recipe or package name and includes all version and revision

9625

numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and

9626

<filename>bash-4.2-r1/</filename>).

9627

This variable is comprised of the following:

9628

9629

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

9636

<info>

9637

PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf."

</info>

9642

When inheriting the

9643

9644

class, this variable identifies packages that contain

9645

the pixbuf loaders used with

9646

<filename>gdk-pixbuf</filename>.

9647

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

9648

assumes that the loaders are in the recipe's main package

9649

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

9650

Use this variable if the loaders you need are in a package

9651

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>

9663

The name of the resulting package created by the

9664

OpenEmbedded build system.

9665

<note>

9666

When using the <filename>PKG</filename> variable, you

9667

must use a package name override.

</note>

</para>

<para>

For example, when the

9673

9674

class renames the output package, it does so by setting

9675

<filename>PKG_<replaceable>packagename</replaceable></filename>.

</para>

</glossdef>

</glossentry>

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

9681

<info>

9682

PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context."

</info>

9687

The path to <filename>pkg-config</filename> files for the

9688

current build context.

9689

<filename>pkg-config</filename> reads this variable

9690

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>

9702

Points to the destination directory for files to be

9703

packaged before they are split into individual packages.

9704

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>

9717

<info>

9718

PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process."

</info>

9723

Points to a shared, global-state directory that holds data

9724

generated during the packaging process.

9725

During the packaging process, the

9726

9727

task packages data for each recipe and installs it into

9728

this temporary, shared area.

Patrick Williams

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

[diff] [blame]

9729

This directory defaults to the following, which you should

9730

not change:

Patrick Williams

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

[diff] [blame]

9731

9732

${STAGING_DIR_HOST}/pkgdata

9733

</literallayout>

Patrick Williams

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

[diff] [blame]

9734

For examples of how this data is used, see the

9735

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

9736

section and the

9737

"<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"

9738

section.

Patrick Williams

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

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

9744

<info>

9745

PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages."

</info>

9750

Points to the parent directory for files to be packaged

9751

after they have been split into individual packages.

9752

This directory defaults to the following:

9753

9754

${WORKDIR}/packages-split

</literallayout>

</para>

<para>

Under this directory, the build system creates

9760

directories for each package specified in

9761

9762

Do not change this default.

</para>

</glossdef>

</glossentry>

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

9768

<info>

Patrick Williams

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

[diff] [blame]

9769

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]

9774

Points to a temporary work area where the

Patrick Williams

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

[diff] [blame]

9775

Patrick Williams

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

[diff] [blame]

9776

task saves package metadata.

Patrick Williams

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

[diff] [blame]

9777

The <filename>PKGDESTWORK</filename> location defaults to

the following:

${WORKDIR}/pkgdata

</literallayout>

Patrick Williams

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

[diff] [blame]

9782

Do not change this default.

9783

</para>

Patrick Williams

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

[diff] [blame]

<para>

The

task copies the package metadata from

9789

<filename>PKGDESTWORK</filename> to

9790

9791

to make it available globally.

9792

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

9798

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]

9803

The epoch of the package(s) built by the recipe.

Patrick Williams

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

[diff] [blame]

9804

By default, <filename>PKGE</filename> is set to

</para>

</glossdef>

</glossentry>

<info>

Patrick Williams

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

[diff] [blame]

9812

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]

9817

The revision of the package(s) built by the recipe.

Patrick Williams

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

[diff] [blame]

9818

By default, <filename>PKGR</filename> is set to

</para>

</glossdef>

</glossentry>

<info>

Patrick Williams

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

[diff] [blame]

9826

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]

9831

The version of the package(s) built by the

9832

recipe.

Patrick Williams

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

[diff] [blame]

9833

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>

9846

This variable can have two separate functions depending on the context: a recipe

9847

name or a resulting package name.

</para>

<para>

<filename>PN</filename> refers to a recipe name in the context of a file used

9852

by the OpenEmbedded build system as input to create a package.

9853

The name is normally extracted from the recipe file name.

9854

For example, if the recipe is named

9855

<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

9861

OpenEmbedded build system.

</para>

<para>

If applicable, the <filename>PN</filename> variable also contains any special

9866

suffix or prefix.

9867

For example, using <filename>bash</filename> to build packages for the native

9868

machine, <filename>PN</filename> is <filename>bash-native</filename>.

9869

Using <filename>bash</filename> to build packages for the target and for Multilib,

9870

<filename>PN</filename> would be <filename>bash</filename> and

9871

<filename>lib64-bash</filename>, respectively.

</para>

</glossdef>

</glossentry>

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

9877

<info>

9878

PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build."

</info>

9883

Lists recipes you do not want the OpenEmbedded build system

9884

to build.

9885

This variable works in conjunction with the

9886

9887

class, which the recipe must inherit globally.

</para>

<para>

To prevent a recipe from being built, inherit the class

9892

globally and use the variable in your

9893

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

9894

Here is an example that prevents

9895

<filename>myrecipe</filename> from being built:

9896

9897

INHERIT += "blacklist"

9898

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>

9905

<info>

9906

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>

9911

Specifies a list of functions to call once the

9912

OpenEmbedded build system has created the host part of

9913

the SDK.

9914

You can specify functions separated by semicolons:

9915

9916

POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the SDK path to a command

9922

within a function, you can use

9923

<filename>${SDK_DIR}</filename>, which points to

9924

the parent directory used by the OpenEmbedded build

9925

system when creating SDK output.

9926

See the

9927

9928

variable for more information.

</para>

</glossdef>

</glossentry>

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

9934

<info>

9935

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>

9940

Specifies a list of functions to call once the

9941

OpenEmbedded build system has created the target part of

9942

the SDK.

9943

You can specify functions separated by semicolons:

9944

9945

POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the SDK path to a command

9951

within a function, you can use

9952

<filename>${SDK_DIR}</filename>, which points to

9953

the parent directory used by the OpenEmbedded build

9954

system when creating SDK output.

9955

See the

9956

9957

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]

9969

The revision of the recipe. The default value for this

9970

variable is "r0".

9971

Subsequent revisions of the recipe conventionally have the

9972

values "r1", "r2", and so forth.

9973

When

9974

9975

increases, <filename>PR</filename> is conventionally reset

9976

to "r0".

9977

<note>

9978

The OpenEmbedded build system does not need the aid of

9979

<filename>PR</filename> to know when to rebuild a

9980

recipe.

9981

The build system uses the task

9982

<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>input checksums</ulink>

along with the

and

mechanisms.

</note>

The <filename>PR</filename> variable primarily becomes

9990

significant when a package manager dynamically installs

9991

packages on an already built image.

9992

In this case, <filename>PR</filename>, which is the default

9993

value of

9994

9995

helps the package manager distinguish which package is the

9996

most recent one in cases where many packages have the same

9997

<filename>PV</filename> (i.e. <filename>PKGV</filename>).

9998

A component having many packages with the same

9999

<filename>PV</filename> usually means that the packages all

10000

install the same upstream version, but with later

10001

(<filename>PR</filename>) version packages including

10002

packaging fixes.

10003

<note>

10004

<filename>PR</filename> does not need to be increased

10005

for changes that do not change the package contents or

10006

metadata.

10007

</note>

10008

Because manually managing <filename>PR</filename> can be

10009

cumbersome and error-prone, an automated solution exists.

10010

See the

10011

"<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"

10012

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>

10018

<info>

10019

PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference."

</info>

10024

If multiple recipes provide an item, this variable

10025

determines which recipe should be given preference.

10026

You should always suffix the variable with the name of the

10027

provided item, and you should set it to the

10028

10029

of the recipe to which you want to give precedence.

10030

Some examples:

10031

10032

PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"

10033

PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"

10034

PREFERRED_PROVIDER_virtual/libgl ?= "mesa"

10035

</literallayout>

Patrick Williams

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

[diff] [blame]

10036

<note>

10037

If you set <filename>PREFERRED_PROVIDER</filename>

10038

for a <filename>virtual/*</filename> item, then any

10039

recipe that

10040

10041

that item that is not selected by

10042

<filename>PREFERRED_PROVIDER</filename> is prevented

10043

from building, which is usually desirable since this

10044

mechanism is designed to select between mutually

10045

exclusive alternative providers.

10046

</note>

Patrick Williams

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

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

10052

<info>

10053

PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference."

</info>

10058

If there are multiple versions of recipes available, this

10059

variable determines which recipe should be given preference.

10060

You must always suffix the variable with the

10061

10062

you want to select, and you should set the

10063

10064

accordingly for precedence.

10065

You can use the "<filename>%</filename>" character as a

10066

wildcard to match any number of characters, which can be

10067

useful when specifying versions that contain long revision

10068

numbers that could potentially change.

10069

Here are two examples:

10070

Patrick Williams

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

[diff] [blame]

10071

PREFERRED_VERSION_python = "3.4.0"

Patrick Williams

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

[diff] [blame]

10072

PREFERRED_VERSION_linux-yocto = "3.19%"

10073

</literallayout>

Patrick Williams

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

[diff] [blame]

10074

<note>

10075

The specified version is matched against

10076

10077

which does not necessarily match the version part of

10078

the recipe's filename.

10079

For example, consider two recipes

10080

<filename>foo_1.2.bb</filename> and

10081

<filename>foo_git.bb</filename> where

10082

<filename>foo_git.bb</filename> contains the following

10083

assignment:

10084

10085

PV = "1.1+git${SRCPV}"

10086

</literallayout>

10087

In this case, the correct way to select

10088

<filename>foo_git.bb</filename> is by using an

10089

assignment such as the following:

10090

10091

PREFERRED_VERSION_foo = "1.1+git%"

10092

</literallayout>

10093

Compare that previous example against the following

10094

incorrect example, which does not work:

10095

10096

PREFERRED_VERSION_foo = "git"

10097

</literallayout>

10098

</note>

Patrick Williams

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

[diff] [blame]

10099

Sometimes the <filename>PREFERRED_VERSION</filename>

10100

variable can be set by configuration files in a way that

is hard to change.

You can use

to set a machine-specific override.

10105

Here is an example:

10106

10107

PREFERRED_VERSION_linux-yocto_qemux86 = "3.4%"

10108

</literallayout>

10109

Although not recommended, worst case, you can also use the

10110

"forcevariable" override, which is the strongest override

possible.

Here is an example:

PREFERRED_VERSION_linux-yocto_forcevariable = "3.4%"

10115

</literallayout>

Patrick Williams

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

[diff] [blame]

10116

<note>

10117

The <filename>_forcevariable</filename> override is

10118

not handled specially.

10119

This override only works because the default value of

10120

10121

includes "forcevariable".

10122

</note>

Patrick Williams

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

[diff] [blame]

</para>

</glossdef>

</glossentry>

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

10128

<info>

10129

PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."

</info>

10134

Specifies additional paths from which the OpenEmbedded

10135

build system gets source code.

10136

When the build system searches for source code, it first

10137

tries the local download directory.

10138

If that location fails, the build system tries locations

10139

defined by <filename>PREMIRRORS</filename>, the upstream

10140

source, and then locations specified by

in that order.

</para>

<para>

Assuming your distribution

10147

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

10148

is "poky", the default value for

10149

<filename>PREMIRRORS</filename> is defined in the

10150

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

Patrick Williams

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

[diff] [blame]

10151

<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

10156

build system to attempt before any others by adding

10157

something like the following to the

10158

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

10159

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

10160

10161

PREMIRRORS_prepend = "\

10162

git://.*/.* http://www.yoctoproject.org/sources/ \n \

10163

ftp://.*/.* http://www.yoctoproject.org/sources/ \n \

10164

http://.*/.* http://www.yoctoproject.org/sources/ \n \

10165

https://.*/.* http://www.yoctoproject.org/sources/ \n"

10166

</literallayout>

10167

These changes cause the build system to intercept

10168

Git, FTP, HTTP, and HTTPS requests and direct them to

10169

the <filename>http://</filename> sources mirror.

10170

You can use <filename>file://</filename> URLs to point

10171

to local directories or network shares as well.

</para>

</glossdef>

</glossentry>

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

10177

<info>

10178

PRIORITY[doc] = "Indicates the importance of a package. The default value is 'optional'. Other standard values are 'required', 'standard' and 'extra'."

</info>

10183

Indicates the importance of a package.

</para>

<para>

<filename>PRIORITY</filename> is considered to be part of

10188

the distribution policy because the importance of any given

10189

recipe depends on the purpose for which the distribution

10190

is being produced.

10191

Thus, <filename>PRIORITY</filename> is not normally set

within recipes.

</para>

<para>

You can set <filename>PRIORITY</filename> to "required",

10197

"standard", "extra", and "optional", which is the default.

</para>

</glossdef>

</glossentry>

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

10203

<info>

10204

PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver."

</info>

10209

Specifies libraries installed within a recipe that

10210

should be ignored by the OpenEmbedded build system's

10211

shared library resolver.

10212

This variable is typically used when software being

10213

built by a recipe has its own private versions of a

10214

library normally provided by another recipe.

10215

In this case, you would not want the package containing

10216

the private libraries to be set as a dependency on other

10217

unrelated packages that should instead depend on the

10218

package providing the standard version of the library.

</para>

<para>

Libraries specified in this variable should be specified

10223

by their file name.

10224

For example, from the Firefox recipe in meta-browser:

10225

10226

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]

10235

10236

<para>

10237

For more information, see the

10238

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

10239

section.

10240

</para>

Patrick Williams

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

[diff] [blame]

</glossdef>

</glossentry>

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

10245

<info>

10246

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>

10251

A list of aliases by which a particular recipe can be

10252

known.

10253

By default, a recipe's own

10254

10255

is implicitly already in its <filename>PROVIDES</filename>

10256

list.

10257

If a recipe uses <filename>PROVIDES</filename>, the

10258

additional aliases are synonyms for the recipe and can

10259

be useful satisfying dependencies of other recipes during

10260

the build as specified by

10261

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

</para>

<para>

Consider the following example

10266

<filename>PROVIDES</filename> statement from a recipe

10267

file <filename>libav_0.8.11.bb</filename>:

10268

10269

PROVIDES += "libpostproc"

10270

</literallayout>

10271

The <filename>PROVIDES</filename> statement results in

10272

the "libav" recipe also being known as "libpostproc".

10273

</para>

Patrick Williams

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

[diff] [blame]

10274

10275

<para>

10276

In addition to providing recipes under alternate names,

10277

the <filename>PROVIDES</filename> mechanism is also used

10278

to implement virtual targets.

10279

A virtual target is a name that corresponds to some

10280

particular functionality (e.g. a Linux kernel).

10281

Recipes that provide the functionality in question list the

10282

virtual target in <filename>PROVIDES</filename>.

10283

Recipes that depend on the functionality in question can

10284

include the virtual target in

10285

10286

to leave the choice of provider open.

</para>

<para>

Conventionally, virtual targets have names on the form

10291

"virtual/function" (e.g. "virtual/kernel").

10292

The slash is simply part of the name and has no

10293

syntactical significance.

</para>

<para>

The

variable is used to select which particular recipe

10300

provides a virtual target.

10301

<note>

10302

<para>A corresponding mechanism for virtual runtime

10303

dependencies (packages) exists.

10304

However, the mechanism does not depend on any special

10305

functionality beyond ordinary variable assignments.

10306

For example,

10307

<filename>VIRTUAL-RUNTIME_dev_manager</filename>

10308

refers to the package of the component that manages

10309

the <filename>/dev</filename> directory.</para>

10310

10311

<para>Setting the "preferred provider" for runtime

10312

dependencies is as simple as using the following

10313

assignment in a configuration file:</para>

10314

10315

VIRTUAL-RUNTIME_dev_manager = "udev"

10316

</literallayout>

10317

</note>

10318

</para>

Patrick Williams

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

[diff] [blame]

</glossdef>

</glossentry>

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

10323

<info>

10324

PRSERV_HOST[doc] = "The network based PR service host and port."

</info>

10329

The network based

10330

10331

service host and port.

</para>

<para>

The <filename>conf/local.conf.sample.extended</filename>

10336

configuration file in the

10337

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

10338

shows how the <filename>PRSERV_HOST</filename> variable is

10339

set:

10340

10341

PRSERV_HOST = "localhost:0"

10342

</literallayout>

10343

You must set the variable if you want to automatically

10344

start a local

10345

<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.

10346

You can set <filename>PRSERV_HOST</filename> to other

10347

values to use a remote PR service.

</para>

</glossdef>

</glossentry>

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

10353

<info>

10354

PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe."

</info>

10359

Specifies whether or not

10360

<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink>

10361

(ptest) functionality is enabled when building a recipe.

10362

You should not set this variable directly.

10363

Enabling and disabling building Package Tests

10364

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>

10378

The version of the recipe.

10379

The version is normally extracted from the recipe filename.

10380

For example, if the recipe is named

Patrick Williams

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

[diff] [blame]

10381

<filename>expat_2.0.1.bb</filename>, then the default value

10382

of <filename>PV</filename> will be "2.0.1".

Patrick Williams

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

[diff] [blame]

10383

<filename>PV</filename> is generally not overridden within

Patrick Williams

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

[diff] [blame]

10384

a recipe unless it is building an unstable (i.e.

10385

development) version from a source code repository

Patrick Williams

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

[diff] [blame]

10386

(e.g. Git or Subversion).

10387

</para>

Patrick Williams

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

[diff] [blame]

10388

10389

<para>

10390

<filename>PV</filename> is the default value of the

10391

10392

variable.

10393

</para>

Patrick Williams

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

[diff] [blame]

</glossdef>

</glossentry>

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

10398

<info>

10399

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>

10404

When used by recipes that inherit the

or

classes, denotes the Application Binary Interface (ABI)

10411

currently in use for Python.

10412

By default, the ABI is "m".

10413

You do not have to set this variable as the OpenEmbedded

10414

build system sets it for you.

</para>

<para>

The OpenEmbedded build system uses the ABI to construct

10419

directory names used when installing the Python headers

10420

and libraries in sysroot

10421

(e.g. <filename>.../python3.3m/...</filename>).

</para>

<para>

Recipes that inherit the

10426

10427

class during cross-builds also use this variable to

10428

locate the headers and libraries of the appropriate Python

10429

that the extension is targeting.

</para>

</glossdef>

</glossentry>

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

10435

<info>

10436

PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built."

</info>

10441

When used by recipes that inherit the

or

classes, specifies the major Python version being built.

10448

For Python 2.x, <filename>PYTHON_PN</filename> would

10449

be "python2". For Python 3.x, the variable would be

10450

"python3".

10451

You do not have to set this variable as the

10452

OpenEmbedded build system automatically sets it for you.

</para>

<para>

The variable allows recipes to use common infrastructure

10457

such as the following:

10458

10459

DEPENDS += "${PYTHON_PN}-native"

10460

</literallayout>

10461

In the previous example, the version of the dependency

10462

is <filename>PYTHON_PN</filename>.

</para>

</glossdef>

</glossentry>

</glossdiv>

Patrick Williams

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

[diff] [blame]

10469

10470

10471

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

10472

<info>

10473

RANLIB[doc] = "Minimal command and arguments to run 'ranlib'."

</info>

10478

The minimal command and arguments to run

10479

<filename>ranlib</filename>.

</para>

</glossdef>

</glossentry>

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

10485

<info>

10486

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>

10491

The list of packages that conflict with packages.

10492

Note that packages will not be installed if conflicting

10493

packages are not first removed.

</para>

<para>

Like all package-controlling variables, you must always use

10498

them in conjunction with a package name override.

10499

Here is an example:

10500

10501

RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>"

</literallayout>

</para>

<para>

BitBake, which the OpenEmbedded build system uses, supports

10507

specifying versioned dependencies.

10508

Although the syntax varies depending on the packaging

10509

format, BitBake hides these differences from you.

10510

Here is the general syntax to specify versions with

10511

the <filename>RCONFLICTS</filename> variable:

10512

10513

RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

10514

</literallayout>

10515

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a dependency on version

10525

1.2 or greater of the package <filename>foo</filename>:

10526

10527

RCONFLICTS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

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

10534

<info>

Patrick Williams

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

[diff] [blame]

10535

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]

10540

Lists runtime dependencies of a package.

10541

These dependencies are other packages that must be

10542

installed in order for the package to function correctly.

10543

As an example, the following assignment declares that the

10544

package <filename>foo</filename> needs the packages

10545

<filename>bar</filename> and <filename>baz</filename> to

10546

be installed:

10547

10548

RDEPENDS_foo = "bar baz"

10549

</literallayout>

10550

The most common types of package runtime dependencies are

10551

automatically detected and added.

10552

Therefore, most recipes do not need to set

10553

<filename>RDEPENDS</filename>.

10554

For more information, see the

10555

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

10556

section.

Patrick Williams

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

[diff] [blame]

10557

</para>

10558

10559

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10560

The practical effect of the above

10561

<filename>RDEPENDS</filename> assignment is that

10562

10563

will be declared as dependencies inside the package

10564

<filename>foo</filename> when it is written out by one of

the

tasks.

Exactly how this is done depends on which package format

10569

is used, which is determined by

10570

10571

When the corresponding package manager installs the

10572

package, it will know to also install the packages on

which it depends.

</para>

<para>

To ensure that the packages <filename>bar</filename> and

10578

<filename>baz</filename> get built, the previous

10579

<filename>RDEPENDS</filename> assignment also causes a task

10580

dependency to be added.

10581

This dependency is from the recipe's

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10582

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10583

(not to be confused with

10584

10585

task to the <filename>do_package_write_*</filename>

10586

task of the recipes that build <filename>bar</filename> and

10587

<filename>baz</filename>.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

The names of the packages you list within

10592

<filename>RDEPENDS</filename> must be the names of other

10593

packages - they cannot be recipe names.

10594

Although package names and recipe names usually match,

10595

the important point here is that you are

10596

providing package names within the

10597

<filename>RDEPENDS</filename> variable.

10598

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

10606

to packages being built, you should always use the variable

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10607

in a form with an attached package name (remember that a

10608

single recipe can build multiple packages).

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10609

For example, suppose you are building a development package

10610

that depends on the <filename>perl</filename> package.

10611

In this case, you would use the following

10612

<filename>RDEPENDS</filename> statement:

10613

10614

RDEPENDS_${PN}-dev += "perl"

10615

</literallayout>

10616

In the example, the development package depends on

10617

the <filename>perl</filename> package.

10618

Thus, the <filename>RDEPENDS</filename> variable has the

10619

<filename>${PN}-dev</filename> package name as part of the

10620

variable.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10621

<note>

10622

<title>Caution</title>

10623

<filename>RDEPENDS_${PN}-dev</filename> includes

10624

10625

by default.

10626

This default is set in the BitBake configuration file

10627

(<filename>meta/conf/bitbake.conf</filename>).

10628

Be careful not to accidentally remove

10629

<filename>${PN}</filename> when modifying

10630

<filename>RDEPENDS_${PN}-dev</filename>.

10631

Use the "+=" operator rather than the "=" operator.

10632

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10633

</para>

10634

10635

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10636

The package names you use with

10637

<filename>RDEPENDS</filename> must appear as they would in

10638

the <filename>PACKAGES</filename> variable.

10639

The

10640

10641

variable allows a different name to be used for

10642

the final package (e.g. the

10643

10644

class uses this to rename packages), but this final package

10645

name cannot be used with <filename>RDEPENDS</filename>,

10646

which makes sense as <filename>RDEPENDS</filename> is meant

10647

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

10652

specifying versioned dependencies.

10653

Although the syntax varies depending on the packaging

10654

format, BitBake hides these differences from you.

10655

Here is the general syntax to specify versions with

10656

the <filename>RDEPENDS</filename> variable:

10657

10658

RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

10659

</literallayout>

10660

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a dependency on version

10670

1.2 or greater of the package <filename>foo</filename>:

10671

10672

RDEPENDS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

<para>

For information on build-time dependencies, see the

10678

10679

variable.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

10680

You can also see the

10681

"<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and

10682

"<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"

10683

sections in the BitBake User Manual for additional

10684

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>

10690

<info>

10691

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

10700

exist in the current configuration in order for the

10701

OpenEmbedded build system to build the recipe.

10702

In other words, if the

10703

<filename>REQUIRED_DISTRO_FEATURES</filename> variable

10704

lists a feature that does not appear in

10705

<filename>DISTRO_FEATURES</filename> within the

10706

current configuration, an error occurs and the

build stops.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

10712

<glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>

10713

<info>

10714

RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed."

</info>

10719

With <filename>rm_work</filename> enabled, this

10720

variable specifies a list of recipes whose work directories

10721

should not be removed.

10722

See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"

10723

section for more details.

</para>

</glossdef>

</glossentry>

<info>

ROOT_HOME[doc] = "Defines the root home directory."

</info>

10735

Defines the root home directory.

10736

By default, this directory is set as follows in the

10737

BitBake configuration file:

10738

10739

ROOT_HOME ??= "/home/root"

10740

</literallayout>

10741

<note>

10742

This default value is likely used because some

10743

embedded solutions prefer to have a read-only root

10744

filesystem and prefer to keep writeable data in one

place.

</note>

</para>

<para>

You can override the default by setting the variable

10751

in any layer or in the <filename>local.conf</filename> file.

10752

Because the default is set using a "weak" assignment

10753

(i.e. "??="), you can use either of the following forms

10754

to define your override:

ROOT_HOME = "/root"

ROOT_HOME ?= "/root"

</literallayout>

These override examples use <filename>/root</filename>,

10760

which is probably the most commonly used override.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>

10766

<info>

10767

ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem."

</info>

10772

Indicates a filesystem image to include as the root

filesystem.

</para>

<para>

The <filename>ROOTFS</filename> variable is an optional

10778

variable used with the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

10779

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>

10786

<info>

10787

ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."

</info>

10792

Specifies a list of functions to call after the

10793

OpenEmbedded build system has installed packages.

10794

You can specify functions separated by semicolons:

10795

10796

ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

10802

within a function, you can use

10803

<filename>${IMAGE_ROOTFS}</filename>, which points to

10804

the directory that becomes the root filesystem image.

10805

See the

10806

10807

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>

10813

<info>

10814

ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."

</info>

10819

Specifies a list of functions to call once the

10820

OpenEmbedded build system has created the root filesystem.

10821

You can specify functions separated by semicolons:

10822

10823

ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

10829

within a function, you can use

10830

<filename>${IMAGE_ROOTFS}</filename>, which points to

10831

the directory that becomes the root filesystem image.

10832

See the

10833

10834

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>

10840

<info>

10841

ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."

</info>

10846

Specifies a list of functions to call after the

10847

OpenEmbedded build system has removed unnecessary

10848

packages.

10849

When runtime package management is disabled in the

10850

image, several packages are removed including

10851

<filename>base-passwd</filename>,

10852

<filename>shadow</filename>, and

10853

<filename>update-alternatives</filename>.

10854

You can specify functions separated by semicolons:

10855

10856

ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

10862

within a function, you can use

10863

<filename>${IMAGE_ROOTFS}</filename>, which points to

10864

the directory that becomes the root filesystem image.

10865

See the

10866

10867

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>

10873

<info>

10874

ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."

</info>

10879

Specifies a list of functions to call before the

10880

OpenEmbedded build system has created the root filesystem.

10881

You can specify functions separated by semicolons:

10882

10883

ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass the root filesystem path to a command

10889

within a function, you can use

10890

<filename>${IMAGE_ROOTFS}</filename>, which points to

10891

the directory that becomes the root filesystem image.

10892

See the

10893

10894

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>

10900

<info>

10901

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>

10906

A list of package name aliases that a package also provides.

10907

These aliases are useful for satisfying runtime dependencies

10908

of other packages both during the build and on the target

10909

(as specified by

10910

<filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).

10911

<note>

10912

A package's own name is implicitly already in its

10913

<filename>RPROVIDES</filename> list.

</note>

</para>

<para>

As with all package-controlling variables, you must always

10919

use the variable in conjunction with a package name override.

10920

Here is an example:

10921

10922

RPROVIDES_${PN} = "widget-abi-2"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>

10929

<info>

10930

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>

10935

A list of packages that extends the usability of a package

10936

being built.

10937

The package being built does not depend on this list of

10938

packages in order to successfully build, but rather

10939

uses them for extended usability.

10940

To specify runtime dependencies for packages, see the

10941

<filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>

variable.

</para>

<para>

The package manager will automatically install the

10947

<filename>RRECOMMENDS</filename> list of packages when

10948

installing the built package.

10949

However, you can prevent listed packages from being

10950

installed by using the

and

variables.

</para>

<para>

Packages specified in

10960

<filename>RRECOMMENDS</filename> need not actually be

10961

produced.

10962

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.

10970

If such a recipe does exist and the package is not produced,

10971

the build continues without error.

</para>

<para>

Because the <filename>RRECOMMENDS</filename> variable

10976

applies to packages being built, you should always attach

10977

an override to the variable to specify the particular

10978

package whose usability is being extended.

10979

For example, suppose you are building a development package

10980

that is extended to support wireless functionality.

10981

In this case, you would use the following:

10982

10983

RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>"

10984

</literallayout>

10985

In the example, the package name

10986

(<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)

10987

must appear as it would in the

10988

<filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>

10989

namespace before any renaming of the output package by

10990

classes such as <filename>debian.bbclass</filename>.

</para>

<para>

BitBake, which the OpenEmbedded build system uses, supports

10995

specifying versioned recommends.

10996

Although the syntax varies depending on the packaging

10997

format, BitBake hides these differences from you.

10998

Here is the general syntax to specify versions with

10999

the <filename>RRECOMMENDS</filename> variable:

11000

11001

RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

11002

</literallayout>

11003

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a recommend on version

11013

1.2 or greater of the package <filename>foo</filename>:

11014

11015

RRECOMMENDS_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>

11022

<info>

11023

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>

11028

A list of packages replaced by a package.

11029

The package manager uses this variable to determine which

11030

package should be installed to replace other package(s)

11031

during an upgrade.

11032

In order to also have the other package(s) removed at the

11033

same time, you must add the name of the other

11034

package to the

11035

<filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.

</para>

<para>

As with all package-controlling variables, you must use

11040

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

11050

specifying versioned replacements.

11051

Although the syntax varies depending on the packaging

11052

format, BitBake hides these differences from you.

11053

Here is the general syntax to specify versions with

11054

the <filename>RREPLACES</filename> variable:

11055

11056

RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"

11057

</literallayout>

11058

For <filename>operator</filename>, you can specify the

following:

=

<

>

<=

>=

</literallayout>

For example, the following sets up a replacement using

11068

version 1.2 or greater of the package

11069

<filename>foo</filename>:

11070

11071

RREPLACES_${PN} = "foo (>= 1.2)"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>

11078

<info>

11079

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>

11084

A list of additional packages that you can suggest for

11085

installation by the package manager at the time a package

11086

is installed.

11087

Not all package managers support this functionality.

</para>

<para>

As with all package-controlling variables, you must always

11092

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>

11113

The location in the

11114

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>

11115

where unpacked recipe source code resides.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11116

By default, this directory is

11117

<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>,

11118

where <filename>${BPN}</filename> is the base recipe name

11119

and <filename>${PV}</filename> is the recipe version.

11120

If the source tarball extracts the code to a directory

11121

named anything other than <filename>${BPN}-${PV}</filename>,

11122

or if the source code if fetched from an SCM such as

11123

Git or Subversion, then you must set <filename>S</filename>

11124

in the recipe so that the OpenEmbedded build system

11125

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

11130

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

11131

top-level folder named <filename>poky</filename> and a

11132

default Build Directory at <filename>poky/build</filename>.

11133

In this case, the work directory the build system uses

11134

to keep the unpacked recipe for <filename>db</filename>

11135

is the following:

11136

11137

poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19

11138

</literallayout>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11139

The unpacked source code resides in the

11140

<filename>db-5.1.19</filename> folder.

</para>

<para>

This next example assumes a Git repository.

11145

By default, Git repositories are cloned to

11146

<filename>${WORKDIR}/git</filename> during

11147

11148

Since this path is different from the default value of

11149

<filename>S</filename>, you must set it specifically

11150

so the source can be located:

11151

11152

SRC_URI = "git://path/to/repo.git"

11153

S = "${WORKDIR}/git"

11154

</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>

11160

<info>

11161

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>

11166

Specifies a list of command-line utilities that should be

11167

checked for during the initial sanity checking process when

11168

running BitBake.

11169

If any of the utilities are not installed on the build host,

11170

then BitBake immediately exits with an error.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>

11176

<info>

11177

SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against."

</info>

11182

A list of the host distribution identifiers that the

11183

build system has been tested against.

11184

Identifiers consist of the host distributor ID

11185

followed by the release,

11186

as reported by the <filename>lsb_release</filename> tool

11187

or as read from <filename>/etc/lsb-release</filename>.

11188

Separate the list items with explicit newline

11189

characters (<filename>\n</filename>).

11190

If <filename>SANITY_TESTED_DISTROS</filename> is not empty

11191

and the current value of

11192

11193

does not appear in the list, then the build system reports

11194

a warning that indicates the current host distribution has

11195

not been tested as a build host.

</para>

</glossdef>

</glossentry>

<info>

SDK_ARCH[doc] = "The target architecture for the SDK."

</info>

11207

The target architecture for the SDK.

11208

Typically, you do not directly set this variable.

Instead, use

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>

11216

<info>

11217

SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed."

</info>

11222

The directory set up and used by the

11223

11224

to which the SDK is deployed.

11225

The <filename>populate_sdk_base</filename> class defines

11226

<filename>SDK_DEPLOY</filename> as follows:

11227

11228

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>

11241

The parent directory used by the OpenEmbedded build system

11242

when creating SDK output.

11243

The

11244

11245

class defines the variable as follows:

11246

11247

SDK_DIR = "${<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>}/sdk"

11248

</literallayout>

11249

<note>

11250

The <filename>SDK_DIR</filename> directory is a

11251

temporary directory as it is part of

11252

<filename>WORKDIR</filename>.

11253

The final output directory is

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11260

11261

<info>

11262

SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK."

</info>

11267

Controls whether or not shared state artifacts are copied

11268

into the extensible SDK.

11269

The default value of "full" copies all of the required

11270

shared state artifacts into the extensible SDK.

11271

The value "minimal" leaves these artifacts out of the

11272

SDK.

11273

<note>

11274

If you set the variable to "minimal", you need to

11275

ensure

11276

11277

is set in the SDK's configuration to enable the

11278

artifacts to be fetched as needed.

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11284

<glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm>

11285

<info>

11286

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>

11291

The manifest file for the host part of the SDK.

11292

This file lists all the installed packages that make up

11293

the host part of SDK.

11294

The file contains package information on a line-per-package

11295

basis as follows:

11296

11297

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

11305

11306

SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"

11307

</literallayout>

11308

The location is derived using the

and

variables.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11317

<glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm>

11318

<info>

11319

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>

11324

When set to "1", specifies to include the packagedata for

11325

all recipes in the "world" target in the extensible SDK.

11326

Including this data allows the

11327

<filename>devtool search</filename> command to find these

11328

recipes in search results, as well as allows the

11329

<filename>devtool add</filename> command to map

11330

dependencies more effectively.

11331

<note>

11332

Enabling the <filename>SDK_INCLUDE_PKGDATA</filename>

11333

variable significantly increases build time because

11334

all of world needs to be built.

11335

Enabling the variable also slightly increases the size

11336

of the extensible SDK.

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

11342

<glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm>

11343

<info>

11344

SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK."

</info>

11349

When set to "1", specifies to include the toolchain in the

11350

extensible SDK.

11351

Including the toolchain is useful particularly when

11352

11353

is set to "minimal" to keep the SDK reasonably small

11354

but you still want to provide a usable toolchain.

11355

For example, suppose you want to use the toolchain from an

11356

IDE (e.g. Eclipse) or from other tools and you do not

11357

want to perform additional steps to install the toolchain.

</para>

<para>

The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable

11362

defaults to "0" if <filename>SDK_EXT_TYPE</filename>

11363

is set to "minimal", and defaults to "1" if

11364

<filename>SDK_EXT_TYPE</filename> is set to "full".

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11369

<glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm>

11370

<info>

11371

SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration."

</info>

11376

A list of classes to remove from the

11377

11378

value globally within the extensible SDK configuration.

11379

The default value is "buildhistory icecc".

</para>

<para>

Some classes are not generally applicable within

11384

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>

11391

<info>

11392

SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration."

</info>

11397

A list of variables not allowed through from the build

11398

system configuration into the extensible SDK configuration.

11399

Usually, these are variables that are specific to the

11400

machine on which the build system is running and thus

11401

would be potentially problematic within the extensible SDK.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm>

11407

<info>

11408

SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration."

</info>

11413

A list of variables allowed through from the build system

11414

configuration into the extensible SDK configuration.

11415

This list overrides the variables specified using the

11416

11417

variable as well as any variables identified by automatic

11418

blacklisting due to the "/" character being found at the

11419

start of the value, which is usually indicative of being a

11420

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]

11426

11427

<info>

11428

SDK_NAME[doc] = "The base name for SDK output files."

</info>

11433

The base name for SDK output files.

11434

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>

11456

Specifies the operating system for which the SDK

11457

will be built.

11458

The default value is the value of

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>

11465

<info>

11466

SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output."

</info>

11471

The location used by the OpenEmbedded build system when

creating SDK output.

The

class defines the variable as follows:

11476

11477

SDK_OUTPUT = "${<link linkend='var-SDK_DIR'>SDK_DIR</link>}/image"

11478

</literallayout>

11479

<note>

11480

The <filename>SDK_OUTPUT</filename> directory is a

11481

temporary directory as it is part of

11482

<filename>WORKDIR</filename> by way of

11483

<filename>SDK_DIR</filename>.

11484

The final output directory is

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>

11492

<info>

11493

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>

11498

Specifies a list of architectures compatible with

11499

the SDK machine.

11500

This variable is set automatically and should not

11501

normally be hand-edited.

11502

Entries are separated using spaces and listed in order

11503

of priority.

11504

The default value for

11505

<filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch

11506

${SDK_ARCH}-${SDKPKGSUFFIX}".

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>

11512

<info>

11513

SDK_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the SDK."

</info>

11518

Specifies a list of functions to call once the

11519

OpenEmbedded build system has created the SDK.

11520

You can specify functions separated by semicolons:

11521

11522

SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "

</literallayout>

</para>

<para>

If you need to pass an SDK path to a command within a

11528

function, you can use

11529

<filename>${SDK_DIR}</filename>, which points to

11530

the parent directory used by the OpenEmbedded build system

11531

when creating SDK output.

11532

See the

11533

11534

variable for more information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>

11540

<info>

11541

SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."

</info>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11546

The toolchain binary prefix used for

11547

<filename>nativesdk</filename> recipes.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11548

The OpenEmbedded build system uses the

11549

<filename>SDK_PREFIX</filename> value to set the

11550

11551

when building <filename>nativesdk</filename> recipes.

11552

The default value is "${SDK_SYS}-".

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11557

<glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm>

11558

<info>

11559

SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK."

</info>

11564

A list of shared state tasks added to the extensible SDK.

11565

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

11573

<filename>SDK_RECRDEP_TASKS</filename> variable, the

11574

above four tasks are always added to the SDK.

11575

To specify tasks beyond these four, you need to use

11576

the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g.

11577

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]

11584

11585

<info>

11586

SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built."

</info>

11591

Specifies the system, including the architecture and the

11592

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>

11609

<info>

11610

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>

11615

The manifest file for the target part of the SDK.

11616

This file lists all the installed packages that make up

11617

the target part of the SDK.

11618

The file contains package information on a line-per-package

11619

basis as follows:

11620

11621

<replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>

</literallayout>

</para>

<para>

The

class defines the manifest file as follows:

11629

11630

SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"

11631

</literallayout>

11632

The location is derived using the

and

variables.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11641

<glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm>

11642

<info>

11643

SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation."

</info>

11648

A list of targets to install from shared state as part of

11649

the standard or extensible SDK installation.

11650

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

11656

internal variable and typically would not be changed.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm>

11662

<info>

11663

SDK_TITLE[doc] = "Specifies a title to be printed when running the SDK installer."

</info>

11668

Specifies a title to be printed when running the SDK

11669

installer.

11670

The <filename>SDK_TITLE</filename> variable defaults to

11671

"<replaceable>distro</replaceable> SDK" for the standard

11672

SDK and "<replaceable>distro</replaceable> Extensible SDK"

11673

for the extensible SDK, where

11674

<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>

11684

<info>

11685

SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK."

</info>

11690

An optional URL for an update server for the extensible

11691

SDK.

11692

If set, the value is used as the default update server when

11693

running <filename>devtool sdk-update</filename> within the

extensible SDK.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11699

<glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm>

11700

<info>

11701

SDK_VENDOR[doc] = "Specifies the name of the SDK vendor."

</info>

11706

Specifies the name of the SDK vendor.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDK_VERSION'><glossterm>SDK_VERSION</glossterm>

11712

<info>

11713

SDK_VERSION[doc] = "Specifies the version for the SDK."

</info>

11718

Specifies the version of the SDK.

11719

The distribution configuration file (e.g.

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11720

<filename>/meta-poky/conf/distro/poky.conf</filename>)

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11721

defines the <filename>SDK_VERSION</filename> as follows:

11722

11723

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>

11738

<info>

11739

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>

11744

Equivalent to

11745

<filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.

11746

However, this variable applies to the SDK generated from an

11747

image using the following command:

11748

11749

$ bitbake -c populate_sdk <replaceable>imagename</replaceable>

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>

11756

<info>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

11757

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]

11762

The machine for which the SDK is built.

11763

In other words, the SDK is built such that it

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11764

runs on the target you specify with the

11765

<filename>SDKMACHINE</filename> value.

11766

The value points to a corresponding

11767

<filename>.conf</filename> file under

11768

<filename>conf/machine-sdk/</filename>.

</para>

<para>

You can use "i686" and "x86_64" as possible values

11773

for this variable. The variable defaults to "i686"

11774

and is set in the local.conf file in the Build Directory.

SDKMACHINE ?= "i686"

</literallayout>

<note>

You cannot set the <filename>SDKMACHINE</filename>

11780

variable in your distribution configuration file.

11781

If you do, the configuration will not take affect.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>

11788

<info>

11789

SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system."

</info>

11794

Defines the path offered to the user for installation

11795

of the SDK that is generated by the OpenEmbedded build

11796

system.

11797

The path appears as the default location for installing

11798

the SDK when you run the SDK's installation script.

11799

You can override the offered path when you run the

script.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm>

11806

<info>

11807

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>

11812

The full path to the sysroot used for cross-compilation

11813

within an SDK as it will be when installed into the

default

</para>

</glossdef>

</glossentry>

<glossentry id='var-SECTION'><glossterm>SECTION</glossterm>

11821

<info>

11822

SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable."

</info>

11827

The section in which packages should be categorized.

11828

Package management utilities can make use of this variable.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>

11834

<info>

11835

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>

11840

Specifies the optimization flags passed to the C compiler

11841

when building for the target.

11842

The flags are passed through the default value of the

variable.

</para>

<para>

The <filename>SELECTED_OPTIMIZATION</filename> variable

11849

takes the value of

11850

<filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>

11851

unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".

11852

If that is the case, the value of

11853

<filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>

11859

<info>

11860

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>

11865

Defines a serial console (TTY) to enable using getty.

11866

Provide a value that specifies the baud rate followed by

11867

the TTY device name separated by a space.

11868

You cannot specify more than one TTY device:

11869

11870

SERIAL_CONSOLE = "115200 ttyS0"

11871

</literallayout>

11872

<note>

11873

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>

11884

<info>

11885

SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty."

</info>

11890

Defines the serial consoles (TTYs) to enable using getty.

11891

Provide a value that specifies the baud rate followed by

11892

the TTY device name separated by a semicolon.

11893

Use spaces to separate multiple devices:

11894

11895

SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>

11902

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

11903

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]

11908

Specifies serial consoles, which must be listed in

11909

11910

to check against <filename>/proc/console</filename>

11911

before enabling them using getty.

11912

This variable allows aliasing in the format:

11913

<device>:<alias>.

11914

If a device was listed as "sclp_line0"

11915

in <filename>/dev/</filename> and "ttyS0" was listed

11916

in <filename>/proc/console</filename>, you would do the

11917

following:

11918

11919

SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"

11920

</literallayout>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

11921

This variable is currently only supported with SysVinit

11922

(i.e. not with systemd).

</para>

</glossdef>

</glossentry>

<glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>

11928

<info>

11929

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>

11934

A list of recipe dependencies that should not be used to

11935

determine signatures of tasks from one recipe when they

11936

depend on tasks from another recipe.

11937

For example:

11938

11939

SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"

</literallayout>

</para>

<para>

In this example, <filename>intone</filename> depends on

11945

<filename>mplayer2</filename>.

</para>

<para>

Use of this variable is one mechanism to remove dependencies

11950

that affect task signatures and thus force rebuilds when a

11951

recipe changes.

11952

<note><title>Caution</title>

11953

If you add an inappropriate dependency for a recipe

11954

relationship, the software might break during

11955

runtime if the interface of the second recipe was

11956

changed after the first recipe had been built.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>

11963

<info>

11964

SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change."

</info>

11969

A list of recipes that are completely stable and will

11970

never change.

11971

The ABI for the recipes in the list are presented by

11972

output from the tasks run to build the recipe.

11973

Use of this variable is one way to remove dependencies from

11974

one recipe on another that affect task signatures and

11975

thus force rebuilds when the recipe changes.

11976

<note><title>Caution</title>

11977

If you add an inappropriate variable to this list,

11978

the software might break at runtime if the

11979

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>

11987

<info>

11988

SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU."

</info>

11993

Specifies the number of bits for the target system CPU.

11994

The value should be either "32" or "64".

</para>

</glossdef>

</glossentry>

<glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>

12000

<info>

12001

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>

12006

Specifies the endian byte order of the target system.

12007

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]

12012

<glossentry id='var-SKIP_FILEDEPS'><glossterm>SKIP_FILEDEPS</glossterm>

12013

<info>

12014

SKIP_FILEDEPS[doc] = "Enables you to remove all files from

12015

the "Provides" section of an RPM package."

</info>

12020

Enables removal of all files from the "Provides" section of

12021

an RPM package.

12022

Removal of these files is required for packages containing

12023

prebuilt binaries and libraries such as

12024

<filename>libstdc++</filename> and

12025

<filename>glibc</filename>.

</para>

<para>

To enable file removal, set the variable to "1" in your

12030

<filename>conf/local.conf</filename> configuration file

12031

in your:

12032

<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]

12040

<glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>

12041

<info>

12042

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>

12047

Groups together machines based upon the same family

12048

of SOC (System On Chip).

12049

You typically set this variable in a common

12050

<filename>.inc</filename> file that you include in the

12051

configuration files of all the machines.

12052

<note>

12053

You must include

12054

<filename>conf/machine/include/soc-family.inc</filename>

12055

for this variable to appear in

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>

12063

<info>

12064

SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform."

</info>

12069

Defines the suffix for shared libraries used on the

12070

target platform.

12071

By default, this suffix is ".so.*" for all Linux-based

12072

systems and is defined in the

12073

<filename>meta/conf/bitbake.conf</filename> configuration

file.

</para>

<para>

You will see this variable referenced in the default values

12079

of <filename>FILES_${PN}</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>

12085

<info>

12086

SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform."

</info>

12091

Defines the suffix for the development symbolic link

12092

(symlink) for shared libraries on the target platform.

12093

By default, this suffix is ".so" for Linux-based

12094

systems and is defined in the

12095

<filename>meta/conf/bitbake.conf</filename> configuration

file.

</para>

<para>

You will see this variable referenced in the default values

12101

of <filename>FILES_${PN}-dev</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm>

12107

<info>

12108

SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks."

</info>

12113

When you are fetching files to create a mirror of sources

12114

(i.e. creating a source mirror), setting

12115

<filename>SOURCE_MIRROR_FETCH</filename> to "1" in your

12116

<filename>local.conf</filename> configuration file ensures

12117

the source for all recipes are fetched regardless of

12118

whether or not a recipe is compatible with the

12119

configuration.

12120

A recipe is considered incompatible with the currently

12121

configured machine when either or both the

variable and

variables specify compatibility with a machine other

12126

than that of the current machine or host.

12127

<note><title>Warning</title>

12128

Do not set the

12129

<filename>SOURCE_MIRROR_FETCH</filename> variable

12130

unless you are creating a source mirror.

12131

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>

12139

<info>

12140

SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI."

</info>

12145

Defines your own

12146

12147

from which to first fetch source before attempting to fetch

12148

from the upstream specified in

</para>

<para>

To use this variable, you must globally inherit the

12154

12155

class and then provide the URL to your mirrors.

12156

Here is the general syntax:

12157

12158

INHERIT += "own-mirrors"

12159

SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>"

12160

</literallayout>

12161

<note>

12162

You can specify only a single URL in

12163

<filename>SOURCE_MIRROR_URL</filename>.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>

12170

<info>

12171

SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/."

</info>

12176

Maps commonly used license names to their SPDX counterparts

12177

found in <filename>meta/files/common-licenses/</filename>.

12178

For the default <filename>SPDXLICENSEMAP</filename>

12179

mappings, see the

12180

<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>

12192

<info>

12193

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>

12198

A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the

12199

OpenEmbedded build system to create variants of recipes or packages.

12200

The list specifies the prefixes to strip off during certain circumstances

12201

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>

12213

The list of source files - local or remote.

12214

This variable tells the OpenEmbedded build system which bits

12215

to pull in for the build and how to pull them in.

12216

For example, if the recipe or append file only needs to

12217

fetch a tarball from the Internet, the recipe or

12218

append file uses a single <filename>SRC_URI</filename>

12219

entry.

12220

On the other hand, if the recipe or append file needs to

12221

fetch a tarball, apply two patches, and include a custom

12222

file, the recipe or append file would include four

12223

instances of the variable.

12224

</para>

12225

12226

<para>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12227

The following list explains the available URI protocols.

12228

URI protocols are highly dependent on particular BitBake

12229

Fetcher submodules.

12230

Depending on the fetcher BitBake uses, various URL

12231

parameters are employed.

12232

For specifics on the supported Fetchers, see the

12233

"<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"

12234

section in the BitBake User Manual.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12235

12236

12237

Fetches files, which are usually files shipped with

12238

the

12239

<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,

12240

from the local machine.

12241

The path is relative to the

12242

12243

variable.

12244

Thus, the build system searches, in order, from the

12245

following directories, which are assumed to be a

12246

subdirectories of the directory in which the

12247

recipe file (<filename>.bb</filename>) or

12248

append file (<filename>.bbappend</filename>)

resides:

The base recipe name without any special

12253

suffix or version numbers.

12254

</para></listitem>

12255

12256

<filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.

12257

The base recipe name and version but without

12258

any special package name suffix.

12259

</para></listitem>

12260

<listitem><para><emphasis>files -</emphasis>

12261

Files within a directory, which is named

12262

<filename>files</filename> and is also

12263

alongside the recipe or append file.

</para></listitem>

</itemizedlist>

<note>

If you want the build system to pick up files

12268

specified through a

12269

12270

statement from your append file, you need to be

12271

sure to extend the

12272

<filename>FILESPATH</filename>

12273

variable by also using the

12274

12275

variable from within your append file.

12276

</note>

12277

</para></listitem>

12278

<listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a

12279

Bazaar revision control repository.</para></listitem>

12280

<listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a

12281

Git revision control repository.</para></listitem>

12282

<listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from

12283

an OSC (OpenSUSE Build service) revision control repository.</para></listitem>

12284

<listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from

12285

a repo (Git) repository.</para></listitem>

12286

12287

Fetches files from a ClearCase repository.

12288

</para></listitem>

12289

<listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from

12290

the Internet using <filename>http</filename>.</para></listitem>

12291

<listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files

12292

from the Internet using <filename>https</filename>.</para></listitem>

12293

<listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files

12294

from the Internet using <filename>ftp</filename>.</para></listitem>

12295

<listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from

12296

a CVS revision control repository.</para></listitem>

12297

<listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from

12298

a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>

12299

<listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from

12300

a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>

12301

<listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from

12302

a secure shell.</para></listitem>

12303

<listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from

12304

a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>

</itemizedlist>

</para>

<para>

Standard and recipe-specific options for <filename>SRC_URI</filename> exist.

12310

Here are standard options:

12311

12312

<listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply

12313

the patch or not.

12314

The default action is to apply the patch.</para></listitem>

12315

<listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which

12316

striplevel to use when applying the patch.

12317

The default level is 1.</para></listitem>

12318

<listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies

12319

the directory in which the patch should be applied.

12320

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:

12327

12328

<listitem><para><emphasis><filename>mindate</filename> -</emphasis>

12329

Apply the patch only if

12330

12331

is equal to or greater than <filename>mindate</filename>.

12332

</para></listitem>

12333

<listitem><para><emphasis><filename>maxdate</filename> -</emphasis>

12334

Apply the patch only if <filename>SRCDATE</filename>

12335

is not later than <filename>mindate</filename>.

12336

</para></listitem>

12337

<listitem><para><emphasis><filename>minrev</filename> -</emphasis>

12338

Apply the patch only if <filename>SRCREV</filename>

12339

is equal to or greater than <filename>minrev</filename>.

12340

</para></listitem>

12341

<listitem><para><emphasis><filename>maxrev</filename> -</emphasis>

12342

Apply the patch only if <filename>SRCREV</filename>

12343

is not later than <filename>maxrev</filename>.

12344

</para></listitem>

12345

12346

Apply the patch only if <filename>SRCREV</filename>

12347

is equal to <filename>rev</filename>.

12348

</para></listitem>

12349

<listitem><para><emphasis><filename>notrev</filename> -</emphasis>

12350

Apply the patch only if <filename>SRCREV</filename>

12351

is not equal to <filename>rev</filename>.

</para></listitem>

</itemizedlist>

</para>

<para>

Here are some additional options worth mentioning:

12358

12359

<listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls

12360

whether or not to unpack the file if it is an archive.

12361

The default action is to unpack the file.</para></listitem>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12362

<listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file

12363

(or extracts its contents) into the specified

12364

subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

12365

when the Git fetcher is used.

12366

</para></listitem>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12367

<listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file

12368

(or extracts its contents) into the specified

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12369

subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

12370

when the local (<filename>file://</filename>)

12371

fetcher is used.

12372

</para></listitem>

12373

<listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file

12374

(or extracts its contents) into the specified

12375

subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

12376

when the CVS fetcher is used.

12377

</para></listitem>

12378

<listitem><para><emphasis><filename>subpath</filename> -</emphasis>

12379

Limits the checkout to a specific subpath of the

12380

tree when using the Git fetcher is used.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12381

</para></listitem>

12382

<listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a

12383

name to be used for association with <filename>SRC_URI</filename> checksums

12384

when you have more than one file specified in <filename>SRC_URI</filename>.

12385

</para></listitem>

12386

<listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies

12387

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>

12394

<info>

12395

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>

12400

By default, the OpenEmbedded build system automatically detects whether

12401

12402

contains files that are machine-specific.

12403

If so, the build system automatically changes

12404

<filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.

12405

Setting this variable to "0" disables this behavior.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>

12411

<info>

12412

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>

12417

The date of the source code used to build the package.

12418

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>

12424

<info>

12425

SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV."

</info>

12430

Returns the version string of the current package.

12431

This string is used to help define the value of

</para>

<para>

The <filename>SRCPV</filename> variable is defined in the

12437

<filename>meta/conf/bitbake.conf</filename> configuration

12438

file in the

12439

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

12440

as follows:

12441

12442

SRCPV = "${@bb.fetch2.get_srcrev(d)}"

</literallayout>

</para>

<para>

Recipes that need to define <filename>PV</filename> do so

12448

with the help of the <filename>SRCPV</filename>.

12449

For example, the <filename>ofono</filename> recipe

12450

(<filename>ofono_git.bb</filename>) located in

12451

<filename>meta/recipes-connectivity</filename> in the

12452

Source Directory defines <filename>PV</filename> as

12453

follows:

12454

12455

PV = "0.12-git${SRCPV}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>

12462

<info>

12463

SRCREV[doc] = "The revision of the source code used to build the package. This variable applies to Subversion, Git, Mercurial and Bazaar only."

</info>

12468

The revision of the source code used to build the package.

12469

This variable applies to Subversion, Git, Mercurial and

12470

Bazaar only.

12471

Note that if you want to build a fixed revision and you

12472

want to avoid performing a query on the remote repository

12473

every time BitBake parses your recipe, you should specify

12474

a <filename>SRCREV</filename> that is a

12475

full revision identifier and not just a tag.

</para>

<note>

For information on limitations when inheriting the latest

12480

revision of software using <filename>SRCREV</filename>,

12481

see the

12482

12483

variable description.

</note>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>

12489

<info>

12490

SSTATE_DIR[doc] = "The directory for the shared state cache."

</info>

12495

The directory for the shared state cache.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>

12501

<info>

12502

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>

12507

If set to "1", allows fetches from

12508

mirrors that are specified in

12509

12510

to work even when fetching from the network has been

12511

disabled by setting <filename>BB_NO_NETWORK</filename>

12512

to "1".

12513

Using the

12514

<filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>

12515

variable is useful if you have set

12516

<filename>SSTATE_MIRRORS</filename> to point to an

12517

internal server for your shared state cache, but

12518

you want to disable any other fetching from the network.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>

12524

<info>

12525

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>

12530

Configures the OpenEmbedded build system to search other

12531

mirror locations for prebuilt cache data objects before

12532

building out the data.

12533

This variable works like fetcher

12534

12535

and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>

12536

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

12542

as HTTP or FTP.

12543

The locations you specify need to contain the shared state

12544

cache (sstate-cache) results from previous builds.

12545

The sstate-cache you point to can also be from builds on

other machines.

</para>

<para>

If a mirror uses the same structure as

12551

12552

you need to add

12553

"PATH" at the end as shown in the examples below.

12554

The build system substitutes the correct path within the

12555

directory structure.

12556

12557

SSTATE_MIRRORS ?= "\

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12558

file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12559

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>

12566

<info>

12567

STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host."

</info>

12572

Specifies the path to the <filename>/lib</filename>

12573

subdirectory of the sysroot directory for the

build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>

12580

<info>

12581

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>

12586

Specifies the path to the <filename>/lib</filename>

12587

subdirectory of the sysroot directory for the target

12588

for which the current recipe is being built

12589

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>

12595

<info>

12596

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>

12601

Specifies the path to the

12602

<filename>/usr/bin</filename> subdirectory of the

12603

sysroot directory for the target for which the current

12604

recipe is being built

12605

(<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>

12611

<info>

12612

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>

12617

Specifies the path to the directory containing binary

12618

configuration scripts.

12619

These scripts provide configuration information for

12620

other software that wants to make use of libraries or

12621

include files provided by the software associated with

12622

the script.

12623

<note>

12624

This style of build configuration has been largely

12625

replaced by <filename>pkg-config</filename>.

12626

Consequently, if <filename>pkg-config</filename>

12627

is supported by the library to which you are linking,

12628

it is recommended you use

12629

<filename>pkg-config</filename> instead of a

12630

provided configuration script.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>

12637

<info>

12638

STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host."

</info>

12643

Specifies the path to the

12644

<filename>/usr/bin</filename> subdirectory of the

12645

sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>

12651

<info>

12652

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>

12657

Specifies the path to the <filename>/usr/share</filename>

12658

subdirectory of the sysroot directory for the target

12659

for which the current recipe is being built

12660

(<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>

12666

<info>

12667

STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host."

</info>

12672

Specifies the path to the <filename>/usr/share</filename>

12673

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>

12679

<info>

12680

STAGING_DIR[doc] = "Specifies the path to the top-level sysroots directory (i.e. ${TMPDIR}/sysroots)."

</info>

12685

Specifies the path to the top-level sysroots directory

12686

(i.e.

12687

<filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots</filename>).

12688

<note>

12689

Recipes should never write files directly under

12690

this directory because the OpenEmbedded build system

12691

manages the directory automatically.

12692

Instead, files should be installed to

within your recipe's

task and then the OpenEmbedded build system will

12697

stage a subset of those files into the sysroot.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>

12704

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12705

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]

12710

Specifies the path to the sysroot directory for the system

12711

that the component is built to run on (the system that hosts

12712

the component).

12713

For most recipes, this sysroot is the one that the recipe's

12714

12715

task copies files into.

12716

Exceptions include <filename>-native</filename> recipes,

12717

where the <filename>do_populate_sysroot</filename> task

12718

instead uses

12719

12720

Depending on the type of recipe and the build target,

12721

<filename>STAGING_DIR_HOST</filename> can have the

12722

following values:

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12723

12724

<listitem><para>For recipes building for the target

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12725

machine, the value is

12726

"${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".

12727

</para></listitem>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

12728

<listitem><para>For native recipes building

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12729

for the build host, the value is empty given the

12730

assumption that when building for the build host,

12731

the build host's own directories should be used.

12732

12733

<filename>-native</filename> recipes are not

12734

installed into host paths like such as

12735

<filename>/usr</filename>.

12736

Rather, these recipes are installed into

12737

<filename>STAGING_DIR_NATIVE</filename>.

12738

When compiling <filename>-native</filename>

12739

recipes, standard build environment variables

such as

and

are set up so that both host paths and

12745

<filename>STAGING_DIR_NATIVE</filename> are

12746

searched for libraries and headers using, for

12747

example, GCC's <filename>-isystem</filename>

12748

option.</para>

12749

12750

<para>This emphasizes that the

12751

<filename>STAGING_DIR*</filename> variables

12752

should be viewed as input variables by tasks

such as

and

Having the real system root correspond to

12759

<filename>STAGING_DIR_HOST</filename> makes

12760

conceptual sense for

12761

<filename>-native</filename> recipes, as

12762

they make use of host headers and libraries.

12763

</para>

12764

</note>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12765

</para></listitem>

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

12766

<listitem><para>For native SDK

12767

recipes that build for the SDK

12768

(<filename>nativesdk</filename>), the value is

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12769

"${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>

12777

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12778

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]

12783

Specifies the path to the sysroot directory used when

12784

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>

12790

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12791

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]

12796

Specifies the path to the sysroot used for the system for

12797

which the component generates code.

12798

For components that do not generate code, which is the

12799

majority, <filename>STAGING_DIR_TARGET</filename> is set

12800

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

12806

system but those binaries in turn generate code for

12807

another different system (e.g. cross-canadian recipes).

12808

Using terminology from GNU, the primary system is referred

12809

to as the "HOST" and the secondary, or different, system is

12810

referred to as the "TARGET".

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12811

Thus, the binaries run on the "HOST" system

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12812

and generate binaries for the "TARGET" system.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12813

The <filename>STAGING_DIR_HOST</filename> variable points

12814

to the sysroot used for the "HOST" system, while

12815

<filename>STAGING_DIR_TARGET</filename>

12816

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>

12822

<info>

12823

STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host."

</info>

12828

Specifies the path to the <filename>/etc</filename>

12829

subdirectory of the sysroot directory for the

build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>

12836

<info>

12837

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>

12842

Specifies the path to the <filename>/usr</filename>

12843

subdirectory of the sysroot directory for the target

12844

for which the current recipe is being built

12845

(<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>

12851

<info>

12852

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>

12857

Specifies the path to the

12858

<filename>/usr/include</filename> subdirectory of the

12859

sysroot directory for the target for which the current

12860

recipe being built

12861

(<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>

12867

<info>

12868

STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host."

</info>

12873

Specifies the path to the <filename>/usr/include</filename>

12874

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

12879

<glossentry id='var-STAGING_KERNEL_BUILDDIR'><glossterm>STAGING_KERNEL_BUILDDIR</glossterm>

12880

<info>

12881

STAGING_KERNEL_BUILDDIR[doc] = "Points to the directory containing the kernel build artifacts."

</info>

12886

Points to the directory containing the kernel build

12887

artifacts.

12888

Recipes building software that needs to access kernel

12889

build artifacts

12890

(e.g. <filename>systemtap-uprobes</filename>) can look in

12891

the directory specified with the

12892

<filename>STAGING_KERNEL_BUILDDIR</filename> variable to

12893

find these artifacts after the kernel has been built.

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

12898

<glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>

12899

<info>

12900

STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules."

</info>

12905

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>

12912

<info>

12913

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>

12918

Specifies the path to the <filename>/usr/lib</filename>

12919

subdirectory of the sysroot directory for the target for

12920

which the current recipe is being built

12921

(<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>

12927

<info>

12928

STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host."

</info>

12933

Specifies the path to the <filename>/usr/lib</filename>

12934

subdirectory of the sysroot directory for the build host.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAMP'><glossterm>STAMP</glossterm>

12940

<info>

12941

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>

12946

Specifies the base path used to create recipe stamp files.

12947

The path to an actual stamp file is constructed by evaluating this

12948

string and then appending additional information.

12949

Currently, the default assignment for <filename>STAMP</filename>

12950

as set in the <filename>meta/conf/bitbake.conf</filename> file

12951

is:

12952

12953

STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"

</literallayout>

</para>

<para>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

12958

For information on how BitBake uses stamp files to determine

12959

if a task should be rerun, see the

12960

"<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]

12965

See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,

information.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>

12977

<info>

12978

STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps."

</info>

12983

Specifies the base directory in which the OpenEmbedded

12984

build system places stamps.

12985

The default directory is

12986

<filename>${TMPDIR}/stamps</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-STRIP'><glossterm>STRIP</glossterm>

12992

<info>

12993

STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)."

</info>

12998

The minimal command and arguments to run

12999

<filename>strip</filename>, which is used to strip

symbols.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>

13006

<info>

13007

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>

13012

The short (72 characters or less) summary of the binary package for packaging

13013

systems such as <filename>opkg</filename>, <filename>rpm</filename> or

13014

<filename>dpkg</filename>.

13015

By default, <filename>SUMMARY</filename> is used to define

13016

the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>

13017

variable if <filename>DESCRIPTION</filename> is not set

in the recipe.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>

13024

<info>

13025

SVNDIR[doc] = "The directory where Subversion checkouts will be stored."

</info>

13030

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>

13037

<info>

13038

SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console."

</info>

13043

Specifies the kernel boot default console.

13044

If you want to use a console other than the default,

13045

set this variable in your recipe as follows where "X" is

13046

the console number you want to use:

13047

13048

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>

13062

<info>

13063

SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file."

</info>

13068

Lists additional options to add to the syslinux file.

13069

You need to set this variable in your recipe.

13070

If you want to list multiple options, separate the options

13071

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>

13083

<info>

13084

SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off."

</info>

13089

Specifies the alternate serial port or turns it off.

13090

To turn off serial, set this variable to an empty string

13091

in your recipe.

13092

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>

13107

<info>

13108

SYSLINUX_SPLASH[doc] = "An .LSS file used as the background for the VGA boot menu when you are using the boot menu."

</info>

13113

An <filename>.LSS</filename> file used as the background

13114

for the VGA boot menu when you are using the boot menu.

13115

You need to set this variable in your recipe.

</para>

<para>

The

class checks for this variable and if found, the

13122

OpenEmbedded build system installs the splash screen.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>

13128

<info>

13129

SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument."

</info>

13134

Specifies the alternate console=tty... kernel boot argument.

13135

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]

13149

<glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>

13150

<info>

13151

SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task."

</info>

13156

Directories that are staged into the sysroot by the

13157

13158

task.

13159

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>

13174

<info>

13175

SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task."

</info>

13180

Directories that are not staged into the sysroot by the

13181

13182

task.

13183

You can use this variable to exclude certain subdirectories

13184

of directories listed in

13185

13186

from staging.

13187

By default, the following directories are not staged:

13188

13189

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>

13204

<info>

13205

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>

13210

Extra directories staged into the sysroot by the

13211

13212

task for <filename>-native</filename> recipes, in addition

13213

to those specified in

13214

13215

By default, the following extra directories are staged:

13216

13217

SYSROOT_DIRS_NATIVE = " \

${bindir} \

${sbindir} \

${base_bindir} \

${base_sbindir} \

${libexecdir} \

${sysconfdir} \

${localstatedir} \

"

</literallayout>

<note>

Programs built by <filename>-native</filename> recipes

13229

run directly from the sysroot

13230

(<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>),

13231

which is why additional directories containing program

13232

executables and supporting files need to be staged.

</note>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13238

<glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>

13239

<info>

13240

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>

13245

A list of functions to execute after files are staged into

13246

the sysroot.

13247

These functions are usually used to apply additional

13248

processing on the staged files, or to stage additional

files.

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>

13255

<info>

13256

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>

13261

When inheriting the

13262

13263

class, this variable specifies whether the service you have

13264

specified in

13265

13266

should be started automatically or not.

13267

By default, the service is enabled to automatically start

13268

at boot time.

13269

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]

13284

<glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm>

13285

<info>

13286

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>

13291

When

13292

13293

is set to "systemd-boot", the

13294

<filename>SYSTEMD_BOOT_CFG</filename> variable specifies the

13295

configuration file that should be used.

13296

By default, the

13297

13298

class sets the <filename>SYSTEMD_BOOT_CFG</filename> as

13299

follows:

13300

13301

SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf"

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

13307

<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>

13313

<info>

13314

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>

13319

When

13320

13321

is set to "systemd-boot", the

13322

<filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies

13323

a list of entry files

13324

(<filename>*.conf</filename>) to be installed

13325

containing one boot entry per file.

13326

By default, the

13327

13328

class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as

13329

follows:

13330

13331

SYSTEMD_BOOT_ENTRIES ?= ""

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

13337

<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>

13343

<info>

13344

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>

13349

When

13350

13351

is set to "systemd-boot", the

13352

<filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies

13353

the boot menu timeout in seconds.

13354

By default, the

13355

13356

class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as

13357

follows:

13358

13359

SYSTEMD_BOOT_TIMEOUT ?= "10"

</literallayout>

</para>

<para>

For information on Systemd-boot, see the

13365

<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]

13370

<glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>

13371

<info>

13372

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>

13377

When inheriting the

13378

13379

class, this variable locates the systemd unit files when

13380

they are not found in the main recipe's package.

13381

By default, the

13382

<filename>SYSTEMD_PACKAGES</filename> variable is set

13383

such that the systemd unit files are assumed to reside in

13384

the recipes main package:

13385

13386

SYSTEMD_PACKAGES ?= "${PN}"

</literallayout>

</para>

<para>

If these unit files are not in this recipe's main

13392

package, you need to use

13393

<filename>SYSTEMD_PACKAGES</filename> to list the package

13394

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>

13401

<info>

13402

SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package."

</info>

13407

When inheriting the

13408

13409

class, this variable specifies the systemd service name for

a package.

</para>

<para>

When you specify this file in your recipe, use a package

13415

name override to indicate the package to which the value

13416

applies.

13417

Here is an example from the connman recipe:

13418

13419

SYSTEMD_SERVICE_${PN} = "connman.service"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>

13426

<info>

13427

SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should be running a getty, the default is '1'."

</info>

13432

When using

13433

<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,

13434

specifies a space-separated list of the virtual terminals

13435

that should be running a

13436

<ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>

13437

(allowing login), assuming

is not set to "0".

</para>

<para>

The default value for

13444

<filename>SYSVINIT_ENABLED_GETTYS</filename> is "1"

13445

(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>

13461

This variable points to a directory were BitBake places

13462

temporary files, which consist mostly of task logs and

13463

scripts, when building a particular recipe.

13464

The variable is typically set as follows:

13465

13466

T = "${WORKDIR}/temp"

</literallayout>

</para>

<para>

The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>

13472

is the directory into which BitBake unpacks and builds the

13473

recipe.

13474

The default <filename>bitbake.conf</filename> file sets this variable.</para>

13475

<para>The <filename>T</filename> variable is not to be confused with

13476

the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,

13477

which points to the root of the directory tree where BitBake

13478

places the output of an entire build.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>

13484

<info>

13485

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>

13490

The target machine's architecture.

13491

The OpenEmbedded build system supports many

13492

architectures.

13493

Here is an example list of architectures supported.

13494

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>

13517

<info>

13518

TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system."

</info>

13523

Specifies architecture-specific assembler flags for the

13524

target system.

13525

<filename>TARGET_AS_ARCH</filename> is initialized from

13526

13527

by default in the BitBake configuration file

13528

(<filename>meta/conf/bitbake.conf</filename>):

13529

13530

TARGET_AS_ARCH = "${TUNE_ASARGS}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>

13537

<info>

13538

TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system."

</info>

13543

Specifies architecture-specific C compiler flags for the

13544

target system.

13545

<filename>TARGET_CC_ARCH</filename> is initialized from

by default.

<note>

It is a common workaround to append

13550

13551

to <filename>TARGET_CC_ARCH</filename>

13552

in recipes that build software for the target that

13553

would not otherwise respect the exported

13554

<filename>LDFLAGS</filename> variable.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>

13561

<info>

13562

TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune."

</info>

13567

This is a specific kernel compiler flag for a CPU or

13568

Application Binary Interface (ABI) tune.

13569

The flag is used rarely and only for cases where a

13570

userspace

13571

13572

is not compatible with the kernel compilation.

13573

The <filename>TARGET_CC_KERNEL_ARCH</filename> variable

13574

allows the kernel (and associated modules) to use a

13575

different configuration.

13576

See the

13577

<filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>

13578

file in the

13579

<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>

13586

<info>

13587

TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS."

</info>

13592

Specifies the flags to pass to the C compiler when building

13593

for the target.

13594

When building in the target context,

13595

13596

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

13601

the

13602

13603

variable in the environment to the

13604

<filename>TARGET_CFLAGS</filename> value so that

13605

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>

13612

<info>

13613

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>

13618

Specifies the flags to pass to the C pre-processor

13619

(i.e. to both the C and the C++ compilers) when building

13620

for the target.

13621

When building in the target context,

13622

13623

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

13628

the

13629

13630

variable in the environment to the

13631

<filename>TARGET_CPPFLAGS</filename> value so that

13632

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>

13639

<info>

13640

TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target."

</info>

13645

Specifies the flags to pass to the C++ compiler when

13646

building for the target.

13647

When building in the target context,

13648

13649

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

13654

the

13655

13656

variable in the environment to the

13657

<filename>TARGET_CXXFLAGS</filename> value so that

13658

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>

13665

<info>

13666

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>

13671

Specifies the method for handling FPU code.

13672

For FPU-less targets, which include most ARM CPUs, the variable must be

13673

set to "soft".

13674

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>

13680

<info>

13681

TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system."

</info>

13686

Specifies architecture-specific linker flags for the

13687

target system.

13688

<filename>TARGET_LD_ARCH</filename> is initialized from

13689

13690

by default in the BitBake configuration file

13691

(<filename>meta/conf/bitbake.conf</filename>):

13692

13693

TARGET_LD_ARCH = "${TUNE_LDARGS}"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>

13700

<info>

13701

TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target."

</info>

13706

Specifies the flags to pass to the linker when building

13707

for the target.

13708

When building in the target context,

13709

13710

is set to the value of this variable by default.

</para>

<para>

Additionally, the SDK's environment setup script sets

13715

the

13716

13717

variable in the environment to the

13718

<filename>TARGET_LDFLAGS</filename> value so that

13719

executables built using the SDK also have the flags

applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>

13726

<info>

13727

TARGET_OS[doc] = "Specifies the target's operating system."

</info>

13732

Specifies the target's operating system.

13733

The variable can be set to "linux" for <filename>glibc</filename>-based systems and

13734

to "linux-uclibc" for <filename>uclibc</filename>.

13735

For ARM/EABI targets, there are also "linux-gnueabi" and

13736

"linux-uclibc-gnueabi" values possible.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_PREFIX'><glossterm>TARGET_PREFIX</glossterm>

13742

<info>

13743

TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools."

</info>

13748

Specifies the prefix used for the toolchain binary target

tools.

</para>

<para>

Depending on the type of recipe and the build target,

13754

<filename>TARGET_PREFIX</filename> is set as follows:

13755

13756

13757

For recipes building for the target machine,

13758

the value is

13759

"${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".

13760

</para></listitem>

13761

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

13762

For native recipes, the build system sets the

13763

variable to the value of

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13764

<filename>BUILD_PREFIX</filename>.

13765

</para></listitem>

13766

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

13767

For native SDK recipes

13768

(<filename>nativesdk</filename>), the

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13769

build system sets the variable to the value of

13770

<filename>SDK_PREFIX</filename>.

</para></listitem>

</itemizedlist>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm>

13778

<info>

13779

TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."

</info>

13784

Specifies the system, including the architecture and the

13785

operating system, for which the build is occurring in

13786

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

13799

<filename>TARGET_SYS</filename> variable yourself.

</note>

</para>

<para>

Consider these two examples:

13805

13806

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

13807

Given a native recipe on a 32-bit, x86 machine

13808

running Linux, the value is "i686-linux".

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

13809

</para></listitem>

13810

13811

Given a recipe being built for a little-endian,

13812

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>

13821

<info>

13822

TARGET_VENDOR[doc] = "The name of the target vendor."

</info>

13827

Specifies the name of the target vendor.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm>

13833

<info>

13834

TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."

</info>

13839

Specifies a suffix to be appended onto the

13840

13841

value.

13842

The suffix identifies the <filename>libc</filename> variant

13843

for building.

13844

When you are building for multiple variants with the same

13845

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,

13846

this mechanism ensures that output for different

13847

<filename>libc</filename> variants is kept separate to

13848

avoid potential conflicts.

</para>

<para>

In the <filename>defaultsetup.conf</filename> file, the

13853

default value of <filename>TCLIBCAPPEND</filename> is

13854

"-${TCLIBC}".

13855

However, distros such as poky, which normally only support

13856

one <filename>libc</filename> variant, set

13857

<filename>TCLIBCAPPEND</filename> to "" in their distro

13858

configuration file resulting in no suffix being applied.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>

13864

<info>

13865

TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc' or 'uclibc'."

</info>

13870

Specifies the GNU standard C library (<filename>libc</filename>)

13871

variant to use during the build process.

13872

This variable replaces <filename>POKYLIBC</filename>, which is no longer

supported.

</para>

<para>

You can select "glibc" or "uclibc".

</para>

</glossdef>

</glossentry>

<glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>

13883

<info>

13884

TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'."

</info>

13889

Specifies the toolchain selector.

13890

<filename>TCMODE</filename> controls the characteristics

13891

of the generated packages and images by telling the

13892

OpenEmbedded build system which toolchain profile to use.

13893

By default, the OpenEmbedded build system builds its own

13894

internal toolchain.

13895

The variable's default value is "default", which uses

13896

that internal toolchain.

13897

<note>

13898

If <filename>TCMODE</filename> is set to a value

13899

other than "default", then it is your responsibility

13900

to ensure that the toolchain is compatible with the

13901

default toolchain.

13902

Using older or newer versions of these components

13903

might cause build problems.

13904

See the

13905

<ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>

13906

for the specific components with which the toolchain

must be compatible.

</note>

</para>

<para>

The <filename>TCMODE</filename> variable is similar to

13913

13914

which controls the variant of the GNU standard C library

13915

(<filename>libc</filename>) used during the build process:

13916

<filename>glibc</filename> or <filename>uclibc</filename>.

</para>

<para>

With additional layers, it is possible to use a pre-compiled

13921

external toolchain.

13922

One example is the Sourcery G++ Toolchain.

13923

The support for this toolchain resides in the separate

13924

<trademark class='registered'>Mentor Graphics</trademark>

13925

<filename>meta-sourcery</filename> layer at

13926

<ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.

</para>

<para>

The layer's <filename>README</filename> file contains

13931

information on how to use the Sourcery G++ Toolchain as

13932

an external toolchain.

13933

In summary, you must be sure to add the layer to your

13934

<filename>bblayers.conf</filename> file in front of the

13935

<filename>meta</filename> layer and then set the

13936

<filename>EXTERNAL_TOOLCHAIN</filename>

13937

variable in your <filename>local.conf</filename> file

13938

to the location in which you installed the toolchain.

</para>

<para>

The fundamentals used for this example apply to any

13943

external toolchain.

13944

You can use <filename>meta-sourcery</filename> as a

13945

template for adding support for other external toolchains.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>

13951

<info>

13952

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>

13957

The location the OpenEmbedded build system uses to export

13958

tests when the

13959

13960

variable is set to "1".

</para>

<para>

The <filename>TEST_EXPORT_DIR</filename> variable defaults

13965

to <filename>"${TMPDIR}/testimage/${PN}"</filename>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>

13971

<info>

13972

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>

13977

Specifies to export the tests only.

13978

Set this variable to "1" if you do not want to run the

13979

tests but you want them to be exported in a manner that

13980

you to run them outside of the build system.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>

13986

<info>

13987

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>

13992

Automatically runs the series of automated tests for

13993

images when an image is successfully built.

</para>

<para>

These tests are written in Python making use of the

13998

<filename>unittest</filename> module, and the majority of

13999

them run commands on the target system over

14000

<filename>ssh</filename>.

14001

You can set this variable to "1" in your

14002

<filename>local.conf</filename> file in the

14003

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>

14004

to have the OpenEmbedded build system automatically run

14005

these tests after an image successfully builds:

TEST_IMAGE = "1"

</literallayout>

For more information on enabling, running, and writing

14010

these tests, see the

14011

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

14012

section in the Yocto Project Development Manual and the

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

14013

"<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>

14026

Holds the SSH log and the boot log for QEMU machines.

14027

The <filename>TEST_LOG_DIR</filename> variable defaults

14028

to <filename>"${WORKDIR}/testimage"</filename>.

14029

<note>

14030

Actual test results reside in the task log

14031

(<filename>log.do_testimage</filename>), which is in

14032

the <filename>${WORKDIR}/temp/</filename> directory.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>

14039

<info>

14040

TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test"

</info>

14045

For automated hardware testing, specifies the command to

14046

use to control the power of the target machine under test.

14047

Typically, this command would point to a script that

14048

performs the appropriate action (e.g. interacting

14049

with a web-enabled power strip).

14050

The specified command should expect to receive as the last

14051

argument "off", "on" or "cycle" specifying to power off,

14052

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>

14059

<info>

14060

TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD"

</info>

14065

For automated hardware testing, specifies additional

14066

arguments to pass through to the command specified in

14067

14068

Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>

14069

is optional.

14070

You can use it if you wish, for example, to separate the

14071

machine-specific and non-machine-specific parts of the

arguments.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>

14078

<info>

14079

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>

14084

The time in seconds allowed for an image to boot before

14085

automated runtime tests begin to run against an

14086

image.

14087

The default timeout period to allow the boot process to

14088

reach the login prompt is 500 seconds.

14089

You can specify a different value in the

14090

<filename>local.conf</filename> file.

</para>

<para>

For more information on testing images, see the

14095

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

14096

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>

14102

<info>

14103

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>

14108

For automated hardware testing, specifies the command

14109

to use to connect to the serial console of the target

14110

machine under test.

14111

This command simply needs to connect to the serial console

14112

and forward that connection to standard input and output

14113

as any normal terminal program does.

</para>

<para>

For example, to use the Picocom terminal program on

14118

serial device <filename>/dev/ttyUSB0</filename> at

14119

115200bps, you would set the variable as follows:

14120

14121

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>

14128

<info>

14129

TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD."

</info>

14134

For automated hardware testing, specifies additional

14135

arguments to pass through to the command specified in

14136

14137

Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>

14138

is optional.

14139

You can use it if you wish, for example, to separate the

14140

machine-specific and non-machine-specific parts of the

command.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>

14147

<info>

14148

TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected."

</info>

14153

The IP address of the build machine (host machine).

14154

This IP address is usually automatically detected.

14155

However, if detection fails, this variable needs to be set

14156

to the IP address of the build machine (i.e. where

14157

the build is taking place).

14158

<note>

14159

The <filename>TEST_SERVER_IP</filename> variable

14160

is only used for a small number of tests such as

14161

the "smart" test suite, which needs to download

14162

packages from <filename>DEPLOY_DIR/rpm</filename>.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>

14169

<info>

14170

TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine."

</info>

14175

Specifies the target controller to use when running tests

14176

against a test image.

14177

The default controller to use is "qemu":

TEST_TARGET = "qemu"

</literallayout>

</para>

<para>

A target controller is a class that defines how an

14185

image gets deployed on a target and how a target is started.

14186

A layer can extend the controllers by adding a module

14187

in the layer's <filename>/lib/oeqa/controllers</filename>

14188

directory and by inheriting the

14189

<filename>BaseTarget</filename> class, which is an abstract

14190

class that cannot be used as a value of

14191

<filename>TEST_TARGET</filename>.

</para>

<para>

You can provide the following arguments with

14196

<filename>TEST_TARGET</filename>:

14197

14198

<listitem><para><emphasis>"qemu" and "QemuTarget":</emphasis>

14199

Boots a QEMU image and runs the tests.

14200

See the

14201

"<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"

14202

section in the Yocto Project Development Manual for

14203

more information.

14204

</para></listitem>

14205

<listitem><para><emphasis>"simpleremote" and "SimpleRemoteTarget":</emphasis>

14206

Runs the tests on target hardware that is already

14207

up and running.

14208

The hardware can be on the network or it can be

14209

a device running an image on QEMU.

14210

You must also set

14211

14212

when you use "simpleremote" or "SimpleRemoteTarget".

14213

<note>

14214

This argument is defined in

14215

<filename>meta/lib/oeqa/targetcontrol.py</filename>.

14216

The small caps names are kept for compatibility

reasons.

</note>

</para></listitem>

<listitem><para><emphasis>"GummibootTarget":</emphasis>

14221

Automatically deploys and runs tests on an

14222

EFI-enabled machine that has a master image

14223

installed.

14224

<note>

14225

This argument is defined in

14226

<filename>meta/lib/oeqa/controllers/masterimage.py</filename>.

</note>

</para></listitem>

</itemizedlist>

</para>

<para>

For information on running tests on hardware, see the

14234

"<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"

14235

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>

14241

<info>

14242

TEST_TARGET_IP[doc] = "The IP address of your hardware under test."

</info>

14247

The IP address of your hardware under test.

14248

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"

14260

</literallayout>

14261

Specifying a port is useful when SSH is started on a

14262

non-standard port or in cases when your hardware under test

14263

is behind a firewall or network that is not directly

14264

accessible from your host and you need to do port address

translation.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>

14271

<info>

14272

TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing."

</info>

14277

An ordered list of tests (modules) to run against

14278

an image when performing automated runtime testing.

</para>

<para>

The OpenEmbedded build system provides a core set of tests

14283

that can be used against images.

14284

<note>

14285

Currently, there is only support for running these tests

14286

under QEMU.

14287

</note>

14288

Tests include <filename>ping</filename>,

14289

<filename>ssh</filename>, <filename>df</filename> among

14290

others.

14291

You can add your own tests to the list of tests by

14292

appending <filename>TEST_SUITES</filename> as follows:

14293

14294

TEST_SUITES_append = " <replaceable>mytest</replaceable>"

14295

</literallayout>

14296

Alternatively, you can provide the "auto" option to

14297

have all applicable tests run against the image.

14298

14299

TEST_SUITES_append = " auto"

14300

</literallayout>

14301

Using this option causes the build system to automatically

14302

run tests that are applicable to the image.

14303

Tests that are not applicable are skipped.

</para>

<para>

The order in which tests are run is important.

14308

Tests that depend on another test must appear later in the

14309

list than the test on which they depend.

14310

For example, if you append the list of tests with two

14311

tests (<filename>test_A</filename> and

14312

<filename>test_B</filename>) where

14313

<filename>test_B</filename> is dependent on

14314

<filename>test_A</filename>, then you must order the tests

14315

as follows:

14316

14317

TEST_SUITES = " test_A test_B"

</literallayout>

</para>

<para>

For more information on testing images, see the

14323

"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"

14324

section in the Yocto Project Development Manual.

</para>

</glossdef>

</glossentry>

<glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>

14330

<info>

14331

THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located."

</info>

14336

The directory in which the file BitBake is currently

14337

parsing is located.

14338

Do not manually set this variable.

</para>

</glossdef>

</glossentry>

<info>

TIME[doc] = "The time the build was started using HMS format."

</info>

14350

The time the build was started.

14351

Times appear using the hour, minute, and second (HMS)

14352

format (e.g. "140159" for one minute and fifty-nine

14353

seconds past 1400 hours).

</para>

</glossdef>

</glossentry>

<glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>

14359

<info>

14360

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>

14365

This variable is the base directory the OpenEmbedded

14366

build system uses for all build output and intermediate

14367

files (other than the shared state cache).

14368

By default, the <filename>TMPDIR</filename> variable points

14369

to <filename>tmp</filename> within the

14370

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

</para>

<para>

If you want to establish this directory in a location other

14375

than the default, you can uncomment and edit the following

14376

statement in the

14377

<filename>conf/local.conf</filename> file in the

14378

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:

14379

14380

#TMPDIR = "${TOPDIR}/tmp"

14381

</literallayout>

14382

An example use for this scenario is to set

14383

<filename>TMPDIR</filename> to a local disk, which does

14384

not use NFS, while having the Build Directory use NFS.

</para>

<para>

The filesystem used by <filename>TMPDIR</filename> must

14389

have standard filesystem semantics (i.e. mixed-case files

14390

are unique, POSIX file locking, and persistent inodes).

14391

Due to various issues with NFS and bugs in some

14392

implementations, NFS does not meet this minimum

14393

requirement.

14394

Consequently, <filename>TMPDIR</filename> cannot be on

NFS.

</para>

</glossdef>

</glossentry>

<glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>

14401

<info>

14402

TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment."

</info>

14407

This variable lists packages the OpenEmbedded build system

14408

uses when building an SDK, which contains a

14409

cross-development environment.

14410

The packages specified by this variable are part of the

14411

toolchain set that runs on the

14412

14413

and each package should usually have the prefix

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14414

<filename>nativesdk-</filename>.

14415

For example, consider the following command when

14416

building an SDK:

14417

14418

$ bitbake -c populate_sdk <replaceable>imagename</replaceable>

14419

</literallayout>

14420

In this case, a default list of packages is set in this

14421

variable, but you can add additional packages to the list.

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

For background information on cross-development toolchains

14426

in the Yocto Project development environment, see the

14427

"<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"

14428

section.

14429

For information on setting up a cross-development

14430

environment, see the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14431

<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>

14437

<info>

14438

TOOLCHAIN_OUTPUTNAME[doc] = "Defines the name used for the toolchain output."

</info>

14443

This variable defines the name used for the toolchain

output.

The

class sets the

<filename>TOOLCHAIN_OUTPUTNAME</filename> variable as

14449

follows:

14450

14451

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>

14463

<info>

14464

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>

14469

This variable lists packages the OpenEmbedded build system

14470

uses when it creates the target part of an SDK

14471

(i.e. the part built for the target hardware), which

14472

includes libraries and headers.

</para>

<para>

For background information on cross-development toolchains

14477

in the Yocto Project development environment, see the

14478

"<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"

14479

section.

14480

For information on setting up a cross-development

14481

environment, see the

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

14482

<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>

14488

<info>

14489

TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images."

</info>

14494

The top-level

14495

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

14496

BitBake automatically sets this variable when you

14497

initialize your build environment using either

or

</para>

</glossdef>

</glossentry>

<glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>

14506

<info>

14507

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>

14512

A sanitized version of

14513

14514

This variable is used where the architecture is needed in

14515

a value where underscores are not allowed, for example

14516

within package filenames.

14517

In this case, dash characters replace any underscore

14518

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>

14534

The GNU canonical architecture for a specific architecture

14535

(i.e. <filename>arm</filename>,

14536

<filename>armeb</filename>,

14537

<filename>mips</filename>,

14538

<filename>mips64</filename>, and so forth).

14539

BitBake uses this value to setup configuration.

</para>

<para>

<filename>TUNE_ARCH</filename> definitions are specific to

14544

a given architecture.

14545

The definitions can be a single static definition, or

14546

can be dynamically adjusted.

14547

You can see details for a given CPU family by looking at

14548

the architecture's <filename>README</filename> file.

14549

For example, the

14550

<filename>meta/conf/machine/include/mips/README</filename>

14551

file in the

14552

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>

14553

provides information for <filename>TUNE_ARCH</filename>

14554

specific to the <filename>mips</filename> architecture.

</para>

<para>

<filename>TUNE_ARCH</filename> is tied closely to

14559

14560

which defines the target machine's architecture.

14561

The BitBake configuration file

14562

(<filename>meta/conf/bitbake.conf</filename>) sets

14563

<filename>TARGET_ARCH</filename> as follows:

14564

14565

TARGET_ARCH = "${TUNE_ARCH}"

</literallayout>

</para>

<para>

The following list, which is by no means complete since

14571

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>

14587

<info>

14588

TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system."

</info>

14593

Specifies architecture-specific assembler flags for

14594

the target system.

14595

The set of flags is based on the selected tune features.

14596

<filename>TUNE_ASARGS</filename> is set using

14597

the tune include files, which are typically under

14598

<filename>meta/conf/machine/include/</filename> and are

influenced through

For example, the

<filename>meta/conf/machine/include/x86/arch-x86.inc</filename>

14603

file defines the flags for the x86 architecture as follows:

14604

14605

TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"

14606

</literallayout>

14607

<note>

14608

Board Support Packages (BSPs) select the tune.

14609

The selected tune, in turn, affects the tune variables

14610

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>

14618

<info>

14619

TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system."

</info>

14624

Specifies architecture-specific C compiler flags for

14625

the target system.

14626

The set of flags is based on the selected tune features.

14627

<filename>TUNE_CCARGS</filename> is set using

14628

the tune include files, which are typically under

14629

<filename>meta/conf/machine/include/</filename> and are

influenced through

<note>

Board Support Packages (BSPs) select the tune.

14634

The selected tune, in turn, affects the tune variables

14635

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>

14643

<info>

14644

TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system."

</info>

14649

Specifies architecture-specific linker flags for

14650

the target system.

14651

The set of flags is based on the selected tune features.

14652

<filename>TUNE_LDARGS</filename> is set using

14653

the tune include files, which are typically under

14654

<filename>meta/conf/machine/include/</filename> and are

influenced through

For example, the

<filename>meta/conf/machine/include/x86/arch-x86.inc</filename>

14659

file defines the flags for the x86 architecture as follows:

14660

14661

TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"

14662

</literallayout>

14663

<note>

14664

Board Support Packages (BSPs) select the tune.

14665

The selected tune, in turn, affects the tune variables

14666

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>

14674

<info>

14675

TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor."

</info>

14680

Features used to "tune" a compiler for optimal use

14681

given a specific processor.

14682

The features are defined within the tune files and allow

14683

arguments (i.e. <filename>TUNE_*ARGS</filename>) to be

14684

dynamically generated based on the features.

</para>

<para>

The OpenEmbedded build system verifies the features

14689

to be sure they are not conflicting and that they are

supported.

</para>

<para>

The BitBake configuration file

14695

(<filename>meta/conf/bitbake.conf</filename>) defines

14696

<filename>TUNE_FEATURES</filename> as follows:

14697

14698

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>

14708

<info>

14709

TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages."

</info>

14714

The package architecture understood by the packaging

14715

system to define the architecture, ABI, and tuning of

14716

output packages.

14717

The specific tune is defined using the "_tune" override

14718

as follows:

14719

14720

TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>"

</literallayout>

</para>

<para>

These tune-specific package architectures are defined in

14726

the machine include files.

14727

Here is an example of the "core2-32" tuning as used

14728

in the

14729

<filename>meta/conf/machine/include/tune-core2.inc</filename>

14730

file:

14731

14732

TUNE_PKGARCH_tune-core2-32 = "core2-32"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>

14739

<info>

14740

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>

14745

An underlying Application Binary Interface (ABI) used by

14746

a particular tuning in a given toolchain layer.

14747

Providers that use prebuilt libraries can use the

14748

<filename>TUNEABI</filename>,

and

variables to check compatibility of tunings against their

14753

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>

14767

<info>

14768

TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST."

</info>

14773

If set, the OpenEmbedded system ignores the

14774

14775

variable.

14776

Providers that use prebuilt libraries can use the

14777

<filename>TUNEABI_OVERRIDE</filename>,

14778

<filename>TUNEABI_WHITELIST</filename>,

14779

and

14780

14781

variables to check compatibility of a tuning against their

14782

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>

14794

<info>

14795

TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed."

</info>

14800

A whitelist of permissible

14801

14802

values.

14803

If <filename>TUNEABI_WHITELIST</filename> is not set,

14804

all tunes are allowed.

14805

Providers that use prebuilt libraries can use the

14806

<filename>TUNEABI_WHITELIST</filename>,

14807

14808

and <filename>TUNEABI</filename> variables to check

14809

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>

14822

<info>

14823

TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature."

</info>

14828

Specifies CPU or Application Binary Interface (ABI)

14829

tuning features that conflict with <replaceable>feature</replaceable>.

</para>

<para>

Known tuning conflicts are specified in the machine include

14834

files in the

14835

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.

14836

Here is an example from the

14837

<filename>meta/conf/machine/include/mips/arch-mips.inc</filename>

14838

include file that lists the "o32" and "n64" features as

14839

conflicting with the "n32" feature:

14840

14841

TUNECONFLICTS[n32] = "o32 n64"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm>

14848

<info>

14849

TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features."

</info>

14854

Specifies a valid CPU or Application Binary Interface (ABI)

14855

tuning feature.

14856

The specified feature is stored as a flag.

14857

Valid features are specified in the machine include files

14858

(e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).

14859

Here is an example from that file:

14860

14861

TUNEVALID[bigendian] = "Enable big-endian mode."

</literallayout>

</para>

<para>

See the machine include files in the

14867

<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>

14878

<info>

14879

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

14893

<filename>meta-fsl-arm</filename> layer.

14894

14895

UBOOT_CONFIG ??= "sd"

14896

UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"

14897

UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"

14898

UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"

14899

UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"

14900

</literallayout>

14901

In this example, "sd" is selected as the configuration

14902

of the possible four for the

14903

<filename>UBOOT_MACHINE</filename>.

14904

The "sd" configuration defines "mx6qsabreauto_config"

14905

as the value for <filename>UBOOT_MACHINE</filename>, while

14906

the "sdcard" specifies the

14907

<filename>IMAGE_FSTYPES</filename> to use for the U-boot

image.

</para>

<para>

For more information on how the

14913

<filename>UBOOT_CONFIG</filename> is handled, see the

14914

<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>

14921

<info>

14922

UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."

</info>

14927

Specifies the entry point for the U-Boot image.

14928

During U-Boot image creation, the

14929

<filename>UBOOT_ENTRYPOINT</filename> variable is passed

14930

as a command-line parameter to the

14931

<filename>uboot-mkimage</filename> utility.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>

14937

<info>

14938

UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image."

</info>

14943

Specifies the load address for the U-Boot image.

14944

During U-Boot image creation, the

14945

<filename>UBOOT_LOADADDRESS</filename> variable is passed

14946

as a command-line parameter to the

14947

<filename>uboot-mkimage</filename> utility.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>

14953

<info>

14954

UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image."

</info>

14959

Appends a string to the name of the local version of the

14960

U-Boot image.

14961

For example, assuming the version of the U-Boot image

14962

built was "2013.10, the full version string reported by

14963

U-Boot would be "2013.10-yocto" given the following

14964

statement:

14965

14966

UBOOT_LOCALVERSION = "-yocto"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>

14973

<info>

14974

UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image."

</info>

14979

Specifies the value passed on the

14980

<filename>make</filename> command line when building

14981

a U-Boot image.

14982

The value indicates the target platform configuration.

14983

You typically set this variable from the machine

14984

configuration file (i.e.

14985

<filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>).

</para>

<para>

Please see the "Selection of Processor Architecture and

14990

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>

14997

<info>

14998

UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile."

</info>

15003

Specifies the target called in the

15004

<filename>Makefile</filename>.

15005

The default target is "all".

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>

15011

<info>

15012

UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."

</info>

15017

Points to the generated U-Boot extension.

15018

For example, <filename>u-boot.sb</filename> has a

15019

<filename>.sb</filename> extension.

</para>

<para>

The default U-Boot extension is

</para>

</glossdef>

</glossentry>

<glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>

15030

<info>

15031

UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."

</info>

15036

Specifies the target used for building U-Boot.

15037

The target is passed directly as part of the "make" command

15038

(e.g. SPL and AIS).

15039

If you do not specifically set this variable, the

15040

OpenEmbedded build process passes and uses "all" for the

15041

target during the U-Boot building process.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UNKNOWN_CONFIGURE_WHITELIST'><glossterm>UNKNOWN_CONFIGURE_WHITELIST</glossterm>

15047

<info>

15048

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>

15053

Specifies a list of options that, if reported by the

15054

configure script as being invalid, should not generate a

warning during the

task.

Normally, invalid configure options are simply not passed

15059

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]

15063

However, common options, for example, exist that are passed

15064

to all configure scripts at a class level that might not

15065

be valid for some configure scripts.

15066

It follows that no benefit exists in seeing a warning about

15067

these options.

15068

For these cases, the options are added to

15069

<filename>UNKNOWN_CONFIGURE_WHITELIST</filename>.

</para>

<para>

The configure arguments check that uses

15074

<filename>UNKNOWN_CONFIGURE_WHITELIST</filename> is part

15075

of the

15076

15077

class and is only enabled if the recipe inherits the

class.

</para>

</glossdef>

</glossentry>

<glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>

15085

<info>

15086

UPDATERCPN[doc] = "Specifies the package that contains the initscript that is to be enabled."

</info>

15091

For recipes inheriting the

15092

15093

class, <filename>UPDATERCPN</filename> specifies

15094

the package that contains the initscript that is to be

enabled.

</para>

<para>

The default value is "${PN}".

15100

Given that almost all recipes that install initscripts

15101

package them in the main package for the recipe, you

15102

rarely need to set this variable in individual recipes.

</para>

</glossdef>

</glossentry>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15107

<glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm>

15108

<info>

15109

UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository."

</info>

15114

When the

15115

15116

class is enabled globally, you can perform a per-recipe

15117

check for what the latest upstream source code version is

15118

by calling

15119

<filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.

15120

If the recipe source code is provided from Git

15121

repositories, the OpenEmbedded build system determines the

15122

latest upstream version by picking the latest tag from the

15123

list of all repository tags.

15124

You can use the

15125

<filename>UPSTREAM_CHECK_GITTAGREGEX</filename>

15126

variable to provide a regular expression to filter only the

15127

relevant tags should the default filter not work

15128

correctly.

15129

15130

UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"

</literallayout>

</para>

</glossdef>

</glossentry>

<glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm>

15137

<info>

15138

UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI."

</info>

15143

When the

15144

15145

class is enabled globally, use the

15146

<filename>UPSTREAM_CHECK_REGEX</filename> variable to

15147

specify a different regular expression instead of the

15148

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>

15159

<info>

15160

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>

15165

When the

15166

15167

class is enabled globally, you can perform a per-recipe

15168

check for what the latest upstream source code version is

15169

by calling <filename>bitbake -c checkpkg</filename>

15170

<replaceable>recipe</replaceable>.

15171

If the source code is provided from tarballs, the latest

15172

version is determined by fetching the directory listing

15173

where the tarball is and attempting to find a later tarball.

15174

When this approach does not work, you can use

15175

<filename>UPSTREAM_CHECK_URI</filename> to

15176

provide a different URI that contains the link to the

15177

latest tarball.

15178

15179

UPSTREAM_CHECK_URI = "recipe_url"

</literallayout>

</para>

</glossdef>

</glossentry>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15185

<glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm>

15186

<info>

15187

USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population."

</info>

15192

Determines if <filename>devtmpfs</filename> is used for

15193

<filename>/dev</filename> population.

15194

The default value used for <filename>USE_DEVFS</filename>

15195

is "1" when no value is specifically set.

15196

Typically, you would set <filename>USE_DEVFS</filename>

15197

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>"

15204

section in the Yocto Project Development Manual for

15205

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>

15217

When using

15218

<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,

15219

determines whether or not to run a

15220

<ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>

15221

on any virtual terminals in order to enable logging in

15222

through those terminals.

</para>

<para>

The default value used for <filename>USE_VT</filename>

15227

is "1" when no default value is specifically set.

15228

Typically, you would set <filename>USE_VT</filename>

15229

to "0" in the machine configuration file for machines

15230

that do not have a graphical display attached and

15231

therefore do not need virtual terminal functionality.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>

15237

<info>

15238

USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features."

</info>

15243

A list of classes to globally inherit.

15244

These classes are used by the OpenEmbedded build system

15245

to enable extra features (e.g.

15246

<filename>buildstats</filename>,

15247

<filename>image-mklibs</filename>, and so forth).

</para>

<para>

The default list is set in your

15252

<filename>local.conf</filename> file:

15253

15254

USER_CLASSES ?= "buildstats image-mklibs image-prelink"

15255

</literallayout>

15256

For more information, see

Patrick Williams

2016-06-20 12:57:21 -0500

[diff] [blame]

15257

<filename>meta-poky/conf/local.conf.sample</filename> in

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15258

the

15259

<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>

15265

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15266

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]

15271

If set to "error", forces the OpenEmbedded build system to

15272

produce an error if the user identification

15273

(<filename>uid</filename>) and group identification

15274

(<filename>gid</filename>) values are not defined

15275

in <filename>files/passwd</filename>

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15276

and <filename>files/group</filename> files.

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15277

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

15282

apply <filename>uid</filename> and

15283

<filename>gid</filename> values.

15284

Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>

15285

variable is by default not set.

15286

If you plan on using statically assigned

15287

15288

values, you should set

15289

the <filename>USERADD_ERROR_DYNAMIC</filename> variable in

15290

your <filename>local.conf</filename> file as

15291

follows:

15292

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15293

USERADD_ERROR_DYNAMIC = "error"

Patrick Williams

2015-09-15 14:41:29 -0500

[diff] [blame]

15294

</literallayout>

15295

Overriding the default behavior implies you are going to

15296

also take steps to set static <filename>uid</filename> and

15297

<filename>gid</filename> values through use of the

and

variables.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>

15308

<info>

15309

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>

15314

Specifies a password file to use for obtaining static

15315

group identification (<filename>gid</filename>) values

15316

when the OpenEmbedded build system adds a group to the

15317

system during package installation.

</para>

<para>

When applying static group identification

15322

(<filename>gid</filename>) values, the OpenEmbedded build

15323

system looks in

15324

15325

for a <filename>files/group</filename> file and then applies

15326

those <filename>uid</filename> values.

15327

Set the variable as follows in your

15328

<filename>local.conf</filename> file:

15329

15330

USERADD_GID_TABLES = "files/group"

</literallayout>

</para>

<note>

Setting the

variable to "useradd-staticids" causes the build system

15338

to use static <filename>gid</filename> values.

</note>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>

15344

<info>

15345

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

15354

require users and/or groups to be added.

</para>

<para>

You must set this variable if the recipe inherits the

15359

class.

15360

For example, the following enables adding a user for the

15361

main package in a recipe:

15362

15363

USERADD_PACKAGES = "${PN}"

15364

</literallayout>

15365

<note>

15366

If follows that if you are going to use the

15367

<filename>USERADD_PACKAGES</filename> variable,

15368

you need to set one or more of the

or

variables.

</note>

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>

15381

<info>

15382

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

15391

to the <filename>useradd</filename> command

15392

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>

15398

recipe:

15399

15400

USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \

15401

--no-create-home --shell /bin/false \

15402

--user-group messagebus"

15403

</literallayout>

15404

For information on the standard Linux shell command

15405

<filename>useradd</filename>, see

15406

<ulink url='http://linux.die.net/man/8/useradd'></ulink>.

</para>

</glossdef>

</glossentry>

<glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>

15412

<info>

15413

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>

15418

Specifies a password file to use for obtaining static

15419

user identification (<filename>uid</filename>) values

15420

when the OpenEmbedded build system adds a user to the

15421

system during package installation.

</para>

<para>

When applying static user identification

15426

(<filename>uid</filename>) values, the OpenEmbedded build

15427

system looks in

15428

15429

for a <filename>files/passwd</filename> file and then applies

15430

those <filename>uid</filename> values.

15431

Set the variable as follows in your

15432

<filename>local.conf</filename> file:

15433

15434

USERADD_UID_TABLES = "files/passwd"

</literallayout>

</para>

<note>

Setting the

variable to "useradd-staticids" causes the build system

15442

to use static <filename>uid</filename> values.

</note>

</glossdef>

</glossentry>

<glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>

15448

<info>

Patrick Williams

2017-02-23 20:41:17 -0600

[diff] [blame]

15449

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>

15454

When set to "useradd-staticids", causes the

15455

OpenEmbedded build system to base all user and group

15456

additions on a static

15457

<filename>passwd</filename> and

15458

<filename>group</filename> files found in

</para>

<para>

To use static user identification (<filename>uid</filename>)

15464

and group identification (<filename>gid</filename>)

15465

values, set the variable

15466

as follows in your <filename>local.conf</filename> file:

15467

15468

USERADDEXTENSION = "useradd-staticids"

15469

</literallayout>

15470

<note>

15471

Setting this variable to use static

15472

15473

values causes the OpenEmbedded build system to employ

15474

the

Patrick Williams

2016-03-30 15:21:19 -0500

[diff] [blame]

15475

Patrick Williams