Blame - poky/documentation/sdk-manual/sdk-appendix-neon.xml - stefanberger/openbmc

<filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename>

262

is in the current directory.

263

</para></listitem>

264

<listitem><para>If necessary, start the Eclipse IDE

265

and be sure you are in the Workbench.

266

</para></listitem>

267

<listitem><para>Select "Install New Software" from

268

the "Help" pull-down menu.

269

</para></listitem>

270

<listitem><para>Click "Add".

271

</para></listitem>

272

<listitem><para>Provide anything you want in the

273

"Name" field.

274

</para></listitem>

275

<listitem><para>Click "Archive" and browse to the

276

ZIP file you built earlier.

277

This ZIP file should not be "unzipped", and must

278

be the <filename>*archive.zip</filename> file

279

created by running the

280

<filename>build.sh</filename> script.

281

</para></listitem>

282

<listitem><para>Click the "OK" button.

283

</para></listitem>

284

<listitem><para>Check the boxes that appear in

285

the installation window to install the

286

following:

287

288

Yocto Project SDK Plug-in

289

Yocto Project Documentation plug-in

290

</literallayout>

291

</para></listitem>

292

<listitem><para>Finish the installation by clicking

293

through the appropriate buttons.

294

You can click "OK" when prompted about

295

installing software that contains unsigned

296

content.

297

</para></listitem>

298

<listitem><para>Restart the Eclipse IDE if

necessary.

</para></listitem>

</orderedlist>

</para>

<para>

At this point you should be able to configure the

306

Eclipse Yocto Plug-in as described in the

307

"<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>"

section.</para>

</section>

</section>

<title>Configuring the Neon Eclipse Yocto Plug-in</title>

314

315

<para>

316

Configuring the Neon Eclipse Yocto Plug-in involves setting the

317

Cross Compiler options and the Target options.

318

The configurations you choose become the default settings

319

for all projects.

320

You do have opportunities to change them later when

321

you configure the project (see the following section).

</para>

<para>

To start, you need to do the following from within the

326

Eclipse IDE:

327

328

<listitem><para>Choose "Preferences" from the

329

"Window" menu to display the Preferences Dialog.

330

</para></listitem>

331

<listitem><para>Click "Yocto Project SDK" to display

332

the configuration screen.

333

</para></listitem>

334

</itemizedlist>

335

The following sub-sections describe how to configure the

336

the plug-in.

337

<note>

338

Throughout the descriptions, a start-to-finish example for

339

preparing a QEMU image for use with Eclipse is referenced

340

as the "wiki" and is linked to the example on the

341

<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink>

wiki page.

</note>

</para>

<title>Configuring the Cross-Compiler Options</title>

348

349

<para>

350

Cross Compiler options enable Eclipse to use your specific

351

cross compiler toolchain.

352

To configure these options, you must select

353

the type of toolchain, point to the toolchain, specify

354

the sysroot location, and select the target

355

architecture.

356

357

<listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>

358

Choose between

359

<filename>Standalone pre-built toolchain</filename>

360

and

361

<filename>Build system derived toolchain</filename>

362

for Cross Compiler Options.

363

364

365

<filename>Standalone Pre-built Toolchain:</filename></emphasis>

366

Select this type when you are using

367

a stand-alone cross-toolchain.

368

For example, suppose you are an

369

application developer and do not

370

need to build a target image.

371

Instead, you just want to use an

372

architecture-specific toolchain on

373

an existing kernel and target root

374

filesystem.

375

In other words, you have downloaded

376

and installed a pre-built toolchain

377

for an existing image.

378

</para></listitem>

379

380

<filename>Build System Derived Toolchain:</filename></emphasis>

381

Select this type if you built the

382

toolchain as part of the

383

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

384

When you select

385

<filename>Build system derived toolchain</filename>,

386

you are using the toolchain built and

387

bundled inside the Build Directory.

388

For example, suppose you created a

389

suitable image using the steps in the

390

<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.

391

In this situation, you would select the

392

<filename>Build system derived toolchain</filename>.

</para></listitem>

</itemizedlist>

</para></listitem>

<listitem><para><emphasis>Specify the Toolchain Root Location:</emphasis>

397

If you are using a stand-alone pre-built

398

toolchain, you should be pointing to where it is

399

installed (e.g.

400

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

401

See the

402

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

403

section for information about how the SDK is

404

installed.</para>

405

<para>If you are using a build system derived

406

toolchain, the path you provide for the

407

<filename>Toolchain Root Location</filename>

408

field is the

409

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

410

from which you run the

411

<filename>bitbake</filename> command (e.g

412

<filename>/home/scottrif/poky/build</filename>).</para>

413

<para>For more information, see the

414

"<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"

415

section.

416

</para></listitem>

417

<listitem><para><emphasis>Specify Sysroot Location:</emphasis>

418

This location is where the root filesystem for

419

the target hardware resides.

420

</para>

421

<para>This location depends on where you

422

separately extracted and installed the

423

target filesystem when you either built

424

it or downloaded it.

425

<note>

426

If you downloaded the root filesystem

427

for the target hardware rather than

428

built it, you must download the

429

<filename>sato-sdk</filename> image

430

in order to build any c/c++ projects.

431

</note>

432

As an example, suppose you prepared an image

433

using the steps in the

434

<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.

435

If so, the <filename>MY_QEMU_ROOTFS</filename>

436

directory is found in the

437

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

438

and you would browse to and select that directory

439

(e.g. <filename>/home/scottrif/build/MY_QEMU_ROOTFS</filename>).

440

</para>

441

<para>For more information on how to install the

442

toolchain and on how to extract and install the

443

sysroot filesystem, see the

444

"<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>"

445

section.

446

</para></listitem>

447

<listitem><para><emphasis>Select the Target Architecture:</emphasis>

448

The target architecture is the type of hardware

449

you are going to use or emulate.

450

Use the pull-down

451

<filename>Target Architecture</filename> menu

452

to make your selection.

453

The pull-down menu should have the supported

454

architectures.

455

If the architecture you need is not listed in

456

the menu, you will need to build the image.

457

See the

458

"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-a-simple-image'>Building a Simple Image</ulink>"

459

section of the Yocto Project Development Tasks

460

Manual for more information.

461

You can also see the

462

<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.

</para></listitem>

</itemizedlist>

</para>

</section>

<title>Configuring the Target Options</title>

470

471

<para>

472

You can choose to emulate hardware using the QEMU

473

emulator, or you can choose to run your image on actual

hardware.

Select this option if you will be using the

478

QEMU emulator.

479

If you are using the emulator, you also need to

480

locate the kernel and specify any custom

481

options.</para>

482

<para>If you selected the

483

<filename>Build system derived toolchain</filename>,

484

the target kernel you built will be located in

485

the

486

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

487

in

488

<filename>tmp/deploy/images/<replaceable>machine</replaceable></filename>

489

directory.

490

As an example, suppose you performed the steps in

491

the

492

<ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>.

493

In this case, you specify your Build Directory path

494

followed by the image (e.g.

495

<filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>).

496

</para>

497

<para>If you selected the standalone pre-built

498

toolchain, the pre-built image you downloaded is

499

located in the directory you specified when you

500

downloaded the image.</para>

501

<para>Most custom options are for advanced QEMU

502

users to further customize their QEMU instance.

503

These options are specified between paired

504

angled brackets.

505

Some options must be specified outside the

506

brackets.

507

In particular, the options

508

<filename>serial</filename>,

509

<filename>nographic</filename>, and

510

<filename>kvm</filename> must all be outside the

511

brackets.

512

Use the <filename>man qemu</filename> command

513

to get help on all the options and their use.

514

The following is an example:

515

516

serial ‘<-m 256 -full-screen>’

517

</literallayout></para>

518

<para>

519

Regardless of the mode, Sysroot is already

520

defined as part of the Cross-Compiler Options

521

configuration in the

522

<filename>Sysroot Location:</filename> field.

523

</para></listitem>

524

<listitem><para><emphasis>External HW:</emphasis>

525

Select this option if you will be using actual

526

hardware.</para></listitem>

</itemizedlist>

</para>

<para>

Click the "Apply" and "OK" to save your plug-in

configurations.

</para>

</section>

</section>

</section>

<title>Creating the Project</title>

540

541

<para>

542

You can create two types of projects: Autotools-based, or

543

Makefile-based.

544

This section describes how to create Autotools-based projects

545

from within the Eclipse IDE.

546

For information on creating Makefile-based projects in a

547

terminal window, see the

548

"<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"

549

section.

550

<note>

551

Do not use special characters in project names

552

(e.g. spaces, underscores, etc.). Doing so can

553

cause the configuration to fail.

</note>

</para>

<para>

To create a project based on a Yocto template and then display

559

the source code, follow these steps:

560

561

<listitem><para>Select "C Project" from the "File -> New" menu.

562

</para></listitem>

563

<listitem><para>Expand <filename>Yocto Project SDK Autotools Project</filename>.

564

</para></listitem>

565

<listitem><para>Select <filename>Hello World ANSI C Autotools Projects</filename>.

566

This is an Autotools-based project based on a Yocto

567

template.

568

</para></listitem>

569

<listitem><para>Put a name in the <filename>Project name:</filename>

570

field.

571

Do not use hyphens as part of the name

572

(e.g. <filename>hello</filename>).

573

</para></listitem>

574

<listitem><para>Click "Next".

575

</para></listitem>

576

<listitem><para>Add appropriate information in the various

577

fields.

578

</para></listitem>

579

<listitem><para>Click "Finish".

580

</para></listitem>

581

<listitem><para>If the "open perspective" prompt appears,

582

click "Yes" so that you are in the C/C++ perspective.

583

</para></listitem>

584

<listitem><para>The left-hand navigation pane shows your

585

project.

586

You can display your source by double clicking the

587

project's source file.

</para></listitem>

</orderedlist>

</para>

</section>

<title>Configuring the Cross-Toolchains</title>

<para>

The earlier section,

"<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>",

599

sets up the default project configurations.

600

You can override these settings for a given project by following

601

these steps:

602

603

<listitem><para>Select "Yocto Project Settings" from

604

the "Project -> Properties" menu.

605

This selection brings up the Yocto Project Settings

606

Dialog and allows you to make changes specific to an

607

individual project.</para>

608

<para>By default, the Cross Compiler Options and Target

609

Options for a project are inherited from settings you

610

provided using the Preferences Dialog as described

611

earlier in the

612

"<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" section.

613

The Yocto Project Settings Dialog allows you to override

614

those default settings for a given project.

615

</para></listitem>

616

<listitem><para>Make or verify your configurations for the

617

project and click "OK".

618

</para></listitem>

619

<listitem><para>Right-click in the navigation pane and

620

select "Reconfigure Project" from the pop-up menu.

621

This selection reconfigures the project by running

622

<filename>autogen.sh</filename> in the workspace for

623

your project.

624

The script also runs <filename>libtoolize</filename>,

625

<filename>aclocal</filename>,

626

<filename>autoconf</filename>,

627

<filename>autoheader</filename>,

628

<filename>automake --a</filename>, and

629

<filename>./configure</filename>.

630

Click on the "Console" tab beneath your source code to

631

see the results of reconfiguring your project.

</para></listitem>

</orderedlist>

</para>

</section>

<title>Building the Project</title>

639

640

<para>

641

To build the project select "Build All" from the

642

"Project" menu.

643

The console should update and you can note the cross-compiler

644

you are using.

645

<note>

646

When building "Yocto Project SDK Autotools" projects, the

647

Eclipse IDE might display error messages for

648

Functions/Symbols/Types that cannot be "resolved", even when

649

the related include file is listed at the project navigator and

650

when the project is able to build.

651

For these cases only, it is recommended to add a new linked

652

folder to the appropriate sysroot.

653

Use these steps to add the linked folder:

Select the project.

</para></listitem>

Select "Folder" from the

660

<filename>File > New</filename> menu.

661

</para></listitem>

662

663

In the "New Folder" Dialog, select "Link to alternate

664

location (linked folder)".

665

</para></listitem>

666

667

Click "Browse" to navigate to the include folder inside

668

the same sysroot location selected in the Yocto Project

669

configuration preferences.

</para></listitem>

Click "OK".

</para></listitem>

Click "Finish" to save the linked folder.

</para></listitem>

</orderedlist>

</note>

</para>

</section>

<title>Starting QEMU in User-Space NFS Mode</title>

684

685

<para>

686

To start the QEMU emulator from within Eclipse, follow these

steps:

<note>

See the

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

691

chapter in the Yocto Project Development Tasks Manual

692

for more information on using QEMU.

693

</note>

694

695

<listitem><para>Expose and select "External Tools

696

Configurations ..." from the "Run -> External Tools" menu.

697

</para></listitem>

698

699

Locate and select your image in the navigation panel to

700

the left (e.g. <filename>qemu_i586-poky-linux</filename>).

701

</para></listitem>

702

703

Click "Run" to launch QEMU.

704

<note>

705

The host on which you are running QEMU must have

706

the <filename>rpcbind</filename> utility running to be

707

able to make RPC calls on a server on that machine.

708

If QEMU does not invoke and you receive error messages

709

involving <filename>rpcbind</filename>, follow the

710

suggestions to get the service running.

711

As an example, on a new Ubuntu 16.04 LTS installation,

712

you must do the following in order to get QEMU to

713

launch:

714

715

$ sudo apt-get install rpcbind

716

</literallayout>

717

After installing <filename>rpcbind</filename>, you

718

need to edit the

719

<filename>/etc/init.d/rpcbind</filename> file to

720

include the following line:

OPTIONS="-i -w"

</literallayout>

After modifying the file, you need to start the

725

service:

726

727

$ sudo service portmap restart

</literallayout>

</note>

</para></listitem>

<listitem><para>If needed, enter your host root password in

732

the shell window at the prompt.

733

This sets up a <filename>Tap 0</filename> connection

734

needed for running in user-space NFS mode.

735

</para></listitem>

736

<listitem><para>Wait for QEMU to launch.

737

</para></listitem>

738

<listitem><para>Once QEMU launches, you can begin operating

739

within that environment.

740

One useful task at this point would be to determine the

741

IP Address for the user-space NFS by using the

742

<filename>ifconfig</filename> command.

743

The IP address of the QEMU machine appears in the

744

xterm window.

745

You can use this address to help you see which particular

746

IP address the instance of QEMU is using.

</para></listitem>

</orderedlist>

</para>

</section>

<title>Deploying and Debugging the Application</title>

754

755

<para>

756

Once the QEMU emulator is running the image, you can deploy

757

your application using the Eclipse IDE and then use

758

the emulator to perform debugging.

759

Follow these steps to deploy the application.

760

<note>

761

Currently, Eclipse does not support SSH port forwarding.

762

Consequently, if you need to run or debug a remote

763

application using the host display, you must create a

764

tunneling connection from outside Eclipse and keep

765

that connection alive during your work.

766

For example, in a new terminal, run the following:

767

768

$ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable>

769

</literallayout>

770

Using the above form, here is an example:

771

772

$ ssh -XY root@192.168.7.2

773

</literallayout>

774

After running the command, add the command to be executed

775

in Eclipse's run configuration before the application

as follows:

export DISPLAY=:10.0

</literallayout>

Be sure to not destroy the connection during your QEMU

781

session (i.e. do not

782

exit out of or close that shell).

783

</note>

784

785

<listitem><para>Select "Debug Configurations..." from the

786

"Run" menu.</para></listitem>

787

<listitem><para>In the left area, expand

788

<filename>C/C++Remote Application</filename>.

789

</para></listitem>

790

<listitem><para>Locate your project and select it to bring

791

up a new tabbed view in the Debug Configurations Dialog.

792

</para></listitem>

793

<listitem><para>Click on the "Debugger" tab to see the

794

cross-tool debugger you are using.

795

Be sure to change to the debugger perspective in Eclipse.

796

</para></listitem>

797

<listitem><para>Click on the "Main" tab.

798

</para></listitem>

799

<listitem><para>Create a new connection to the QEMU instance

800

by clicking on "new".</para></listitem>

801

<listitem><para>Select <filename>SSH</filename>, which means

802

Secure Socket Shell.

803

Optionally, you can select a TCF connection instead.

804

</para></listitem>

805

<listitem><para>Click "Next".

806

</para></listitem>

807

<listitem><para>Clear out the "Connection name" field and

808

enter any name you want for the connection.

809

</para></listitem>

810

<listitem><para>Put the IP address for the connection in

811

the "Host" field.

812

For QEMU, the default is <filename>192.168.7.2</filename>.

813

However, if a previous QEMU session did not exit

814

cleanly, the IP address increments (e.g.

815

<filename>192.168.7.3</filename>).

816

<note>

817

You can find the IP address for the current QEMU

818

session by looking in the xterm that opens when

you launch QEMU.

</note>

</para></listitem>

<listitem><para>Enter <filename>root</filename>, which

823

is the default for QEMU, for the "User" field.

824

Be sure to leave the password field empty.

825

</para></listitem>

826

<listitem><para>Click "Finish" to close the

827

New Connections Dialog.

828

</para></listitem>

829

<listitem><para>If necessary, use the drop-down menu now in the

830

"Connection" field and pick the IP Address you entered.

831

</para></listitem>

832

<listitem><para>Assuming you are connecting as the root user,

833

which is the default for QEMU x86-64 SDK images provided by

834

the Yocto Project, in the "Remote Absolute File Path for

835

C/C++ Application" field, browse to

836

<filename>/home/root/</filename><replaceable>ProjectName</replaceable>

837

(e.g. <filename>/home/root/hello</filename>).

838

You could also browse to any other path you have write

839

access to on the target such as

840

<filename>/usr/bin</filename>.

841

This location is where your application will be located on

842

the QEMU system.

843

If you fail to browse to and specify an appropriate

844

location, QEMU will not understand what to remotely

845

launch.

846

Eclipse is helpful in that it auto fills your application

847

name for you assuming you browsed to a directory.

If you are prompted to provide a username

852

and to optionally set a password, be sure

853

you provide "root" as the username and you

854

leave the password field blank.

855

</para></listitem>

856

857

If browsing to a directory fails or times

858

out, but you can

859

<filename>ssh</filename> into your QEMU

860

or target from the command line and you

861

have proxies set up, it is likely that

862

Eclipse is sending the SSH traffic to a

863

proxy.

864

In this case, either use TCF , or click on

865

"Configure proxy settings" in the

866

connection dialog and add the target IP

867

address to the "bypass proxy" section.

868

You might also need to change

869

"Active Provider" from Native to Manual.

</para></listitem>

</itemizedlist>

</note>

</para></listitem>

Be sure you change to the "Debug" perspective in Eclipse.

876

</para></listitem>

877

<listitem><para>Click "Debug"

878

</para></listitem>

879

<listitem><para>Accept the debug perspective.

</para></listitem>

</orderedlist>

</para>

</section>

<title>Using Linuxtools</title>

887

888

<para>

889

As mentioned earlier in the manual, performance tools exist

890

(Linuxtools) that enhance your development experience.

891

These tools are aids in developing and debugging applications and

892

images.

893

You can run these tools from within the Eclipse IDE through the

"Linuxtools" menu.

</para>

<para>

For information on how to configure and use these tools, see

899

<ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>.

</para>

</section>

</appendix>

<!--

vim: expandtab tw=80 ts=4

905

-->