Using STWorkbench with STLinux Using STWorkbench to develop existing applications

Introduction

STWorkbench is an Eclipse-based IDE shipped with the STLinux distribution. It supports development and debugging of STLinux applications. STWorkbench can be easily used to drive an existing make system, without the need to convert applications to the STWorkbench build system ("Managed Make").

This describes how to import an existing software tree into an STWorkbench project, build it and debug it.

STWorkbench concepts

To simplify using the interface, here are some of the main aspects.

• Workbench - the main Eclipse/STWorkbench window.

• Workspace - a container of projects.

  On startup a directory is chosen for the workspace. Projects can be either copied into that directory or developed in their original location. In either case they are displayed in the C/C++ Projects view, which is the main interface to the workspace.

  Note: Workspaces are handled individually for each user and do not need to be archived under source control.
  The Eclipse/STWorkbench ClearCase plug-ins map one workspace to each ClearCase view.

• Project - a set of files and folders from which one or more executable or library is built.

  A project consists of a standard source tree, to which STWorkbench adds two additional files in the top level: .project and .cdtproject.

• View - a tabbed sub-window in the workbench.

• Perspective - a set of views.

  Perspectives allow a set of related views to be opened and closed together. For example, there is one perspective for C/C++ development and another for debugging.

• Launch configuration - the settings required to run and debug an application.

  Once a launch configuration is created to run an application, it can also be used to debug the application.

Importing an existing application

To work on an application in STWorkbench, it must be imported into a project in the workspace. The easiest way is to wrap a project around the existing application tree. This writes two dotfiles (.project and .cdtproject) into the top level of the filesystem tree. No other changes are made to the application, 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 Makefile project. To wrap a Makefile project around your existing application:

1. Start STWorkbench and specify a workspace directory in your home area, the location is unimportant. Once the dotfiles have been created, a project can be imported into any workspace.

2. Select File > New > Project.

3. In the C category, select C Project and click Next.

4. Give the project a meaningful name.

5. To leave the source tree in it's original location, uncheck Use default location and enter the location of the tree in the Location field.

   Note: The wizard may warn that "Directory with specified name already exists!". This can be ignored.

   

6. Select Makefile project and the appropriate toolchain.

7. Click Next. The Select Configurations page appears. Click Advanced settings....

8. To modify the make commands emitted when cleaning and building the project, select the C/C++ Build section:

   

• The make command to be invoked and build directory can be set on the Builder settings tab.
• The make targets can be set on the Behaviour tab.
• To trigger a rebuild whenever a file is saved, check Build on resource save (Auto Build).

9. In the C/C++ Build > Settings section, check the ST Elf Parser. This is used to extract symbol information from binaries.

10. In the C/C++ Build > Discovery options section, change the Compiler invocation command to the name of your compiler, for example sh4-linux-gcc. This allows STWorkbench to locate the correct set of include files.

11. Click Finish. The project is created.

    Note: To change any of the settings, select 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, select Window > Show View > Other > Make > Make Targets to open the Make Targets view. 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.

For more information on working with Make Targets, see Driving an existing make system.

Running and debugging the application

Once an executable has been built in the project, it can be run and debugged.

Note: Any executable that is enclosed in a project can be debugged; it is not necessary to develop and build it in STWorkbench.

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

   

2. Highlight STLinux Target Application and click New . A launch configuration is created; give it a meaningful name.

3. Select the Main tab. Fill in the Project and C/C++ Application fields.

   

4. Select the Debugger tab. Select the ST40 Linux GDB Debugger. Fill in the Target name or IP address of a board that is currently running STLinux.

   Note: 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 is copied to the target and executed. Its stdout and stderr streams appear in the Console view.

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

6. To debug the application, click Run > Debug or click the Debug toolbar button. The launch configuration is reused. If prompted, move to the Debug perspective.

The controls to debug the application are similar to those found in other GUIs. To set breakpoints, double-click the border of the source file. The Debug view has toolbar buttons to step, resume and terminate your application. It also displays thread lists and callstacks.

The Debug view also contains two entries for consoles, indicated by an icon showing a PC tower and a green triangle. Click either of them to 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.

For further information on how STWorkbench can be used to develop and debug large existing applications, see the following STWorkbench tutorials:

• Building an STLinux kernel
• Developing an STLinux kernel
• Booting an STLinux kernel
• Debugging an STLinux kernel
• Direct Debugging of Executables