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

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

[diff] [blame]

215

</para>

216

217

<para>

Patrick Williams

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

[diff] [blame]

218

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

219

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

220

are actually symbolic links to

221

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

222

and

223

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

224

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

225

it ran.

226

The symlinks always point to the files corresponding to the most

recent run.

</para>

</section>

<title>Viewing Variable Values</title>

233

<para>

234

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

235

variable values after parsing.

236

The following command displays the variable values after the

237

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

238

<filename>bblayers.conf</filename>,

239

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

parsed:

$ bitbake -e

</literallayout>

The following command displays variable values after a specific

245

recipe has been parsed.

246

The variables include those from the configuration as well:

247

248

$ bitbake -e recipename

249

</literallayout>

250

251

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

252

Internally, after parsing the configuration, a copy of the

253

resulting datastore is made prior to parsing each recipe.

254

This copying implies that variables set in one recipe will

255

not be visible to other recipes.</para>

256

257

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

258

datastore based on the recipe datastore, which means that

259

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

266

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

267

including temporary values that were later overriden.

268

This description also includes variable flags (varflags) set on

269

the variable.

270

The output can be very helpful during debugging.

</para>

<para>

Variables that are exported to the environment are preceded by

275

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

276

<filename>bitbake -e</filename>.

277

See the following example:

278

279

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

285

<filename>bitbake -e</filename> and

286

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

287

commands includes the following information:

288

289

290

The output starts with a tree listing all configuration

291

files and classes included globally, recursively listing

292

the files they include or inherit in turn.

293

Much of the behavior of the OpenEmbedded build system

294

(including the behavior of the

295

296

is implemented in the

297

298

class and the classes it inherits, rather than being built

into BitBake itself.

</para></listitem>

After the variable values, all functions appear in the

303

output.

304

For shell functions, variables referenced within the

305

function body are expanded.

306

If a function has been modified using overrides or

307

using override-style operators like

308

<filename>_append</filename> and

309

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

310

function body appears in the output.

</para></listitem>

</itemizedlist>

</para>

</section>

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

318

319

<para>

320

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

321

utility to query

322

323

and display various package-related information.

324

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

325

on packages that have already been built.

</para>

<para>

Following are a few of the available

330

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

331

<note>

332

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

333

package names and paths.

</note>

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

338

Lists all packages that have been built, optionally

339

limiting the match to packages that match

340

<replaceable>pattern</replaceable>.

341

</para></listitem>

342

343

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

344

Lists the files and directories contained in the given

packages.

<note>

<para>

A different way to view the contents of a package is

349

to look at the

350

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

351

directory of the recipe that generates the

352

package.

353

This directory is created by the

354

355

task and has one subdirectory for each package the

356

recipe generates, which contains the files stored in

357

that package.</para>

358

<para>

359

If you want to inspect the

360

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

361

directory, make sure that

362

363

is not enabled when you build the recipe.

</para>

</note>

</para></listitem>

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

369

Lists the names of the packages that contain the given

370

paths.

371

For example, the following tells us that

372

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

373

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

374

package:

375

376

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

377

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

</literallayout>

</para></listitem>

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

382

Lists the name of the recipes that

383

produce the given packages.

</para></listitem>

</itemizedlist>

</para>

<para>

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

390

command, use the help facility:

391

392

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

393

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

</literallayout>

</para>

</section>

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

400

401

<para>

402

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

403

recipes before the one you have specified.

404

Dependency information can help you understand why a recipe is

built.

</para>

<para>

To generate dependency information for a recipe, run the following

410

command:

411

412

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

413

</literallayout>

414

This command writes the following files in the current directory:

415

416

417

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

418

recipes/targets involved in building

419

<replaceable>recipename</replaceable>.

420

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

421

recipe needs to run when building

422

<replaceable>recipename</replaceable> from scratch.

Targets that are in

are not listed.

</para></listitem>

Patrick Williams

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

[diff] [blame]

428

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

429

dependencies between tasks.

</para></listitem>

</itemizedlist>

</para>

<para>

The graphs are in

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

438

<filename>dot</filename> tool from

439

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

440

<note><title>Notes</title>

441

442

443

DOT files use a plain text format.

444

The graphs generated using the

445

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

446

large as to be difficult to read without special

447

pruning (e.g. with Bitbake's

448

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

449

Despite the form and size of the graphs, the

450

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

451

be possible to read and provide useful information.

452

</para>

453

454

<para>As an example, the

455

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

456

lines such as the following:

457

458

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

459

</literallayout>

460

The above example line reveals that the

461

462

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

463

464

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

465

466

dependency between the two recipes.

467

</para></listitem>

468

469

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

470

can be processed, see the

471

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

472

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

481

by using the following command:

482

Brad Bishop

6e60e8b

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

[diff] [blame^]

483

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

Patrick Williams

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

[diff] [blame]

484

</literallayout>

485

This command displays a GUI window from which you can view

486

build-time and runtime dependencies for the recipes involved in

487

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

497

section of the BitBake User Manual, BitBake tries to automatically

498

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

499

the task if any values of the variables change.

500

This determination is usually reliable.

501

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

502

then you might have to manually declare dependencies on those

503

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

504

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

505

section of the BitBake User Manual.

</para>

<para>

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

510

automatically for a given task, you can list the variable

511

dependencies BitBake has determined by doing the following:

512

513

514

Build the recipe containing the task:

515

516

$ bitbake <replaceable>recipename</replaceable>

</literallayout>

</para></listitem>

Inside the

directory, find the signature data

523

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

524

task.

525

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

526

Python database of all the metadata that went into creating

527

the input checksum for the task.

528

As an example, for the

529

530

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

531

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

532

following location:

533

534

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

535

</literallayout>

536

For tasks that are accelerated through the shared state

537

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

538

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

539

written into

540

541

along with the cached task output.

542

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

543

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

544

</para></listitem>

545

546

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

547

<filename>sigdata</filename> or

548

<filename>siginfo</filename> file.

549

Here is an example:

550

551

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

552

</literallayout>

553

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

554

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

555

dependencies for the task.

556

This list also includes indirect dependencies from

557

variables depending on other variables, recursively.

558

559

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

560

</literallayout>

561

<note>

562

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

563

also count as variable dependencies.

564

These functions in turn depend on the variables they

565

reference.

566

</note>

567

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

568

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

569

variable, and

570

<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

578

comparing two <filename>siginfo</filename> or

579

<filename>sigdata</filename> files.

580

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

581

between two versions of a task.

582

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

583

file, the command behaves like

584

<filename>bitbake-dumpsig</filename>.

</para>

<para>

You can also use BitBake to dump out the signature construction

589

information without executing tasks by using either of the

590

following BitBake command-line options:

591

592

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

593

-S <replaceable>SIGNATURE_HANDLER</replaceable>

594

</literallayout>

595

<note>

596

Two common values for

597

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

598

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

599

dumped signature with the cached one, respectively.

600

</note>

601

Using BitBake with either of these options causes BitBake to dump

602

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

603

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

604

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>

610

611

<para>

Patrick Williams

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

[diff] [blame]

612

Any given recipe consists of a set of tasks.

Patrick Williams

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

[diff] [blame]

613

The standard BitBake behavior in most cases is:

614

<filename>do_fetch</filename>,

615

<filename>do_unpack</filename>,

616

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

617

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

618

<filename>do_package</filename>,

619

<filename>do_package_write_*</filename>, and

620

<filename>do_build</filename>.

621

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

622

on which it depends build first.

623

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

624

of the default build chain.

625

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

626

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

627

Here is an example:

628

629

$ bitbake matchbox-desktop -c devshell

</literallayout>

</para>

<para>

Patrick Williams

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

[diff] [blame]

634

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

635

which means that all other tasks (including tasks from other

636

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

637

task.

638

Even when you manually specify a task to run with

639

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

640

considers it "out of date".

641

See the

642

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

643

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.

648

because you made manual modifications to the recipe's

649

650

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

651

<filename>-f</filename> option.

652

<note>

653

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>

658

variable flag is already set for the task.

659

</note>

660

The following example shows one way you can use the

661

<filename>-f</filename> option:

Patrick Williams

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

[diff] [blame]

662

663

$ bitbake matchbox-desktop

664

.

665

.

Patrick Williams

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

[diff] [blame]

666

make some changes to the source code in the work directory

Patrick Williams

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

[diff] [blame]

667

.

668

.

669

$ bitbake matchbox-desktop -c compile -f

670

$ bitbake matchbox-desktop

</literallayout>

</para>

<para>

This sequence first builds and then recompiles

676

<filename>matchbox-desktop</filename>.

677

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

678

after the compile.

679

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

680

task was rerun and therefore understands that the other tasks

681

also need to be run again.

682

</para>

683

684

<para>

Patrick Williams

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

[diff] [blame]

685

Another, shorter way to rerun a task and all

686

687

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

688

option.

689

<note>

690

This option is upper-cased and is separate from the

691

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

692

</note>

693

Using this option invalidates the given task and then runs the

694

695

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

696

tasks on which it depends.

697

You could replace the final two commands in the previous example

698

with the following single command:

699

700

$ bitbake matchbox-desktop -C compile

701

</literallayout>

702

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

703

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

704

input checksum of the specified task.

705

This tainting indirectly causes the task and its

706

dependent tasks to be rerun through the normal task dependency

707

mechanisms.

708

<note>

709

BitBake explicitly keeps track of which tasks have been

710

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

711

following for builds involving such tasks:

712

713

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

714

</literallayout>

715

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

716

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

717

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

718

you took.

719

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

720

and rebuild the recipe, as follows:

721

722

$ bitbake matchbox-desktop -c clean

723

$ bitbake matchbox-desktop

</literallayout>

</note>

</para>

<para>

Patrick Williams

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

[diff] [blame]

729

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

730

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

731

732

$ bitbake matchbox-desktop -c listtasks

733

</literallayout>

734

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

735

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

</para>

</section>

Patrick Williams

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

[diff] [blame]

739

740

<title>General BitBake Problems</title>

741

742

<para>

743

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

744

The debug output gives more information about what BitBake

745

is doing and the reason behind it.

746

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

747

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

</para>

<para>

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

752

BitBake chose a certain version of a package or why BitBake

753

picked a certain provider.

754

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

unexpected.

</para>

</section>

<title>Development Host System Issues</title>

761

762

<para>

763

Sometimes issues on the host development system can cause your

764

build to fail.

765

Following are known, host-specific problems.

766

Be sure to always consult the

767

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

768

for a look at all release-related issues.

769

770

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

771

If your development host system has the unpatched

772

<filename>GNU Make 3.82</filename>,

773

the

774

775

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

776

the build.</para>

777

<para>Typically, every distribution that ships

778

<filename>GNU Make 3.82</filename> as

779

the default already has the patched version.

780

However, some distributions, such as Debian, have

781

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

782

is unpatched.

783

You will see this error on these types of distributions.

784

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

785

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

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Building with No Dependencies</title>

793

<para>

794

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

795

you can use the following command form:

796

797

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

798

</literallayout>

799

This command form does not check for dependencies.

800

Consequently, you should use it

801

only when you know existing dependencies have been met.

802

<note>

803

You can also specify fragments of the filename.

804

In this case, BitBake checks for a unique match.

</note>

</para>

</section>

Patrick Williams

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

[diff] [blame]

809

810

<title>Recipe Logging Mechanisms</title>

811

<para>

Patrick Williams

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

[diff] [blame]

812

The Yocto Project provides several logging functions for producing

813

debugging output and reporting errors and warnings.

814

For Python functions, the following logging functions exist.

815

All of these functions log to

816

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

817

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

818

settings:

Patrick Williams

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

[diff] [blame]

819

Patrick Williams

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

[diff] [blame]

820

821

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

822

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

823

also logging to stdout.

824

</para></listitem>

825

826

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

827

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

828

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

829

</para></listitem>

830

831

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

832

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

833

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

834

equal to <replaceable>level</replaceable>.

835

See the

836

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

837

option in the BitBake User Manual for more information.

838

</para></listitem>

839

840

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

841

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

842

while also logging to stdout.

843

</para></listitem>

844

845

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

846

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

847

while also logging to stdout.

848

<note>

849

Calling this function does not cause the task to fail.

</note>

</para></listitem>

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

854

This logging function is similar to

855

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

856

but also causes the calling task to fail.

857

<note>

858

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

859

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

860

statement after the function.

861

</note>

862

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

867

The same logging functions are also available in shell functions,

868

under the names

869

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

870

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

871

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

872

The

873

874

class implements these functions.

875

See that class in the

Patrick Williams

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

[diff] [blame]

876

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

Patrick Williams

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

[diff] [blame]

877

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

878

for information.

Patrick Williams

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

[diff] [blame]

</para>

<title>Logging With Python</title>

883

<para>

884

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

885

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

886

"silent" as possible.

887

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

</para>

<para>

Following is an example written in Python.

892

The code handles logging for a function that determines the

893

number of tasks needed to be run.

894

See the

895

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

896

section for additional information:

897

898

python do_listtasks() {

899

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

900

if noteworthy_condition:

901

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

902

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

903

if warning_trigger:

904

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

905

if recoverable_error:

906

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

907

if fatal_error:

908

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

909

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

910

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

}

</literallayout>

</para>

</section>

<title>Logging With Bash</title>

918

<para>

919

When creating recipes using Bash and inserting code that handles build

920

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

921

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

922

recipes written in Python described in the previous section.

</para>

<para>

Following is an example written in Bash.

927

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

928

929

do_my_function() {

930

bbdebug 2 "Running do_my_function"

931

if [ exceptional_condition ]; then

932

bbnote "Hit exceptional_condition"

933

fi

934

bbdebug 2 "Got to point xyz"

935

if [ warning_trigger ]; then

936

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

937

fi

938

if [ recoverable_error ]; then

939

bberror "Hit recoverable_error, correcting"

940

fi

941

if [ fatal_error ]; then

942

bbfatal "fatal_error detected"

943

fi

944

bbdebug 2 "Completed do_my_function"

}

</literallayout>

</para>

</section>

</section>

<title>Other Tips</title>

953

954

<para>

955

Here are some other tips that you might find useful:

956

Patrick Williams

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

[diff] [blame]

957

958

When adding new packages, it is worth watching for

959

undesirable items making their way into compiler command

960

lines.

961

For example, you do not want references to local system

962

files like

963

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

964

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

Patrick Williams

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

[diff] [blame]

965

</para></listitem>

Patrick Williams

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

[diff] [blame]

966

967

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

Patrick Williams

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

[diff] [blame]

968

boot splashscreen,

Patrick Williams

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

[diff] [blame]

969

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

970

command line.

Patrick Williams

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

[diff] [blame]

971

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

972

and thus allows you to see the console.

973

It is also possible to switch out of the splashscreen by

Patrick Williams

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

[diff] [blame]

974

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

on a Zaurus).

</para></listitem>

Removing

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

981

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

982

can often fix temporary build issues.

983

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

984

relatively cheap operation, because task output will be

985

cached in

986

987

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

988

also in the Build Directory).

989

<note>

990

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

991

workaround rather than a fix.

992

Consequently, trying to determine the underlying cause

993

of an issue before removing the directory is a good

idea.

</note>

</para></listitem>

Understanding how a feature is used in practice within

999

existing recipes can be very helpful.

1000

It is recommended that you configure some method that

1001

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

1002

1003

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

1004

function to recursively search through common

1005

recipe-related files, skipping binary files,

1006

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

1007

Build Directory (assuming its name starts with

"build"):

g() {

grep -Ir \

--exclude-dir=.git \

--exclude-dir='build*' \

1014

--include='*.bb*' \

1015

--include='*.inc*' \

1016

--include='*.conf*' \

--include='*.py*' \

"$@"

}

</literallayout>

Following are some usage examples:

1022

1023

$ g FOO # Search recursively for "FOO"

1024

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

1025

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

1026

</literallayout>

1027

If figuring out how some feature works requires a lot of

1028

searching, it might indicate that the documentation should

1029

be extended or improved.

1030

In such cases, consider filing a documentation bug using

1031

the Yocto Project implementation of

1032

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

1033

For general information on how to submit a bug against

1034

the Yocto Project, see the

1035

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

1036

section in the Yocto Project Development Manual.

1037

<note>

1038

The manuals might not be the right place to document

1039

variables that are purely internal and have a limited

1040

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

1041

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

1042

</note>

Patrick Williams

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

[diff] [blame]

</para></listitem>

</itemizedlist>

</para>

</section>

</section>

<title>Maintaining Build Output Quality</title>

1051

1052

<para>

1053

Many factors can influence the quality of a build.

1054

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

1055

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

1056

can occur that you might not detect until later.

1057

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

1058

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

1059

dependency on another library, which is auto-detected.

1060

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

1061

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

1062

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

1070

the quality of your build output.

1071

You can use the class to highlight unexpected and possibly unwanted

1072

changes in the build output.

1073

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

1074

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

1075

repository where you can examine the information.

</para>

<para>

The remainder of this section describes the following:

1080

1081

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

1082

build history</para></listitem>

1083

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

1084

</para></listitem>

1085

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

1086

</para></listitem>

1087

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

1088

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

</itemizedlist>

</para>

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

1094

1095

<para>

1096

Build history is disabled by default.

1097

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

1098

statement and set the

1099

1100

variable to "1" at the end of your

1101

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

1102

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

1103

1104

INHERIT += "buildhistory"

1105

BUILDHISTORY_COMMIT = "1"

1106

</literallayout>

1107

Enabling build history as previously described

1108

causes the build process to collect build

1109

output information and commit it to a local

1110

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

1111

<note>

1112

Enabling build history increases your build times slightly,

1113

particularly for images, and increases the amount of disk

1114

space used during the build.

</note>

</para>

<para>

You can disable build history by removing the previous statements

1120

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

</para>

</section>

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

1126

1127

<para>

1128

Build history information is kept in

1129

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

1130

in the Build Directory as defined by the

1131

1132

variable.

1133

The following is an example abbreviated listing:

</para>

<para>

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

1139

that lists the revisions of the repositories for the layers enabled

1140

when the build was produced.

1141

The rest of the data splits into separate

1142

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

1143

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

described below.

</para>

<title>Build History Package Information</title>

1149

1150

<para>

1151

The history for each package contains a text file that has

1152

name-value pairs with information about the package.

1153

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

1154

contains the following:

PV = 1.22.1

PR = r32

RPROVIDES =

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

1160

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

1161

PKGSIZE = 540168

1162

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

1163

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

1164

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

1165

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

1166

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

1167

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

1168

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

1169

</literallayout>

1170

Most of these name-value pairs correspond to variables used

1171

to produce the package.

1172

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

1173

actual list of files in the package, and

1174

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

1175

in the package in bytes.

</para>

<para>

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

1180

package came (e.g.

1181

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

PV = 1.22.1

PR = r32

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

1186

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

1187

virtual/libc virtual/update-alternatives

1188

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

1189

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

1190

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

</literallayout>

</para>

<para>

Finally, for those recipes fetched from a version control

1196

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

1197

that are specified in the recipe and lists the actual revisions

1198

used during the build.

1199

Listed and actual revisions might differ when

1200

1201

is set to

1202

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

1203

Here is an example assuming

1204

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

1205

1206

# SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"

1207

SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"

1208

# SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"

1209

SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"

1210

</literallayout>

1211

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

1212

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

1213

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

1214

from build history and report them in a format suitable for

1215

use in global configuration (e.g.,

1216

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

1217

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

1218

fixed set of revisions.

1219

Here is some example output from this command:

1220

1221

$ buildhistory-collect-srcrevs -a

1222

# i586-poky-linux

1223

SRCREV_pn-glibc = "b8079dd0d360648e4e8de48656c5c38972621072"

1224

SRCREV_pn-glibc-initial = "b8079dd0d360648e4e8de48656c5c38972621072"

1225

SRCREV_pn-opkg-utils = "53274f087565fd45d8452c5367997ba6a682a37a"

1226

SRCREV_pn-kmod = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"

1227

# x86_64-linux

1228

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

1229

SRCREV_pn-dtc-native = "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf"

1230

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

1231

SRCREV_glibc_pn-cross-localedef-native = "b8079dd0d360648e4e8de48656c5c38972621072"

1232

SRCREV_localedef_pn-cross-localedef-native = "c833367348d39dad7ba018990bfdaffaec8e9ed3"

1233

SRCREV_pn-prelink-native = "faa069deec99bf61418d0bab831c83d7c1b797ca"

1234

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

1235

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

1236

SRCREV_pn-kmod-native = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"

1237

# qemux86-poky-linux

1238

SRCREV_machine_pn-linux-yocto = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"

1239

SRCREV_meta_pn-linux-yocto = "a227f20eff056e511d504b2e490f3774ab260d6f"

1240

# all-poky-linux

1241

SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11"

1242

</literallayout>

1243

<note>

1244

Here are some notes on using the

1245

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

1246

1247

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

1248

<filename>SRCREV</filename> was

1249

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

1250

was used) are reported.

1251

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

1252

<filename>SRCREV</filename> values.

1253

</para></listitem>

1254

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

1255

if overrides are applied elsewhere in the build system

1256

configuration.

1257

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

1258

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

1259

if you need to work around this restriction.

1260

</para></listitem>

1261

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

1262

building for multiple machines.

1263

However, the script does place a

1264

comment before each set of values that specifies

1265

which triplet to which they belong as shown above

1266

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

</para></listitem>

</itemizedlist>

</note>

</para>

</section>

<title>Build History Image Information</title>

1275

1276

<para>

1277

The files produced for each image are as follows:

1278

1279

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

1280

A directory containing selected files from the root

1281

filesystem.

1282

The files are defined by

1283

1284

</para></listitem>

1285

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

1286

Human-readable information about the build configuration

1287

and metadata source revisions.

1288

This file contains the full build header as printed

1289

by BitBake.</para></listitem>

1290

1291

Dependency graphs for the image that are

1292

compatible with <filename>graphviz</filename>.

1293

</para></listitem>

1294

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

1295

A list of files in the image with permissions,

1296

owner, group, size, and symlink information.

1297

</para></listitem>

1298

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

1299

A text file containing name-value pairs with information

1300

about the image.

1301

See the following listing example for more information.

1302

</para></listitem>

1303

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

1304

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

1305

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

1306

A list of installed packages ordered by size.

1307

</para></listitem>

1308

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

1309

A list of installed packages with full package

1310

filenames.</para></listitem>

1311

</itemizedlist>

1312

<note>

1313

Installed package information is able to be gathered and

1314

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

1325

IMAGE_CLASSES = image_types

1326

IMAGE_FEATURES = debug-tweaks

1327

IMAGE_LINGUAS =

1328

IMAGE_INSTALL = packagegroup-core-boot run-postinsts

1329

BAD_RECOMMENDATIONS =

1330

NO_RECOMMENDATIONS =

1331

PACKAGE_EXCLUDE =

1332

ROOTFS_POSTPROCESS_COMMAND = write_package_manifest; license_create_manifest; \

1333

write_image_manifest ; buildhistory_list_installed_image ; \

1334

buildhistory_get_image_installed ; ssh_allow_empty_password; \

1335

postinst_enable_logging; rootfs_update_timestamp ; ssh_disable_dns_lookup ;

1336

IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;

1337

IMAGESIZE = 6900

1338

</literallayout>

1339

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

1340

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

1341

name-value pairs are variables that may have influenced the

1342

content of the image.

1343

This information is often useful when you are trying to determine

1344

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

</para>

</section>

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

1350

1351

<para>

1352

As you can see, build history produces image information,

1353

including dependency graphs, so you can see why something

1354

was pulled into the image.

1355

If you are just interested in this information and not

1356

interested in collecting specific package or SDK information,

1357

you can enable writing only image information without

1358

any history by adding the following to your

1359

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

1360

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

1361

1362

INHERIT += "buildhistory"

1363

BUILDHISTORY_COMMIT = "0"

1364

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]

1374

Patrick Williams

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

[diff] [blame]

1375

<para>

1376

Build history collects similar information on the contents

Patrick Williams

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

[diff] [blame]

1377

of SDKs

1378

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

Patrick Williams

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

[diff] [blame]

1379

as compared to information it collects for images.

Patrick Williams

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

[diff] [blame]

1380

Furthermore, this information differs depending on whether an

1381

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]

1386

1387

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

1388

A list of files in the SDK with permissions,

1389

owner, group, size, and symlink information.

1390

This list includes both the host and target parts

of the SDK.

</para></listitem>

A text file containing name-value pairs with information

1395

about the SDK.

1396

See the following listing example for more information.

1397

</para></listitem>

Patrick Williams

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

[diff] [blame]

1398

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

1399

A text file containing name-value pairs with information

1400

about task group sizes

1401

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

1402

have a total size).

1403

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

1404

exists only when an extensible SDK is created.

1405

</para></listitem>

1406

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

1407

A text file containing name-value pairs with information

1408

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

1409

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

1410

exists only when an extensible SDK is created.

1411

</para></listitem>

1412

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

1413

A folder that contains copies of the files mentioned in

1414

<filename>BUILDHISTORY_SDK_FILES</filename> if the

1415

files are present in the output.

1416

Additionally, the default value of

1417

<filename>BUILDHISTORY_SDK_FILES</filename> is specific

1418

to the extensible SDK although you can set it

1419

differently if you would like to pull in specific files

1420

from the standard SDK.</para>

1421

<para>The default files are

1422

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

1423

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

1424

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

1425

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

1426

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

1427

Thus, for an extensible SDK, these files get copied

1428

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

1429

</para></listitem>

Patrick Williams

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

[diff] [blame]

1430

<listitem><para>The following information appears under

1431

each of the <filename>host</filename>

1432

and <filename>target</filename> directories

1433

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

1434

on the target, respectively:

Patrick Williams

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

[diff] [blame]

1435

<note>

1436

The following files for the most part are empty

1437

when producing an extensible SDK because this

1438

type of SDK is not constructed from packages as is

1439

the standard SDK.

1440

</note>

Patrick Williams

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

[diff] [blame]

1441

1442

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

1443

Dependency graph for the SDK that is

1444

compatible with <filename>graphviz</filename>.

1445

</para></listitem>

1446

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

1447

A list of installed packages by name only.

1448

</para></listitem>

1449

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

1450

A list of installed packages ordered by size.

1451

</para></listitem>

1452

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

1453

A list of installed packages with full package

1454

filenames.</para></listitem>

</itemizedlist>

</para></listitem>

</itemizedlist>

</para>

<para>

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

1462

1463

DISTRO = poky

1464

DISTRO_VERSION = 1.3+snapshot-20130327

1465

SDK_NAME = poky-glibc-i686-arm

1466

SDK_VERSION = 1.3+snapshot

1467

SDKMACHINE =

1468

SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs

1469

BAD_RECOMMENDATIONS =

1470

SDKSIZE = 352712

1471

</literallayout>

1472

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

1473

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

1474

name-value pairs are variables that might have influenced the

1475

content of the SDK.

1476

This information is often useful when you are trying to

1477

determine why a change in the package or file listings

has occurred.

</para>

</section>

<title>Examining Build History Information</title>

1484

1485

<para>

1486

You can examine build history output from the command line or

1487

from a web interface.

</para>

<para>

To see any changes that have occurred (assuming you have

1492

1493

you can simply

1494

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

1501

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

1502

changing by a few bytes).

</para>

<para>

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

1507

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

1508

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

1509

Here is an example:

1510

1511

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

1512

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

1513

/etc/anotherpkg.conf was added

1514

/sbin/anotherpkg was added

1515

* (installed-package-names.txt):

1516

* anotherpkg was added

1517

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

1518

anotherpkg was added

1519

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

1520

* PR changed from "r0" to "r1"

1521

* PV changed from "0.1.10" to "0.1.12"

1522

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

1523

* PR changed from "r0" to "r1"

1524

* PV changed from "0.1.10" to "0.1.12"

1525

</literallayout>

Patrick Williams

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

[diff] [blame]

1526

<note>

1527

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

1528

the <filename>GitPython</filename> package.

1529

Be sure to install it using Pip3 as follows:

1530

1531

$ pip3 install GitPython --user

1532

</literallayout>

1533

Alternatively, you can install

1534

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

1535

distribution package manager (e.g.

1536

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

1537

<filename>zipper</filename>).

1538

</note>

Patrick Williams