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

Scott Rifenbark

b0466fb

2019-01-22 10:21:44 -0800

[diff] [blame]

176

yocto-2.6.1

Scott Rifenbark

fa4cfe3

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

[diff] [blame]

177

yocto_1.5_M5.rc8

178

</literallayout>

179

For this example, check out the branch based on the

180

&DISTRO_REL_TAG; release:

181

182

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

183

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

Brad Bishop

316dfdd

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

[diff] [blame]

184

</literallayout>

185

The previous Git checkout command creates a local branch

186

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

187

branch exactly match the repository's files in the

188

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

Scott Rifenbark

fa4cfe3

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

[diff] [blame]

189

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

194

Project related repositories, see the

195

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

196

section in the Yocto Project Development Tasks Manual.

</para>

</section>

<title>Building Your Image</title>

202

203

<para>

204

Use the following steps to build your image.

205

The build process creates an entire Linux distribution, including

206

the toolchain, from source.

<note>

If you are working behind a firewall and your build

211

host is not set up for proxies, you could encounter

212

problems with the build process when fetching source

213

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

214

</para></listitem>

215

216

If you do not know your proxy settings, consult your

217

local network infrastructure resources and get that

218

information.

219

A good starting point could also be to check your

220

web browser settings.

221

Finally, you can find more information on the

222

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

223

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]

233

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

Brad Bishop

316dfdd

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

[diff] [blame]

234

235

environment setup script to define Yocto Project's

236

build environment on your build host.

237

Scott Rifenbark

fa4cfe3

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

[diff] [blame]

238

$ cd ~/poky

Brad Bishop

316dfdd

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

[diff] [blame]

239

$ source &OE_INIT_FILE;

Scott Rifenbark

fa4cfe3

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

[diff] [blame]

240

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

241

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

242

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

243

for more information as common configuration options are commented.

244

245

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

246

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

247

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

248

249

The Yocto Project has extensive documentation about OE including a reference

250

manual which can be found at:

251

http://yoctoproject.org/documentation

252

253

For more information about OpenEmbedded see their website:

254

http://www.openembedded.org/

255

256

257

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

258

259

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]

268

</literallayout>

269

Among other things, the script creates the

270

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

271

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

272

and is located in the

273

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

274

After the script runs, your current working directory

275

is set to the Build Directory.

276

Later, when the build completes, the Build Directory

277

contains all the files created during the build.

278

</para></listitem>

279

280

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

281

When you set up the build environment, a local

282

configuration file named

283

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

284

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

285

Build Directory.

286

For this example, the defaults are set to build

287

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

288

suitable for emulation.

289

The package manager used is set to the RPM package

290

manager.

291

<tip>

292

You can significantly speed up your build and guard

293

against fetcher failures by using mirrors.

294

To use mirrors, add these lines to your

295

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

directory:

SSTATE_MIRRORS = "\

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

300

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

301

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

302

"

303

</literallayout>

304

The previous examples showed how to add sstate

305

paths for Yocto Project &YOCTO_DOC_VERSION_MINUS_ONE;,

306

&YOCTO_DOC_VERSION;, and a development area.

307

For a complete index of sstate locations, see

308

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

</tip>

</para></listitem>

<emphasis>Start the Build:</emphasis>

313

Continue with the following command to build an OS image

314

for the target, which is

315

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

316

317

$ bitbake core-image-sato

318

</literallayout>

319

For information on using the

320

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

321

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

322

section in the Yocto Project Overview and Concepts Manual,

323

or see the

324

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

325

section in the BitBake User Manual.

326

</para></listitem>

327

328

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

329

Once this particular image is built, you can start

330

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

336

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

337

chapter in the Yocto Project Development Tasks Manual.

</para></listitem>

Exit QEMU by either clicking on the shutdown icon or by

342

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

343

transcript window from which you evoked QEMU.

</para></listitem>

</orderedlist>

</para>

</section>

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

351

352

<para>

353

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

354

for emulation only.

355

This section shows you how to customize your build for specific

356

hardware by adding a hardware layer into the Yocto Project

357

development environment.

</para>

<para>

In general, layers are repositories that contain related sets of

362

instructions and configurations that tell the Yocto Project what

363

to do.

364

Isolating related metadata into functionally specific layers

365

facilitates modular development and makes it easier to reuse the

366

layer metadata.

367

<note>

368

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

</note>

</para>

<para>

Follow these steps to add a hardware layer:

374

375

376

<emphasis>Find a Layer:</emphasis>

377

Lots of hardware layers exist.

378

The Yocto Project

379

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

380

has many hardware layers.

381

This example adds the

382

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

hardware layer.

</para></listitem>

<emphasis>Clone the Layer</emphasis>

387

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

388

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

389

Poky repository created earlier:

390

391

$ cd ~/poky

392

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

393

Cloning into 'meta-altera'...

394

remote: Counting objects: 25170, done.

395

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

396

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

397

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

398

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

399

Checking connectivity... done.

400

</literallayout>

401

The hardware layer now exists with other layers inside

402

the Poky reference repository on your build host as

403

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

404

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>

409

The

410

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

411

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

412

specifies the machine for the build.

413

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

414

variable to "cyclone5".

415

These configurations are used:

416

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

417

<note>

418

See the

419

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

420

step earlier for more information on configuring the

build.

</note>

</para></listitem>

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

426

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

427

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

428

is found in the

429

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

430

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

431

432

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

433

command to add the layer to the configuration file:

434

435

$ cd ~/poky/build

436

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

437

NOTE: Starting bitbake server...

438

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

439

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

440

</literallayout>

441

You can find more information on adding layers in the

442

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

447

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

448

development environment and configured it to build for the

449

"cyclone5" machine.

450

<note>

451

The previous steps are for demonstration purposes only.

452

If you were to attempt to build an image for the

453

"cyclone5" build, you should read the Altera

454

<filename>README</filename>.

</note>

</para>

</section>

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

461

462

<para>

463

Maybe you have an application or specific set of behaviors you

464

need to isolate.

465

You can create your own general layer using the

466

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

467

The tool automates layer creation by setting up a

468

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

469

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

470

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

471

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

</para>

<para>

The following commands run the tool to create a layer named

476

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

477

<filename>poky</filename> directory:

478

479

$ cd ~/poky

480

$ bitbake-layers create-layer meta-mylayer

481

NOTE: Starting bitbake server...

482

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

483

</literallayout>

484

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

485

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

486

section in the Yocto Project Development Tasks Manual.

</para>

</section>

<title>Where To Go Next</title>

492

493

<para>

494

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

495

be asking yourself "What now?"

496

The Yocto Project has many sources of information including

497

the website, wiki pages, and user manuals:

498

499

500

<emphasis>Website:</emphasis>

501

The

502

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

503

provides background information, the latest builds,

504

breaking news, full development documentation, and

505

access to a rich Yocto Project Development Community

506

into which you can tap.

507

</para></listitem>

508

509

<emphasis>Developer Screencast:</emphasis>

510

The

511

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

512

provides a 30-minute video created for users unfamiliar

513

with the Yocto Project but familiar with Linux build

514

hosts.

515

While this screencast is somewhat dated, the

516

introductory and fundamental concepts are useful for

the beginner.

</para></listitem>

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

521

The

522

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

523

is a great place to start to learn about the

524

Yocto Project.

525

This manual introduces you to the Yocto Project and its

526

development environment.

527

The manual also provides conceptual information for

528

various aspects of the Yocto Project.

529

</para></listitem>

530

531

<emphasis>Yocto Project Wiki:</emphasis>

532

The

533

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

534

provides additional information on where to go next

535

when ramping up with the Yocto Project, release

536

information, project planning, and QA information.

537

</para></listitem>

538

539

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

540

Related mailing lists provide a forum for discussion,

541

patch submission and announcements.

542

Several mailing lists exist and are grouped according

543

to areas of concern.

544

See the

545

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

546

section in the Yocto Project Reference Manual for a

547

complete list of Yocto Project mailing lists.

548

</para></listitem>

549

550

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

551

The

552

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

553

section in the Yocto Project Reference Manual provides a

554

comprehensive list of all related links and other

user documentation.

</para></listitem>

</itemizedlist>

</para>

</section>

</article>

<!--

vim: expandtab tw=80 ts=4

563

-->