Blame - import-layers/yocto-poky/documentation/ref-manual/introduction.xml - openbmc/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>

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

171

<listitem><para>Ubuntu 16.04</para></listitem>

Patrick Williams

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

[diff] [blame]

172

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

173

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

174

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

175

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

Patrick Williams

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

[diff] [blame]

176

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

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

177

<listitem><para>Fedora release 23</para></listitem>

178

<listitem><para>Fedora release 24</para></listitem>

Patrick Williams

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

[diff] [blame]

179

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

180

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

181

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

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

182

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

183

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

Patrick Williams

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

[diff] [blame]

184

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

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

185

<!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem>

186

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

Patrick Williams

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

[diff] [blame]

187

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

188

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

189

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

190

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

191

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

192

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

193

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

194

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

195

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

196

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

197

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

198

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

199

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

Brad Bishop

2017-12-04 01:01:44 -0500

[diff] [blame^]

200

<listitem><para>openSUSE 42.1</para></listitem>

Patrick Williams

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

[diff] [blame]

</itemizedlist>

</para>

<note>

While the Yocto Project Team attempts to ensure all Yocto Project

206

releases are one hundred percent compatible with each officially

207

supported Linux distribution, instances might exist where you

208

encounter a problem while using the Yocto Project on a specific

209

distribution.

Patrick Williams

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

[diff] [blame]

</note>

</section>

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

215

216

<para>

217

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

218

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

219

This section provides required packages according to

220

Linux distribution and function.

</para>

<title>Ubuntu and Debian</title>

225

226

<para>

227

The following list shows the required packages by function

228

given a supported Ubuntu or Debian Linux distribution:

229

<note>

230

If your build system has the

231

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

232

might experience QEMU build failures due to the package

233

installing its own custom

234

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

235

the Debian system.

236

If you run into this situation, either of the following

237

solutions exist:

238

239

$ sudo apt-get build-dep qemu

240

$ sudo apt-get remove oss4-dev

</literallayout>

</note>

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

245

Packages needed to build an image on a headless

246

system:

247

248

$ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;

249

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

250

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

251

Packages recommended if the host system has graphics

252

support or if you are going to use the Eclipse

253

IDE:

254

255

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

256

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

257

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

258

Packages needed if you are going to build out the

259

Yocto Project documentation manuals:

260

261

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

262

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

Patrick Williams

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

[diff] [blame]

263

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

264

Packages needed if you are going to run

265

<filename>oe-selftest</filename>:

266

267

$ sudo apt-get install python-git

268

</literallayout>

269

</para></listitem>

Patrick Williams

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

[diff] [blame]

</itemizedlist>

</para>

</section>

<title>Fedora Packages</title>

276

277

<para>

278

The following list shows the required packages by function

279

given a supported Fedora Linux distribution:

280

281

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

282

Packages needed to build an image for a headless

283

system:

284

Patrick Williams

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

[diff] [blame]

285

$ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;

Patrick Williams

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

[diff] [blame]

286

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

287

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

288

Packages recommended if the host system has graphics

289

support or if you are going to use the Eclipse

290

IDE:

291

Patrick Williams

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

[diff] [blame]

292

$ sudo dnf install SDL-devel xterm

Patrick Williams

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

[diff] [blame]

293

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

294

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

295

Packages needed if you are going to build out the

296

Yocto Project documentation manuals:

297

Patrick Williams

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

[diff] [blame]

298

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

Patrick Williams

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

[diff] [blame]

299

docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc

300

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

Patrick Williams

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

[diff] [blame]

301

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

302

Packages needed if you are going to run

303

<filename>oe-selftest</filename>:

304

Patrick Williams

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

[diff] [blame]

305

$ sudo dnf install python3-GitPython

Patrick Williams

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

[diff] [blame]

306

</literallayout>

307

</para></listitem>

Patrick Williams

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

[diff] [blame]

</itemizedlist>

</para>

</section>

<title>openSUSE Packages</title>

314

315

<para>

316

The following list shows the required packages by function

317

given a supported openSUSE Linux distribution:

318

319

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

320

Packages needed to build an image for a headless

321

system:

322

323

$ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;

324

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

325

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

326

Packages recommended if the host system has graphics

327

support or if you are going to use the Eclipse

328

IDE:

329

330

$ sudo zypper install libSDL-devel xterm

331

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

332

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

333

Packages needed if you are going to build out the

334

Yocto Project documentation manuals:

335

336

$ sudo zypper install make fop xsltproc dblatex xmlto

337

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

Patrick Williams

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

[diff] [blame]

338

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

339

Packages needed if you are going to run

340

<filename>oe-selftest</filename>:

341

342

$ sudo zypper install python-GitPython

Patrick Williams

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

[diff] [blame]

343

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

</itemizedlist>

</para>

</section>

<title>CentOS Packages</title>

350

351

<para>

352

The following list shows the required packages by function

353

given a supported CentOS Linux distribution:

354

<note>

Patrick Williams

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

[diff] [blame]

355

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

356

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

357

and tar).

358

It is recommended that you install the buildtools in order

359

to provide versions that will work with the OpenEmbedded

360

build system.

361

For information on how to install the buildtools tarball,

362

see the

Patrick Williams

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

[diff] [blame]

363

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

section.

</note>

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

368

Packages needed to build an image for a headless

369

system:

370

371

$ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL;

372

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

373

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

374

Packages recommended if the host system has graphics

375

support or if you are going to use the Eclipse

376

IDE:

377

378

$ sudo yum install SDL-devel xterm

379

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

380

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

381

Packages needed if you are going to build out the

382

Yocto Project documentation manuals:

383

384

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

385

docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc

386

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

Patrick Williams

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

[diff] [blame]

387

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

388

Packages needed if you are going to run

389

<filename>oe-selftest</filename>:

390

391

$ sudo yum install GitPython

392

</literallayout>

393

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

401

402

<para>

403

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

404

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

405

Python:

406

Patrick Williams

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

[diff] [blame]

407

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

Patrick Williams

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

[diff] [blame]

408

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

Patrick Williams

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

[diff] [blame]

409

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

415

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

416

tarball that contains these tools.

417

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

418

tarball or use BitBake to build the tarball.

</para>

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

423

424

<para>

425

Downloading and running a pre-built buildtools installer is

426

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

427

428

429

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

430

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

431

</para></listitem>

432

433

Execute the installation script.

434

Here is an example:

435

436

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

437

</literallayout>

438

During execution, a prompt appears that allows you to

439

choose the installation directory.

440

For example, you could choose the following:

441

442

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

</literallayout>

</para></listitem>

Source the tools environment setup script by using a

447

command like the following:

448

449

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

450

</literallayout>

451

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

452

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

453

</para>

454

<para>

455

After you have sourced the setup script,

456

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

457

and any other environment variables required to run the

458

tools are initialized.

459

The results are working versions versions of Git, tar,

460

Python and <filename>chrpath</filename>.

</para></listitem>

</orderedlist>

</para>

</section>

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

468

469

<para>

470

Building and running your own buildtools installer applies

471

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

472

In this case, you use that machine to build the

473

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

474

take steps to transfer and run it on a

475

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

481

buildtools installer:

482

483

484

On the machine that is able to run BitBake,

485

be sure you have set up your build environment with

486

the setup script

487

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

or

</para></listitem>

Run the BitBake command to build the tarball:

493

494

$ bitbake buildtools-tarball

</literallayout>

<note>

The

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

500

determines whether you build tools for a 32-bit

501

or 64-bit system.

502

</note>

503

Once the build completes, you can find the

504

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

505

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

506

subdirectory of the

507

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

508

The installer file has the string "buildtools"

in the name.

</para></listitem>

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

513

build host to the machine that does not meet the

514

Git, tar, or Python requirements.

515

</para></listitem>

516

517

On the machine that does not meet the requirements,

518

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

519

to install the tools.

520

Here is an example:

521

522

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

523

</literallayout>

524

During execution, a prompt appears that allows you to

525

choose the installation directory.

526

For example, you could choose the following:

527

528

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

</literallayout>

</para></listitem>

Source the tools environment setup script by using a

533

command like the following:

534

535

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

536

</literallayout>

537

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

538

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

539

</para>

540

<para>

541

After you have sourced the setup script,

542

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

543

and any other environment variables required to run the

544

tools are initialized.

545

The results are working versions versions of Git, tar,

546

Python and <filename>chrpath</filename>.

</para></listitem>

</orderedlist>

</para>

</section>

</section>

</section>

<title>Obtaining the Yocto Project</title>

556

<para>

557

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

558

of methods:

559

560

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

561

Working from a copy of the upstream

562

<filename>poky</filename> repository is the

563

preferred method for obtaining and using a Yocto Project

564

release.

565

You can view the Yocto Project Source Repositories at

566

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

567

In particular, you can find the

568

<filename>poky</filename> repository at

569

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

570

</para></listitem>

571

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

572

releases are available as tarballs through

573

574

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

575

tarball releases are available at

576

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

Patrick Williams

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

[diff] [blame]

577

These builds include Yocto Project releases, SDK installation

578

scripts, and experimental builds.

Patrick Williams