Blame - documentation/adt-manual/adt-prepare.xml - stefanberger/openbmc

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

85

of the Yocto Project Reference Manual.

86

</para>

87

88

89

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

90

91

<para>

92

The ADT Installer is contained in the ADT Installer tarball.

93

You can get the tarball using either of these methods:

94

95

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

96

You can download the tarball from

97

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

98

any directory.</para></listitem>

99

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

100

You can use

101

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

102

to generate the tarball inside an existing

103

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

104

</para>

105

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

106

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

107

environment setup script

108

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

109

or

110

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

111

located in the Source Directory before running the

112

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

113

tarball.</para>

114

<para>The following example commands establish

115

the

116

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

117

check out the current release branch, set up the

118

build environment while also creating the default

119

Build Directory, and run the

120

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

121

tarball

122

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

123

<note>

124

Before using BitBake to build the ADT tarball, be

125

sure to make sure your

126

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

127

configured.

128

See the

129

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

130

section in the Yocto Project Reference Manual for

131

general configuration information.

</note>

$ cd ~

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

136

$ cd poky

137

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

138

$ source &OE_INIT_FILE;

139

$ bitbake adt-installer

140

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

</itemizedlist>

</para>

</section>

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

147

148

<para>

149

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

150

You can unpack the tarball in any directory you wish.

151

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

152

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

153

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

154

155

$ cd ~

156

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

157

$ tar -xjf adt_installer.tar.bz2

158

</literallayout>

159

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

160

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

161

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

</para>

<para>

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

166

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

167

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.

172

For configuration values and restrictions, see the comments in

173

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

174

175

176

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

177

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

178

the installation is based.

179

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

180

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

181

directory structure follows the same layout as the reference directory

182

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

183

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

184

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

185

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

186

environments.</para></listitem>

187

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

188

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

189

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

190

or not to install user-mode NFS.

191

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

192

you should install NFS.

193

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

194

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

195

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

196

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

197

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

198

You might also have to modify your firewall settings to allow

199

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

200

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

201

filesystem images you want to download from the

202

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

203

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

204

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

205

The value of this variable must have been specified with

206

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

207

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

208

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

209

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

210

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

211

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

212

</para></listitem>

213

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

214

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,

221

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

227

location for cross-toolchain installation.

228

The default location is

229

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

230

After either accepting the default location or selecting your

231

own location, you are prompted to run the installation script

232

interactively or in silent mode.

233

If you want to closely monitor the installation,

234

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

235

Follow the prompts from the script to complete the installation.

</para>

<para>

Once the installation completes, the ADT, which includes the

240

cross-toolchain, is installed in the selected installation

241

directory.

242

You will notice environment setup files for the cross-toolchain

243

in the installation directory, and image tarballs in the

244

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

245

installer configurations, and the target sysroot located

246

according to the

247

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

248

variable also in your configuration file.

</para>

</section>

</section>

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

255

256

<para>

257

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

258

do so by running the toolchain installer.

259

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

260

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

261

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

262

might still need to install the target sysroot by installing and

263

extracting it separately.

264

For information on how to install the sysroot, see the

265

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

272

273

<listitem><para>Go to

274

275

and find the folder that matches your host

276

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

277

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

278

for 64-bit machines).</para>

279

<para>Go into that folder and download the toolchain

280

installer whose name includes the appropriate target

281

architecture.

282

The toolchains provided by the Yocto Project

283

are based off of the

284

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

285

contain libraries appropriate for developing

286

against that image.

287

For example, if your host development system is a

288

64-bit x86 system and you are going to use

289

your cross-toolchain for a 32-bit x86

290

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

291

folder and download the following installer:

292

293

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

294

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

295

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

296

For cases where you cannot use an installer

297

from the download area, you can build your own as

298

described in the

299

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

300

section.</para></listitem>

301

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

302

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

303

<note>

304

You must change the permissions on the toolchain

305

installer script so that it is executable.

306

</note></para>

307

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

308

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

309

system and a 32-bit x86 target architecture.

310

The example assumes the toolchain installer is located

311

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

312

313

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

314

</literallayout>

315

The first thing the installer prompts you for is the

316

directory into which you want to install the toolchain.

317

The default directory used is

318

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

319

If you do not have write permissions for the directory

320

into which you are installing the toolchain, the

321

toolchain installer notifies you and exits.

322

Be sure you have write permissions in the directory and

323

run the installer again.</para>

324

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

325

installed.

326

You will notice environment setup files for the

327

cross-toolchain in the installation directory.

</para></listitem>

</orderedlist>

</para>

</section>

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

335

336

<para>

337

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

338

to generate the toolchain within an existing

339

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

340

This method does not install the toolchain into the default

341

<filename>/opt</filename> directory.

342

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

343

do that separately as well.

</para>

<para>

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

348

349

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

350

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

355

located in the

356

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

357

</para></listitem>

358

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

359

At this point, you should be sure that the

360

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

361

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

362

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

363

is set for the target architecture.

364

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

365

list the values you can use for the

366

<filename>MACHINE</filename> variable.

367

<note>

368

You can populate the Build Directory with the

369

cross-toolchains for more than a single architecture.

370

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

371

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

372

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

373

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

374

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

375

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

376

complete the cross-toolchain generation.

377

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

378

the cross-toolchain is

379

generated and populated within the Build Directory.

380

You will notice environment setup files for the

381

cross-toolchain that contain the string

382

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

383

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

384

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

385

toolchain, you still need to separately extract and install

386

the sysroot filesystem.

387

For information on how to do this, see the

388

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

397

398

<para>

399

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

400

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

401

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

402

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

403

For this release, the default installation directory is

404

<filename>&YOCTO_ADTPATH_DIR;</filename>.

405

If you installed the toolchain in the

406

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

407

you can find the environment setup

408

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

413

architecture for which you are developing.

414

Environment setup scripts begin with the string

415

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

416

name the architecture.

417

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

418

IA-based architecture installed in the default installation directory

419

would be the following:

420

421

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

422

</literallayout>

423

When you run the setup script, many environment variables are

424

defined:

425

426

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

427

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

428

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

429

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

430

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

431

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

432

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

433

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

434

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

435

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

436

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

437

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

438

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

439

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

440

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

441

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

442

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

443

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

444

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

445

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

446

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

447

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

454

455

<para>

456

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

457

hardware or the QEMU emulator.

458

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

459

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

</para>

<title>Getting the Images</title>

464

465

<para>

466

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

467

pre-built versions.

468

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

469

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

470

section of the Yocto Project Quick Start.

471

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

472

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

478

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

479

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

480

that you can use unaltered in the QEMU emulator.

481

These kernel images reside in the release

482

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

483

and are ideal for experimentation using Yocto Project.

484

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

485

see the

486

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

487

chapter in the Yocto Project Reference Manual.

</para>

<para>

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

492

building or using one of the Yocto Project development images

493

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

494

include the development packages as part of your image recipe.

</para>

<para>

If you plan on remotely deploying and debugging your

499

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

500

that contains the Yocto Target Communication Framework (TCF) agent

501

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

502

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

507

section in the Yocto Project Reference Manual for information on

508

image features.

509

</note>

510

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

511

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

512

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

513

so that the

514

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

515

variable includes the "eclipse-debug" feature.

516

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

517

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

518

will be included in the image and is launched automatically after

the boot.

</para>

</section>

<title>Extracting the Root Filesystem</title>

525

526

<para>

527

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

528

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

529

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

530

filesystem is automatically extracted and installed.

</para>

<para>

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

535

536

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

537

</para></listitem>

538

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

539

target sysroot.

540

For example, the Eclipse IDE environment with the Eclipse

541

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

542

under NFS.</para></listitem>

543

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

544

using the root filesystem as the target sysroot.

</para></listitem>

</itemizedlist>

</para>

<para>

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

551

the cross-development environment setup script to establish

552

necessary environment variables.

553

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

554

the toolchain environment script in the

555

<filename>tmp</filename> directory.

556

If you installed the toolchain by hand, the environment setup

557

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

</para>

<para>

After sourcing the environment script, use the

562

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

filesystem image.

</para>

<para>

Following is an example.

568

The second command sets up the environment.

569

In this case, the setup script is located in the

570

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

571

The third command extracts the root filesystem from a previously

572

built filesystem that is located in the

573

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

574

Furthermore, this command extracts the root filesystem into the

575

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

576

577

$ cd ~

578

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

579

$ runqemu-extract-sdk \

580

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

581

$HOME/qemux86-sato

582

</literallayout>

583

You could now point to the target sysroot at

584

<filename>qemux86-sato</filename>.

</para>

</section>

</section>

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

591

592

<para>

593

As an alternative to locating and downloading a toolchain installer,

594

you can build the toolchain installer if you have a

595

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

596

<note>

597

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

598

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

599

installer.

600

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

601

the target sysroot.

602

For information on how to install the sysroot, see the

603

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

610

following command:

611

612

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

613

</literallayout>

614

The command results in a toolchain installer that contains the sysroot

615

that matches your target root filesystem.

</para>

<para>

Another powerful feature is that the toolchain is completely

620

self-contained.

621

The binaries are linked against their own copy of

622

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

623

on the target system.

624

To achieve this, the pointer to the dynamic loader is

625

configured at install time since that path cannot be dynamically

626

altered.

627

This is the reason for a wrapper around the

628

<filename>populate_sdk</filename> archive.

</para>

<para>

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

633

binaries are produced per architecture.

634

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

635

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

636

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

641

This reduces the space needed for the tools.

642

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

643

since those binaries are target-specific.

</para>

<para>

Remember, before using any BitBake command, you

648

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

653

located in the Source Directory and you must make sure your

654

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

655

In particular, you need to be sure the

656

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

657

variable matches the architecture for which you are building and that

658

the

659

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

660

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

661

run on an architecture that differs from your current development host

662

machine (i.e. the build machine).

</para>

<para>

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

667

installer will be in

668

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

669

<note>

670

By default, this toolchain does not build static binaries.

671

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

672

you need to be sure your image has the appropriate static

673

development libraries.

674

Use the

675

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

676

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

677

install the appropriate library packages.

678

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

679

development libraries:

680

681

IMAGE_INSTALL_append = " glibc-staticdev"

</literallayout>

</note>

</para>

</section>

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

689

690

<para>

691

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

692

development.

693

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

are as follows:

Understand where the installed toolchain resides.

698

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

699

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

704

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

705

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

711

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

712

to the location in which you installed the toolchain.

713

</para></listitem>

714

</itemizedlist>

715

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

716

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

717

Sourcery G++ Toolchain.

718

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

719

<filename>README</filename> file at

720

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

721

You can find further information by reading about the

722

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

723

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

</para>

</section>

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

729

730

<para>

731

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

732

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

733

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>

751

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

752

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

753

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

754

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

755

</para></listitem>

756

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

</para></listitem>

</itemizedlist>

<title>Installing the Toolchain</title>

762

763

<para>

764

You can download a tarball installer, which includes the

765

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

766

script, and support files from the appropriate directory under

767

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

768

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

769

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

770

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

771

The toolchains the Yocto Project provides are based off the

772

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

773

libraries appropriate for developing against that image.

774

Each type of development system supports five or more target

architectures.

</para>

<para>

The names of the tarball installer scripts are such that a

780

string representing the host system appears first in the

781

filename and then is immediately followed by a string

782

representing the target architecture.

</para>

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

787

788

Where:

789

<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

794

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

795

The Yocto Project builds toolchain installers using the

796

following BitBake command:

797

798

bitbake core-image-sato -c populate_sdk

799

800

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

801

802

i586, x86_64, powerpc, mips, armv7a or armv5te

803

804

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

805

Yocto Project:

806

807

&DISTRO;, &DISTRO;+snapshot

</literallayout>

<para>

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

812

development host system and a i586-tuned target architecture

813

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

814

815

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

</literallayout>

</para>

<para>

Toolchains are self-contained and by default are installed into

821

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

822

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

823

installation directory.

</para>

<para>

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

828

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

829

You must change the permissions on the toolchain

830

installer script so that it is executable.

</para>

<para>

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

835

<note>

836

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

837

the toolchain, the toolchain installer notifies you and exits.

838

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

850

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

851

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

857

858

<para>

859

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

860

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

861

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

862

Download areas exist for the five supported machine architectures:

863

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

864

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

</para>

<para>

Most kernel files have one of the following forms:

869

870

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

871

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

872

873

Where:

874

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

875

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

</literallayout>

</para>

<para>

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

881

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

882

bulleted item in the Yocto Project Development Manual.

</para>

</section>

<title>Downloading the Filesystem</title>

888

889

<para>

890

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

891

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

892

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

898

<filename>tar</filename>.

899

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

900

QEMU emulator.

901

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

902

and used for build purposes with the Yocto Project.

903

904

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

905

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

906

907

Where:

908

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

909

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

910

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

911

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

912

chapter in the Yocto Project Reference Manual.

913

914

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

915

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

</literallayout>

</para>

</section>

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

922

923

<para>

924

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

925

The following command form sets up the emulation environment.

926

927

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

928

929

Where:

930

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

931

i586, x86_64, ppc603e, mips, or armv5te.

932

933

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

934

Not all setup scripts include this string.

</literallayout>

</para>

<para>

Finally, this command form invokes the QEMU emulator

940

941

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

942

943

Where:

944

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

945

qemuppc, qemumips, or qemuarm.

946

947

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

948

949

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

</literallayout>

</para>

<para>

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

956

environment and launch QEMU.

957

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

958

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

959

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

960

961

$ cd $HOME

962

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

963

$ runqemu qemux86 bzImage-qemux86.bin \

964

core-image-sato-qemux86.ext3

</literallayout>

</para>

<para>

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

970

target architecture.

971

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

972

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

973

shell in command-line mode.

974

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

975

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

976

command-line mode.</note>

</para>

</section>

</section>

</chapter>

<!--

vim: expandtab tw=80 ts=4

984

-->