Blame - documentation/ref-manual/introduction.xml - openbmc/openbmc

Patrick Williams

c124f4f

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>

12

This manual provides reference information for the current release of the Yocto Project.

13

The Yocto Project is an open-source collaboration project focused on embedded Linux

14

developers.

15

Amongst other things, the Yocto Project uses the OpenEmbedded build system, which

16

is based on the Poky project, to construct complete Linux images.

17

You can find complete introductory and getting started information on the Yocto Project

18

by reading the

19

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

20

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

21

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

22

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

23

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

24

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

25

You can find information on tracing and profiling in the

26

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

27

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

28

OpenEmbedded build system is based on, see the

29

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

30

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

31

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

</para>

</section>

<title>Documentation Overview</title>

37

<para>

38

This reference manual consists of the following:

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

43

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

</para></listitem>

Provides a more detailed look at the Yocto Project development

48

environment within the context of development.

</para></listitem>

Describes fundamental Yocto Project components as well as an explanation

53

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

58

one Yocto Project Release to another.

</para></listitem>

Describes the

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

64

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

65

or by cloning the upstream

66

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

</para></listitem>

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

71

72

73

Describes the tasks defined by the OpenEmbedded build system.

</para></listitem>

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

86

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

87

88

89

Presents most variables used by the OpenEmbedded build system, which

90

uses BitBake.

91

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

</para></listitem>

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

96

97

98

Provides answers for commonly asked questions in the Yocto Project

99

development environment.</para></listitem>

100

101

102

Provides guidance on how you can contribute back to the Yocto

103

Project.</para></listitem>

</itemizedlist>

</para>

</section>

<title>System Requirements</title>

111

<para>

112

For general Yocto Project system requirements, see the

113

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

114

in the Yocto Project Quick Start.

115

The remainder of this section provides details on system requirements

116

not covered in the Yocto Project Quick Start.

</para>

<title>Supported Linux Distributions</title>

121

122

<para>

123

Currently, the Yocto Project is supported on the following

distributions:

<note>

<para>

Yocto Project releases are tested against the stable Linux

128

distributions in the following list.

129

The Yocto Project should work on other distributions but

130

validation is not performed against them.

</para>

<para>

In particular, the Yocto Project does not support

135

and currently has no plans to support

136

rolling-releases or development distributions due to their

137

constantly changing nature.

138

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

139

our priority is on the supported platforms listed below.

</para>

<para>

If you encounter problems, please go to

144

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

145

and submit a bug.

146

We are interested in hearing about your experience.

</para>

</note>

<!--

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

152

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

153

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

154

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

155

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

156

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

157

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

158

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

159

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

160

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

161

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

162

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

163

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

164

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

165

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

166

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

167

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

168

169

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

170

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

171

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

172

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

173

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

174

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

175

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

176

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

177

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

178

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

179

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

180

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

181

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

182

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

</itemizedlist>

</para>

<note>

While the Yocto Project Team attempts to ensure all Yocto Project

188

releases are one hundred percent compatible with each officially

189

supported Linux distribution, instances might exist where you

190

encounter a problem while using the Yocto Project on a specific

191

distribution.

192

For example, the CentOS 6.4 distribution does not include the

193

Gtk+ 2.20.0 and PyGtk 2.21.0 (or higher) packages, which are

194

required to run

195

<ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.

</note>

</section>

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

201

202

<para>

203

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

204

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

205

This section provides required packages according to

206

Linux distribution and function.

</para>

<title>Ubuntu and Debian</title>

211

212

<para>

213

The following list shows the required packages by function

214

given a supported Ubuntu or Debian Linux distribution:

215

<note>

216

If your build system has the

217

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

218

might experience QEMU build failures due to the package

219

installing its own custom

220

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

221

the Debian system.

222

If you run into this situation, either of the following

223

solutions exist:

224

225

$ sudo apt-get build-dep qemu

226

$ sudo apt-get remove oss4-dev

</literallayout>

</note>

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

231

Packages needed to build an image on a headless

232

system:

233

234

$ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;

235

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

236

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

237

Packages recommended if the host system has graphics

238

support or if you are going to use the Eclipse

239

IDE:

240

241

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

242

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

243

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

244

Packages needed if you are going to build out the

245

Yocto Project documentation manuals:

246

247

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

248

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

249

<listitem><para><emphasis>ADT Installer Extras:</emphasis>

250

Packages needed if you are going to be using the

251

<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:

252

253

$ sudo apt-get install autoconf automake libtool libglib2.0-dev

254

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

</itemizedlist>

</para>

</section>

<title>Fedora Packages</title>

261

262

<para>

263

The following list shows the required packages by function

264

given a supported Fedora Linux distribution:

265

266

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

267

Packages needed to build an image for a headless

268

system:

269

270

$ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL;

271

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

272

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

273

Packages recommended if the host system has graphics

274

support or if you are going to use the Eclipse

275

IDE:

276

277

$ sudo yum install SDL-devel xterm perl-Thread-Queue

278

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

279

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

280

Packages needed if you are going to build out the

281

Yocto Project documentation manuals:

282

283

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

284

docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc

285

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

286

<listitem><para><emphasis>ADT Installer Extras:</emphasis>

287

Packages needed if you are going to be using the

288

<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:

289

290

$ sudo yum install autoconf automake libtool glib2-devel

291

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

</itemizedlist>

</para>

</section>

<title>openSUSE Packages</title>

298

299

<para>

300

The following list shows the required packages by function

301

given a supported openSUSE Linux distribution:

302

303

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

304

Packages needed to build an image for a headless

305

system:

306

307

$ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;

308

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

309

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

310

Packages recommended if the host system has graphics

311

support or if you are going to use the Eclipse

312

IDE:

313

314

$ sudo zypper install libSDL-devel xterm

315

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

316

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

317

Packages needed if you are going to build out the

318

Yocto Project documentation manuals:

319

320

$ sudo zypper install make fop xsltproc dblatex xmlto

321

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

322

<listitem><para><emphasis>ADT Installer Extras:</emphasis>

323

Packages needed if you are going to be using the

324

<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:

325

326

$ sudo zypper install autoconf automake libtool glib2-devel

327

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

</itemizedlist>

</para>

</section>

<title>CentOS Packages</title>

334

335

<para>

336

The following list shows the required packages by function

337

given a supported CentOS Linux distribution:

338

<note>

339

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

340

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

341

and tar).

342

It is recommended that you install the buildtools in order

343

to provide versions that will work with the OpenEmbedded

344

build system.

345

For information on how to install the buildtools tarball,

346

see the

347

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

section.

</note>

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

352

Packages needed to build an image for a headless

353

system:

354

355

$ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL;

356

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

357

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

358

Packages recommended if the host system has graphics

359

support or if you are going to use the Eclipse

360

IDE:

361

362

$ sudo yum install SDL-devel xterm

363

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

364

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

365

Packages needed if you are going to build out the

366

Yocto Project documentation manuals:

367

368

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

369

docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc

370

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

371

<listitem><para><emphasis>ADT Installer Extras:</emphasis>

372

Packages needed if you are going to be using the

373

<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:

374

375

$ sudo yum install autoconf automake libtool glib2-devel

376

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

</itemizedlist>

</para>

</section>

</section>

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

384

385

<para>

386

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

387

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

388

Python:

389

390

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

391

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

392

<listitem><para>Python 2.7.3 or greater not including

393

Python 3.x, which is not supported.</para></listitem>

</itemizedlist>

</para>

<para>

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

399

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

400

tarball that contains these tools.

401

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

402

tarball or use BitBake to build the tarball.

</para>

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

407

408

<para>

409

Downloading and running a pre-built buildtools installer is

410

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

411

412

413

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

414

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

415

</para></listitem>

416

417

Execute the installation script.

418

Here is an example:

419

420

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

421

</literallayout>

422

During execution, a prompt appears that allows you to

423

choose the installation directory.

424

For example, you could choose the following:

425

426

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

</literallayout>

</para></listitem>

Source the tools environment setup script by using a

431

command like the following:

432

433

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

434

</literallayout>

435

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

436

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

437

</para>

438

<para>

439

After you have sourced the setup script,

440

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

441

and any other environment variables required to run the

442

tools are initialized.

443

The results are working versions versions of Git, tar,

444

Python and <filename>chrpath</filename>.

</para></listitem>

</orderedlist>

</para>

</section>

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

452

453

<para>

454

Building and running your own buildtools installer applies

455

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

456

In this case, you use that machine to build the

457

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

458

take steps to transfer and run it on a

459

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

465

buildtools installer:

466

467

468

On the machine that is able to run BitBake,

469

be sure you have set up your build environment with

470

the setup script

471

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

or

</para></listitem>

Run the BitBake command to build the tarball:

477

478

$ bitbake buildtools-tarball

</literallayout>

<note>

The

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

484

determines whether you build tools for a 32-bit

485

or 64-bit system.

486

</note>

487

Once the build completes, you can find the

488

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

489

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

490

subdirectory of the

491

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

492

The installer file has the string "buildtools"

in the name.

</para></listitem>

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

497

build host to the machine that does not meet the

498

Git, tar, or Python requirements.

499

</para></listitem>

500

501

On the machine that does not meet the requirements,

502

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

503

to install the tools.

504

Here is an example:

505

506

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

507

</literallayout>

508

During execution, a prompt appears that allows you to

509

choose the installation directory.

510

For example, you could choose the following:

511

512

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

</literallayout>

</para></listitem>

Source the tools environment setup script by using a

517

command like the following:

518

519

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

520

</literallayout>

521

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

522

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

523

</para>

524

<para>

525

After you have sourced the setup script,

526

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

527

and any other environment variables required to run the

528

tools are initialized.

529

The results are working versions versions of Git, tar,

530

Python and <filename>chrpath</filename>.

</para></listitem>

</orderedlist>

</para>

</section>

</section>

</section>

<title>Obtaining the Yocto Project</title>

540

<para>

541

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

542

of methods:

543

544

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

545

Working from a copy of the upstream

546

<filename>poky</filename> repository is the

547

preferred method for obtaining and using a Yocto Project

548

release.

549

You can view the Yocto Project Source Repositories at

550

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

551

In particular, you can find the

552

<filename>poky</filename> repository at

553

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

554

</para></listitem>

555

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

556

releases are available as tarballs through

557

558

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

559

tarball releases are available at

560

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

561

These builds include Yocto Project releases, meta-toolchain

562

tarball installation scripts, and experimental builds.

563

</para></listitem>

564

<listitem><para><emphasis>Yocto Project Website:</emphasis> You can

565

find tarball releases of the Yocto Project and supported BSPs

566

at the

567

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

568

Along with these downloads, you can find lots of other

569

information at this site.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Development Checkouts</title>

577

<para>

578

Development using the Yocto Project requires a local

579

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

580

You can set up the Source Directory by cloning a copy of the upstream

581

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

582

For information on how to do this, see the

583

"<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"

584

section in the Yocto Project Development Manual.

</para>

</section>

</chapter>

<!--

vim: expandtab tw=80 ts=4

591

-->