How To Guide How to import an existing software tree into STWorkbench

Introduction

STWorkbench is an Eclipse-based IDE, shipped with the STLinux distribution, that provides support for developing and debugging STLinux applications.

One common fallacy about STWorkbench is that users are forced to convert their applications to its own build system ("Managed Make") to use it. In fact, it can very easily be used to drive an existing make system.

This document describes the steps required to import an existing software tree into an STWorkbench project, build it, and debug it.

STWorkbench concepts

For new users of Eclipse/STWorkbench, some aspects of its rather idiosyncratic interface can be a little confusing. Here, we define some of the key concepts needed to navigate an Eclipse-based workbench.

Importing an existing application

To work on an application in STWorkbench, it has to be imported into a project in the workspace. The easiest way to do this is wrap a project around the existing application tree. The effect of this is to write two dotfiles (.project and .cdtproject) into the top level of the filesystem tree. No other changes are made to the application, and so it can still be developed outside STWorkbench as before.

There are several different project types. For a C/C++ project with an existing make system, the correct project type to use is Standard Make C Project.

Steps to wrap a Standard Make C Project around your existing application:

2) Select File -> New -> Project. Select Standard Make C Project in the C category and click Next.

3) Give the project a meaningful name.

4) To leave the source tree in it's original location, uncheck Project contents and enter the location of the tree in the Directory field. Click Next.

The C/Make Project Settings page is opened.

5) If required, edit the Make Builder tab. It contains the make commands to be emitted when cleaning and building the project. The defaults are to make clean and make all in the top level of the project. For the STWorkbench Build Automatically option to work (triggering a rebuild whenever a file is saved), Build on resource save (Auto Build) must be checked.

6) In the Binary Parser tab, uncheck Elf Parser, and use ST Elf Parser instead. This contains some enhancements for ELF files produced by ST toolsets.

Note: "Binary parsers" are used to extract symbol information from ELF files.

7) In the Discovery options tab, change the Compiler invocation command to sh4-linux-gcc or st231-linux-gcc as appropriate. This is used to locate the right set of include files.

8) In the C/C++ Indexer tab, choose an indexer. If the application is indexed then a much wider variety of features are available, for example navigating to function declarations. By default, no indexer is selected.

Note: This is because the Full C/C++ Indexer currently handles large applications very badly. Work to correct this is ongoing in the Eclipse community. As a compromise, if you have ctags available on your system, you can select the CTags Indexer which provides some of the functionality and is much more scalable.

9) Click Finish. The project is created.

Note: Any of the settings mentioned above can changed later in Project -> Properties.

Building the application

When the project is built, STWorkbench invokes make, calling the make targets specified in the Make Builder section of the new project wizard. The output of the build process is displayed in the Console view.

To invoke more complex make commands, use the Make Targets view. If it is not already visible, it can be opened from Window -> Show View -> Other -> Make -> Make Targets. This provides an interface for invoking make in any part of the project tree with any arguments. Make targets defined in this way are saved in the project for future use.

Running and debugging the application

1) To run the executable, select Run -> Run.... The Create, manage and run configurations dialog is displayed. The left hand pane gives a list of launch configuration types.

2) Highlight STLinux Target Application and click New . A launch configuration is created, which should be given a meaningful name.

3) In the Main tab, fill in the Project and C/C++ Application fields.

4) In the Debugger tab, fill in the Target name or IP address of a board that is currently running STLinux.

Important: It is a prerequisite of running and debugging applications that the STLinux target board is booted, reachable on the network, and that the chosen user (probably root) is able to log into the target via ssh (e.g. ssh root@target) without a password or any prompting.

5) Click Run . The executable will be copied to the target an executed. Its stdout and stderr streams will be visible in an external rxvt terminal.

Note: To run the application again, simply click the Run toolbar button.

6) To debug the application, click the Debug toolbar button. The launch configuration is reused. If prompted to move to the Debug perspective, do so.

The controls to debug the application are very similar to those found in other GUIs. Breakpoints can be set by double-clicking the border of the source file, and the Debug view, which displays thread lists and callstacks, also contains the toolbar buttons to step, resume and terminate your application.

The Debug view also contains two entries for "consoles" (indicated by an icon showing a PC tower and a green triangle). Clicking on either of them will display it in the Console view. One is the console for your application, giving you access to stdin, stdout and stderr. The other is the console for gdb, where you can issue arbitrary gdb commands.

Note: Since no "(gdb)" prompt is displayed, it is not always clear when gdb is accepting input - commands can only be entered when the application is suspended!

Hopefully this is enough information to illustrate how STWorkbench can be used to develop and/or debug large existing applications. Much more information is available in the STWorkbench online help, including tutorials on building, developing and debugging STLinux kernel code.