Blame - poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml - openbmc/openbmc

the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons.

18

</para>

19

</legalnotice>

<imagedata fileref="figures/yocto-project-transp.png"

24

width="6in" depth="1in"

25

align="right" scale="25" />

</abstract>

</articleinfo>

<title>Welcome!</title>

<para>

Welcome!

This short document steps you through the process for a typical

35

image build using the Yocto Project.

36

The document also introduces how to configure a build for specific

37

hardware.

38

You will use Yocto Project to build a reference embedded OS

39

called Poky.

Brad Bishop

1a4b7ee

2018-12-16 17:11:34 -0800

[diff] [blame]

40

<note><title>Notes</title>

41

42

43

The examples in this paper assume you are using a

44

native Linux system running a recent Ubuntu Linux

45

distribution.

46

If the machine you want to use Yocto Project on to

47

build an image

48

(<ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>)

49

is not a native Linux system, you can

50

still perform these steps by using CROss PlatformS

51

(CROPS) and setting up a Poky container.

52

See the

53

<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>"

54

section in the Yocto Project Development Tasks Manual for more

information.

</para></listitem>

You cannot use a build host that is using the

59

<ulink url='https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux'>Windows Subsystem for Linux</ulink>

60

(WSL).

61

The Yocto Project is not compatible with WSL.

62

</para></listitem>

63

</itemizedlist>

Brad Bishop

316dfdd

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

[diff] [blame]

</note>

</para>

<para>

If you want more conceptual or background information on the

69

Yocto Project, see the

70

<ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.

</para>

</section>

<title>Compatible Linux Distribution</title>

<para>

Make sure your

<ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>

80

meets the following requirements:

81

82

83

50 Gbytes of free disk space

84

</para></listitem>

85

86

Runs a supported Linux distribution (i.e. recent releases of

87

Fedora, openSUSE, CentOS, Debian, or Ubuntu). For a list of

88

Linux distributions that support the Yocto Project, see the

89

"<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"

90

section in the Yocto Project Reference Manual.

Brad Bishop

1a4b7ee

2018-12-16 17:11:34 -0800

[diff] [blame]

91

For detailed information on preparing your build host, see

92

the

93

"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>"

94

section in the Yocto Project Development Tasks Manual.

Brad Bishop

316dfdd

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

[diff] [blame]

</para></listitem>

Git 1.8.3.1 or greater

</para></listitem>

tar 1.27 or greater

</para></listitem>

Python 3.4.0 or greater.

106

</para></listitem>

107

</itemizedlist>

108

If your build host does not meet any of these three listed

109

version requirements, you can take steps to prepare the

110

system so that you can still use the Yocto Project.

111

See the

112

"<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"

113

section in the Yocto Project Reference Manual for information.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Build Host Packages</title>

121

122

<para>

123

You must install essential host packages on your

124

build host.

125

The following command installs the host packages based on an

126

Ubuntu distribution:

127

<note>

128

For host package requirements on all supported Linux

129

distributions, see the

Brad Bishop

1a4b7ee

2018-12-16 17:11:34 -0800

[diff] [blame]

130

"<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-build-host'>Required Packages for the Build Host</ulink>"

Brad Bishop

316dfdd

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

[diff] [blame]

131

section in the Yocto Project Reference Manual.

132

</note>

133

134

$ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm

</literallayout>

</para>

</section>

<title>Use Git to Clone Poky</title>

141

142

<para>

143

Once you complete the setup instructions for your machine,

144

you need to get a copy of the Poky repository on your build

145

host.

146

Use the following commands to clone the Poky

Scott Rifenbark

fa4cfe3

2019-01-11 11:55:06 -0800

[diff] [blame]

147

repository.

Brad Bishop

316dfdd

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

[diff] [blame]

148

149

$ git clone git://git.yoctoproject.org/poky

150

Cloning into 'poky'...

Scott Rifenbark

fa4cfe3

2019-01-11 11:55:06 -0800

[diff] [blame]

151

remote: Counting objects: 428632, done.

152

remote: Compressing objects: 100% (101203/101203), done.

153

remote: Total 428632 (delta 320463), reused 428532 (delta 320363)

154

Receiving objects: 100% (428632/428632), 153.01 MiB | 12.40 MiB/s, done.

155

Resolving deltas: 100% (320463/320463), done.

Brad Bishop

316dfdd

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

[diff] [blame]

156

Checking connectivity... done.

Scott Rifenbark

fa4cfe3

2019-01-11 11:55:06 -0800

[diff] [blame]

157

</literallayout>

158

Move to the <filename>poky</filename> directory and take a look

at the tags:

$ cd poky

$ git fetch --tags

$ git tag

1.1_M1.final

1.1_M1.rc1

1.1_M1.rc2

1.1_M2.final

1.1_M2.rc1

.

.

.

yocto-2.5

yocto-2.5.1

yocto-2.5.2

yocto-2.6

yocto_1.5_M5.rc8

</literallayout>

For this example, check out the branch based on the

179

&DISTRO_REL_TAG; release:

180

181

$ git checkout tags/&DISTRO_REL_TAG; -b my-&DISTRO_REL_TAG;

182

Switched to a new branch 'my-&DISTRO_REL_TAG;'

Brad Bishop

316dfdd

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

[diff] [blame]

183

</literallayout>

184

The previous Git checkout command creates a local branch

185

named my-&DISTRO_REL_TAG;. The files available to you in that

186

branch exactly match the repository's files in the

187

"&DISTRO_NAME_NO_CAP;" development branch at the time of the

Scott Rifenbark

fa4cfe3

2019-01-11 11:55:06 -0800

[diff] [blame]

188

Yocto Project &DISTRO_REL_TAG; release.

Brad Bishop

316dfdd

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

[diff] [blame]

</para>

<para>

For more options and information about accessing Yocto

193

Project related repositories, see the

194

"<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"

195

section in the Yocto Project Development Tasks Manual.

</para>

</section>

<title>Building Your Image</title>

201

202

<para>

203

Use the following steps to build your image.

204

The build process creates an entire Linux distribution, including

205

the toolchain, from source.

<note>

If you are working behind a firewall and your build

210

host is not set up for proxies, you could encounter

211

problems with the build process when fetching source

212

code (e.g. fetcher failures or Git failures).

213

</para></listitem>

214

215

If you do not know your proxy settings, consult your

216

local network infrastructure resources and get that

217

information.

218

A good starting point could also be to check your

219

web browser settings.

220

Finally, you can find more information on the

221

"<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"

222

page of the Yocto Project Wiki.

</para></listitem>

</itemizedlist>

</note>

</para>

<para>

<emphasis>Initialize the Build Environment:</emphasis>

Scott Rifenbark

fa4cfe3

2019-01-11 11:55:06 -0800

[diff] [blame]

232

From within the <filename>poky</filename> directory, run the

Brad Bishop

316dfdd

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

[diff] [blame]

233

234

environment setup script to define Yocto Project's

235

build environment on your build host.

236

Scott Rifenbark

fa4cfe3

2019-01-11 11:55:06 -0800

[diff] [blame]

237

$ cd ~/poky

Brad Bishop

316dfdd

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

[diff] [blame]

238

$ source &OE_INIT_FILE;

Scott Rifenbark

fa4cfe3

2019-01-11 11:55:06 -0800

[diff] [blame]

239

You had no conf/local.conf file. This configuration file has therefore been

240

created for you with some default values. You may wish to edit it to, for

241

example, select a different MACHINE (target hardware). See conf/local.conf

242

for more information as common configuration options are commented.

243

244

You had no conf/bblayers.conf file. This configuration file has therefore been

245

created for you with some default values. To add additional metadata layers

246

into your configuration please add entries to conf/bblayers.conf.

247

248

The Yocto Project has extensive documentation about OE including a reference

249

manual which can be found at:

250

http://yoctoproject.org/documentation

251

252

For more information about OpenEmbedded see their website:

253

http://www.openembedded.org/

254

255

256

### Shell environment set up for builds. ###

257

258

You can now run 'bitbake <target>'

Common targets are:

core-image-minimal

core-image-sato

meta-toolchain

meta-ide-support

You can also run generated qemu images with a command like 'runqemu qemux86'

Brad Bishop

316dfdd

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

[diff] [blame]

267

</literallayout>

268

Among other things, the script creates the

269

<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>,

270

which is <filename>build</filename> in this case

271

and is located in the

272

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

273

After the script runs, your current working directory

274

is set to the Build Directory.

275

Later, when the build completes, the Build Directory

276

contains all the files created during the build.

277

</para></listitem>

278

279

<emphasis>Examine Your Local Configuration File:</emphasis>

280

When you set up the build environment, a local

281

configuration file named

282

<filename>local.conf</filename> becomes available in

283

a <filename>conf</filename> subdirectory of the

284

Build Directory.

285

For this example, the defaults are set to build

286

for a <filename>qemux86</filename> target, which is

287

suitable for emulation.

288

The package manager used is set to the RPM package

289

manager.

290

<tip>

291

You can significantly speed up your build and guard

292

against fetcher failures by using mirrors.

293

To use mirrors, add these lines to your

294

<filename>local.conf</filename> file in the Build

directory:

SSTATE_MIRRORS = "\

file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \

299

file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \

300

file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \

301

"

302

</literallayout>

303

The previous examples showed how to add sstate

304

paths for Yocto Project &YOCTO_DOC_VERSION_MINUS_ONE;,

305

&YOCTO_DOC_VERSION;, and a development area.

306

For a complete index of sstate locations, see

307

<ulink url='http://sstate.yoctoproject.org/'></ulink>.

</tip>

</para></listitem>

<emphasis>Start the Build:</emphasis>

312

Continue with the following command to build an OS image

313

for the target, which is

314

<filename>core-image-sato</filename> in this example:

315

316

$ bitbake core-image-sato

317

</literallayout>

318

For information on using the

319

<filename>bitbake</filename> command, see the

320

"<ulink url='&YOCTO_DOCS_OM_URL;#usingpoky-components-bitbake'>BitBake</ulink>"

321

section in the Yocto Project Overview and Concepts Manual,

322

or see the

323

"<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>"

324

section in the BitBake User Manual.

325

</para></listitem>

326

327

<emphasis>Simulate Your Image Using QEMU:</emphasis>

328

Once this particular image is built, you can start

329

QEMU, which is a Quick EMUlator that ships with

the Yocto Project:

$ runqemu qemux86

</literallayout>

If you want to learn more about running QEMU, see the

335

"<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>"

336

chapter in the Yocto Project Development Tasks Manual.

</para></listitem>

Exit QEMU by either clicking on the shutdown icon or by

341

typing <filename>Ctrl-C</filename> in the QEMU

342

transcript window from which you evoked QEMU.

</para></listitem>

</orderedlist>

</para>

</section>

<title>Customizing Your Build for Specific Hardware</title>

350

351

<para>

352

So far, all you have done is quickly built an image suitable

353

for emulation only.

354

This section shows you how to customize your build for specific

355

hardware by adding a hardware layer into the Yocto Project

356

development environment.

</para>

<para>

In general, layers are repositories that contain related sets of

361

instructions and configurations that tell the Yocto Project what

362

to do.

363

Isolating related metadata into functionally specific layers

364

facilitates modular development and makes it easier to reuse the

365

layer metadata.

366

<note>

367

By convention, layer names start with the string "meta-".

</note>

</para>

<para>

Follow these steps to add a hardware layer:

373

374

375

<emphasis>Find a Layer:</emphasis>

376

Lots of hardware layers exist.

377

The Yocto Project

378

<ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>

379

has many hardware layers.

380

This example adds the

381

<ulink url='https://github.com/kraj/meta-altera'>meta-altera</ulink>

hardware layer.

</para></listitem>

<emphasis>Clone the Layer</emphasis>

386

Use Git to make a local copy of the layer on your machine.

387

You can put the copy in the top level of the copy of the

388

Poky repository created earlier:

389

390

$ cd ~/poky

391

$ git clone https://github.com/kraj/meta-altera.git

392

Cloning into 'meta-altera'...

393

remote: Counting objects: 25170, done.

394

remote: Compressing objects: 100% (350/350), done.

395

remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219

396

Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done.

397

Resolving deltas: 100% (13385/13385), done.

398

Checking connectivity... done.

399

</literallayout>

400

The hardware layer now exists with other layers inside

401

the Poky reference repository on your build host as

402

<filename>meta-altera</filename> and contains all the

403

metadata needed to support hardware from Altera, which

is owned by Intel.

</para></listitem>

<emphasis>Change the Configuration to Build for a Specific Machine:</emphasis>

408

The

409

<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>

410

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

411

specifies the machine for the build.

412

For this example, set the <filename>MACHINE</filename>

413

variable to "cyclone5".

414

These configurations are used:

415

<ulink url='https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf'></ulink>.

416

<note>

417

See the

418

"<link linkend='conf-file-step'>Examine Your Local Configuration File</link>"

419

step earlier for more information on configuring the

build.

</note>

</para></listitem>

<emphasis>Add Your Layer to the Layer Configuration File:</emphasis>

425

Before you can use a layer during a build, you must add it

426

to your <filename>bblayers.conf</filename> file, which

427

is found in the

428

<ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>

429

<filename>conf</filename> directory.</para>

430

431

<para>Use the <filename>bitbake-layers add-layer</filename>

432

command to add the layer to the configuration file:

433

434

$ cd ~/poky/build

435

$ bitbake-layers add-layer ../meta-altera

436

NOTE: Starting bitbake server...

437

Parsing recipes: 100% |##################################################################| Time: 0:00:32

438

Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets, 123 skipped, 0 masked, 0 errors.

439

</literallayout>

440

You can find more information on adding layers in the

441

"<ulink url='&YOCTO_DOCS_DEV_URL;#adding-a-layer-using-the-bitbake-layers-script'>Adding a Layer Using the <filename>bitbake-layers</filename> Script</ulink>"

section.

</para></listitem>

</orderedlist>

Completing these steps has added the

446

<filename>meta-altera</filename> layer to your Yocto Project

447

development environment and configured it to build for the

448

"cyclone5" machine.

449

<note>

450

The previous steps are for demonstration purposes only.

451

If you were to attempt to build an image for the

452

"cyclone5" build, you should read the Altera

453

<filename>README</filename>.

</note>

</para>

</section>

<title>Creating Your Own General Layer</title>

460

461

<para>

462

Maybe you have an application or specific set of behaviors you

463

need to isolate.

464

You can create your own general layer using the

465

<filename>bitbake-layers create-layer</filename> command.

466

The tool automates layer creation by setting up a

467

subdirectory with a <filename>layer.conf</filename>

468

configuration file, a <filename>recipes-example</filename>

469

subdirectory that contains an <filename>example.bb</filename>

470

recipe, a licensing file, and a <filename>README</filename>.

</para>

<para>

The following commands run the tool to create a layer named

475

<filename>meta-mylayer</filename> in the

476

<filename>poky</filename> directory:

477

478

$ cd ~/poky

479

$ bitbake-layers create-layer meta-mylayer

480

NOTE: Starting bitbake server...

481

Add your new layer with 'bitbake-layers add-layer meta-mylayer'

482

</literallayout>

483

For more information on layers and how to create them, see the

484

"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"

485

section in the Yocto Project Development Tasks Manual.

</para>

</section>

<title>Where To Go Next</title>

491

492

<para>

493

Now that you have experienced using the Yocto Project, you might

494

be asking yourself "What now?"

495

The Yocto Project has many sources of information including

496

the website, wiki pages, and user manuals:

497

498

499

<emphasis>Website:</emphasis>

500

The

501

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

502

provides background information, the latest builds,

503

breaking news, full development documentation, and

504

access to a rich Yocto Project Development Community

505

into which you can tap.

506

</para></listitem>

507

508

<emphasis>Developer Screencast:</emphasis>

509

The

510

<ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New Developer Screencast Tutorial</ulink>

511

provides a 30-minute video created for users unfamiliar

512

with the Yocto Project but familiar with Linux build

513

hosts.

514

While this screencast is somewhat dated, the

515

introductory and fundamental concepts are useful for

the beginner.

</para></listitem>

<emphasis>Yocto Project Overview and Concepts Manual:</emphasis>

520

The

521

<ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>

522

is a great place to start to learn about the

523

Yocto Project.

524

This manual introduces you to the Yocto Project and its

525

development environment.

526

The manual also provides conceptual information for

527

various aspects of the Yocto Project.

528

</para></listitem>

529

530

<emphasis>Yocto Project Wiki:</emphasis>

531

The

532

<ulink url='&YOCTO_WIKI_URL;'>Yocto Project Wiki</ulink>

533

provides additional information on where to go next

534

when ramping up with the Yocto Project, release

535

information, project planning, and QA information.

536

</para></listitem>

537

538

<emphasis>Yocto Project Mailing Lists:</emphasis>

539

Related mailing lists provide a forum for discussion,

540

patch submission and announcements.

541

Several mailing lists exist and are grouped according

542

to areas of concern.

543

See the

544

"<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"

545

section in the Yocto Project Reference Manual for a

546

complete list of Yocto Project mailing lists.

547

</para></listitem>

548

549

<emphasis>Comprehensive List of Links and Other Documentation:</emphasis>

550

The

551

"<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"

552

section in the Yocto Project Reference Manual provides a

553

comprehensive list of all related links and other

user documentation.

</para></listitem>

</itemizedlist>

</para>

</section>

</article>

<!--

vim: expandtab tw=80 ts=4

562

-->