Blame - import-layers/yocto-poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml - stefanberger/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.

40

<note>

41

The examples in this paper assume you are using a native Linux

42

system running a recent Ubuntu Linux distribution.

43

If the machine you want to use

44

Yocto Project on to build an image is not a native Linux

45

system, you can still perform these steps by using CROss

46

PlatformS (CROPS) and setting up a Poky container.

47

See the

48

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

49

section in the Yocto Project Development Tasks Manual for more

information.

</note>

</para>

<para>

If you want more conceptual or background information on the

56

Yocto Project, see the

57

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

67

meets the following requirements:

68

69

70

50 Gbytes of free disk space

71

</para></listitem>

72

73

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

74

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

75

Linux distributions that support the Yocto Project, see the

76

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

77

section in the Yocto Project Reference Manual.

</para></listitem>

Git 1.8.3.1 or greater

</para></listitem>

tar 1.27 or greater

</para></listitem>

Python 3.4.0 or greater.

89

</para></listitem>

90

</itemizedlist>

91

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

92

version requirements, you can take steps to prepare the

93

system so that you can still use the Yocto Project.

94

See the

95

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

96

section in the Yocto Project Reference Manual for information.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Build Host Packages</title>

104

105

<para>

106

You must install essential host packages on your

107

build host.

108

The following command installs the host packages based on an

109

Ubuntu distribution:

110

<note>

111

For host package requirements on all supported Linux

112

distributions, see the

113

"<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"

114

section in the Yocto Project Reference Manual.

115

</note>

116

117

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

</literallayout>

</para>

</section>

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

124

125

<para>

126

Once you complete the setup instructions for your machine,

127

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

128

host.

129

Use the following commands to clone the Poky

130

repository and then checkout the &DISTRO_REL_TAG; release:

131

132

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

133

Cloning into 'poky'...

134

remote: Counting objects: 361782, done.

135

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

136

remote: Total 361782 (delta 268619), reused 361439 (delta 268277)

137

Receiving objects: 100% (361782/361782), 131.94 MiB | 6.88 MiB/s, done.

138

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

139

Checking connectivity... done.

140

$ git checkout tags/yocto-2.5 -b my-yocto-2.5

141

</literallayout>

142

The previous Git checkout command creates a local branch

143

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

144

branch exactly match the repository's files in the

145

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

146

Yocto Project &DISTRO; release.

</para>

<para>

For more options and information about accessing Yocto

151

Project related repositories, see the

152

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

153

section in the Yocto Project Development Tasks Manual.

</para>

</section>

<title>Building Your Image</title>

159

160

<para>

161

Use the following steps to build your image.

162

The build process creates an entire Linux distribution, including

163

the toolchain, from source.

<note>

If you are working behind a firewall and your build

168

host is not set up for proxies, you could encounter

169

problems with the build process when fetching source

170

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

171

</para></listitem>

172

173

If you do not know your proxy settings, consult your

174

local network infrastructure resources and get that

175

information.

176

A good starting point could also be to check your

177

web browser settings.

178

Finally, you can find more information on the

179

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

180

page of the Yocto Project Wiki.

</para></listitem>

</itemizedlist>

</note>

</para>

<para>

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

190

Run the

191

192

environment setup script to define Yocto Project's

193

build environment on your build host.

194

195

$ source &OE_INIT_FILE;

196

</literallayout>

197

Among other things, the script creates the

198

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

199

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

200

and is located in the

201

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

202

After the script runs, your current working directory

203

is set to the Build Directory.

204

Later, when the build completes, the Build Directory

205

contains all the files created during the build.

206

</para></listitem>

207

208

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

209

When you set up the build environment, a local

210

configuration file named

211

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

212

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

213

Build Directory.

214

For this example, the defaults are set to build

215

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

216

suitable for emulation.

217

The package manager used is set to the RPM package

218

manager.

219

<tip>

220

You can significantly speed up your build and guard

221

against fetcher failures by using mirrors.

222

To use mirrors, add these lines to your

223

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

directory:

SSTATE_MIRRORS = "\

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

228

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

229

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

230

"

231

</literallayout>

232

The previous examples showed how to add sstate

233

paths for Yocto Project &YOCTO_DOC_VERSION_MINUS_ONE;,

234

&YOCTO_DOC_VERSION;, and a development area.

235

For a complete index of sstate locations, see

236

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

</tip>

</para></listitem>

<emphasis>Start the Build:</emphasis>

241

Continue with the following command to build an OS image

242

for the target, which is

243

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

244

245

$ bitbake core-image-sato

246

</literallayout>

247

For information on using the

248

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

249

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

250

section in the Yocto Project Overview and Concepts Manual,

251

or see the

252

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

253

section in the BitBake User Manual.

254

</para></listitem>

255

256

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

257

Once this particular image is built, you can start

258

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

264

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

265

chapter in the Yocto Project Development Tasks Manual.

</para></listitem>

Exit QEMU by either clicking on the shutdown icon or by

270

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

271

transcript window from which you evoked QEMU.

</para></listitem>

</orderedlist>

</para>

</section>

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

279

280

<para>

281

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

282

for emulation only.

283

This section shows you how to customize your build for specific

284

hardware by adding a hardware layer into the Yocto Project

285

development environment.

</para>

<para>

In general, layers are repositories that contain related sets of

290

instructions and configurations that tell the Yocto Project what

291

to do.

292

Isolating related metadata into functionally specific layers

293

facilitates modular development and makes it easier to reuse the

294

layer metadata.

295

<note>

296

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

</note>

</para>

<para>

Follow these steps to add a hardware layer:

302

303

304

<emphasis>Find a Layer:</emphasis>

305

Lots of hardware layers exist.

306

The Yocto Project

307

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

308

has many hardware layers.

309

This example adds the

310

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

hardware layer.

</para></listitem>

<emphasis>Clone the Layer</emphasis>

315

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

316

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

317

Poky repository created earlier:

318

319

$ cd ~/poky

320

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

321

Cloning into 'meta-altera'...

322

remote: Counting objects: 25170, done.

323

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

324

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

325

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

326

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

327

Checking connectivity... done.

328

</literallayout>

329

The hardware layer now exists with other layers inside

330

the Poky reference repository on your build host as

331

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

332

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>

337

The

338

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

339

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

340

specifies the machine for the build.

341

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

342

variable to "cyclone5".

343

These configurations are used:

344

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

345

<note>

346

See the

347

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

348

step earlier for more information on configuring the

build.

</note>

</para></listitem>

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

354

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

355

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

356

is found in the

357

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

358

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

359

360

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

361

command to add the layer to the configuration file:

362

363

$ cd ~/poky/build

364

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

365

NOTE: Starting bitbake server...

366

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

367

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

368

</literallayout>

369

You can find more information on adding layers in the

370

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

375

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

376

development environment and configured it to build for the

377

"cyclone5" machine.

378

<note>

379

The previous steps are for demonstration purposes only.

380

If you were to attempt to build an image for the

381

"cyclone5" build, you should read the Altera

382

<filename>README</filename>.

</note>

</para>

</section>

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

389

390

<para>

391

Maybe you have an application or specific set of behaviors you

392

need to isolate.

393

You can create your own general layer using the

394

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

395

The tool automates layer creation by setting up a

396

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

397

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

398

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

399

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

</para>

<para>

The following commands run the tool to create a layer named

404

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

405

<filename>poky</filename> directory:

406

407

$ cd ~/poky

408

$ bitbake-layers create-layer meta-mylayer

409

NOTE: Starting bitbake server...

410

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

411

</literallayout>

412

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

413

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

414

section in the Yocto Project Development Tasks Manual.

</para>

</section>

<title>Where To Go Next</title>

420

421

<para>

422

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

423

be asking yourself "What now?"

424

The Yocto Project has many sources of information including

425

the website, wiki pages, and user manuals:

426

427

428

<emphasis>Website:</emphasis>

429

The

430

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

431

provides background information, the latest builds,

432

breaking news, full development documentation, and

433

access to a rich Yocto Project Development Community

434

into which you can tap.

435

</para></listitem>

436

437

<emphasis>Developer Screencast:</emphasis>

438

The

439

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

440

provides a 30-minute video created for users unfamiliar

441

with the Yocto Project but familiar with Linux build

442

hosts.

443

While this screencast is somewhat dated, the

444

introductory and fundamental concepts are useful for

the beginner.

</para></listitem>

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

449

The

450

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

451

is a great place to start to learn about the

452

Yocto Project.

453

This manual introduces you to the Yocto Project and its

454

development environment.

455

The manual also provides conceptual information for

456

various aspects of the Yocto Project.

457

</para></listitem>

458

459

<emphasis>Yocto Project Wiki:</emphasis>

460

The

461

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

462

provides additional information on where to go next

463

when ramping up with the Yocto Project, release

464

information, project planning, and QA information.

465

</para></listitem>

466

467

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

468

Related mailing lists provide a forum for discussion,

469

patch submission and announcements.

470

Several mailing lists exist and are grouped according

471

to areas of concern.

472

See the

473

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

474

section in the Yocto Project Reference Manual for a

475

complete list of Yocto Project mailing lists.

476

</para></listitem>

477

478

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

479

The

480

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

481

section in the Yocto Project Reference Manual provides a

482

comprehensive list of all related links and other

user documentation.

</para></listitem>

</itemizedlist>

</para>

</section>

</article>

<!--

vim: expandtab tw=80 ts=4

491

-->