Blame - import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml - openbmc/openbmc

Patrick Williams

d8c66bc

2016-06-20 12:57:21 -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; ] >

<title>Using the Extensible SDK</title>

8

9

<para>

10

This chapter describes the extensible SDK and how to use it.

11

The extensible SDK makes it easy to add new applications and libraries

12

to an image, modify the source for an existing component, test

13

changes on the target hardware, and ease integration into the rest of the

14

<ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>.

</para>

<para>

Information in this chapter covers features that are not part of the

19

standard SDK.

20

In other words, the chapter presents information unique to the

21

extensible SDK only.

22

For information on how to use the standard SDK, see the

23

"<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>"

chapter.

</para>

<title>Setting Up to Use the Extensible SDK</title>

29

30

<para>

31

Getting set up to use the extensible SDK is identical to getting set

32

up to use the standard SDK.

33

You still need to locate and run the installer and then run the

34

environment setup script.

35

See the

36

"<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>"

37

and the

38

"<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>"

39

sections for general information.

40

The following items highlight the only differences between getting

41

set up to use the extensible SDK as compared to the standard SDK:

42

43

<listitem><para><emphasis>Default Installation Directory:</emphasis>

44

By default, the extensible SDK installs into the

45

<filename>poky_sdk</filename> folder of your home directory.

46

As with the standard SDK, you can choose to install the

47

extensible SDK in any location when you run the installer.

48

However, unlike the standard SDK, the location you choose needs

49

to be writable for whichever users need to use the SDK,

50

since files will need to be written under that directory during

51

the normal course of operation.

52

</para></listitem>

53

<listitem><para><emphasis>Build Tools and Build System:</emphasis>

54

The extensible SDK installer performs additional tasks as

55

compared to the standard SDK installer.

56

The extensible SDK installer extracts build tools specific

57

to the SDK and the installer also prepares the internal build

58

system within the SDK.

59

Here is example output for running the extensible SDK

60

installer:

61

62

$ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.1+snapshot.sh

63

Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.1+snapshot

64

===================================================================================

65

Enter target directory for SDK (default: ~/poky_sdk):

66

You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y

67

Extracting SDK......................................................................done

68

Setting it up...

69

Extracting buildtools...

70

Preparing build system...

71

done

72

SDK has been successfully set up and is ready to be used.

73

Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.

74

$ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux

</literallayout>

</para></listitem>

</itemizedlist>

</para>

<para>

After installing the SDK, you need to run the SDK environment setup

script.

Here is the output:

$ source environment-setup-core2-64-poky-linux

86

SDK environment now set up; additionally you may now run devtool to perform development tasks.

87

Run devtool --help for further details.

88

</literallayout>

89

Once you run the environment setup script, you have

90

<filename>devtool</filename> available.

</para>

</section>

<title>Using <filename>devtool</filename> in Your SDK Workflow</title>

96

97

<para>

98

The cornerstone of the extensible SDK is a command-line tool

99

called <filename>devtool</filename>.

100

This tool provides a number of features that help

101

you build, test and package software within the extensible SDK, and

102

optionally integrate it into an image built by the OpenEmbedded build

system.

</para>

<para>

The <filename>devtool</filename> command line is organized similarly

108

to

109

<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a

110

number of sub-commands for each function.

111

You can run <filename>devtool --help</filename> to see all the

commands.

</para>

<para>

Two <filename>devtool</filename> subcommands that provide

117

entry-points into development are:

118

119

<listitem><para><emphasis><filename>devtool add</filename></emphasis>:

120

Assists in adding new software to be built.

121

</para></listitem>

122

<listitem><para><emphasis><filename>devtool modify</filename></emphasis>:

123

Sets up an environment to enable you to modify the source of

124

an existing component.

125

</para></listitem>

126

</itemizedlist>

127

As with the OpenEmbedded build system, "recipes" represent software

128

packages within <filename>devtool</filename>.

129

When you use <filename>devtool add</filename>, a recipe is

130

automatically created.

131

When you use <filename>devtool modify</filename>, the specified

132

existing recipe is used in order to determine where to get the source

133

code and how to patch it.

134

In both cases, an environment is set up so that when you build the

135

recipe a source tree that is under your control is used in order to

136

allow you to make changes to the source as desired.

137

By default, both new recipes and the source go into a "workspace"

138

directory under the SDK.

</para>

<para>

The remainder of this section presents the

143

<filename>devtool add</filename> and

144

<filename>devtool modify</filename> workflows.

</para>

<title>Use <filename>devtool add</filename> to Add an Application</title>

149

150

<para>

151

The <filename>devtool add</filename> command generates

152

a new recipe based on existing source code.

153

This command takes advantage of the

154

<ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>

155

layer that many <filename>devtool</filename> commands

156

use.

157

The command is flexible enough to allow you to extract source

158

code into both the workspace or a separate local Git repository

159

and to use existing code that does not need to be extracted.

</para>

<para>

Depending on your particular scenario, the arguments and options

164

you use with <filename>devtool add</filename> form different

165

combinations.

166

The following diagram shows common development flows

167

you would use with the <filename>devtool add</filename>

command:

</para>

<para>

</para>

<para>

<listitem><para><emphasis>Generating the New Recipe</emphasis>:

178

The top part of the flow shows three scenarios by which

179

you could use <filename>devtool add</filename> to

180

generate a recipe based on existing source code.</para>

181

182

<para>In a shared development environment, it is

183

typical where other developers are responsible for

184

various areas of source code.

185

As a developer, you are probably interested in using

186

that source code as part of your development using

187

the Yocto Project.

188

All you need is access to the code, a recipe, and a

189

controlled area in which to do your work.</para>

190

191

<para>Within the diagram, three possible scenarios

192

feed into the <filename>devtool add</filename> workflow:

193

194

<listitem><para><emphasis>Left</emphasis>:

195

The left scenario represents a common situation

196

where the source code does not exist locally

197

and needs to be extracted.

198

In this situation, you just let it get

199

extracted to the default workspace - you do not

200

want it in some specific location outside of the

201

workspace.

202

Thus, everything you need will be located in the

203

workspace:

204

205

$ devtool add <replaceable>recipe fetchuri</replaceable>

206

</literallayout>

207

With this command, <filename>devtool</filename>

208

creates a recipe and an append file in the

209

workspace as well as extracts the upstream

210

source files into a local Git repository also

211

within the <filename>sources</filename> folder.

212

</para></listitem>

213

<listitem><para><emphasis>Middle</emphasis>:

214

The middle scenario also represents a situation where

215

the source code does not exist locally.

216

In this case, the code is again upstream

217

and needs to be extracted to some

218

local area - this time outside of the default

219

workspace.

220

As always, if required <filename>devtool</filename> creates

221

a Git repository locally during the extraction.

222

Furthermore, the first positional argument

223

<replaceable>srctree</replaceable> in this case

224

identifies where the

225

<filename>devtool add</filename> command

226

will locate the extracted code outside of the

227

workspace:

228

229

$ devtool add <replaceable>recipe srctree fetchuri</replaceable>

230

</literallayout>

231

In summary, the source code is pulled from

232

<replaceable>fetchuri</replaceable> and extracted

233

into the location defined by

234

<replaceable>srctree</replaceable> as a local

235

Git repository.</para>

236

237

<para>Within workspace, <filename>devtool</filename>

238

creates both the recipe and an append file

239

for the recipe.

240

</para></listitem>

241

<listitem><para><emphasis>Right</emphasis>:

242

The right scenario represents a situation

243

where the source tree (srctree) has been

244

previously prepared outside of the

245

<filename>devtool</filename> workspace.

246

</para>

247

248

<para>The following command names the recipe

249

and identifies where the existing source tree

250

is located:

251

252

$ devtool add <replaceable>recipe srctree</replaceable>

253

</literallayout>

254

The command examines the source code and creates

255

a recipe for it placing the recipe into the

256

workspace.</para>

257

258

<para>Because the extracted source code already exists,

259

<filename>devtool</filename> does not try to

260

relocate it into the workspace - just the new

261

the recipe is placed in the workspace.</para>

262

263

<para>Aside from a recipe folder, the command

264

also creates an append folder and places an initial

265

<filename>*.bbappend</filename> within.

</para></listitem>

</itemizedlist>

</para></listitem>

<listitem><para><emphasis>Edit the Recipe</emphasis>:

270

At this point, you can use <filename>devtool edit-recipe</filename>

271

to open up the editor as defined by the

272

<filename>$EDITOR</filename> environment variable

273

and modify the file:

274

275

$ devtool edit-recipe <replaceable>recipe</replaceable>

276

</literallayout>

277

From within the editor, you can make modifications to the

278

recipe that take affect when you build it later.

279

</para></listitem>

280

<listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>:

281

At this point in the flow, the next step you

282

take depends on what you are going to do with

283

the new code.</para>

284

<para>If you need to take the build output and eventually

285

move it to the target hardware, you would use

286

<filename>devtool build</filename>:

287

288

$ devtool build <replaceable>recipe</replaceable>

289

</literallayout></para>

290

<para>On the other hand, if you want an image to

291

contain the recipe's packages for immediate deployment

292

onto a device (e.g. for testing purposes), you can use

293

the <filename>devtool build-image</filename> command:

294

295

$ devtool build-image <replaceable>image</replaceable>

296

</literallayout>

297

</para></listitem>

298

<listitem><para><emphasis>Deploy the Build Output</emphasis>:

299

When you use the <filename>devtool build</filename>

300

command to build out your recipe, you probably want to

301

see if the resulting build output works as expected on target

302

hardware.

303

<note>

304

This step assumes you have a previously built

305

image that is already either running in QEMU or

306

running on actual hardware.

307

Also, it is assumed that for deployment of the image

308

to the target, SSH is installed in the image and if

309

the image is running on real hardware that you have

310

network access to and from your development machine.

311

</note>

312

You can deploy your build output to that target hardware by

313

using the <filename>devtool deploy-target</filename> command:

314

315

$ devtool deploy-target <replaceable>recipe target</replaceable>

316

</literallayout>

317

The <replaceable>target</replaceable> is a live target machine

318

running as an SSH server.</para>

319

320

<para>You can, of course, also deploy the image you build

321

using the <filename>devtool build-image</filename> command

322

to actual hardware.

323

However, <filename>devtool</filename> does not provide a

324

specific command that allows you to do this.

325

</para></listitem>

326

<listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>:

327

Once you are satisfied with the recipe, if you have made

328

any changes to the source tree that you want to have

329

applied by the recipe, you need to generate patches

330

from those changes.

331

You do this before moving the recipe

332

to its final layer and cleaning up the workspace area

333

<filename>devtool</filename> uses.

334

This optional step is especially relevant if you are

335

using or adding third-party software.</para>

336

<para>To convert commits created using Git to patch files,

337

use the <filename>devtool update-recipe</filename> command.

338

<note>

339

Any changes you want to turn into patches must be

340

committed to the Git repository in the source tree.

341

</note>

342

343

$ devtool update-recipe <replaceable>recipe</replaceable>

344

</literallayout>

345

</para></listitem>

346

<listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:

347

Before cleaning up the workspace, you need to move the

348

final recipe to its permanent layer.

349

You must do this before using the

350

<filename>devtool reset</filename> command if you want to

351

retain the recipe.

352

</para></listitem>

353

<listitem><para><emphasis>Reset the Recipe</emphasis>:

354

As a final step, you can restore the state such that

355

standard layers and the upstream source is used to build

356

the recipe rather than data in the workspace.

357

To reset the recipe, use the <filename>devtool reset</filename>

358

command:

359

360

$ devtool reset <replaceable>recipe</replaceable>

</literallayout>

</para></listitem>

</orderedlist>

</para>

</section>

<title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>

369

370

<para>

371

The <filename>devtool modify</filename> command prepares the

372

way to work on existing code that already has a recipe in

373

place.

374

The command is flexible enough to allow you to extract code,

375

specify the existing recipe, and keep track of and gather any

376

patch files from other developers that are

377

associated with the code.

</para>

<para>

Depending on your particular scenario, the arguments and options

382

you use with <filename>devtool modify</filename> form different

383

combinations.

384

The following diagram shows common development flows

385

you would use with the <filename>devtool modify</filename>

command:

</para>

<para>

</para>

<para>

<listitem><para><emphasis>Preparing to Modify the Code</emphasis>:

396

The top part of the flow shows three scenarios by which

397

you could use <filename>devtool modify</filename> to

398

prepare to work on source files.

399

Each scenario assumes the following:

400

401

<listitem><para>The recipe exists in some layer external

402

to the <filename>devtool</filename> workspace.

403

</para></listitem>

404

<listitem><para>The source files exist upstream in an

405

un-extracted state or locally in a previously

extracted state.

</para></listitem>

</itemizedlist>

The typical situation is where another developer has

410

created some layer for use with the Yocto Project and

411

their recipe already resides in that layer.

412

Furthermore, their source code is readily available

413

either upstream or locally.

414

415

<listitem><para><emphasis>Left</emphasis>:

416

The left scenario represents a common situation

417

where the source code does not exist locally

418

and needs to be extracted.

419

In this situation, the source is extracted

420

into the default workspace location.

421

The recipe, in this scenario, is in its own

422

layer outside the workspace

423

(i.e.

424

<filename>meta-</filename><replaceable>layername</replaceable>).

425

</para>

426

427

<para>The following command identifies the recipe

428

and by default extracts the source files:

429

430

$ devtool modify <replaceable>recipe</replaceable>

431

</literallayout>

432

Once <filename>devtool</filename>locates the recipe,

433

it uses the

434

435

variable to locate the source code and

436

any local patch files from other developers are

437

located.

438

<note>

439

You cannot provide an URL for

440

<replaceable>srctree</replaceable> when using the

441

<filename>devtool modify</filename> command.

442

</note>

443

With this scenario, however, since no

444

<replaceable>srctree</replaceable> argument exists, the

445

<filename>devtool modify</filename> command by default

446

extracts the source files to a Git structure.

447

Furthermore, the location for the extracted source is the

448

default area within the workspace.

449

The result is that the command sets up both the source

450

code and an append file within the workspace with the

451

recipe remaining in its original location.

452

</para></listitem>

453

<listitem><para><emphasis>Middle</emphasis>:

454

The middle scenario represents a situation where

455

the source code also does not exist locally.

456

In this case, the code is again upstream

457

and needs to be extracted to some

458

local area as a Git repository.

459

The recipe, in this scenario, is again in its own

460

layer outside the workspace.</para>

461

462

<para>The following command tells

463

<filename>devtool</filename> what recipe with

464

which to work and, in this case, identifies a local

465

area for the extracted source files that is outside

466

of the default workspace:

467

468

$ devtool modify <replaceable>recipe srctree</replaceable>

469

</literallayout>

470

As with all extractions, the command uses

471

the recipe's <filename>SRC_URI</filename> to locate the

472

source files.

473

Once the files are located, the command by default

474

extracts them.

475

Providing the <replaceable>srctree</replaceable>

476

argument instructs <filename>devtool</filename> where

477

place the extracted source.</para>

478

479

<para>Within workspace, <filename>devtool</filename>

480

creates an append file for the recipe.

481

The recipe remains in its original location but

482

the source files are extracted to the location you

483

provided with <replaceable>srctree</replaceable>.

484

</para></listitem>

485

<listitem><para><emphasis>Right</emphasis>:

486

The right scenario represents a situation

487

where the source tree

488

(<replaceable>srctree</replaceable>) exists as a

489

previously extracted Git structure outside of

490

the <filename>devtool</filename> workspace.

491

In this example, the recipe also exists

492

elsewhere in its own layer.

493

</para>

494

495

<para>The following command tells

496

<filename>devtool</filename> the recipe

497

with which to work, uses the "-n" option to indicate

498

source does not need to be extracted, and uses

499

<replaceable>srctree</replaceable> to point to the

500

previously extracted source files:

501

502

$ devtool modify -n <replaceable>recipe srctree</replaceable>

</literallayout>

</para>

<para>Once the command finishes, it creates only

507

an append file for the recipe in the workspace.

508

The recipe and the source code remain in their

original locations.

</para></listitem>

</itemizedlist>

</para></listitem>

<listitem><para><emphasis>Edit the Source</emphasis>:

514

Once you have used the <filename>devtool modify</filename>

515

command, you are free to make changes to the source

516

files.

517

You can use any editor you like to make and save

518

your source code modifications.

519

</para></listitem>

520

<listitem><para><emphasis>Build the Recipe</emphasis>:

521

Once you have updated the source files, you can build

522

the recipe.

523

</para></listitem>

524

<listitem><para><emphasis>Deploy the Build Output</emphasis>:

525

When you use the <filename>devtool build</filename>

526

command to build out your recipe, you probably want to see

527

if the resulting build output works as expected on target

528

hardware.

529

<note>

530

This step assumes you have a previously built

531

image that is already either running in QEMU or

532

running on actual hardware.

533

Also, it is assumed that for deployment of the image

534

to the target, SSH is installed in the image and if

535

the image is running on real hardware that you have

536

network access to and from your development machine.

537

</note>

538

You can deploy your build output to that target hardware by

539

using the <filename>devtool deploy-target</filename> command:

540

541

$ devtool deploy-target <replaceable>recipe target</replaceable>

542

</literallayout>

543

The <replaceable>target</replaceable> is a live target machine

544

running as an SSH server.</para>

545

546

<para>You can, of course, also deploy the image you build

547

using the <filename>devtool build-image</filename> command

548

to actual hardware.

549

However, <filename>devtool</filename> does not provide a

550

specific command that allows you to do this.

551

</para></listitem>

552

<listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:

553

After you have debugged your changes, you can

554

use <filename>devtool update-recipe</filename> to

555

generate patch files for all the commits you have

556

made.

557

<note>

558

Patch files are generated only for changes

you have committed.

</note>

$ devtool update-recipe <replaceable>recipe</replaceable>

563

</literallayout>

564

By default, the

565

<filename>devtool update-recipe</filename> command

566

creates the patch files in a folder named the same

567

as the recipe beneath the folder in which the recipe

568

resides, and updates the recipe's

569

570

statement to point to the generated patch files.

571

<note>

572

You can use the

573

"--append <replaceable>LAYERDIR</replaceable>"

574

option to cause the command to create append files

575

in a specific layer rather than the default

recipe layer.

</note>

</para></listitem>

<listitem><para><emphasis>Restore the Workspace</emphasis>:

580

The <filename>devtool reset</filename> restores the

581

state so that standard layers and upstream sources are

582

used to build the recipe rather than what is in the

583

workspace.

584

585

$ devtool reset <replaceable>recipe</replaceable>

</literallayout>

</para></listitem>

</orderedlist>

</para>

</section>

</section>

<title>A Closer Look at <filename>devtool add</filename></title>

595

596

<para>

597

The <filename>devtool add</filename> command automatically creates a

598

recipe based on the source tree with which you provide it.

599

Currently, the command has support for the following:

600

601

602

Autotools (<filename>autoconf</filename> and

603

<filename>automake</filename>)

</para></listitem>

CMake

</para></listitem>

Scons

</para></listitem>

<filename>qmake</filename>

613

</para></listitem>

614

615

Plain <filename>Makefile</filename>

616

</para></listitem>

617

618

Out-of-tree kernel module

619

</para></listitem>

620

621

Binary package (i.e. "-b" option)

622

</para></listitem>

623

624

Node.js module through

</para></listitem>

Python modules that use <filename>setuptools</filename>

629

or <filename>distutils</filename>

</para></listitem>

</itemizedlist>

</para>

<para>

Apart from binary packages, the determination of how a source tree

636

should be treated is automatic based on the files present within

637

that source tree.

638

For example, if a <filename>CMakeLists.txt</filename> file is found,

639

then the source tree is assumed to be using

640

CMake and is treated accordingly.

641

<note>

642

In most cases, you need to edit the automatically generated

643

recipe in order to make it build properly.

644

Typically, you would go through several edit and build cycles

645

until you can build the recipe.

646

Once the recipe can be built, you could use possible further

647

iterations to test the recipe on the target device.

</note>

</para>

<para>

The remainder of this section covers specifics regarding how parts

653

of the recipe are generated.

</para>

<title>Name and Version</title>

658

659

<para>

660

If you do not specify a name and version on the command

661

line, <filename>devtool add</filename> attempts to determine

662

the name and version of the software being built from

663

various metadata within the source tree.

664

Furthermore, the command sets the name of the created recipe

665

file accordingly.

666

If the name or version cannot be determined, the

667

<filename>devtool add</filename> command prints an error and

668

you must re-run the command with both the name and version

669

or just the name or version specified.

</para>

<para>

Sometimes the name or version determined from the source tree

674

might be incorrect.

675

For such a case, you must reset the recipe:

676

677

$ devtool reset -n <replaceable>recipename</replaceable>

678

</literallayout>

679

After running the <filename>devtool reset</filename> command,

680

you need to run <filename>devtool add</filename> again and

681

provide the name or the version.

</para>

</section>

<title>Dependency Detection and Mapping</title>

687

688

<para>

689

The <filename>devtool add</filename> command attempts to

690

detect build-time dependencies and map them to other recipes

691

in the system.

692

During this mapping, the command fills in the names of those

693

recipes in the

694

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

695

value within the recipe.

696

If a dependency cannot be mapped, then a comment is placed in

697

the recipe indicating such.

698

The inability to map a dependency might be caused because the

699

naming is not recognized or because the dependency simply is

700

not available.

701

For cases where the dependency is not available, you must use

702

the <filename>devtool add</filename> command to add an

703

additional recipe to satisfy the dependency and then come

704

back to the first recipe and add its name to

705

<filename>DEPENDS</filename>.

</para>

<para>

If you need to add runtime dependencies, you can do so by

710

adding the following to your recipe:

711

712

RDEPENDS_${PN} += "dependency1 dependency2 ..."

713

</literallayout>

714

<note>

715

The <filename>devtool add</filename> command often cannot

716

distinguish between mandatory and optional dependencies.

717

Consequently, some of the detected dependencies might

718

in fact be optional.

719

When in doubt, consult the documentation or the configure

720

script for the software the recipe is building for further

721

details.

722

In some cases, you might find you can substitute the

723

dependency for an option to disable the associated

724

functionality passed to the configure script.

</note>

</para>

</section>

<title>License Detection</title>

731

732

<para>

733

The <filename>devtool add</filename> command attempts to

734

determine if the software you are adding is able to be

735

distributed under a common open-source license and sets the

736

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

737

value accordingly.

738

You should double-check this value against the documentation

739

or source files for the software you are building and update

740

that <filename>LICENSE</filename> value if necessary.

</para>

<para>

The <filename>devtool add</filename> command also sets the

745

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

746

value to point to all files that appear to be license-related.

747

However, license statements often appear in comments at the top

748

of source files or within documentation.

749

Consequently, you might need to amend the

750

<filename>LIC_FILES_CHKSUM</filename> variable to point to one

751

or more of those comments if present.

752

Setting <filename>LIC_FILES_CHKSUM</filename> is particularly

753

important for third-party software.

754

The mechanism attempts to ensure correct licensing should you

755

upgrade the recipe to a newer upstream version in future.

756

Any change in licensing is detected and you receive an error

757

prompting you to check the license text again.

</para>

<para>

If the <filename>devtool add</filename> command cannot

762

determine licensing information, the

763

<filename>LICENSE</filename> value is set to "CLOSED" and the

764

<filename>LIC_FILES_CHKSUM</filename> vaule remains unset.

765

This behavior allows you to continue with development but is

766

unlikely to be correct in all cases.

767

Consequently, you should check the documentation or source

768

files for the software you are building to determine the actual

license.

</para>

</section>

<title>Adding Makefile-Only Software</title>

775

776

<para>

777

The use of <filename>make</filename> by itself is very common

778

in both proprietary and open source software.

779

Unfortunately, Makefiles are often not written with

780

cross-compilation in mind.

781

Thus, <filename>devtool add</filename> often cannot do very

782

much to ensure that these Makefiles build correctly.

783

It is very common, for example, to explicitly call

784

<filename>gcc</filename> instead of using the

785

<filename>CC</filename> variable.

786

Usually, in a cross-compilation environment,

787

<filename>gcc</filename> is the compiler for the build host

788

and the cross-compiler is named something similar to

789

<filename>arm-poky-linux-gnueabi-gcc</filename> and might

790

require some arguments (e.g. to point to the associated sysroot

791

for the target machine).

</para>

<para>

When writing a recipe for Makefile-only software, keep the

following in mind:

You probably need to patch the Makefile to use

800

variables instead of hardcoding tools within the

801

toolchain such as <filename>gcc</filename> and

802

<filename>g++</filename>.

803

</para></listitem>

804

805

The environment in which <filename>make</filename> runs

806

is set up with various standard variables for

807

compilation (e.g. <filename>CC</filename>,

808

<filename>CXX</filename>, and so forth) in a similar

809

manner to the environment set up by the SDK's

810

environment setup script.

811

One easy way to see these variables is to run the

812

<filename>devtool build</filename> command on the

813

recipe and then look in

814

<filename>oe-logs/run.do_compile</filename>.

815

Towards the top of this file you will see a list of

816

environment variables that are being set.

817

You can take advantage of these variables within the

Makefile.

</para></listitem>

If the Makefile sets a default for a variable using "=",

822

that default overrides the value set in the environment,

823

which is usually not desirable.

824

In this situation, you can either patch the Makefile

825

so it sets the default using the "?=" operator, or

826

you can alternatively force the value on the

827

<filename>make</filename> command line.

828

To force the value on the command line, add the

829

variable setting to

830

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

831

within the recipe as follows:

832

833

EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"

834

</literallayout>

835

In the above example, single quotes are used around the

836

variable settings as the values are likely to contain

837

spaces because required default options are passed to

the compiler.

</para></listitem>

Hardcoding paths inside Makefiles is often problematic

842

in a cross-compilation environment.

843

This is particularly true because those hardcoded paths

844

often point to locations on the build host and thus

845

will either be read-only or will introduce

846

contamination into the cross-compilation by virtue of

847

being specific to the build host rather than the target.

848

Patching the Makefile to use prefix variables or other

849

path variables is usually the way to handle this.

850

</para></listitem>

851

852

Sometimes a Makefile runs target-specific commands such

853

as <filename>ldconfig</filename>.

854

For such cases, you might be able to simply apply

855

patches that remove these commands from the Makefile.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Adding Native Tools</title>

863

864

<para>

865

Often, you need to build additional tools that run on the

866

build host system as opposed to the target.

867

You should indicate this using one of the following methods

868

when you run <filename>devtool add</filename>:

869

870

871

Specify the name of the recipe such that it ends

872

with "-native".

873

Specifying the name like this produces a recipe that

874

only builds for the build host.

875

</para></listitem>

876

877

Specify the "&dash;&dash;also-native" option with the

878

<filename>devtool add</filename> command.

879

Specifying this option creates a recipe file that still

880

builds for the target but also creates a variant with

881

a "-native" suffix that builds for the build host.

</para></listitem>

</itemizedlist>

<note>

If you need to add a tool that is shipped as part of a

886

source tree that builds code for the target, you can

887

typically accomplish this by building the native and target

888

parts separately rather than within the same compilation

889

process.

890

Realize though that with the "&dash;&dash;also-native" option, you

891

can add the tool using just one recipe file.

</note>

</para>

</section>

<title>Adding Node.js Modules</title>

898

899

<para>

900

You can use the <filename>devtool add</filename> command in the

901

following form to add Node.js modules:

902

903

$ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"

904

</literallayout>

905

The name and version parameters are mandatory.

906

Lockdown and shrinkwrap files are generated and pointed to by

907

the recipe in order to freeze the version that is fetched for

908

the dependencies according to the first time.

909

This also saves checksums that are verified on future fetches.

910

Together, these behaviors ensure the reproducibility and

911

integrity of the build.

912

<note><title>Notes</title>

913

914

915

You must use quotes around the URL.

916

The <filename>devtool add</filename> does not require

917

the quotes, but the shell considers ";" as a splitter

918

between multiple commands.

919

Thus, without the quotes,

920

<filename>devtool add</filename> does not receive the

921

other parts, which results in several "command not

found" errors.

</para></listitem>

In order to support adding

926

Node.js modules, a

927

<filename>nodejs</filename> recipe must be part of your

928

SDK in order to provide Node.js

itself.

</para></listitem>

</itemizedlist>

</note>

</para>

</section>

</section>

<title>Working With Recipes</title>

939

940

<para>

941

When building a recipe with <filename>devtool build</filename> the

942

typical build progression is as follows:

Fetch the source

</para></listitem>

Unpack the source

</para></listitem>

Configure the source

</para></listitem>

Compiling the source

</para></listitem>

Install the build output

958

</para></listitem>

959

960

Package the installed output

961

</para></listitem>

962

</orderedlist>

963

For recipes in the workspace, fetching and unpacking is disabled

964

as the source tree has already been prepared and is persistent.

965

Each of these build steps is defined as a function, usually with a

966

"do_" prefix.

967

These functions are typically shell scripts but can instead be written

in Python.

</para>

<para>

If you look at the contents of a recipe, you will see that the

973

recipe does not include complete instructions for building the

974

software.

975

Instead, common functionality is encapsulated in classes inherited

976

with the <filename>inherit</filename> directive, leaving the recipe

977

to describe just the things that are specific to the software to be

978

built.

979

A <ulink url='ref-classes-base'><filename>base</filename></ulink>

980

class exists that is implicitly inherited by all recipes and provides

981

the functionality that most typical recipes need.

</para>

<para>

The remainder of this section presents information useful when

986

working with recipes.

</para>

<title>Finding Logs and Work Files</title>

991

992

<para>

993

When you are debugging a recipe that you previously created using

994

<filename>devtool add</filename> or whose source you are modifying

995

by using the <filename>devtool modify</filename> command, after

996

the first run of <filename>devtool build</filename>, you will

997

find some symbolic links created within the source tree:

998

<filename>oe-logs</filename>, which points to the directory in

999

which log files and run scripts for each build step are created

1000

and <filename>oe-workdir</filename>, which points to the temporary

1001

work area for the recipe.

1002

You can use these links to get more information on what is

1003

happening at each build step.

</para>

<para>

These locations under <filename>oe-workdir</filename> are

1008

particularly useful:

1009

1010

<listitem><para><filename>image/</filename>:

1011

Contains all of the files installed at the

1012

<ulink url='&YOCTO_DOCS_REF_URL;ref-tasks-install'><filename>do_install</filename></ulink>

1013

stage.

1014

Within a recipe, this directory is referred to by the

1015

expression

1016

<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>.

1017

</para></listitem>

1018

<listitem><para><filename>sysroot-destdir/</filename>:

1019

Contains a subset of files installed within

1020

<filename>do_install</filename> that have been put into the

1021

shared sysroot.

1022

For more information, see the

1023

"<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>"

1024

section.

1025

</para></listitem>

1026

<listitem><para><filename>packages-split/</filename>:

1027

Contains subdirectories for each package produced by the

1028

recipe.

1029

For more information, see the

1030

"<link linkend='sdk-packaging'>Packaging</link>" section.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Setting Configure Arguments</title>

1038

1039

<para>

1040

If the software your recipe is building uses GNU autoconf,

1041

then a fixed set of arguments is passed to it to enable

1042

cross-compilation plus any extras specified by

1043

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

1044

set within the recipe.

1045

If you wish to pass additional options, add them to

1046

<filename>EXTRA_OECONF</filename>.

1047

Other supported build tools have similar variables

1048

(e.g.

1049

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

1050

for CMake,

1051

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

1052

for Scons, and so forth).

1053

If you need to pass anything on the <filename>make</filename>

1054

command line, you can use <filename>EXTRA_OEMAKE</filename> to do

so.

</para>

<para>

You can use the <filename>devtool configure-help</filename> command

1060

to help you set the arguments listed in the previous paragraph.

1061

The command determines the exact options being passed, and shows

1062

them to you along with any custom arguments specified through

1063

<filename>EXTRA_OECONF</filename>.

1064

If applicable, the command also shows you the output of the

1065

configure script's "&dash;&dash;help" option as a reference.

</para>

</section>

<title>Sharing Files Between Recipes</title>

1071

1072

<para>

1073

Recipes often need to use files provided by other recipes on

1074

the build host.

1075

For example, an application linking to a common library needs

1076

access to the library itself and its associated headers.

1077

The way this access is accomplished within the extensible SDK is

1078

through the sysroot.

1079

One sysroot exists per "machine" for which the SDK is being built.

1080

In practical terms, this means a sysroot exists for the target

1081

machine, and a sysroot exists for the build host.

</para>

<para>

Recipes should never write files directly into the sysroot.

1086

Instead, files should be installed into standard locations

1087

during the

1088

<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>

task within the

directory.

A subset of these files automatically go into the sysroot.

1093

The reason for this limitation is that almost all files that go

1094

into the sysroot are cataloged in manifests in order to ensure

1095

they can be removed later when a recipe is modified or removed.

1096

Thus, the sysroot is able to remain free from stale files.

</para>

</section>

<title>Packaging</title>

1102

1103

<para>

1104

Packaging is not always particularly relevant within the

1105

extensible SDK.

1106

However, if you examine how build output gets into the final image

1107

on the target device, it is important to understand packaging

1108

because the contents of the image are expressed in terms of

1109

packages and not recipes.

</para>

<para>

During the

<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>

1115

task, files installed during the

1116

<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>

1117

task are split into one main package, which is almost always named

1118

the same as the recipe, and several other packages.

1119

This separation is done because not all of those installed files

1120

are always useful in every image.

1121

For example, you probably do not need any of the documentation

1122

installed in a production image.

1123

Consequently, for each recipe the documentation files are separated

1124

into a <filename>-doc</filename> package.

1125

Recipes that package software that has optional modules or

1126

plugins might do additional package splitting as well.

</para>

<para>

After building a recipe you can see where files have gone by

1131

looking in the <filename>oe-workdir/packages-split</filename>

1132

directory, which contains a subdirectory for each package.

1133

Apart from some advanced cases, the

1134

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

1135

and

1136

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

1137

variables controls splitting.

1138

The <filename>PACKAGES</filename> variable lists all of the

1139

packages to be produced, while the <filename>FILES</filename>

1140

variable specifies which files to include in each package,

1141

using an override to specify the package.

1142

For example, <filename>FILES_${PN}</filename> specifies the files

1143

to go into the main package (i.e. the main package is named the

1144

same as the recipe and

1145

1146

evaluates to the recipe name).

1147

The order of the <filename>PACKAGES</filename> value is significant.

1148

For each installed file, the first package whose

1149

<filename>FILES</filename> value matches the file is the package

1150

into which the file goes.

1151

Defaults exist for both the <filename>PACKAGES</filename> and

1152

<filename>FILES</filename> variables.

1153

Consequently, you might find you do not even need to set these

1154

variables in your recipe unless the software the recipe is

1155

building installs files into non-standard locations.

</para>

</section>

</section>

<title>Restoring the Target Device to its Original State</title>

1162

1163

<para>

1164

If you use the <filename>devtool deploy-target</filename>

1165

command to write a recipe's build output to the target, and

1166

you are working on an existing component of the system, then you

1167

might find yourself in a situation where you need to restore the

1168

original files that existed prior to running the

1169

<filename>devtool deploy-target</filename> command.

1170

Because the <filename>devtool deploy-target</filename> command

1171

backs up any files it overwrites, you can use the

1172

<filename>devtool undeploy-target</filename> to restore those files

1173

and remove any other files the recipe deployed.

1174

Consider the following example:

1175

1176

$ devtool undeploy-target lighttpd root@192.168.7.2

1177

</literallayout>

1178

If you have deployed multiple applications, you can remove them

1179

all at once thus restoring the target device back to its

1180

original state:

1181

1182

$ devtool undeploy-target -a root@192.168.7.2

1183

</literallayout>

1184

Information about files deployed to the target as well as any

1185

backed up files are stored on the target itself.

1186

This storage of course requires some additional space

1187

on the target machine.

1188

<note>

1189

The <filename>devtool deploy-target</filename> and

1190

<filename>devtool undeploy-target</filename> command do not

1191

currently interact with any package management system on the

1192

target device (e.g. RPM or OPKG).

1193

Consequently, you should not intermingle operations

1194

<filename>devtool deploy-target</filename> and the package

1195

manager operations on the target device.

1196

Doing so could result in a conflicting set of files.

</note>

</para>

</section>

<title>Installing Additional Items Into the Extensible SDK</title>

1203

1204

<para>

1205

The extensible SDK typically only comes with a small number of tools

1206

and libraries out of the box.

1207

If you have a minimal SDK, then it starts mostly empty and is

1208

populated on-demand.

1209

However, sometimes you will need to explicitly install extra items

1210

into the SDK.

1211

If you need these extra items, you can first search for the items

1212

using the <filename>devtool search</filename> command.

1213

For example, suppose you need to link to libGL but you are not sure

1214

which recipe provides it.

1215

You can use the following command to find out:

1216

1217

$ devtool search libGL

1218

mesa A free implementation of the OpenGL API

1219

</literallayout>

1220

Once you know the recipe (i.e. <filename>mesa</filename> in this

1221

example), you can install it:

1222

1223

$ devtool sdk-install mesa

1224

</literallayout>

1225

By default, the <filename>devtool sdk-install</filename> assumes the

1226

item is available in pre-built form from your SDK provider.

1227

If the item is not available and it is acceptable to build the item

1228

from source, you can add the "-s" option as follows:

1229

1230

$ devtool sdk-install -s mesa

1231

</literallayout>

1232

It is important to remember that building the item from source takes

1233

significantly longer than installing the pre-built artifact.

1234

Also, if no recipe exists for the item you want to add to the SDK, you

1235

must instead add it using the <filename>devtool add</filename> command.

</para>

</section>

<title>Updating the Extensible SDK</title>

1241

1242

<para>

1243

If you are working with an extensible SDK that gets occasionally

1244

updated (e.g. typically when that SDK has been provided to you by

1245

another party), then you will need to manually pull down those

1246

updates to your installed SDK.

</para>

<para>

To update your installed SDK, run the following:

$ devtool sdk-update

</literallayout>

The previous command assumes your SDK provider has set the default

1255

update URL for you.

1256

If that URL has not been set, you need to specify it yourself as

1257

follows:

1258

1259

$ devtool sdk-update <replaceable>path_to_update_directory</replaceable>

1260

</literallayout>

1261

<note>

1262

The URL needs to point specifically to a published SDK and not an

1263

SDK installer that you would download and install.

</note>

</para>

</section>

<title>Creating a Derivative SDK With Additional Components</title>

1270

1271

<para>

1272

You might need to produce an SDK that contains your own custom

1273

libraries for sending to a third party (e.g., if you are a vendor with

1274

customers needing to build their own software for the target platform).

1275

If that is the case, then you can produce a derivative SDK based on

1276

the currently installed SDK fairly easily.

1277

Use these steps:

1278

1279

<listitem><para>If necessary, install an extensible SDK that

1280

you want to use as a base for your derivative SDK.

1281

</para></listitem>

1282

<listitem><para>Source the environment script for the SDK.

1283

</para></listitem>

1284

<listitem><para>Add the extra libraries or other components

1285

you want by using the <filename>devtool add</filename>

1286

command.

1287

</para></listitem>

1288

<listitem><para>Run the <filename>devtool build-sdk</filename>

command.

</para></listitem>

</orderedlist>

The above procedure takes the recipes added to the workspace and

1293

constructs a new SDK installer containing those recipes and the

1294

resulting binary artifacts.

1295

The recipes go into their own separate layer in the constructed

1296

derivative SDK, leaving the workspace clean and ready for users

1297

to add their own recipes.

</para>

</section>

</chapter>

<!--

vim: expandtab tw=80 ts=4

1304

-->