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

2018-02-25 22:55:05 -0500

[diff] [blame]

238

I see lots of 404 responses for files when the OpenEmbedded

239

build system is trying to download sources.

240

Is something wrong?

Patrick Williams

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

[diff] [blame]

</para>

</question>

<para>

Nothing is wrong.

The OpenEmbedded build system checks any configured source mirrors before downloading

247

from the upstream sources.

248

The build system does this searching for both source archives and

249

pre-checked out versions of SCM-managed software.

250

These checks help in large installations because it can reduce load on the SCM servers

251

themselves.

252

The address above is one of the default mirrors configured into the

253

build system.

254

Consequently, if an upstream source disappears, the team

255

can place sources there so builds continue to work.

</para>

</answer>

</qandaentry>

<para>

I have machine-specific data in a package for one machine only but the package is

264

being marked as machine-specific in all cases, how do I prevent this?

</para>

</question>

<para>

Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>

270

</filename> = "0" in the <filename>.bb</filename> file but make sure the package is

271

manually marked as

272

machine-specific for the case that needs it.

273

The code that handles

274

<filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in

275

the <filename>meta/classes/base.bbclass</filename> file.

</para>

</answer>

</qandaentry>

Patrick Williams

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

[diff] [blame]

282

Patrick Williams

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

[diff] [blame]

283

I'm behind a firewall and need to use a proxy server. How do I do that?

</para>

</question>

<para>

Patrick Williams

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

[diff] [blame]

288

Most source fetching by the OpenEmbedded build system is done

289

by <filename>wget</filename> and you therefore need to specify

290

the proxy settings in a <filename>.wgetrc</filename> file,

291

which can be in your home directory if you are a single user

292

or can be in <filename>/usr/local/etc/wgetrc</filename> as

a global user file.

</para>

<para>

Following is the applicable code for setting various proxy

298

types in the <filename>.wgetrc</filename> file.

299

By default, these settings are disabled with comments.

300

To use them, remove the comments:

Patrick Williams

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

[diff] [blame]

301

Patrick Williams

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

[diff] [blame]

302

# You can set the default proxies for Wget to use for http, https, and ftp.

303

# They will override the value in the environment.

304

#https_proxy = http://proxy.yoyodyne.com:18023/

305

#http_proxy = http://proxy.yoyodyne.com:18023/

306

#ftp_proxy = http://proxy.yoyodyne.com:18023/

307

308

# If you do not want to use proxy at all, set this to off.

309

#use_proxy = on

Patrick Williams

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

[diff] [blame]

310

</literallayout>

311

The Yocto Project also includes a

Patrick Williams

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

[diff] [blame]

312

<filename>meta-poky/conf/site.conf.sample</filename> file that

313

shows how to configure CVS and Git proxy servers if needed.

314

For more information on setting up various proxy types and

315

configuring proxy servers, see the

316

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

317

Wiki page.

Patrick Williams

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

[diff] [blame]

</para>

</answer>

</qandaentry>

<para>

What’s the difference between <replaceable>target</replaceable> and <replaceable>target</replaceable><filename>-native</filename>?

</para>

</question>

<para>

The <filename>*-native</filename> targets are designed to run on the system

331

being used for the build.

332

These are usually tools that are needed to assist the build in some way such as

333

<filename>quilt-native</filename>, which is used to apply patches.

334

The non-native version is the one that runs on the target device.

</para>

</answer>

</qandaentry>

<para>

I'm seeing random build failures. Help?!

</para>

</question>

<para>

If the same build is failing in totally different and random

348

ways, the most likely explanation is:

349

350

<listitem><para>The hardware you are running the build on

351

has some problem.</para></listitem>

352

<listitem><para>You are running the build under

353

virtualization, in which case the virtualization

354

probably has bugs.</para></listitem>

355

</itemizedlist>

356

The OpenEmbedded build system processes a massive amount of

357

data that causes lots of network, disk and CPU activity and

358

is sensitive to even single-bit failures in any of these areas.

359

True random failures have always been traced back to hardware

360

or virtualization issues.

</para>

</answer>

</qandaentry>

<para>

When I try to build a native recipe, the build fails with <filename>iconv.h</filename> problems.

</para>

</question>

<para>

If you get an error message that indicates GNU

374

<filename>libiconv</filename> is not in use but

375

<filename>iconv.h</filename> has been included from

376

<filename>libiconv</filename>, you need to check to see if

377

you have a previously installed version of the header file

378

in <filename>/usr/local/include</filename>.

379

380

#error GNU libiconv not in use but included iconv.h is from libiconv

381

</literallayout>

382

If you find a previously installed file, you should either

383

uninstall it or temporarily rename it and try the build again.

</para>

<para>

This issue is just a single manifestation of "system

Patrick Williams

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

[diff] [blame]

388

leakage" issues caused when the OpenEmbedded build system

Patrick Williams

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

[diff] [blame]

389

finds and uses previously installed files during a native

390

build.

391

This type of issue might not be limited to

392

<filename>iconv.h</filename>.

393

Be sure that leakage cannot occur from

394

<filename>/usr/local/include</filename> and

395

<filename>/opt</filename> locations.

</para>

</answer>

</qandaentry>

<para>

What do we need to ship for license compliance?

</para>

</question>

<para>

This is a difficult question and you need to consult your lawyer

409

for the answer for your specific case.

410

It is worth bearing in mind that for GPL compliance, there needs

411

to be enough information shipped to allow someone else to

412

rebuild and produce the same end result you are shipping.

413

This means sharing the source code, any patches applied to it,

414

and also any configuration information about how that package

415

was configured and built.

</para>

<para>

You can find more information on licensing in the

Brad Bishop

316dfdd

2018-06-25 12:45:53 -0400

[diff] [blame^]

420

"<ulink url='&YOCTO_DOCS_OM_URL;#licensing'>Licensing</ulink>"

421

section in the Yocto Project Overview and Concepts Manual

422

and also in the

Brad Bishop

2018-02-25 22:55:05 -0500

[diff] [blame]

423

"<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"

Brad Bishop

316dfdd

2018-06-25 12:45:53 -0400

[diff] [blame^]

424

section in the Yocto Project Development Tasks Manual.

Patrick Williams

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

[diff] [blame]

</para>

</answer>

</qandaentry>

<para>

How do I disable the cursor on my touchscreen device?

</para>

</question>

<para>

You need to create a form factor file as described in the

438

"<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"

439

section in the Yocto Project Board Support Packages (BSP)

440

Developer's Guide.

441

Set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to

one as follows:

HAVE_TOUCHSCREEN=1

</literallayout>

</para>

</answer>

</qandaentry>

<para>

How do I make sure connected network interfaces are brought up by default?

</para>

</question>

<para>

The default interfaces file provided by the netbase recipe does not

459

automatically bring up network interfaces.

460

Therefore, you will need to add a BSP-specific netbase that includes an interfaces

461

file.

462

See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"

463

section in the Yocto Project Board Support Packages (BSP)

464

Developer's Guide for information on creating these types of

465

miscellaneous recipe files.

466

</para>

467

<para>

468

For example, add the following files to your layer:

469

470

meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces

471

meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend

</literallayout>

</para>

</answer>

</qandaentry>

<para>

How do I create images with more free space?

</para>

</question>

<para>

By default, the OpenEmbedded build system creates images

486

that are 1.3 times the size of the populated root filesystem.

487

To affect the image size, you need to set various

488

configurations:

489

490

<listitem><para><emphasis>Image Size:</emphasis>

491

The OpenEmbedded build system uses the

492

493

variable to define the size of the image in Kbytes.

494

The build system determines the size by taking into

495

account the initial root filesystem size before any

496

modifications such as requested size for the image and

497

any requested additional free disk space to be

498

added to the image.</para></listitem>

499

<listitem><para><emphasis>Overhead:</emphasis>

500

Use the

501

502

variable to define the multiplier that the build system

503

applies to the initial image size, which is 1.3 by

504

default.</para></listitem>

505

<listitem><para><emphasis>Additional Free Space:</emphasis>

506

Use the

507

508

variable to add additional free space to the image.

509

The build system adds this space to the image after

510

it determines its

511

<filename>IMAGE_ROOTFS_SIZE</filename>.

</para></listitem>

</itemizedlist>

</para>

</answer>

</qandaentry>

<para>

Why don't you support directories with spaces in the pathnames?

</para>

</question>

<para>

The Yocto Project team has tried to do this before but too

527

many of the tools the OpenEmbedded build system depends on,

528

such as <filename>autoconf</filename>, break when they find

529

spaces in pathnames.

530

Until that situation changes, the team will not support spaces

in pathnames.

</para>

</answer>

</qandaentry>

<para>

How do I use an external toolchain?

</para>

</question>

<para>

The toolchain configuration is very flexible and customizable.

545

It is primarily controlled with the

546

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

547

variable.

548

This variable controls which <filename>tcmode-*.inc</filename>

549

file to include from the

550

<filename>meta/conf/distro/include</filename> directory within

551

the

Brad Bishop

2018-02-25 22:55:05 -0500

[diff] [blame]

552

Patrick Williams

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

[diff] [blame]

</para>

<para>

The default value of <filename>TCMODE</filename> is "default",

557

which tells the OpenEmbedded build system to use its internally

558

built toolchain (i.e. <filename>tcmode-default.inc</filename>).

559

However, other patterns are accepted.

560

In particular, "external-*" refers to external toolchains.

561

One example is the Sourcery G++ Toolchain.

562

The support for this toolchain resides in the separate

563

<filename>meta-sourcery</filename> layer at

564

<ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.

</para>

<para>

In addition to the toolchain configuration, you also need a

569

corresponding toolchain recipe file.

570

This recipe file needs to package up any pre-built objects in

571

the toolchain such as <filename>libgcc</filename>,

572

<filename>libstdcc++</filename>, any locales, and

573

<filename>libc</filename>.

</para>

</answer>

</qandaentry>

How does the OpenEmbedded build system obtain source code and

582

will it work behind my firewall or proxy server?

</para>

</question>

<para>

The way the build system obtains source code is highly

588

configurable.

589

You can setup the build system to get source code in most

590

environments if HTTP transport is available.

591

</para>

592

<para>

593

When the build system searches for source code, it first

594

tries the local download directory.

595

If that location fails, Poky tries

596

597

the upstream source, and then

in that order.

</para>

<para>

Assuming your distribution is "poky", the OpenEmbedded build

603

system uses the Yocto Project source

604

<filename>PREMIRRORS</filename> by default for SCM-based

605

sources, upstreams for normal tarballs, and then falls back

606

to a number of other mirrors including the Yocto Project

607

source mirror if those fail.

608

</para>

609

<para>

610

As an example, you could add a specific server for the

611

build system to attempt before any others by adding something

612

like the following to the <filename>local.conf</filename>

613

configuration file:

614

615

PREMIRRORS_prepend = "\

616

git://.*/.* http://www.yoctoproject.org/sources/ \n \

617

ftp://.*/.* http://www.yoctoproject.org/sources/ \n \

618

http://.*/.* http://www.yoctoproject.org/sources/ \n \

619

https://.*/.* http://www.yoctoproject.org/sources/ \n"

</literallayout>

</para>

<para>

These changes cause the build system to intercept Git, FTP,

624

HTTP, and HTTPS requests and direct them to the

625

<filename>http://</filename> sources mirror.

626

You can use <filename>file://</filename> URLs to point to

627

local directories or network shares as well.

628

</para>

629

<para>

630

Aside from the previous technique, these options also exist:

BB_NO_NETWORK = "1"

</literallayout>

This statement tells BitBake to issue an error instead of

635

trying to access the Internet.

636

This technique is useful if you want to ensure code builds

637

only from local sources.

638

</para>

639

<para>

640

Here is another technique:

641

642

BB_FETCH_PREMIRRORONLY = "1"

643

</literallayout>

644

This statement limits the build system to pulling source

645

from the <filename>PREMIRRORS</filename> only.

646

Again, this technique is useful for reproducing builds.

647

</para>

648

<para>

649

Here is another technique:

650

651

BB_GENERATE_MIRROR_TARBALLS = "1"

652

</literallayout>

653

This statement tells the build system to generate mirror

654

tarballs.

655

This technique is useful if you want to create a mirror server.

656

If not, however, the technique can simply waste time during

the build.

</para>

<para>

Finally, consider an example where you are behind an

661

HTTP-only firewall.

662

You could make the following changes to the

663

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

664

the <filename>PREMIRRORS</filename> server is current:

665

666

PREMIRRORS_prepend = "\

667

ftp://.*/.* http://www.yoctoproject.org/sources/ \n \

668

http://.*/.* http://www.yoctoproject.org/sources/ \n \

669

https://.*/.* http://www.yoctoproject.org/sources/ \n"

670

BB_FETCH_PREMIRRORONLY = "1"

671

</literallayout>

672

These changes would cause the build system to successfully

673

fetch source over HTTP and any network accesses to anything

674

other than the <filename>PREMIRRORS</filename> would fail.

675

</para>

676

<para>

677

The build system also honors the standard shell environment

678

variables <filename>http_proxy</filename>,

679

<filename>ftp_proxy</filename>,

680

<filename>https_proxy</filename>, and

681

<filename>all_proxy</filename> to redirect requests through

proxy servers.

</para>

<note>

You can find more information on the

686

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

Wiki page.

</note>

</answer>

</qandaentry>

<para>

Can I get rid of build output so I can start over?

</para>

</question>

<para>

Yes - you can easily do this.

701

When you use BitBake to build an image, all the build output

702

goes into the directory created when you run the

703

build environment setup script (i.e.

Brad Bishop

2018-02-25 22:55:05 -0500

[diff] [blame]

By default, this

Patrick Williams

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

[diff] [blame]

707

is named <filename>build</filename> but can be named

anything you want.

</para>

<para>

Within the Build Directory, is the <filename>tmp</filename>

713

directory.

714

To remove all the build output yet preserve any source code or

715

downloaded files from previous builds, simply remove the

716

<filename>tmp</filename> directory.

</para>

</answer>

</qandaentry>

<para>

Why do <filename>${bindir}</filename> and <filename>${libdir}</filename> have strange values for <filename>-native</filename> recipes?

</para>

</question>

<para>

Executables and libraries might need to be used from a

730

directory other than the directory into which they were

731

initially installed.

732

Complicating this situation is the fact that sometimes these

733

executables and libraries are compiled with the expectation

734

of being run from that initial installation target directory.

735

If this is the case, moving them causes problems.

</para>

<para>

This scenario is a fundamental problem for package maintainers

740

of mainstream Linux distributions as well as for the

741

OpenEmbedded build system.

742

As such, a well-established solution exists.

743

Makefiles, Autotools configuration scripts, and other build

744

systems are expected to respect environment variables such as

745

<filename>bindir</filename>, <filename>libdir</filename>,

746

and <filename>sysconfdir</filename> that indicate where

747

executables, libraries, and data reside when a program is

748

actually run.

749

They are also expected to respect a

750

<filename>DESTDIR</filename> environment variable, which is

751

prepended to all the other variables when the build system

752

actually installs the files.

753

It is understood that the program does not actually run from

754

within <filename>DESTDIR</filename>.

</para>

<para>

When the OpenEmbedded build system uses a recipe to build a

759

target-architecture program (i.e. one that is intended for

760

inclusion on the image being built), that program eventually

761

runs from the root file system of that image.

762

Thus, the build system provides a value of "/usr/bin" for

763

<filename>bindir</filename>, a value of "/usr/lib" for

764

<filename>libdir</filename>, and so forth.

</para>

<para>

Meanwhile, <filename>DESTDIR</filename> is a path within the

Brad Bishop

2018-02-25 22:55:05 -0500

[diff] [blame]

769

Patrick Williams

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

[diff] [blame]

770

However, when the recipe builds a native program (i.e. one

771

that is intended to run on the build machine), that program

772

is never installed directly to the build machine's root

773

file system.

774

Consequently, the build system uses paths within the Build

775

Directory for <filename>DESTDIR</filename>,

776

<filename>bindir</filename> and related variables.

777

To better understand this, consider the following two paths

778

where the first is relatively normal and the second is not:

779

<note>

780

Due to these lengthy examples, the paths are artificially

781

broken across lines for readability.

782

</note>

783

784

/home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/

785

1.2.8-r0/sysroot-destdir/usr/bin

786

787

/home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/

788

zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/

789

build/tmp/sysroots/x86_64-linux/usr/bin

790

</literallayout>

791

Even if the paths look unusual, they both are correct -

792

the first for a target and the second for a native recipe.

793

These paths are a consequence of the

794

<filename>DESTDIR</filename> mechanism and while they

795

appear strange, they are correct and in practice very effective.

</para>

</answer>

</qandaentry>

<para>

Patrick Williams

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

[diff] [blame]

803

The files provided by my <filename>*-native</filename> recipe do

Patrick Williams

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

[diff] [blame]

804

not appear to be available to other recipes.

805

Files are missing from the native sysroot, my recipe is

806

installing to the wrong place, or I am getting permissions

807

errors during the do_install task in my recipe! What is wrong?

</para>

</question>

<para>

This situation results when a build system does

813

not recognize the environment variables supplied to it by

Brad Bishop

2018-02-25 22:55:05 -0500

[diff] [blame]

814

Patrick Williams