Blame - poky/documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml - mdmillerii/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

147

repository and then checkout the &DISTRO_REL_TAG; release:

148

149

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

150

Cloning into 'poky'...

151

remote: Counting objects: 361782, done.

152

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

153

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

154

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

155

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

156

Checking connectivity... done.

157

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

158

</literallayout>

159

The previous Git checkout command creates a local branch

160

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

161

branch exactly match the repository's files in the

162

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

163

Yocto Project &DISTRO; release.

</para>

<para>

For more options and information about accessing Yocto

168

Project related repositories, see the

169

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

170

section in the Yocto Project Development Tasks Manual.

</para>

</section>

<title>Building Your Image</title>

176

177

<para>

178

Use the following steps to build your image.

179

The build process creates an entire Linux distribution, including

180

the toolchain, from source.

<note>

If you are working behind a firewall and your build

185

host is not set up for proxies, you could encounter

186

problems with the build process when fetching source

187

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

188

</para></listitem>

189

190

If you do not know your proxy settings, consult your

191

local network infrastructure resources and get that

192

information.

193

A good starting point could also be to check your

194

web browser settings.

195

Finally, you can find more information on the

196

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

197

page of the Yocto Project Wiki.

</para></listitem>

</itemizedlist>

</note>

</para>

<para>

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

207

Run the

208

209

environment setup script to define Yocto Project's

210

build environment on your build host.

211

212

$ source &OE_INIT_FILE;

213

</literallayout>

214

Among other things, the script creates the

215

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

216

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

217

and is located in the

218

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

219

After the script runs, your current working directory

220

is set to the Build Directory.

221

Later, when the build completes, the Build Directory

222

contains all the files created during the build.

223

</para></listitem>

224

225

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

226

When you set up the build environment, a local

227

configuration file named

228

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

229

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

230

Build Directory.

231

For this example, the defaults are set to build

232

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

233

suitable for emulation.

234

The package manager used is set to the RPM package

235

manager.

236

<tip>

237

You can significantly speed up your build and guard

238

against fetcher failures by using mirrors.

239

To use mirrors, add these lines to your

240

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

directory:

SSTATE_MIRRORS = "\

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

245

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

246

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

247

"

248

</literallayout>

249

The previous examples showed how to add sstate

250

paths for Yocto Project &YOCTO_DOC_VERSION_MINUS_ONE;,

251

&YOCTO_DOC_VERSION;, and a development area.

252

For a complete index of sstate locations, see

253

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

</tip>

</para></listitem>

<emphasis>Start the Build:</emphasis>

258

Continue with the following command to build an OS image

259

for the target, which is

260

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

261

262

$ bitbake core-image-sato

263

</literallayout>

264

For information on using the

265

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

266

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

267

section in the Yocto Project Overview and Concepts Manual,

268

or see the

269

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

270

section in the BitBake User Manual.

271

</para></listitem>

272

273

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

274

Once this particular image is built, you can start

275

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

281

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

282

chapter in the Yocto Project Development Tasks Manual.

</para></listitem>

Exit QEMU by either clicking on the shutdown icon or by

287

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

288

transcript window from which you evoked QEMU.

</para></listitem>

</orderedlist>

</para>

</section>

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

296

297

<para>

298

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

299

for emulation only.

300

This section shows you how to customize your build for specific

301

hardware by adding a hardware layer into the Yocto Project

302

development environment.

</para>

<para>

In general, layers are repositories that contain related sets of

307

instructions and configurations that tell the Yocto Project what

308

to do.

309

Isolating related metadata into functionally specific layers

310

facilitates modular development and makes it easier to reuse the

311

layer metadata.

312

<note>

313

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

</note>

</para>

<para>

Follow these steps to add a hardware layer:

319

320

321

<emphasis>Find a Layer:</emphasis>

322

Lots of hardware layers exist.

323

The Yocto Project

324

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

325

has many hardware layers.

326

This example adds the

327

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

hardware layer.

</para></listitem>

<emphasis>Clone the Layer</emphasis>

332

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

333

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

334

Poky repository created earlier:

335

336

$ cd ~/poky

337

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

338

Cloning into 'meta-altera'...

339

remote: Counting objects: 25170, done.

340

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

341

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

342

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

343

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

344

Checking connectivity... done.

345

</literallayout>

346

The hardware layer now exists with other layers inside

347

the Poky reference repository on your build host as

348

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

349

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>

354

The

355

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

356

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

357

specifies the machine for the build.

358

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

359

variable to "cyclone5".

360

These configurations are used:

361

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

362

<note>

363

See the

364

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

365

step earlier for more information on configuring the

build.

</note>

</para></listitem>

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

371

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

372

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

373

is found in the

374

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

375

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

376

377

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

378

command to add the layer to the configuration file:

379

380

$ cd ~/poky/build

381

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

382

NOTE: Starting bitbake server...

383

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

384

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

385

</literallayout>

386

You can find more information on adding layers in the

387

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

392

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

393

development environment and configured it to build for the

394

"cyclone5" machine.

395

<note>

396

The previous steps are for demonstration purposes only.

397

If you were to attempt to build an image for the

398

"cyclone5" build, you should read the Altera

399

<filename>README</filename>.

</note>

</para>

</section>

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

406

407

<para>

408

Maybe you have an application or specific set of behaviors you

409

need to isolate.

410

You can create your own general layer using the

411

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

412

The tool automates layer creation by setting up a

413

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

414

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

415

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

416

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

</para>

<para>

The following commands run the tool to create a layer named

421

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

422

<filename>poky</filename> directory:

423

424

$ cd ~/poky

425

$ bitbake-layers create-layer meta-mylayer

426

NOTE: Starting bitbake server...

427

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

428

</literallayout>

429

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

430

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

431

section in the Yocto Project Development Tasks Manual.

</para>

</section>

<title>Where To Go Next</title>

437

438

<para>

439

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

440

be asking yourself "What now?"

441

The Yocto Project has many sources of information including

442

the website, wiki pages, and user manuals:

443

444

445

<emphasis>Website:</emphasis>

446

The

447

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

448

provides background information, the latest builds,

449

breaking news, full development documentation, and

450

access to a rich Yocto Project Development Community

451

into which you can tap.

452

</para></listitem>

453

454

<emphasis>Developer Screencast:</emphasis>

455

The

456

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

457

provides a 30-minute video created for users unfamiliar

458

with the Yocto Project but familiar with Linux build

459

hosts.

460

While this screencast is somewhat dated, the

461

introductory and fundamental concepts are useful for

the beginner.

</para></listitem>

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

466

The

467

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

468

is a great place to start to learn about the

469

Yocto Project.

470

This manual introduces you to the Yocto Project and its

471

development environment.

472

The manual also provides conceptual information for

473

various aspects of the Yocto Project.

474

</para></listitem>

475

476

<emphasis>Yocto Project Wiki:</emphasis>

477

The

478

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

479

provides additional information on where to go next

480

when ramping up with the Yocto Project, release

481

information, project planning, and QA information.

482

</para></listitem>

483

484

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

485

Related mailing lists provide a forum for discussion,

486

patch submission and announcements.

487

Several mailing lists exist and are grouped according

488

to areas of concern.

489

See the

490

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

491

section in the Yocto Project Reference Manual for a

492

complete list of Yocto Project mailing lists.

493

</para></listitem>

494

495

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

496

The

497

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

498

section in the Yocto Project Reference Manual provides a

499

comprehensive list of all related links and other

user documentation.

</para></listitem>

</itemizedlist>

</para>

</section>

</article>

<!--

vim: expandtab tw=80 ts=4

508

-->