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

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

[diff] [blame]

1

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

2

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"

3

[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

4

5

6

<title>Introduction</title>

7

8

9

<title>Introduction</title>

10

11

<para>

Patrick Williams

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

[diff] [blame]

12

This manual provides reference information for the current release

13

of the Yocto Project.

14

The Yocto Project is an open-source collaboration project focused

15

on embedded Linux developers.

16

Amongst other things, the Yocto Project uses the OpenEmbedded build

17

system, which is based on the Poky project, to construct complete

18

Linux images.

19

You can find complete introductory and getting started information

20

on the Yocto Project by reading the

Patrick Williams

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

[diff] [blame]

21

<ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.

Patrick Williams

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

[diff] [blame]

22

</para>

23

24

<para>

Patrick Williams

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

[diff] [blame]

25

For task-based information using the Yocto Project, see the

26

<ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>

27

and the <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.

28

For Board Support Package (BSP) structure information, see the

29

<ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.

Patrick Williams

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

[diff] [blame]

30

For information on how to use a Software Development Kit, (SDK), see the

31

<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.

Patrick Williams

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

[diff] [blame]

32

You can find information on tracing and profiling in the

33

<ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.

34

For information on BitBake, which is the task execution tool the

35

OpenEmbedded build system is based on, see the

36

<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>.

37

Finally, you can also find lots of Yocto Project information on the

38

<ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.

</para>

</section>

<title>Documentation Overview</title>

44

<para>

45

This reference manual consists of the following:

Provides an overview of the components that make up the Yocto Project

Patrick Williams

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

[diff] [blame^]

50

followed by information about debugging images created in the Yocto Project.

Patrick Williams

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

[diff] [blame]

</para></listitem>

Provides a more detailed look at the Yocto Project development

55

environment within the context of development.

</para></listitem>

Describes fundamental Yocto Project components as well as an explanation

60

behind how the Yocto Project uses shared state (sstate) cache to speed build time.

</para></listitem>

Describes release-specific information that helps you move from

65

one Yocto Project Release to another.

</para></listitem>

Describes the

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

71

either by unpacking a released Yocto Project tarball on your host development system,

72

or by cloning the upstream

73

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

</para></listitem>

Describes the classes used in the Yocto Project.</para></listitem>

78

79

80

Describes the tasks defined by the OpenEmbedded build system.

81

</para></listitem>

82

Patrick Williams

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

[diff] [blame^]

83

84

Provides a quick reference for the <filename>devtool</filename>

command.

</para></listitem>

Patrick Williams

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

[diff] [blame]

88

89

Lists and describes QA warning and error messages.

</para></listitem>

Describes the standard images that the Yocto Project supports.

</para></listitem>

Describes mechanisms for creating distribution, machine, and image

98

features during the build process using the OpenEmbedded build system.</para></listitem>

99

100

101

Presents most variables used by the OpenEmbedded build system, which

102

uses BitBake.

103

Entries describe the function of the variable and how to apply them.

</para></listitem>

Provides variable locality or context.</para></listitem>

108

109

110

Provides answers for commonly asked questions in the Yocto Project

111

development environment.</para></listitem>

112

113

114

Provides guidance on how you can contribute back to the Yocto

115

Project.</para></listitem>

</itemizedlist>

</para>

</section>

<title>System Requirements</title>

123

<para>

124

For general Yocto Project system requirements, see the

125

"<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" section

126

in the Yocto Project Quick Start.

127

The remainder of this section provides details on system requirements

128

not covered in the Yocto Project Quick Start.

</para>

<title>Supported Linux Distributions</title>

133

134

<para>

135

Currently, the Yocto Project is supported on the following

distributions:

<note>

<para>

Yocto Project releases are tested against the stable Linux

140

distributions in the following list.

141

The Yocto Project should work on other distributions but

142

validation is not performed against them.

</para>

<para>

In particular, the Yocto Project does not support

147

and currently has no plans to support

148

rolling-releases or development distributions due to their

149

constantly changing nature.

150

We welcome patches and bug reports, but keep in mind that

151

our priority is on the supported platforms listed below.

</para>

<para>

If you encounter problems, please go to

156

<ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>

157

and submit a bug.

158

We are interested in hearing about your experience.

</para>

</note>

<!--

<listitem><para>Ubuntu 10.04</para></listitem>

164

<listitem><para>Ubuntu 11.10</para></listitem>

165

<listitem><para>Ubuntu 12.04 (LTS)</para></listitem>

166

<listitem><para>Ubuntu 13.10</para></listitem> -->

167

<listitem><para>Ubuntu 14.04 (LTS)</para></listitem>

168

<listitem><para>Ubuntu 14.10</para></listitem>

Patrick Williams

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

[diff] [blame]

169

<listitem><para>Ubuntu 15.04</para></listitem>

170

<listitem><para>Ubuntu 15.10</para></listitem>

Patrick Williams

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

[diff] [blame]

171

<!-- <listitem><para>Fedora 16 (Verne)</para></listitem>

172

<listitem><para>Fedora 17 (Spherical)</para></listitem>

173

<listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem>

174

<listitem><para>Fedora release 20 (Heisenbug)</para></listitem> -->

175

<listitem><para>Fedora release 21</para></listitem>

Patrick Williams

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

[diff] [blame]

176

<listitem><para>Fedora release 22</para></listitem>

Patrick Williams

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

[diff] [blame]

177

<!-- <listitem><para>CentOS release 5.6 (Final)</para></listitem>

178

<listitem><para>CentOS release 5.7 (Final)</para></listitem>

179

<listitem><para>CentOS release 5.8 (Final)</para></listitem>

180

<listitem><para>CentOS release 6.3 (Final)</para></listitem> -->

181

<listitem><para>CentOS release 6.x</para></listitem>

182

<listitem><para>CentOS release 7.x</para></listitem>

183

184

<listitem><para>Debian GNU/Linux 7.x (Wheezy)</para></listitem>

185

<listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem>

186

<!-- <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>

187

<listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem>

188

<listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem>

189

<listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem>

190

<listitem><para>Debian GNU/Linux 7.5 (Wheezy)</para></listitem>

191

<listitem><para>Debian GNU/Linux 7.6 (Wheezy)</para></listitem> -->

192

<!-- <listitem><para>openSUSE 11.4</para></listitem>

193

<listitem><para>openSUSE 12.1</para></listitem>

194

<listitem><para>openSUSE 12.2</para></listitem>

195

<listitem><para>openSUSE 12.3</para></listitem>

196

<listitem><para>openSUSE 13.1</para></listitem> -->

197

<listitem><para>openSUSE 13.2</para></listitem>

</itemizedlist>

</para>

<note>

While the Yocto Project Team attempts to ensure all Yocto Project

203

releases are one hundred percent compatible with each officially

204

supported Linux distribution, instances might exist where you

205

encounter a problem while using the Yocto Project on a specific

206

distribution.

Patrick Williams

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

[diff] [blame]

</note>

</section>

<title>Required Packages for the Host Development System</title>

212

213

<para>

214

The list of packages you need on the host development system can

215

be large when covering all build scenarios using the Yocto Project.

216

This section provides required packages according to

217

Linux distribution and function.

</para>

<title>Ubuntu and Debian</title>

222

223

<para>

224

The following list shows the required packages by function

225

given a supported Ubuntu or Debian Linux distribution:

226

<note>

227

If your build system has the

228

<filename>oss4-dev</filename> package installed, you

229

might experience QEMU build failures due to the package

230

installing its own custom

231

<filename>/usr/include/linux/soundcard.h</filename> on

232

the Debian system.

233

If you run into this situation, either of the following

234

solutions exist:

235

236

$ sudo apt-get build-dep qemu

237

$ sudo apt-get remove oss4-dev

</literallayout>

</note>

<listitem><para><emphasis>Essentials:</emphasis>

242

Packages needed to build an image on a headless

243

system:

244

245

$ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;

246

</literallayout></para></listitem>

247

<listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>

248

Packages recommended if the host system has graphics

249

support or if you are going to use the Eclipse

250

IDE:

251

252

$ sudo apt-get install libsdl1.2-dev xterm

253

</literallayout></para></listitem>

254

<listitem><para><emphasis>Documentation:</emphasis>

255

Packages needed if you are going to build out the

256

Yocto Project documentation manuals:

257

258

$ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto

259

</literallayout></para></listitem>

Patrick Williams

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

[diff] [blame]

260

<listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>

261

Packages needed if you are going to run

262

<filename>oe-selftest</filename>:

263

264

$ sudo apt-get install python-git

265

</literallayout>

266

</para></listitem>

Patrick Williams

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

[diff] [blame]

</itemizedlist>

</para>

</section>

<title>Fedora Packages</title>

273

274

<para>

275

The following list shows the required packages by function

276

given a supported Fedora Linux distribution:

277

278

<listitem><para><emphasis>Essentials:</emphasis>

279

Packages needed to build an image for a headless

280

system:

281

Patrick Williams

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

[diff] [blame]

282

$ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;

Patrick Williams

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

[diff] [blame]

283

</literallayout></para></listitem>

284

<listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>

285

Packages recommended if the host system has graphics

286

support or if you are going to use the Eclipse

287

IDE:

288

Patrick Williams

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

[diff] [blame]

289

$ sudo dnf install SDL-devel xterm

Patrick Williams

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

[diff] [blame]

290

</literallayout></para></listitem>

291

<listitem><para><emphasis>Documentation:</emphasis>

292

Packages needed if you are going to build out the

293

Yocto Project documentation manuals:

294

Patrick Williams

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

[diff] [blame]

295

$ sudo dnf install make docbook-style-dsssl docbook-style-xsl \

Patrick Williams

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

[diff] [blame]

296

docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc

297

</literallayout></para></listitem>

Patrick Williams

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

[diff] [blame]

298

<listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>

299

Packages needed if you are going to run

300

<filename>oe-selftest</filename>:

301

Patrick Williams

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

[diff] [blame^]

302

$ sudo dnf install python3-GitPython

Patrick Williams

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

[diff] [blame]

303

</literallayout>

304

</para></listitem>

Patrick Williams

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

[diff] [blame]

</itemizedlist>

</para>

</section>

<title>openSUSE Packages</title>

311

312

<para>

313

The following list shows the required packages by function

314

given a supported openSUSE Linux distribution:

315

316

<listitem><para><emphasis>Essentials:</emphasis>

317

Packages needed to build an image for a headless

318

system:

319

320

$ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;

321

</literallayout></para></listitem>

322

<listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>

323

Packages recommended if the host system has graphics

324

support or if you are going to use the Eclipse

325

IDE:

326

327

$ sudo zypper install libSDL-devel xterm

328

</literallayout></para></listitem>

329

<listitem><para><emphasis>Documentation:</emphasis>

330

Packages needed if you are going to build out the

331

Yocto Project documentation manuals:

332

333

$ sudo zypper install make fop xsltproc dblatex xmlto

334

</literallayout></para></listitem>

Patrick Williams

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

[diff] [blame]

335

<listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>

336

Packages needed if you are going to run

337

<filename>oe-selftest</filename>:

338

339

$ sudo zypper install python-GitPython

Patrick Williams

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

[diff] [blame]

340

</literallayout></para></listitem>

</itemizedlist>

</para>

</section>

<title>CentOS Packages</title>

347

348

<para>

349

The following list shows the required packages by function

350

given a supported CentOS Linux distribution:

351

<note>

Patrick Williams

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

[diff] [blame]

352

For CentOS 6.x, some of the versions of the components

353

provided by the distribution are too old (e.g. Git, Python,

354

and tar).

355

It is recommended that you install the buildtools in order

356

to provide versions that will work with the OpenEmbedded

357

build system.

358

For information on how to install the buildtools tarball,

359

see the

Patrick Williams

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

[diff] [blame]

360

"<link linkend='required-git-tar-and-python-versions'>Required Git, Tar, and Python Versions</link>"

section.

</note>

<listitem><para><emphasis>Essentials:</emphasis>

365

Packages needed to build an image for a headless

366

system:

367

368

$ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL;

369

</literallayout></para></listitem>

370

<listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis>

371

Packages recommended if the host system has graphics

372

support or if you are going to use the Eclipse

373

IDE:

374

375

$ sudo yum install SDL-devel xterm

376

</literallayout></para></listitem>

377

<listitem><para><emphasis>Documentation:</emphasis>

378

Packages needed if you are going to build out the

379

Yocto Project documentation manuals:

380

381

$ sudo yum install make docbook-style-dsssl docbook-style-xsl \

382

docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc

383

</literallayout></para></listitem>

Patrick Williams

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

[diff] [blame]

384

<listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis>

385

Packages needed if you are going to run

386

<filename>oe-selftest</filename>:

387

388

$ sudo yum install GitPython

389

</literallayout>

390

</para></listitem>

Patrick Williams

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

[diff] [blame]

</itemizedlist>

</para>

</section>

</section>

<title>Required Git, tar, and Python Versions</title>

398

399

<para>

400

In order to use the build system, your host development system

401

must meet the following version requirements for Git, tar, and

402

Python:

403

Patrick Williams

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

[diff] [blame]

404

<listitem><para>Git 1.8.3.1 or greater</para></listitem>

Patrick Williams

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

[diff] [blame]

405

<listitem><para>tar 1.24 or greater</para></listitem>

Patrick Williams

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

[diff] [blame^]

406

<listitem><para>Python 3.4.0 or greater</para></listitem>

Patrick Williams

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

[diff] [blame]

</itemizedlist>

</para>

<para>

If your host development system does not meet all these requirements,

412

you can resolve this by installing a <filename>buildtools</filename>

413

tarball that contains these tools.

414

You can get the tarball one of two ways: download a pre-built

415

tarball or use BitBake to build the tarball.

</para>

<title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title>

420

421

<para>

422

Downloading and running a pre-built buildtools installer is

423

the easiest of the two methods by which you can get these tools:

424

425

426

Locate and download the <filename>*.sh</filename> at

427

<ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;/buildtools/'></ulink>.

428

</para></listitem>

429

430

Execute the installation script.

431

Here is an example:

432

433

$ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh

434

</literallayout>

435

During execution, a prompt appears that allows you to

436

choose the installation directory.

437

For example, you could choose the following:

438

439

/home/<replaceable>your-username</replaceable>/buildtools

</literallayout>

</para></listitem>

Source the tools environment setup script by using a

444

command like the following:

445

446

$ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux

447

</literallayout>

448

Of course, you need to supply your installation directory and be

449

sure to use the right file (i.e. i585 or x86-64).

450

</para>

451

<para>

452

After you have sourced the setup script,

453

the tools are added to <filename>PATH</filename>

454

and any other environment variables required to run the

455

tools are initialized.

456

The results are working versions versions of Git, tar,

457

Python and <filename>chrpath</filename>.

</para></listitem>

</orderedlist>

</para>

</section>

<title>Building Your Own <filename>buildtools</filename> Tarball</title>

465

466

<para>

467

Building and running your own buildtools installer applies

468

only when you have a build host that can already run BitBake.

469

In this case, you use that machine to build the

470

<filename>.sh</filename> file and then

471

take steps to transfer and run it on a

472

machine that does not meet the minimal Git, tar, and Python

requirements.

</para>

<para>

Here are the steps to take to build and run your own

478

buildtools installer:

479

480

481

On the machine that is able to run BitBake,

482

be sure you have set up your build environment with

483

the setup script

484

(<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>

or

</para></listitem>

Run the BitBake command to build the tarball:

490

491

$ bitbake buildtools-tarball

</literallayout>

<note>

The

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

497

determines whether you build tools for a 32-bit

498

or 64-bit system.

499

</note>

500

Once the build completes, you can find the

501

<filename>.sh</filename> file that installs

502

the tools in the <filename>tmp/deploy/sdk</filename>

503

subdirectory of the

504

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

505

The installer file has the string "buildtools"

in the name.

</para></listitem>

Transfer the <filename>.sh</filename> file from the

510

build host to the machine that does not meet the

511

Git, tar, or Python requirements.

512

</para></listitem>

513

514

On the machine that does not meet the requirements,

515

run the <filename>.sh</filename> file

516

to install the tools.

517

Here is an example:

518

519

$ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh

520

</literallayout>

521

During execution, a prompt appears that allows you to

522

choose the installation directory.

523

For example, you could choose the following:

524

525

/home/<replaceable>your_username</replaceable>/buildtools

</literallayout>

</para></listitem>

Source the tools environment setup script by using a

530

command like the following:

531

532

$ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux

533

</literallayout>

534

Of course, you need to supply your installation directory and be

535

sure to use the right file (i.e. i585 or x86-64).

536

</para>

537

<para>

538

After you have sourced the setup script,

539

the tools are added to <filename>PATH</filename>

540

and any other environment variables required to run the

541

tools are initialized.

542

The results are working versions versions of Git, tar,

543

Python and <filename>chrpath</filename>.

</para></listitem>

</orderedlist>

</para>

</section>

</section>

</section>

<title>Obtaining the Yocto Project</title>

553

<para>

554

The Yocto Project development team makes the Yocto Project available through a number

555

of methods:

556

557

<listitem><para><emphasis>Source Repositories:</emphasis>

558

Working from a copy of the upstream

559

<filename>poky</filename> repository is the

560

preferred method for obtaining and using a Yocto Project

561

release.

562

You can view the Yocto Project Source Repositories at

563

<ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.

564

In particular, you can find the

565

<filename>poky</filename> repository at

566

<ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>.

567

</para></listitem>

568

<listitem><para><emphasis>Releases:</emphasis> Stable, tested

569

releases are available as tarballs through

570

571

<listitem><para><emphasis>Nightly Builds:</emphasis> These

572

tarball releases are available at

573

<ulink url='&YOCTO_AB_NIGHTLY_URL;'/>.

Patrick Williams

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

[diff] [blame]

574

These builds include Yocto Project releases, SDK installation

575

scripts, and experimental builds.

Patrick Williams