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

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

[diff] [blame]

182

</para>

183

184

<para>

Patrick Williams

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

[diff] [blame]

185

<filename>log.do_</filename><replaceable>taskname</replaceable> and

186

<filename>run.do_</filename><replaceable>taskname</replaceable>

187

are actually symbolic links to

188

<filename>log.do_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>

189

and

190

<filename>log.run_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>,

191

where <replaceable>pid</replaceable> is the PID the task had when

192

it ran.

193

The symlinks always point to the files corresponding to the most

recent run.

</para>

</section>

<title>Viewing Variable Values</title>

200

<para>

201

BitBake's <filename>-e</filename> option is used to display

202

variable values after parsing.

203

The following command displays the variable values after the

204

configuration files (i.e. <filename>local.conf</filename>,

205

<filename>bblayers.conf</filename>,

206

<filename>bitbake.conf</filename> and so forth) have been

parsed:

$ bitbake -e

</literallayout>

The following command displays variable values after a specific

212

recipe has been parsed.

213

The variables include those from the configuration as well:

214

215

$ bitbake -e recipename

216

</literallayout>

217

218

Each recipe has its own private set of variables (datastore).

219

Internally, after parsing the configuration, a copy of the

220

resulting datastore is made prior to parsing each recipe.

221

This copying implies that variables set in one recipe will

222

not be visible to other recipes.</para>

223

224

<para>Likewise, each task within a recipe gets a private

225

datastore based on the recipe datastore, which means that

226

variables set within one task will not be visible to

other tasks.</para>

</note>

</para>

<para>

In the output of <filename>bitbake -e</filename>, each variable is

233

preceded by a description of how the variable got its value,

234

including temporary values that were later overriden.

235

This description also includes variable flags (varflags) set on

236

the variable.

237

The output can be very helpful during debugging.

</para>

<para>

Variables that are exported to the environment are preceded by

242

<filename>export</filename> in the output of

243

<filename>bitbake -e</filename>.

244

See the following example:

245

246

export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86"

</literallayout>

</para>

<para>

In addition to variable values, the output of the

252

<filename>bitbake -e</filename> and

253

<filename>bitbake -e</filename> <replaceable>recipe</replaceable>

254

commands includes the following information:

255

256

257

The output starts with a tree listing all configuration

258

files and classes included globally, recursively listing

259

the files they include or inherit in turn.

260

Much of the behavior of the OpenEmbedded build system

261

(including the behavior of the

262

263

is implemented in the

264

265

class and the classes it inherits, rather than being built

into BitBake itself.

</para></listitem>

After the variable values, all functions appear in the

270

output.

271

For shell functions, variables referenced within the

272

function body are expanded.

273

If a function has been modified using overrides or

274

using override-style operators like

275

<filename>_append</filename> and

276

<filename>_prepend</filename>, then the final assembled

277

function body appears in the output.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Viewing Package Information with <filename>oe-pkgdata-util</filename></title>

285

286

<para>

287

You can use the <filename>oe-pkgdata-util</filename> command-line

288

utility to query

289

290

and display various package-related information.

291

When you use the utility, you must use it to view information

292

on packages that have already been built.

</para>

<para>

Following are a few of the available

297

<filename>oe-pkgdata-util</filename> subcommands.

298

<note>

299

You can use the standard * and ? globbing wildcards as part of

300

package names and paths.

</note>

<filename>oe-pkgdata-util list-pkgs [</filename><replaceable>pattern</replaceable><filename>]</filename>:

305

Lists all packages that have been built, optionally

306

limiting the match to packages that match

307

<replaceable>pattern</replaceable>.

308

</para></listitem>

309

310

<filename>oe-pkgdata-util list-pkg-files </filename><replaceable>package</replaceable><filename> ...</filename>:

311

Lists the files and directories contained in the given

packages.

<note>

<para>

A different way to view the contents of a package is

316

to look at the

317

<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/packages-split</filename>

318

directory of the recipe that generates the

319

package.

320

This directory is created by the

321

322

task and has one subdirectory for each package the

323

recipe generates, which contains the files stored in

324

that package.</para>

325

<para>

326

If you want to inspect the

327

<filename>${WORKDIR}/packages-split</filename>

328

directory, make sure that

329

330

is not enabled when you build the recipe.

</para>

</note>

</para></listitem>

<filename>oe-pkgdata-util find-path </filename><replaceable>path</replaceable><filename> ...</filename>:

336

Lists the names of the packages that contain the given

337

paths.

338

For example, the following tells us that

339

<filename>/usr/share/man/man1/make.1</filename>

340

is contained in the <filename>make-doc</filename>

341

package:

342

343

$ oe-pkgdata-util find-path /usr/share/man/man1/make.1

344

make-doc: /usr/share/man/man1/make.1

</literallayout>

</para></listitem>

<filename>oe-pkgdata-util lookup-recipe </filename><replaceable>package</replaceable><filename> ...</filename>:

349

Lists the name of the recipes that

350

produce the given packages.

</para></listitem>

</itemizedlist>

</para>

<para>

For more information on the <filename>oe-pkgdata-util</filename>

357

command, use the help facility:

358

359

$ oe-pkgdata-util &dash;&dash;help

360

$ oe-pkgdata-util <replaceable>subcommand</replaceable> --help

</literallayout>

</para>

</section>

<title>Viewing Dependencies Between Recipes and Tasks</title>

367

368

<para>

369

Sometimes it can be hard to see why BitBake wants to build other

370

recipes before the one you have specified.

371

Dependency information can help you understand why a recipe is

built.

</para>

<para>

To generate dependency information for a recipe, run the following

377

command:

378

379

$ bitbake -g <replaceable>recipename</replaceable>

380

</literallayout>

381

This command writes the following files in the current directory:

382

383

384

<filename>pn-buildlist</filename>: A list of

385

recipes/targets involved in building

386

<replaceable>recipename</replaceable>.

387

"Involved" here means that at least one task from the

388

recipe needs to run when building

389

<replaceable>recipename</replaceable> from scratch.

Targets that are in

are not listed.

</para></listitem>

<filename>pn-depends.dot</filename>: A graph showing

396

dependencies between build-time targets (recipes).

397

</para></listitem>

398

399

<filename>package-depends.dot</filename>: A graph showing

400

known dependencies between runtime targets.

401

</para></listitem>

402

403

<filename>task-depends.dot</filename>: A graph showing

404

dependencies between tasks.

</para></listitem>

</itemizedlist>

</para>

<para>

The graphs are in

format and can be converted to images (e.g. using the

413

<filename>dot</filename> tool from

414

<ulink url='http://www.graphviz.org/'>Graphviz</ulink>).

415

<note><title>Notes</title>

416

417

418

DOT files use a plain text format.

419

The graphs generated using the

420

<filename>bitbake -g</filename> command are often so

421

large as to be difficult to read without special

422

pruning (e.g. with Bitbake's

423

<filename>-I</filename> option) and processing.

424

Despite the form and size of the graphs, the

425

corresponding <filename>.dot</filename> files can still

426

be possible to read and provide useful information.

427

</para>

428

429

<para>As an example, the

430

<filename>task-depends.dot</filename> file contains

431

lines such as the following:

432

433

"libxslt.do_configure" -> "libxml2.do_populate_sysroot"

434

</literallayout>

435

The above example line reveals that the

436

437

task in <filename>libxslt</filename> depends on the

438

439

task in <filename>libxml2</filename>, which is a normal

440

441

dependency between the two recipes.

442

</para></listitem>

443

444

For an example of how <filename>.dot</filename> files

445

can be processed, see the

446

<filename>scripts/contrib/graph-tool</filename> Python

447

script, which finds and displays paths between graph

nodes.

</para></listitem>

</itemizedlist>

</note>

</para>

<para>

You can use a different method to view dependency information

456

by using the following command:

457

458

$ bitbake -g -u depexp <replaceable>recipename</replaceable>

459

</literallayout>

460

This command displays a GUI window from which you can view

461

build-time and runtime dependencies for the recipes involved in

462

building <replaceable>recipename</replaceable>.

</para>

</section>

<title>Viewing Task Variable Dependencies</title>

<para>

As mentioned in the

"<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>Checksums (Signatures)</ulink>"

472

section of the BitBake User Manual, BitBake tries to automatically

473

determine what variables a task depends on so that it can rerun

474

the task if any values of the variables change.

475

This determination is usually reliable.

476

However, if you do things like construct variable names at runtime,

477

then you might have to manually declare dependencies on those

478

variables using <filename>vardeps</filename> as described in the

479

"<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>"

480

section of the BitBake User Manual.

</para>

<para>

If you are unsure whether a variable dependency is being picked up

485

automatically for a given task, you can list the variable

486

dependencies BitBake has determined by doing the following:

487

488

489

Build the recipe containing the task:

490

491

$ bitbake <replaceable>recipename</replaceable>

</literallayout>

</para></listitem>

Inside the

directory, find the signature data

498

(<filename>sigdata</filename>) file that corresponds to the

499

task.

500

The <filename>sigdata</filename> files contain a pickled

501

Python database of all the metadata that went into creating

502

the input checksum for the task.

503

As an example, for the

504

505

task of the <filename>db</filename> recipe, the

506

<filename>sigdata</filename> file might be found in the

507

following location:

508

509

${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1

510

</literallayout>

511

For tasks that are accelerated through the shared state

512

(<link linkend='shared-state-cache'>sstate</link>)

513

cache, an additional <filename>siginfo</filename> file is

514

written into

515

516

along with the cached task output.

517

The <filename>siginfo</filename> files contain exactly the

518

same information as <filename>sigdata</filename> files.

519

</para></listitem>

520

521

Run <filename>bitbake-dumpsig</filename> on the

522

<filename>sigdata</filename> or

523

<filename>siginfo</filename> file.

524

Here is an example:

525

526

$ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1

527

</literallayout>

528

In the output of the above command, you will find a line

529

like the following, which lists all the (inferred) variable

530

dependencies for the task.

531

This list also includes indirect dependencies from

532

variables depending on other variables, recursively.

533

534

Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch']

535

</literallayout>

536

<note>

537

Functions (e.g. <filename>base_do_fetch</filename>)

538

also count as variable dependencies.

539

These functions in turn depend on the variables they

540

reference.

541

</note>

542

The output of <filename>bitbake-dumpsig</filename> also includes

543

the value each variable had, a list of dependencies for each

544

variable, and

545

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

information.

</para></listitem>

</orderedlist>

</para>

<para>

There is also a <filename>bitbake-diffsigs</filename> command for

553

comparing two <filename>siginfo</filename> or

554

<filename>sigdata</filename> files.

555

This command can be helpful when trying to figure out what changed

556

between two versions of a task.

557

If you call <filename>bitbake-diffsigs</filename> with just one

558

file, the command behaves like

559

<filename>bitbake-dumpsig</filename>.

</para>

<para>

You can also use BitBake to dump out the signature construction

564

information without executing tasks by using either of the

565

following BitBake command-line options:

566

567

&dash;&dash;dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable>

568

-S <replaceable>SIGNATURE_HANDLER</replaceable>

569

</literallayout>

570

<note>

571

Two common values for

572

<replaceable>SIGNATURE_HANDLER</replaceable> are "none" and

573

"printdiff", which dump only the signature or compare the

574

dumped signature with the cached one, respectively.

575

</note>

576

Using BitBake with either of these options causes BitBake to dump

577

out <filename>sigdata</filename> files in the

578

<filename>stamps</filename> directory for every task it would have

579

executed instead of building the specified target package.

Patrick Williams

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

[diff] [blame]

</para>

</section>

<title>Running Specific Tasks</title>

585

586

<para>

Patrick Williams

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

[diff] [blame]

587

Any given recipe consists of a set of tasks.

Patrick Williams

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

[diff] [blame]

588

The standard BitBake behavior in most cases is:

589

<filename>do_fetch</filename>,

590

<filename>do_unpack</filename>,

591

<filename>do_patch</filename>, <filename>do_configure</filename>,

592

<filename>do_compile</filename>, <filename>do_install</filename>,

593

<filename>do_package</filename>,

594

<filename>do_package_write_*</filename>, and

595

<filename>do_build</filename>.

596

The default task is <filename>do_build</filename> and any tasks

597

on which it depends build first.

598

Some tasks, such as <filename>do_devshell</filename>, are not part

599

of the default build chain.

600

If you wish to run a task that is not part of the default build

601

chain, you can use the <filename>-c</filename> option in BitBake.

602

Here is an example:

603

604

$ bitbake matchbox-desktop -c devshell

</literallayout>

</para>

<para>

Patrick Williams

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

[diff] [blame]

609

The <filename>-c</filename> option respects task dependencies,

610

which means that all other tasks (including tasks from other

611

recipes) that the specified task depends on will be run before the

612

task.

613

Even when you manually specify a task to run with

614

<filename>-c</filename>, BitBake will only run the task if it

615

considers it "out of date".

616

See the

617

"<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>"

618

section for how BitBake determines whether a task is "out of date".

</para>

<para>

If you want to force an up-to-date task to be rerun (e.g.

623

because you made manual modifications to the recipe's

624

625

that you want to try out), then you can use the

626

<filename>-f</filename> option.

627

<note>

628

The reason <filename>-f</filename> is never required when

running the

task is because the

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

633

variable flag is already set for the task.

634

</note>

635

The following example shows one way you can use the

636

<filename>-f</filename> option:

Patrick Williams

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

[diff] [blame]

637

638

$ bitbake matchbox-desktop

639

.

640

.

Patrick Williams

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

[diff] [blame]

641

make some changes to the source code in the work directory

Patrick Williams

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

[diff] [blame]

642

.

643

.

644

$ bitbake matchbox-desktop -c compile -f

645

$ bitbake matchbox-desktop

</literallayout>

</para>

<para>

This sequence first builds and then recompiles

651

<filename>matchbox-desktop</filename>.

652

The last command reruns all tasks (basically the packaging tasks)

653

after the compile.

654

BitBake recognizes that the <filename>do_compile</filename>

655

task was rerun and therefore understands that the other tasks

656

also need to be run again.

657

</para>

658

659

<para>

Patrick Williams

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

[diff] [blame]

660

Another, shorter way to rerun a task and all

661

662

that depend on it is to use the <filename>-C</filename>

663

option.

664

<note>

665

This option is upper-cased and is separate from the

666

<filename>-c</filename> option, which is lower-cased.

667

</note>

668

Using this option invalidates the given task and then runs the

669

670

task, which is the default task if no task is given, and the

671

tasks on which it depends.

672

You could replace the final two commands in the previous example

673

with the following single command:

674

675

$ bitbake matchbox-desktop -C compile

676

</literallayout>

677

Internally, the <filename>-f</filename> and

678

<filename>-C</filename> options work by tainting (modifying) the

679

input checksum of the specified task.

680

This tainting indirectly causes the task and its

681

dependent tasks to be rerun through the normal task dependency

682

mechanisms.

683

<note>

684

BitBake explicitly keeps track of which tasks have been

685

tainted in this fashion, and will print warnings such as the

686

following for builds involving such tasks:

687

688

WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run

689

</literallayout>

690

The purpose of the warning is to let you know that the work

691

directory and build output might not be in the clean state they

692

would be in for a "normal" build, depending on what actions

693

you took.

694

To get rid of such warnings, you can remove the work directory

695

and rebuild the recipe, as follows:

696

697

$ bitbake matchbox-desktop -c clean

698

$ bitbake matchbox-desktop

</literallayout>

</note>

</para>

<para>

Patrick Williams

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

[diff] [blame]

704

You can view a list of tasks in a given package by running the

705

<filename>do_listtasks</filename> task as follows:

706

707

$ bitbake matchbox-desktop -c listtasks

708

</literallayout>

709

The results appear as output to the console and are also in the

710

file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.

</para>

</section>

Patrick Williams

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

[diff] [blame]

714

715

<title>Checking for Missing Build-Time Dependencies</title>

Patrick Williams

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

[diff] [blame]

716

717

<para>

Patrick Williams

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

[diff] [blame]

718

A recipe might build successfully even though some of its

719

build-time dependencies are missing from

720

721

Following are the two most common ways in which that can happen:

722

723

724

The build-time dependency just happens to already exist in

725

the staging sysroot

726

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

727

by the time the recipe is built.

728

This situation occurs when the build-time dependency is

729

built earlier during recipe processing.

730

</para></listitem>

731

732

The component built by the recipe conditionally enables

733

functionality depending on whether it can find the

734

build-time dependency in the staging sysroot.

735

If the build-time dependency is missing, the corresponding

736

functionality is disabled.

737

This condition is known as a "floating dependency".

738

</para></listitem>

739

</itemizedlist>

Patrick Williams

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

[diff] [blame]

740

</para>

Patrick Williams

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

[diff] [blame]

741

742

<para>

743

Because dealing with the second case is more complex, focus will

744

be on the first case.

745

The

746

747

QA check checks that every library the component linked against is

748

declared as a build-time dependency.

749

If that is not the case, then the first situation described in the

750

previous list exists, and <filename>build-deps</filename> reports

751

a missing build-time dependency.

</para>

<para>

Another, more manual, way to check a recipe for missing build-time

756

dependencies of the first type is to build with an empty staging

757

sysroot.

758

This method can also find missing build-time dependencies

759

that are not in the form of libraries, which the

760

<filename>build-deps</filename> QA check is unable to find.

</para>

<para>

An easy way to empty the staging sysroots is to simply remove

765

766

which is usually

767

<filename>${</filename><link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link><filename>}/tmp</filename>,

768

as it includes the staging sysroots.

769

Another, faster method to empty the staging sysroots is to use the

770

<filename>scripts/wipe-sysroot</filename> script,

771

which removes just the staging sysroots and keeps everything else

772

in <filename>TMPDIR</filename>.

773

<note>

774

The <filename>scripts/</filename> directory appears in

775

<filename>PATH</filename> after running the build environment

776

initialization script (i.e.

or

which results in the ability to to run

781

<filename>wipe-sysroot</filename> immediately.

</note>

</para>

Patrick Williams

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

[diff] [blame]

</section>

<title>General BitBake Problems</title>

789

790

<para>

791

You can see debug output from BitBake by using the <filename>-D</filename> option.

792

The debug output gives more information about what BitBake

793

is doing and the reason behind it.

794

Each <filename>-D</filename> option you use increases the logging level.

795

The most common usage is <filename>-DDD</filename>.

</para>

<para>

The output from <filename>bitbake -DDD -v</filename> <replaceable>targetname</replaceable> can reveal why

800

BitBake chose a certain version of a package or why BitBake

801

picked a certain provider.

802

This command could also help you in a situation where you think BitBake did something

unexpected.

</para>

</section>

<title>Development Host System Issues</title>

809

810

<para>

811

Sometimes issues on the host development system can cause your

812

build to fail.

813

Following are known, host-specific problems.

814

Be sure to always consult the

815

<ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>

816

for a look at all release-related issues.

817

818

<listitem><para><emphasis><filename>glibc-initial</filename> fails to build</emphasis>:

819

If your development host system has the unpatched

820

<filename>GNU Make 3.82</filename>,

821

the

822

823

task fails for <filename>glibc-initial</filename> during

824

the build.</para>

825

<para>Typically, every distribution that ships

826

<filename>GNU Make 3.82</filename> as

827

the default already has the patched version.

828

However, some distributions, such as Debian, have

829

<filename>GNU Make 3.82</filename> as an option, which

830

is unpatched.

831

You will see this error on these types of distributions.

832

Switch to <filename>GNU Make 3.81</filename> or patch

833

your <filename>make</filename> to solve the problem.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Building with No Dependencies</title>

841

<para>

842

To build a specific recipe (<filename>.bb</filename> file),

843

you can use the following command form:

844

845

$ bitbake -b <replaceable>somepath</replaceable>/<replaceable>somerecipe</replaceable>.bb

846

</literallayout>

847

This command form does not check for dependencies.

848

Consequently, you should use it

849

only when you know existing dependencies have been met.

850

<note>

851

You can also specify fragments of the filename.

852

In this case, BitBake checks for a unique match.

</note>

</para>

</section>

Patrick Williams

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

[diff] [blame]

857

858

<title>Recipe Logging Mechanisms</title>

859

<para>

Patrick Williams

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

[diff] [blame]

860

The Yocto Project provides several logging functions for producing

861

debugging output and reporting errors and warnings.

862

For Python functions, the following logging functions exist.

863

All of these functions log to

864

<filename>${T}/log.do_</filename><replaceable>task</replaceable>,

865

and can also log to standard output (stdout) with the right

866

settings:

Patrick Williams

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

[diff] [blame]

867

Patrick Williams

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

[diff] [blame]

868

869

<filename>bb.plain(</filename><replaceable>msg</replaceable><filename>)</filename>:

870

Writes <replaceable>msg</replaceable> as is to the log while

871

also logging to stdout.

872

</para></listitem>

873

874

<filename>bb.note(</filename><replaceable>msg</replaceable><filename>)</filename>:

875

Writes "NOTE: <replaceable>msg</replaceable>" to the log.

876

Also logs to stdout if BitBake is called with "-v".

877

</para></listitem>

878

879

<filename>bb.debug(</filename><replaceable>level</replaceable><filename>, </filename><replaceable>msg</replaceable><filename>)</filename>:

880

Writes "DEBUG: <replaceable>msg</replaceable>" to the log.

881

Also logs to stdout if the log level is greater than or

882

equal to <replaceable>level</replaceable>.

883

See the

884

"<ulink url='&YOCTO_DOCS_BB_URL;#usage-and-syntax'>-D</ulink>"

885

option in the BitBake User Manual for more information.

886

</para></listitem>

887

888

<filename>bb.warn(</filename><replaceable>msg</replaceable><filename>)</filename>:

889

Writes "WARNING: <replaceable>msg</replaceable>" to the log

890

while also logging to stdout.

891

</para></listitem>

892

893

<filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>:

894

Writes "ERROR: <replaceable>msg</replaceable>" to the log

895

while also logging to stdout.

896

<note>

897

Calling this function does not cause the task to fail.

</note>

</para></listitem>

<filename>bb.fatal(</filename><replaceable>msg</replaceable><filename>)</filename>:

902

This logging function is similar to

903

<filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>

904

but also causes the calling task to fail.

905

<note>

906

<filename>bb.fatal()</filename> raises an exception,

907

which means you do not need to put a "return"

908

statement after the function.

909

</note>

910

</para></listitem>

Patrick Williams

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

[diff] [blame]

</itemizedlist>

</para>

<para>

Patrick Williams

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

[diff] [blame]

915

The same logging functions are also available in shell functions,

916

under the names

917

<filename>bbplain</filename>, <filename>bbnote</filename>,

918

<filename>bbdebug</filename>, <filename>bbwarn</filename>,

919

<filename>bberror</filename>, and <filename>bbfatal</filename>.

920

The

921

922

class implements these functions.

923

See that class in the

Patrick Williams

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

[diff] [blame]

924

<filename>meta/classes</filename> folder of the

Patrick Williams

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

[diff] [blame]

925

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

926

for information.

Patrick Williams

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

[diff] [blame]

</para>

<title>Logging With Python</title>

931

<para>

932

When creating recipes using Python and inserting code that handles build logs,

933

keep in mind the goal is to have informative logs while keeping the console as

934

"silent" as possible.

935

Also, if you want status messages in the log, use the "debug" loglevel.

</para>

<para>

Following is an example written in Python.

940

The code handles logging for a function that determines the

941

number of tasks needed to be run.

942

See the

943

"<link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>"

944

section for additional information:

945

946

python do_listtasks() {

947

bb.debug(2, "Starting to figure out the task list")

948

if noteworthy_condition:

949

bb.note("There are 47 tasks to run")

950

bb.debug(2, "Got to point xyz")

951

if warning_trigger:

952

bb.warn("Detected warning_trigger, this might be a problem later.")

953

if recoverable_error:

954

bb.error("Hit recoverable_error, you really need to fix this!")

955

if fatal_error:

956

bb.fatal("fatal_error detected, unable to print the task list")

957

bb.plain("The tasks present are abc")

958

bb.debug(2, "Finished figuring out the tasklist")

}

</literallayout>

</para>

</section>

<title>Logging With Bash</title>

966

<para>

967

When creating recipes using Bash and inserting code that handles build

968

logs, you have the same goals - informative with minimal console output.

969

The syntax you use for recipes written in Bash is similar to that of

970

recipes written in Python described in the previous section.

</para>

<para>

Following is an example written in Bash.

975

The code logs the progress of the <filename>do_my_function</filename> function.

976

977

do_my_function() {

978

bbdebug 2 "Running do_my_function"

979

if [ exceptional_condition ]; then

980

bbnote "Hit exceptional_condition"

981

fi

982

bbdebug 2 "Got to point xyz"

983

if [ warning_trigger ]; then

984

bbwarn "Detected warning_trigger, this might cause a problem later."

985

fi

986

if [ recoverable_error ]; then

987

bberror "Hit recoverable_error, correcting"

988

fi

989

if [ fatal_error ]; then

990

bbfatal "fatal_error detected"

991

fi

992

bbdebug 2 "Completed do_my_function"

}

</literallayout>

</para>

</section>

</section>

<title>Other Tips</title>

1001

1002

<para>

1003

Here are some other tips that you might find useful:

1004

Patrick Williams

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

[diff] [blame]

1005

1006

When adding new packages, it is worth watching for

1007

undesirable items making their way into compiler command

1008

lines.

1009

For example, you do not want references to local system

1010

files like

1011

<filename>/usr/lib/</filename> or

1012

<filename>/usr/include/</filename>.

Patrick Williams

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

[diff] [blame]

1013

</para></listitem>

Patrick Williams

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

[diff] [blame]

1014

1015

If you want to remove the <filename>psplash</filename>

Patrick Williams

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

[diff] [blame]

1016

boot splashscreen,

Patrick Williams

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

[diff] [blame]

1017

add <filename>psplash=false</filename> to the kernel

1018

command line.

Patrick Williams

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

[diff] [blame]

1019

Doing so prevents <filename>psplash</filename> from loading

1020

and thus allows you to see the console.

1021

It is also possible to switch out of the splashscreen by

Patrick Williams

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

[diff] [blame]

1022

switching the virtual console (e.g. Fn+Left or Fn+Right

on a Zaurus).

</para></listitem>

Removing

(usually <filename>tmp/</filename>, within the

1029

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

1030

can often fix temporary build issues.

1031

Removing <filename>TMPDIR</filename> is usually a

1032

relatively cheap operation, because task output will be

1033

cached in

1034

1035

(usually <filename>sstate-cache/</filename>, which is

1036

also in the Build Directory).

1037

<note>

1038

Removing <filename>TMPDIR</filename> might be a

1039

workaround rather than a fix.

1040

Consequently, trying to determine the underlying cause

1041

of an issue before removing the directory is a good

idea.

</note>

</para></listitem>

Understanding how a feature is used in practice within

1047

existing recipes can be very helpful.

1048

It is recommended that you configure some method that

1049

allows you to quickly search through files.</para>

1050

1051

<para>Using GNU Grep, you can use the following shell

1052

function to recursively search through common

1053

recipe-related files, skipping binary files,

1054

<filename>.git</filename> directories, and the

1055

Build Directory (assuming its name starts with

"build"):

g() {

grep -Ir \

--exclude-dir=.git \

--exclude-dir='build*' \

1062

--include='*.bb*' \

1063

--include='*.inc*' \

1064

--include='*.conf*' \

--include='*.py*' \

"$@"

}

</literallayout>

Following are some usage examples:

1070

1071

$ g FOO # Search recursively for "FOO"

1072

$ g -i foo # Search recursively for "foo", ignoring case

1073

$ g -w FOO # Search recursively for "FOO" as a word, ignoring e.g. "FOOBAR"

1074

</literallayout>

1075

If figuring out how some feature works requires a lot of

1076

searching, it might indicate that the documentation should

1077

be extended or improved.

1078

In such cases, consider filing a documentation bug using

1079

the Yocto Project implementation of

1080

<ulink url='https://bugzilla.yoctoproject.org/'>Bugzilla</ulink>.

1081

For general information on how to submit a bug against

1082

the Yocto Project, see the

1083

"<ulink url='&YOCTO_DOCS_DEV_URL;#tracking-bugs'>Tracking Bugs</ulink>"

1084

section in the Yocto Project Development Manual.

1085

<note>

1086

The manuals might not be the right place to document

1087

variables that are purely internal and have a limited

1088

scope (e.g. internal variables used to implement a

1089

single <filename>.bbclass</filename> file).

1090

</note>

Patrick Williams

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

[diff] [blame]

</para></listitem>

</itemizedlist>

</para>

</section>

</section>

<title>Maintaining Build Output Quality</title>

1099

1100

<para>

1101

Many factors can influence the quality of a build.

1102

For example, if you upgrade a recipe to use a new version of an upstream software

1103

package or you experiment with some new configuration options, subtle changes

1104

can occur that you might not detect until later.

1105

Consider the case where your recipe is using a newer version of an upstream package.

1106

In this case, a new version of a piece of software might introduce an optional

1107

dependency on another library, which is auto-detected.

1108

If that library has already been built when the software is building,

1109

the software will link to the built library and that library will be pulled

1110

into your image along with the new software even if you did not want the

library.

</para>

<para>

The

class exists to help you maintain

1118

the quality of your build output.

1119

You can use the class to highlight unexpected and possibly unwanted

1120

changes in the build output.

1121

When you enable build history, it records information about the contents of

1122

each package and image and then commits that information to a local Git

1123

repository where you can examine the information.

</para>

<para>

The remainder of this section describes the following:

1128

1129

<listitem><para>How you can enable and disable

1130

build history</para></listitem>

1131

<listitem><para>How to understand what the build history contains

1132

</para></listitem>

1133

<listitem><para>How to limit the information used for build history

1134

</para></listitem>

1135

<listitem><para>How to examine the build history from both a

1136

command-line and web interface</para></listitem>

</itemizedlist>

</para>

<title>Enabling and Disabling Build History</title>

1142

1143

<para>

1144

Build history is disabled by default.

1145

To enable it, add the following <filename>INHERIT</filename>

1146

statement and set the

1147

1148

variable to "1" at the end of your

1149

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

1150

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

1151

1152

INHERIT += "buildhistory"

1153

BUILDHISTORY_COMMIT = "1"

1154

</literallayout>

1155

Enabling build history as previously described

1156

causes the build process to collect build

1157

output information and commit it to a local

1158

<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.

1159

<note>

1160

Enabling build history increases your build times slightly,

1161

particularly for images, and increases the amount of disk

1162

space used during the build.

</note>

</para>

<para>

You can disable build history by removing the previous statements

1168

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

</para>

</section>

<title>Understanding What the Build History Contains</title>

1174

1175

<para>

1176

Build history information is kept in

1177

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

1178

in the Build Directory as defined by the

1179

1180

variable.

1181

The following is an example abbreviated listing:

</para>

<para>

At the top level, there is a <filename>metadata-revs</filename> file

1187

that lists the revisions of the repositories for the layers enabled

1188

when the build was produced.

1189

The rest of the data splits into separate

1190

<filename>packages</filename>, <filename>images</filename> and

1191

<filename>sdk</filename> directories, the contents of which are

described below.

</para>

<title>Build History Package Information</title>

1197

1198

<para>

1199

The history for each package contains a text file that has

1200

name-value pairs with information about the package.

1201

For example, <filename>buildhistory/packages/i586-poky-linux/busybox/busybox/latest</filename>

1202

contains the following:

PV = 1.22.1

PR = r32

RPROVIDES =

RDEPENDS = glibc (>= 2.20) update-alternatives-opkg

1208

RRECOMMENDS = busybox-syslog busybox-udhcpc update-rc.d

1209

PKGSIZE = 540168

1210

FILES = /usr/bin/* /usr/sbin/* /usr/lib/busybox/* /usr/lib/lib*.so.* \

1211

/etc /com /var /bin/* /sbin/* /lib/*.so.* /lib/udev/rules.d \

1212

/usr/lib/udev/rules.d /usr/share/busybox /usr/lib/busybox/* \

1213

/usr/share/pixmaps /usr/share/applications /usr/share/idl \

1214

/usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers

1215

FILELIST = /bin/busybox /bin/busybox.nosuid /bin/busybox.suid /bin/sh \

1216

/etc/busybox.links.nosuid /etc/busybox.links.suid

1217

</literallayout>

1218

Most of these name-value pairs correspond to variables used

1219

to produce the package.

1220

The exceptions are <filename>FILELIST</filename>, which is the

1221

actual list of files in the package, and

1222

<filename>PKGSIZE</filename>, which is the total size of files

1223

in the package in bytes.

</para>

<para>

There is also a file corresponding to the recipe from which the

1228

package came (e.g.

1229

<filename>buildhistory/packages/i586-poky-linux/busybox/latest</filename>):

PV = 1.22.1

PR = r32

DEPENDS = initscripts kern-tools-native update-rc.d-native \

1234

virtual/i586-poky-linux-compilerlibs virtual/i586-poky-linux-gcc \

1235

virtual/libc virtual/update-alternatives

1236

PACKAGES = busybox-ptest busybox-httpd busybox-udhcpd busybox-udhcpc \

1237

busybox-syslog busybox-mdev busybox-hwclock busybox-dbg \

1238

busybox-staticdev busybox-dev busybox-doc busybox-locale busybox

</literallayout>

</para>

<para>

Finally, for those recipes fetched from a version control

1244

system (e.g., Git), a file exists that lists source revisions

1245

that are specified in the recipe and lists the actual revisions

1246

used during the build.

1247

Listed and actual revisions might differ when

1248

1249

is set to

1250

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

1251

Here is an example assuming

1252

<filename>buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev</filename>):

1253

1254

# SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"

1255

SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"

1256

# SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"

1257

SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"

1258

</literallayout>

1259

You can use the <filename>buildhistory-collect-srcrevs</filename>

1260

command with the <filename>-a</filename> option to

1261

collect the stored <filename>SRCREV</filename> values

1262

from build history and report them in a format suitable for

1263

use in global configuration (e.g.,

1264

<filename>local.conf</filename> or a distro include file) to

1265

override floating <filename>AUTOREV</filename> values to a

1266

fixed set of revisions.

1267

Here is some example output from this command:

1268

1269

$ buildhistory-collect-srcrevs -a

1270

# i586-poky-linux

1271

SRCREV_pn-glibc = "b8079dd0d360648e4e8de48656c5c38972621072"

1272

SRCREV_pn-glibc-initial = "b8079dd0d360648e4e8de48656c5c38972621072"

1273

SRCREV_pn-opkg-utils = "53274f087565fd45d8452c5367997ba6a682a37a"

1274

SRCREV_pn-kmod = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"

1275

# x86_64-linux

1276

SRCREV_pn-gtk-doc-stub-native = "1dea266593edb766d6d898c79451ef193eb17cfa"

1277

SRCREV_pn-dtc-native = "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf"

1278

SRCREV_pn-update-rc.d-native = "eca680ddf28d024954895f59a241a622dd575c11"

1279

SRCREV_glibc_pn-cross-localedef-native = "b8079dd0d360648e4e8de48656c5c38972621072"

1280

SRCREV_localedef_pn-cross-localedef-native = "c833367348d39dad7ba018990bfdaffaec8e9ed3"

1281

SRCREV_pn-prelink-native = "faa069deec99bf61418d0bab831c83d7c1b797ca"

1282

SRCREV_pn-opkg-utils-native = "53274f087565fd45d8452c5367997ba6a682a37a"

1283

SRCREV_pn-kern-tools-native = "23345b8846fe4bd167efdf1bd8a1224b2ba9a5ff"

1284

SRCREV_pn-kmod-native = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"

1285

# qemux86-poky-linux

1286

SRCREV_machine_pn-linux-yocto = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"

1287

SRCREV_meta_pn-linux-yocto = "a227f20eff056e511d504b2e490f3774ab260d6f"

1288

# all-poky-linux

1289

SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11"

1290

</literallayout>

1291

<note>

1292

Here are some notes on using the

1293

<filename>buildhistory-collect-srcrevs</filename> command:

1294

1295

<listitem><para>By default, only values where the

1296

<filename>SRCREV</filename> was

1297

not hardcoded (usually when <filename>AUTOREV</filename>

1298

was used) are reported.

1299

Use the <filename>-a</filename> option to see all

1300

<filename>SRCREV</filename> values.

1301

</para></listitem>

1302

<listitem><para>The output statements might not have any effect

1303

if overrides are applied elsewhere in the build system

1304

configuration.

1305

Use the <filename>-f</filename> option to add the

1306

<filename>forcevariable</filename> override to each output line

1307

if you need to work around this restriction.

1308

</para></listitem>

1309

<listitem><para>The script does apply special handling when

1310

building for multiple machines.

1311

However, the script does place a

1312

comment before each set of values that specifies

1313

which triplet to which they belong as shown above

1314

(e.g., <filename>i586-poky-linux</filename>).

</para></listitem>

</itemizedlist>

</note>

</para>

</section>

<title>Build History Image Information</title>

1323

1324

<para>

1325

The files produced for each image are as follows:

1326

1327

<listitem><para><filename>image-files:</filename>

1328

A directory containing selected files from the root

1329

filesystem.

1330

The files are defined by

1331

1332

</para></listitem>

1333

<listitem><para><filename>build-id.txt:</filename>

1334

Human-readable information about the build configuration

1335

and metadata source revisions.

1336

This file contains the full build header as printed

1337

by BitBake.</para></listitem>

1338

1339

Dependency graphs for the image that are

1340

compatible with <filename>graphviz</filename>.

1341

</para></listitem>

1342

<listitem><para><filename>files-in-image.txt:</filename>

1343

A list of files in the image with permissions,

1344

owner, group, size, and symlink information.

1345

</para></listitem>

1346

<listitem><para><filename>image-info.txt:</filename>

1347

A text file containing name-value pairs with information

1348

about the image.

1349

See the following listing example for more information.

1350

</para></listitem>

1351

<listitem><para><filename>installed-package-names.txt:</filename>

1352

A list of installed packages by name only.</para></listitem>

1353

<listitem><para><filename>installed-package-sizes.txt:</filename>

1354

A list of installed packages ordered by size.

1355

</para></listitem>

1356

<listitem><para><filename>installed-packages.txt:</filename>

1357

A list of installed packages with full package

1358

filenames.</para></listitem>

1359

</itemizedlist>

1360

<note>

1361

Installed package information is able to be gathered and

1362

produced even if package management is disabled for the final

image.

</note>

</para>

<para>

Here is an example of <filename>image-info.txt</filename>:

DISTRO = poky

DISTRO_VERSION = 1.7

USER_CLASSES = buildstats image-mklibs image-prelink

1373

IMAGE_CLASSES = image_types

1374

IMAGE_FEATURES = debug-tweaks

1375

IMAGE_LINGUAS =

1376

IMAGE_INSTALL = packagegroup-core-boot run-postinsts

1377

BAD_RECOMMENDATIONS =

1378

NO_RECOMMENDATIONS =

1379

PACKAGE_EXCLUDE =

1380

ROOTFS_POSTPROCESS_COMMAND = write_package_manifest; license_create_manifest; \

1381

write_image_manifest ; buildhistory_list_installed_image ; \

1382

buildhistory_get_image_installed ; ssh_allow_empty_password; \

1383

postinst_enable_logging; rootfs_update_timestamp ; ssh_disable_dns_lookup ;

1384

IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;

1385

IMAGESIZE = 6900

1386

</literallayout>

1387

Other than <filename>IMAGESIZE</filename>, which is the

1388

total size of the files in the image in Kbytes, the

1389

name-value pairs are variables that may have influenced the

1390

content of the image.

1391

This information is often useful when you are trying to determine

1392

why a change in the package or file listings has occurred.

</para>

</section>

<title>Using Build History to Gather Image Information Only</title>

1398

1399

<para>

1400

As you can see, build history produces image information,

1401

including dependency graphs, so you can see why something

1402

was pulled into the image.

1403

If you are just interested in this information and not

1404

interested in collecting specific package or SDK information,

1405

you can enable writing only image information without

1406

any history by adding the following to your

1407

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

1408

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

1409

1410

INHERIT += "buildhistory"

1411

BUILDHISTORY_COMMIT = "0"

1412

BUILDHISTORY_FEATURES = "image"

</literallayout>

Here, you set the

variable to use the image feature only.

</para>

</section>

<title>Build History SDK Information</title>

Patrick Williams

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

[diff] [blame]

1422

Patrick Williams

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

[diff] [blame]

1423

<para>

1424

Build history collects similar information on the contents

Patrick Williams

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

[diff] [blame]

1425

of SDKs

1426

(e.g. <filename>bitbake -c populate_sdk imagename</filename>)

Patrick Williams

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

[diff] [blame]

1427

as compared to information it collects for images.

Patrick Williams

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

[diff] [blame]

1428

Furthermore, this information differs depending on whether an

1429

extensible or standard SDK is being produced.

</para>

<para>

The following list shows the files produced for SDKs:

Patrick Williams

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

[diff] [blame]

1434

1435

<listitem><para><filename>files-in-sdk.txt:</filename>

1436

A list of files in the SDK with permissions,

1437

owner, group, size, and symlink information.

1438

This list includes both the host and target parts

of the SDK.

</para></listitem>

A text file containing name-value pairs with information

1443

about the SDK.

1444

See the following listing example for more information.

1445

</para></listitem>

Patrick Williams

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

[diff] [blame]

1446

<listitem><para><filename>sstate-task-sizes.txt:</filename>

1447

A text file containing name-value pairs with information

1448

about task group sizes

1449

(e.g. <filename>do_populate_sysroot</filename> tasks

1450

have a total size).

1451

The <filename>sstate-task-sizes.txt</filename> file

1452

exists only when an extensible SDK is created.

1453

</para></listitem>

1454

<listitem><para><filename>sstate-package-sizes.txt:</filename>

1455

A text file containing name-value pairs with information

1456

for the shared-state packages and sizes in the SDK.

1457

The <filename>sstate-package-sizes.txt</filename> file

1458

exists only when an extensible SDK is created.

1459

</para></listitem>

1460

<listitem><para><filename>sdk-files:</filename>

1461

A folder that contains copies of the files mentioned in

1462

<filename>BUILDHISTORY_SDK_FILES</filename> if the

1463

files are present in the output.

1464

Additionally, the default value of

1465

<filename>BUILDHISTORY_SDK_FILES</filename> is specific

1466

to the extensible SDK although you can set it

1467

differently if you would like to pull in specific files

1468

from the standard SDK.</para>

1469

<para>The default files are

1470

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

1471

<filename>conf/bblayers.conf</filename>,

1472

<filename>conf/auto.conf</filename>,

1473

<filename>conf/locked-sigs.inc</filename>, and

1474

<filename>conf/devtool.conf</filename>.

1475

Thus, for an extensible SDK, these files get copied

1476

into the <filename>sdk-files</filename> directory.

1477

</para></listitem>

Patrick Williams

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

[diff] [blame]

1478

<listitem><para>The following information appears under

1479

each of the <filename>host</filename>

1480

and <filename>target</filename> directories

1481

for the portions of the SDK that run on the host and

1482

on the target, respectively:

Patrick Williams

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

[diff] [blame]

1483

<note>

1484

The following files for the most part are empty

1485

when producing an extensible SDK because this

1486

type of SDK is not constructed from packages as is

1487

the standard SDK.

1488

</note>

Patrick Williams

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

[diff] [blame]

1489

1490

<listitem><para><filename>depends.dot:</filename>

1491

Dependency graph for the SDK that is

1492

compatible with <filename>graphviz</filename>.

1493

</para></listitem>

1494

<listitem><para><filename>installed-package-names.txt:</filename>

1495

A list of installed packages by name only.

1496

</para></listitem>

1497

<listitem><para><filename>installed-package-sizes.txt:</filename>

1498

A list of installed packages ordered by size.

1499

</para></listitem>

1500

<listitem><para><filename>installed-packages.txt:</filename>

1501

A list of installed packages with full package

1502

filenames.</para></listitem>

</itemizedlist>

</para></listitem>

</itemizedlist>

</para>

<para>

Here is an example of <filename>sdk-info.txt</filename>:

1510

1511

DISTRO = poky

1512

DISTRO_VERSION = 1.3+snapshot-20130327

1513

SDK_NAME = poky-glibc-i686-arm

1514

SDK_VERSION = 1.3+snapshot

1515

SDKMACHINE =

1516

SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs

1517

BAD_RECOMMENDATIONS =

1518

SDKSIZE = 352712

1519

</literallayout>

1520

Other than <filename>SDKSIZE</filename>, which is the

1521

total size of the files in the SDK in Kbytes, the

1522

name-value pairs are variables that might have influenced the

1523

content of the SDK.

1524

This information is often useful when you are trying to

1525

determine why a change in the package or file listings

has occurred.

</para>

</section>

<title>Examining Build History Information</title>

1532

1533

<para>

1534

You can examine build history output from the command line or

1535

from a web interface.

</para>

<para>

To see any changes that have occurred (assuming you have

1540

1541

you can simply

1542

use any Git command that allows you to view the history of

a repository.

Here is one method:

$ git log -p

</literallayout>

You need to realize, however, that this method does show

1549

changes that are not significant (e.g. a package's size

1550

changing by a few bytes).

</para>

<para>

A command-line tool called <filename>buildhistory-diff</filename>

1555

does exist, though, that queries the Git repository and prints just

1556

the differences that might be significant in human-readable form.

1557

Here is an example:

1558

1559

$ ~/poky/poky/scripts/buildhistory-diff . HEAD^

1560

Changes to images/qemux86_64/glibc/core-image-minimal (files-in-image.txt):

1561

/etc/anotherpkg.conf was added

1562

/sbin/anotherpkg was added

1563

* (installed-package-names.txt):

1564

* anotherpkg was added

1565

Changes to images/qemux86_64/glibc/core-image-minimal (installed-package-names.txt):

1566

anotherpkg was added

1567

packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"

1568

* PR changed from "r0" to "r1"

1569

* PV changed from "0.1.10" to "0.1.12"

1570

packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)

1571

* PR changed from "r0" to "r1"

1572

* PV changed from "0.1.10" to "0.1.12"

1573

</literallayout>

Patrick Williams

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

[diff] [blame]

1574

<note>

1575

The <filename>buildhistory-diff</filename> tool requires

1576

the <filename>GitPython</filename> package.

1577

Be sure to install it using Pip3 as follows:

1578

1579

$ pip3 install GitPython --user

1580

</literallayout>

1581

Alternatively, you can install

1582

<filename>python3-git</filename> using the appropriate

1583

distribution package manager (e.g.

1584

<filename>apt-get</filename>, <filename>dnf</filename>, or

1585

<filename>zipper</filename>).

1586

</note>

Patrick Williams