Blame - poky/documentation/adt-manual/adt-prepare.xml - mdmillerii/openbmc

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

86

of the Yocto Project Reference Manual.

87

</para>

88

89

90

<title>Getting the ADT Installer Tarball</title>

91

92

<para>

93

The ADT Installer is contained in the ADT Installer tarball.

94

You can get the tarball using either of these methods:

95

96

<listitem><para><emphasis>Download the Tarball:</emphasis>

97

You can download the tarball from

98

<ulink url='&YOCTO_ADTINSTALLER_DL_URL;'></ulink> into

99

any directory.</para></listitem>

100

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

101

You can use

102

<ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>

103

to generate the tarball inside an existing

104

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

105

</para>

106

<para>If you use BitBake to generate the ADT Installer

107

tarball, you must <filename>source</filename> the

108

environment setup script

109

(<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>

110

or

111

<ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)

112

located in the Source Directory before running the

113

<filename>bitbake</filename> command that creates the

114

tarball.</para>

115

<para>The following example commands establish

116

the

117

<ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,

118

check out the current release branch, set up the

119

build environment while also creating the default

120

Build Directory, and run the

121

<filename>bitbake</filename> command that results in the

122

tarball

123

<filename>poky/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>:

124

<note>

125

Before using BitBake to build the ADT tarball, be

126

sure to make sure your

127

<filename>local.conf</filename> file is properly

128

configured.

129

See the

130

"<ulink url='&YOCTO_DOCS_REF_URL;#user-configuration'>User Configuration</ulink>"

131

section in the Yocto Project Reference Manual for

132

general configuration information.

</note>

$ cd ~

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

137

$ cd poky

138

$ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;

139

$ source &OE_INIT_FILE;

140

$ bitbake adt-installer

141

</literallayout></para></listitem>

</itemizedlist>

</para>

</section>

<title>Configuring and Running the ADT Installer Script</title>

148

149

<para>

150

Before running the ADT Installer script, you need to unpack the tarball.

151

You can unpack the tarball in any directory you wish.

152

For example, this command copies the ADT Installer tarball from where

153

it was built into the home directory and then unpacks the tarball into

154

a top-level directory named <filename>adt-installer</filename>:

155

156

$ cd ~

157

$ cp poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME

158

$ tar -xjf adt_installer.tar.bz2

159

</literallayout>

160

Unpacking it creates the directory <filename>adt-installer</filename>,

161

which contains the ADT Installer script (<filename>adt_installer</filename>)

162

and its configuration file (<filename>adt_installer.conf</filename>).

</para>

<para>

Before you run the script, however, you should examine the ADT Installer configuration

167

file and be sure you are going to get what you want.

168

Your configurations determine which kernel and filesystem image are downloaded.

</para>

<para>

The following list describes the configurations you can define for the ADT Installer.

173

For configuration values and restrictions, see the comments in

174

the <filename>adt-installer.conf</filename> file:

175

176

177

<listitem><para><filename>YOCTOADT_REPO</filename>: This area

178

includes the IPKG-based packages and the root filesystem upon which

179

the installation is based.

180

If you want to set up your own IPKG repository pointed to by

181

<filename>YOCTOADT_REPO</filename>, you need to be sure that the

182

directory structure follows the same layout as the reference directory

183

set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.

184

Also, your repository needs to be accessible through HTTP.</para></listitem>

185

<listitem><para><filename>YOCTOADT_TARGETS</filename>: The machine

186

target architectures for which you want to set up cross-development

187

environments.</para></listitem>

188

<listitem><para><filename>YOCTOADT_QEMU</filename>: Indicates whether

189

or not to install the emulator QEMU.</para></listitem>

190

<listitem><para><filename>YOCTOADT_NFS_UTIL</filename>: Indicates whether

191

or not to install user-mode NFS.

192

If you plan to use the Eclipse IDE Yocto plug-in against QEMU,

193

you should install NFS.

194

<note>To boot QEMU images using our userspace NFS server, you need

195

to be running <filename>portmap</filename> or <filename>rpcbind</filename>.

196

If you are running <filename>rpcbind</filename>, you will also need to add the

197

<filename>-i</filename> option when <filename>rpcbind</filename> starts up.

198

Please make sure you understand the security implications of doing this.

199

You might also have to modify your firewall settings to allow

200

NFS booting to work.</note></para></listitem>

201

<listitem><para><filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>: The root

202

filesystem images you want to download from the

203

<filename>YOCTOADT_IPKG_REPO</filename> repository.</para></listitem>

204

<listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_</filename><replaceable>arch</replaceable>: The

205

particular root filesystem used to extract and create the target sysroot.

206

The value of this variable must have been specified with

207

<filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>.

208

For example, if you downloaded both <filename>minimal</filename> and

209

<filename>sato-sdk</filename> images by setting

210

<filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>

211

to "minimal sato-sdk", then <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>

212

must be set to either "minimal" or "sato-sdk".

213

</para></listitem>

214

<listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable>: The

215

location on the development host where the target sysroot is created.

</para></listitem>

</itemizedlist>

</para>

<para>

After you have configured the <filename>adt_installer.conf</filename> file,

222

run the installer using the following command:

$ cd adt-installer

$ ./adt_installer

</literallayout>

Once the installer begins to run, you are asked to enter the

228

location for cross-toolchain installation.

229

The default location is

230

<filename>/opt/poky/</filename><replaceable>release</replaceable>.

231

After either accepting the default location or selecting your

232

own location, you are prompted to run the installation script

233

interactively or in silent mode.

234

If you want to closely monitor the installation,

235

choose “I” for interactive mode rather than “S” for silent mode.

236

Follow the prompts from the script to complete the installation.

</para>

<para>

Once the installation completes, the ADT, which includes the

241

cross-toolchain, is installed in the selected installation

242

directory.

243

You will notice environment setup files for the cross-toolchain

244

in the installation directory, and image tarballs in the

245

<filename>adt-installer</filename> directory according to your

246

installer configurations, and the target sysroot located

247

according to the

248

<filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable>

249

variable also in your configuration file.

</para>

</section>

</section>

<title>Using a Cross-Toolchain Tarball</title>

256

257

<para>

258

If you want to simply install a cross-toolchain by hand, you can

259

do so by running the toolchain installer.

260

The installer includes the pre-built cross-toolchain, the

261

<filename>runqemu</filename> script, and support files.

262

If you use this method to install the cross-toolchain, you

263

might still need to install the target sysroot by installing and

264

extracting it separately.

265

For information on how to install the sysroot, see the

266

"<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.

</para>

<para>

Follow these steps:

<listitem><para><emphasis>Get your toolchain installer using one of the following methods:</emphasis>

273

274

<listitem><para>Go to

275

276

and find the folder that matches your host

277

development system (i.e. <filename>i686</filename>

278

for 32-bit machines or <filename>x86_64</filename>

279

for 64-bit machines).</para>

280

<para>Go into that folder and download the toolchain

281

installer whose name includes the appropriate target

282

architecture.

283

The toolchains provided by the Yocto Project

284

are based off of the

285

<filename>core-image-sato</filename> image and

286

contain libraries appropriate for developing

287

against that image.

288

For example, if your host development system is a

289

64-bit x86 system and you are going to use

290

your cross-toolchain for a 32-bit x86

291

target, go into the <filename>x86_64</filename>

292

folder and download the following installer:

293

294

poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh

295

</literallayout></para></listitem>

296

<listitem><para>Build your own toolchain installer.

297

For cases where you cannot use an installer

298

from the download area, you can build your own as

299

described in the

300

"<link linkend='optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>"

301

section.</para></listitem>

302

</itemizedlist></para></listitem>

303

<listitem><para><emphasis>Once you have the installer, run it to install the toolchain:</emphasis>

304

<note>

305

You must change the permissions on the toolchain

306

installer script so that it is executable.

307

</note></para>

308

<para>The following command shows how to run the installer

309

given a toolchain tarball for a 64-bit x86 development host

310

system and a 32-bit x86 target architecture.

311

The example assumes the toolchain installer is located

312

in <filename>~/Downloads/</filename>.

313

314

$ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh

315

</literallayout>

316

The first thing the installer prompts you for is the

317

directory into which you want to install the toolchain.

318

The default directory used is

319

<filename>/opt/poky/&DISTRO;</filename>.

320

If you do not have write permissions for the directory

321

into which you are installing the toolchain, the

322

toolchain installer notifies you and exits.

323

Be sure you have write permissions in the directory and

324

run the installer again.</para>

325

<para>When the script finishes, the cross-toolchain is

326

installed.

327

You will notice environment setup files for the

328

cross-toolchain in the installation directory.

</para></listitem>

</orderedlist>

</para>

</section>

<title>Using BitBake and the Build Directory</title>

336

337

<para>

338

A final way of making the cross-toolchain available is to use BitBake

339

to generate the toolchain within an existing

340

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

341

This method does not install the toolchain into the default

342

<filename>/opt</filename> directory.

343

As with the previous method, if you need to install the target sysroot, you must

344

do that separately as well.

</para>

<para>

Follow these steps to generate the toolchain into the Build Directory:

349

350

<listitem><para><emphasis>Set up the Build Environment:</emphasis>

351

Source the OpenEmbedded build environment setup

script (i.e.

or

<ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)

356

located in the

357

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

358

</para></listitem>

359

<listitem><para><emphasis>Check your Local Configuration File:</emphasis>

360

At this point, you should be sure that the

361

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

362

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

363

<filename>conf</filename> directory of the Build Directory

364

is set for the target architecture.

365

Comments within the <filename>local.conf</filename> file

366

list the values you can use for the

367

<filename>MACHINE</filename> variable.

Patrick Williams

f1e5d69

2016-03-30 15:21:19 -0500

[diff] [blame]

368

If you do not change the <filename>MACHINE</filename>

369

variable, the OpenEmbedded build system uses

370

<filename>qemux86</filename> as the default target

371

machine when building the cross-toolchain.

Patrick Williams

c124f4f

2015-09-15 14:41:29 -0500

[diff] [blame]

372

<note>

373

You can populate the Build Directory with the

374

cross-toolchains for more than a single architecture.

375

You just need to edit the <filename>MACHINE</filename>

376

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

377

re-run the <filename>bitbake</filename> command.

378

</note></para></listitem>

Patrick Williams

f1e5d69

2016-03-30 15:21:19 -0500

[diff] [blame]

379

<listitem><para><emphasis>Make Sure Your Layers are Enabled:</emphasis>

380

Examine the <filename>conf/bblayers.conf</filename> file

381

and make sure that you have enabled all the compatible

382

layers for your target machine.

383

The OpenEmbedded build system needs to be aware of each

384

layer you want included when building images and

385

cross-toolchains.

386

For information on how to enable a layer, see the

387

"<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"

388

section in the Yocto Project Development Manual.

389

</para></listitem>

Patrick Williams

c124f4f

2015-09-15 14:41:29 -0500

[diff] [blame]

390

<listitem><para><emphasis>Generate the Cross-Toolchain:</emphasis>

391

Run <filename>bitbake meta-ide-support</filename> to

392

complete the cross-toolchain generation.

393

Once the <filename>bitbake</filename> command finishes,

394

the cross-toolchain is

395

generated and populated within the Build Directory.

396

You will notice environment setup files for the

397

cross-toolchain that contain the string

398

"<filename>environment-setup</filename>" in the

399

Build Directory's <filename>tmp</filename> folder.</para>

400

<para>Be aware that when you use this method to install the

401

toolchain, you still need to separately extract and install

402

the sysroot filesystem.

403

For information on how to do this, see the

404

"<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.

</para></listitem>

</orderedlist>

</para>

</section>

</section>

<title>Setting Up the Cross-Development Environment</title>

413

414

<para>

415

Before you can develop using the cross-toolchain, you need to set up the

416

cross-development environment by sourcing the toolchain's environment setup script.

417

If you used the ADT Installer or hand-installed cross-toolchain,

418

then you can find this script in the directory you chose for installation.

419

For this release, the default installation directory is

420

<filename>&YOCTO_ADTPATH_DIR;</filename>.

421

If you installed the toolchain in the

422

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

423

you can find the environment setup

424

script for the toolchain in the Build Directory's <filename>tmp</filename> directory.

</para>

<para>

Be sure to run the environment setup script that matches the

429

architecture for which you are developing.

430

Environment setup scripts begin with the string

431

"<filename>environment-setup</filename>" and include as part of their

432

name the architecture.

433

For example, the toolchain environment setup script for a 64-bit

434

IA-based architecture installed in the default installation directory

435

would be the following:

436

437

&YOCTO_ADTPATH_DIR;/environment-setup-x86_64-poky-linux

438

</literallayout>

439

When you run the setup script, many environment variables are

440

defined:

441

442

<ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation

443

<ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files

444

<ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target

445

<ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler

446

<ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler

447

<ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor

448

<ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler

449

<ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker

450

<ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger

451

<ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols

452

<ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib'

453

<ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy'

454

<ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump'

455

<ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar'

456

<ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm'

457

<ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools

458

<ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools

459

<ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure

460

<ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags

461

<ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags

462

<ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link

463

<ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags

</literallayout>

</para>

</section>

<title>Securing Kernel and Filesystem Images</title>

470

471

<para>

472

You will need to have a kernel and filesystem image to boot using your

473

hardware or the QEMU emulator.

474

Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem

475

as the target sysroot, you need to extract the root filesystem.

</para>

<title>Getting the Images</title>

480

481

<para>

482

To get the kernel and filesystem images, you either have to build them or download

483

pre-built versions.

484

For an example of how to build these images, see the

485

"<ulink url='&YOCTO_DOCS_QS_URL;#qs-buiding-images'>Buiding Images</ulink>"

486

section of the Yocto Project Quick Start.

487

For an example of downloading pre-build versions, see the

488

"<link linkend='using-pre-built'>Example Using Pre-Built Binaries and QEMU</link>"

section.

</para>

<para>

The Yocto Project ships basic kernel and filesystem images for several

494

architectures (<filename>x86</filename>, <filename>x86-64</filename>,

495

<filename>mips</filename>, <filename>powerpc</filename>, and <filename>arm</filename>)

496

that you can use unaltered in the QEMU emulator.

497

These kernel images reside in the release

498

area - <ulink url='&YOCTO_MACHINES_DL_URL;'></ulink>

499

and are ideal for experimentation using Yocto Project.

500

For information on the image types you can build using the OpenEmbedded build system,

501

see the

502

"<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"

503

chapter in the Yocto Project Reference Manual.

</para>

<para>

If you are planning on developing against your image and you are not

508

building or using one of the Yocto Project development images

509

(e.g. <filename>core-image-*-dev</filename>), you must be sure to

510

include the development packages as part of your image recipe.

</para>

<para>

If you plan on remotely deploying and debugging your

515

application from within the Eclipse IDE, you must have an image

516

that contains the Yocto Target Communication Framework (TCF) agent

517

(<filename>tcf-agent</filename>).

518

You can do this by including the <filename>eclipse-debug</filename>

image feature.

<note>

See the

"<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>"

523

section in the Yocto Project Reference Manual for information on

524

image features.

525

</note>

526

To include the <filename>eclipse-debug</filename> image feature,

527

modify your <filename>local.conf</filename> file in the

528

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

529

so that the

530

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

531

variable includes the "eclipse-debug" feature.

532

After modifying the configuration file, you can rebuild the image.

533

Once the image is rebuilt, the <filename>tcf-agent</filename>

534

will be included in the image and is launched automatically after

the boot.

</para>

</section>

<title>Extracting the Root Filesystem</title>

541

542

<para>

543

If you install your toolchain by hand or build it using BitBake and

544

you need a root filesystem, you need to extract it separately.

545

If you use the ADT Installer to install the ADT, the root

546

filesystem is automatically extracted and installed.

</para>

<para>

Here are some cases where you need to extract the root filesystem:

551

552

<listitem><para>You want to boot the image using NFS.

553

</para></listitem>

554

<listitem><para>You want to use the root filesystem as the

555

target sysroot.

556

For example, the Eclipse IDE environment with the Eclipse

557

Yocto Plug-in installed allows you to use QEMU to boot

558

under NFS.</para></listitem>

559

<listitem><para>You want to develop your target application

560

using the root filesystem as the target sysroot.

</para></listitem>

</itemizedlist>

</para>

<para>

To extract the root filesystem, first <filename>source</filename>

567

the cross-development environment setup script to establish

568

necessary environment variables.

569

If you built the toolchain in the Build Directory, you will find

570

the toolchain environment script in the

571

<filename>tmp</filename> directory.

572

If you installed the toolchain by hand, the environment setup

573

script is located in <filename>/opt/poky/&DISTRO;</filename>.

</para>

<para>

After sourcing the environment script, use the

578

<filename>runqemu-extract-sdk</filename> command and provide the

filesystem image.

</para>

<para>

Following is an example.

584

The second command sets up the environment.

585

In this case, the setup script is located in the

586

<filename>/opt/poky/&DISTRO;</filename> directory.

587

The third command extracts the root filesystem from a previously

588

built filesystem that is located in the

589

<filename>~/Downloads</filename> directory.

590

Furthermore, this command extracts the root filesystem into the

591

<filename>qemux86-sato</filename> directory:

592

593

$ cd ~

594

$ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux

595

$ runqemu-extract-sdk \

596

~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \

597

$HOME/qemux86-sato

598

</literallayout>

599

You could now point to the target sysroot at

600

<filename>qemux86-sato</filename>.

</para>

</section>

</section>

<title>Optionally Building a Toolchain Installer</title>

607

608

<para>

609

As an alternative to locating and downloading a toolchain installer,

610

you can build the toolchain installer if you have a

611

<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.

612

<note>

613

Although not the preferred method, it is also possible to use

614

<filename>bitbake meta-toolchain</filename> to build the toolchain

615

installer.

616

If you do use this method, you must separately install and extract

617

the target sysroot.

618

For information on how to install the sysroot, see the

619

"<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"

section.

</note>

</para>

<para>

To build the toolchain installer and populate the SDK image, use the

626

following command:

627

628

$ bitbake <replaceable>image</replaceable> -c populate_sdk

629

</literallayout>

630

The command results in a toolchain installer that contains the sysroot

631

that matches your target root filesystem.

</para>

<para>

Another powerful feature is that the toolchain is completely

636

self-contained.

637

The binaries are linked against their own copy of

638

<filename>libc</filename>, which results in no dependencies

639

on the target system.

640

To achieve this, the pointer to the dynamic loader is

641

configured at install time since that path cannot be dynamically

642

altered.

643

This is the reason for a wrapper around the

644

<filename>populate_sdk</filename> archive.

</para>

<para>

Another feature is that only one set of cross-canadian toolchain

649

binaries are produced per architecture.

650

This feature takes advantage of the fact that the target hardware can

651

be passed to <filename>gcc</filename> as a set of compiler options.

652

Those options are set up by the environment script and contained in

variables such as

and

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

657

This reduces the space needed for the tools.

658

Understand, however, that a sysroot is still needed for every target

659

since those binaries are target-specific.

</para>

<para>

Remember, before using any BitBake command, you

664

must source the build environment setup script

(i.e.

or

<ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)

669

located in the Source Directory and you must make sure your

670

<filename>conf/local.conf</filename> variables are correct.

671

In particular, you need to be sure the

672

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

673

variable matches the architecture for which you are building and that

674

the

675

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

676

variable is correctly set if you are building a toolchain designed to

677

run on an architecture that differs from your current development host

678

machine (i.e. the build machine).

</para>

<para>

When the <filename>bitbake</filename> command completes, the toolchain

683

installer will be in

684

<filename>tmp/deploy/sdk</filename> in the Build Directory.

685

<note>

686

By default, this toolchain does not build static binaries.

687

If you want to use the toolchain to build these types of libraries,

688

you need to be sure your image has the appropriate static

689

development libraries.

690

Use the

691

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

692

variable inside your <filename>local.conf</filename> file to

693

install the appropriate library packages.

694

Following is an example using <filename>glibc</filename> static

695

development libraries:

696

697

IMAGE_INSTALL_append = " glibc-staticdev"

</literallayout>

</note>

</para>

</section>

<title>Optionally Using an External Toolchain</title>

705

706

<para>

707

You might want to use an external toolchain as part of your

708

development.

709

If this is the case, the fundamental steps you need to accomplish

are as follows:

Understand where the installed toolchain resides.

714

For cases where you need to build the external toolchain, you

715

would need to take separate steps to build and install the

toolchain.

</para></listitem>

Make sure you add the layer that contains the toolchain to

720

your <filename>bblayers.conf</filename> file through the

721

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

variable.

</para></listitem>

Set the

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

727

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

728

to the location in which you installed the toolchain.

729

</para></listitem>

730

</itemizedlist>

731

A good example of an external toolchain used with the Yocto Project

732

is <trademark class='registered'>Mentor Graphics</trademark>

733

Sourcery G++ Toolchain.

734

You can see information on how to use that particular layer in the

735

<filename>README</filename> file at

736

<ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.

737

You can find further information by reading about the

738

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

739

variable in the Yocto Project Reference Manual's variable glossary.

</para>

</section>

<title>Example Using Pre-Built Binaries and QEMU</title>

745

746

<para>

747

If hardware, libraries and services are stable, you can get started by using a pre-built binary

748

of the filesystem image, kernel, and toolchain and run it using the QEMU emulator.

749

This scenario is useful for developing application software.

</para>

</imageobject>

<para>Using a Pre-Built Image</para>

</caption>

</mediaobject>

<para>

For this scenario, you need to do several things:

</para>

<listitem><para>Install the appropriate stand-alone toolchain tarball.</para></listitem>

767

<listitem><para>Download the pre-built image that will boot with QEMU.

768

You need to be sure to get the QEMU image that matches your target machine’s

769

architecture (e.g. x86, ARM, etc.).</para></listitem>

770

<listitem><para>Download the filesystem image for your target machine's architecture.

771

</para></listitem>

772

<listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator.

</para></listitem>

</itemizedlist>

<title>Installing the Toolchain</title>

778

779

<para>

780

You can download a tarball installer, which includes the

781

pre-built toolchain, the <filename>runqemu</filename>

782

script, and support files from the appropriate directory under

783

<ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.

784

Toolchains are available for 32-bit and 64-bit x86 development

785

systems from the <filename>i686</filename> and

786

<filename>x86_64</filename> directories, respectively.

787

The toolchains the Yocto Project provides are based off the

788

<filename>core-image-sato</filename> image and contain

789

libraries appropriate for developing against that image.

790

Each type of development system supports five or more target

architectures.

</para>

<para>

The names of the tarball installer scripts are such that a

796

string representing the host system appears first in the

797

filename and then is immediately followed by a string

798

representing the target architecture.

</para>

poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh

803

804

Where:

805

<replaceable>host_system</replaceable> is a string representing your development system:

i686 or x86_64.

<replaceable>image_type</replaceable> is a string representing the image you wish to

810

develop a Software Development Toolkit (SDK) for use against.

811

The Yocto Project builds toolchain installers using the

812

following BitBake command:

813

814

bitbake core-image-sato -c populate_sdk

815

816

<replaceable>arch</replaceable> is a string representing the tuned target architecture:

817

818

i586, x86_64, powerpc, mips, armv7a or armv5te

819

820

<replaceable>release_version</replaceable> is a string representing the release number of the

821

Yocto Project:

822

823

&DISTRO;, &DISTRO;+snapshot

</literallayout>

<para>

For example, the following toolchain installer is for a 64-bit

828

development host system and a i586-tuned target architecture

829

based off the SDK for <filename>core-image-sato</filename>:

830

831

poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh

</literallayout>

</para>

<para>

Toolchains are self-contained and by default are installed into

837

<filename>/opt/poky</filename>.

838

However, when you run the toolchain installer, you can choose an

839

installation directory.

</para>

<para>

The following command shows how to run the installer given a toolchain tarball

844

for a 64-bit x86 development host system and a 32-bit x86 target architecture.

845

You must change the permissions on the toolchain

846

installer script so that it is executable.

</para>

<para>

The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>.

851

<note>

852

If you do not have write permissions for the directory into which you are installing

853

the toolchain, the toolchain installer notifies you and exits.

854

Be sure you have write permissions in the directory and run the installer again.

</note>

</para>

<para>

$ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh

</literallayout>

</para>

<para>

For more information on how to install tarballs, see the

866

"<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and

867

"<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" sections in the Yocto Project Application Developer's Guide.

</para>

</section>

<title>Downloading the Pre-Built Linux Kernel</title>

873

874

<para>

875

You can download the pre-built Linux kernel suitable for running in the QEMU emulator from

876

<ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.

877

Be sure to use the kernel that matches the architecture you want to simulate.

878

Download areas exist for the five supported machine architectures:

879

<filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>,

880

<filename>qemux86</filename>, and <filename>qemux86-64</filename>.

</para>

<para>

Most kernel files have one of the following forms:

885

886

*zImage-qemu<replaceable>arch</replaceable>.bin

887

vmlinux-qemu<replaceable>arch</replaceable>.bin

888

889

Where:

890

<replaceable>arch</replaceable> is a string representing the target architecture:

891

x86, x86-64, ppc, mips, or arm.

</literallayout>

</para>

<para>

You can learn more about downloading a Yocto Project kernel in the

897

"<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>"

898

bulleted item in the Yocto Project Development Manual.

</para>

</section>

<title>Downloading the Filesystem</title>

904

905

<para>

906

You can also download the filesystem image suitable for your target architecture from

907

<ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.

908

Again, be sure to use the filesystem that matches the architecture you want

to simulate.

</para>

<para>

The filesystem image has two tarball forms: <filename>ext3</filename> and

914

<filename>tar</filename>.

915

You must use the <filename>ext3</filename> form when booting an image using the

916

QEMU emulator.

917

The <filename>tar</filename> form can be flattened out in your host development system

918

and used for build purposes with the Yocto Project.

919

920

core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.ext3

921

core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.tar.bz2

922

923

Where:

924

<replaceable>profile</replaceable> is the filesystem image's profile:

925

lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato,

926

sato-dev, or sato-sdk. For information on these types of image

927

profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"

928

chapter in the Yocto Project Reference Manual.

929

930

<replaceable>arch</replaceable> is a string representing the target architecture:

931

x86, x86-64, ppc, mips, or arm.

</literallayout>

</para>

</section>

<title>Setting Up the Environment and Starting the QEMU Emulator</title>

938

939

<para>

940

Before you start the QEMU emulator, you need to set up the emulation environment.

941

The following command form sets up the emulation environment.

942

943

$ source &YOCTO_ADTPATH_DIR;/environment-setup-<replaceable>arch</replaceable>-poky-linux-<replaceable>if</replaceable>

944

945

Where:

946

<replaceable>arch</replaceable> is a string representing the target architecture:

947

i586, x86_64, ppc603e, mips, or armv5te.

948

949

<replaceable>if</replaceable> is a string representing an embedded application binary interface.

950

Not all setup scripts include this string.

</literallayout>

</para>

<para>

Finally, this command form invokes the QEMU emulator

956

957

$ runqemu <replaceable>qemuarch</replaceable> <replaceable>kernel-image</replaceable> <replaceable>filesystem-image</replaceable>

958

959

Where:

960

<replaceable>qemuarch</replaceable> is a string representing the target architecture: qemux86, qemux86-64,

961

qemuppc, qemumips, or qemuarm.

962

963

<replaceable>kernel-image</replaceable> is the architecture-specific kernel image.

964

965

<replaceable>filesystem-image</replaceable> is the .ext3 filesystem image.

</literallayout>

</para>

<para>

Continuing with the example, the following two commands setup the emulation

972

environment and launch QEMU.

973

This example assumes the root filesystem (<filename>.ext3</filename> file) and

974

the pre-built kernel image file both reside in your home directory.

975

The kernel and filesystem are for a 32-bit target architecture.

976

977

$ cd $HOME

978

$ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux

979

$ runqemu qemux86 bzImage-qemux86.bin \

980

core-image-sato-qemux86.ext3

</literallayout>

</para>

<para>

The environment in which QEMU launches varies depending on the filesystem image and on the

986

target architecture.

987

For example, if you source the environment for the ARM target

988

architecture and then boot the minimal QEMU image, the emulator comes up in a new

989

shell in command-line mode.

990

However, if you boot the SDK image, QEMU comes up with a GUI.

991

<note>Booting the PPC image results in QEMU launching in the same shell in

992

command-line mode.</note>

</para>

</section>

</section>

</chapter>

<!--

vim: expandtab tw=80 ts=4

1000

-->