Blame - poky/documentation/ref-manual/faq.xml - stefanberger/openbmc

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

[diff] [blame]

239

I see lots of 404 responses for files when the OpenEmbedded

240

build system is trying to download sources.

241

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

248

from the upstream sources.

249

The build system does this searching for both source archives and

250

pre-checked out versions of SCM-managed software.

251

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

252

themselves.

253

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

254

build system.

255

Consequently, if an upstream source disappears, the team

256

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

265

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>

271

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

272

manually marked as

273

machine-specific for the case that needs it.

274

The code that handles

275

<filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in

276

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

</para>

</answer>

</qandaentry>

Patrick Williams

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

[diff] [blame]

283

Patrick Williams

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

[diff] [blame]

284

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]

289

Most source fetching by the OpenEmbedded build system is done

290

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

291

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

292

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

293

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

299

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

300

By default, these settings are disabled with comments.

301

To use them, remove the comments:

Patrick Williams

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

[diff] [blame]

302

Patrick Williams

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

[diff] [blame]

303

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

304

# They will override the value in the environment.

305

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

306

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

307

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

308

309

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

310

#use_proxy = on

Patrick Williams

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

[diff] [blame]

311

</literallayout>

312

The Yocto Project also includes a

Patrick Williams

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

[diff] [blame]

313

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

314

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

315

For more information on setting up various proxy types and

316

configuring proxy servers, see the

317

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

318

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

332

being used for the build.

333

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

334

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

335

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

349

ways, the most likely explanation is:

350

351

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

352

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

353

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

354

virtualization, in which case the virtualization

355

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

356

</itemizedlist>

357

The OpenEmbedded build system processes a massive amount of

358

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

359

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

360

True random failures have always been traced back to hardware

361

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

375

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

376

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

377

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

378

you have a previously installed version of the header file

379

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

380

381

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

382

</literallayout>

383

If you find a previously installed file, you should either

384

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]

389

leakage" issues caused when the OpenEmbedded build system

Patrick Williams

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

[diff] [blame]

390

finds and uses previously installed files during a native

391

build.

392

This type of issue might not be limited to

393

<filename>iconv.h</filename>.

394

Be sure that leakage cannot occur from

395

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

396

<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

410

for the answer for your specific case.

411

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

412

to be enough information shipped to allow someone else to

413

rebuild and produce the same end result you are shipping.

414

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

415

and also any configuration information about how that package

416

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]

421

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

422

section in the Yocto Project Overview and Concepts Manual

423

and also in the

Brad Bishop

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

[diff] [blame]

424

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

425

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

439

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

440

section in the Yocto Project Board Support Packages (BSP)

441

Developer's Guide.

442

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

460

automatically bring up network interfaces.

461

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

462

file.

463

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

464

section in the Yocto Project Board Support Packages (BSP)

465

Developer's Guide for information on creating these types of

466

miscellaneous recipe files.

467

</para>

468

<para>

469

For example, add the following files to your layer:

470

471

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

472

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

487

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

488

To affect the image size, you need to set various

489

configurations:

490

491

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

492

The OpenEmbedded build system uses the

493

494

variable to define the size of the image in Kbytes.

495

The build system determines the size by taking into

496

account the initial root filesystem size before any

497

modifications such as requested size for the image and

498

any requested additional free disk space to be

499

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

500

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

501

Use the

502

503

variable to define the multiplier that the build system

504

applies to the initial image size, which is 1.3 by

505

default.</para></listitem>

506

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

507

Use the

508

509

variable to add additional free space to the image.

510

The build system adds this space to the image after

511

it determines its

512

<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

528

many of the tools the OpenEmbedded build system depends on,

529

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

530

spaces in pathnames.

531

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.

546

It is primarily controlled with the

547

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

548

variable.

549

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

550

file to include from the

551

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

552

the

Brad Bishop

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

[diff] [blame]

553

Patrick Williams

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

[diff] [blame]

</para>

<para>

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

558

which tells the OpenEmbedded build system to use its internally

559

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

560

However, other patterns are accepted.

561

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

562

One example is the Sourcery G++ Toolchain.

563

The support for this toolchain resides in the separate

564

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

565

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

</para>

<para>

In addition to the toolchain configuration, you also need a

570

corresponding toolchain recipe file.

571

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

572

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

573

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

574

<filename>libc</filename>.

</para>

</answer>

</qandaentry>

How does the OpenEmbedded build system obtain source code and

583

will it work behind my firewall or proxy server?

</para>

</question>

<para>

The way the build system obtains source code is highly

589

configurable.

590

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

591

environments if HTTP transport is available.

592

</para>

593

<para>

594

When the build system searches for source code, it first

595

tries the local download directory.

596

If that location fails, Poky tries

597

598

the upstream source, and then

in that order.

</para>

<para>

Assuming your distribution is "poky", the OpenEmbedded build

604

system uses the Yocto Project source

605

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

606

sources, upstreams for normal tarballs, and then falls back

607

to a number of other mirrors including the Yocto Project

608

source mirror if those fail.

609

</para>

610

<para>

611

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

612

build system to attempt before any others by adding something

613

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

614

configuration file:

615

616

PREMIRRORS_prepend = "\

617

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

618

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

619

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

620

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

</literallayout>

</para>

<para>

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

625

HTTP, and HTTPS requests and direct them to the

626

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

627

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

628

local directories or network shares as well.

629

</para>

630

<para>

631

Aside from the previous technique, these options also exist:

BB_NO_NETWORK = "1"

</literallayout>

This statement tells BitBake to issue an error instead of

636

trying to access the Internet.

637

This technique is useful if you want to ensure code builds

638

only from local sources.

639

</para>

640

<para>

641

Here is another technique:

642

643

BB_FETCH_PREMIRRORONLY = "1"

644

</literallayout>

645

This statement limits the build system to pulling source

646

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

647

Again, this technique is useful for reproducing builds.

648

</para>

649

<para>

650

Here is another technique:

651

652

BB_GENERATE_MIRROR_TARBALLS = "1"

653

</literallayout>

654

This statement tells the build system to generate mirror

655

tarballs.

656

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

657

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

the build.

</para>

<para>

Finally, consider an example where you are behind an

662

HTTP-only firewall.

663

You could make the following changes to the

664

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

665

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

666

667

PREMIRRORS_prepend = "\

668

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

669

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

670

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

671

BB_FETCH_PREMIRRORONLY = "1"

672

</literallayout>

673

These changes would cause the build system to successfully

674

fetch source over HTTP and any network accesses to anything

675

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

676

</para>

677

<para>

678

The build system also honors the standard shell environment

679

variables <filename>http_proxy</filename>,

680

<filename>ftp_proxy</filename>,

681

<filename>https_proxy</filename>, and

682

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

proxy servers.

</para>

<note>

You can find more information on the

687

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

702

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

703

goes into the directory created when you run the

704

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]

708

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

anything you want.

</para>

<para>

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

714

directory.

715

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

716

downloaded files from previous builds, simply remove the

717

<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

731

directory other than the directory into which they were

732

initially installed.

733

Complicating this situation is the fact that sometimes these

734

executables and libraries are compiled with the expectation

735

of being run from that initial installation target directory.

736

If this is the case, moving them causes problems.

</para>

<para>

This scenario is a fundamental problem for package maintainers

741

of mainstream Linux distributions as well as for the

742

OpenEmbedded build system.

743

As such, a well-established solution exists.

744

Makefiles, Autotools configuration scripts, and other build

745

systems are expected to respect environment variables such as

746

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

747

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

748

executables, libraries, and data reside when a program is

749

actually run.

750

They are also expected to respect a

751

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

752

prepended to all the other variables when the build system

753

actually installs the files.

754

It is understood that the program does not actually run from

755

within <filename>DESTDIR</filename>.

</para>

<para>

When the OpenEmbedded build system uses a recipe to build a

760

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

761

inclusion on the image being built), that program eventually

762

runs from the root file system of that image.

763

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

764

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

765

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

770

Patrick Williams

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

[diff] [blame]

771

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

772

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

773

is never installed directly to the build machine's root

774

file system.

775

Consequently, the build system uses paths within the Build

776

Directory for <filename>DESTDIR</filename>,

777

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

778

To better understand this, consider the following two paths

779

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

780

<note>

781

Due to these lengthy examples, the paths are artificially

782

broken across lines for readability.

783

</note>

784

785

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

786

1.2.8-r0/sysroot-destdir/usr/bin

787

788

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

789

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

790

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

791

</literallayout>

792

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

793

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

794

These paths are a consequence of the

795

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

796

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]

804

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

Patrick Williams

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

[diff] [blame]

805

not appear to be available to other recipes.

806

Files are missing from the native sysroot, my recipe is

807

installing to the wrong place, or I am getting permissions

808

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

</para>

</question>

<para>

This situation results when a build system does

814

not recognize the environment variables supplied to it by

Brad Bishop

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

[diff] [blame]

815

Patrick Williams