Chapter 2. Quick Start / Walkthrough

This chapter shows how to create a simple eCos "Hello World" application project from scratch, using the included project template and a default eCos configuration on the target hardware.

  1. Select the relevant New project wizard for your project (C or C++) from the menu (Figure 2.1, “New Project from Menu”) or toolbar (Figure 2.2, “New Project from Toolbar”).

    Figure 2.1. New Project from Menu

    New Project from Menu


    Figure 2.2. New Project from Toolbar

    New Project from Toolbar


    [Tip]Tip

    A C++ project may contain C code, but not vice versa.

  2. Enter a name for your project. If desired, customise its location.

    [Note]Note

    Spaces are not permitted in the name of a project or workspace nor are they allowed in the path to the workspace. This is because Eclipse uses the GNU make utility for which spaces have a specific meaning.

  3. Select the project type and check that the eCos toolchain is selected as illustrated in Figure 2.3, “New Project Wizard”. In this example we will create an eCos Managed Make Application Project of subtype Hello World Managed C Project.

    Figure 2.3. New Project Wizard

    New Project Wizard

    Normally the Empty Project subtype is used as the starting point for new projects, but the Hello World Managed C Project subtype is provided in order to create a project for demonstration purposes which already contains an example application. This application is a simple C program which, when run on the target, will output “Hello World” on the console. In every other respect it is the same as a normal eCos Managed Make Application Project, and only exists to easily demonstrate Eclipse.

    The "eCos toolchain" entries are smart wrappers which automatically detect the correct GNU toolchain (gcc, gdb, …) to invoke based on the eCos configuration. If you later change the project to use a different eCos build, the appropriate toolchain will be invoked based on the settings within the associated eCos configuration.

  4. Press Next. The Settings page appears, which provides a number of fields to customise the Hello World project. Fill these in appropriately, and press Next.

    [Note]Note

    This page does not appear if you selected an Empty Project.

  5. The Select Configurations page appears. It is not normally necessary to change anything here, so press Next again.

  6. The eCos Application Project configuration page appears as illustrated in Figure 2.4, “eCos Application Project configuration”. We are going to create a new eCos configuration, so select that option.

    Figure 2.4. eCos Application Project configuration

    eCos Application Project configuration

    If you already have an eCos configuration for your target hardware in the form of an ECC file, you can instead import it as a configuration project. If you have already created or imported a configuration project, then the option to use an existing configuration project will no longer be greyed out, thereby allowing you to select the configuration project.

  7. We want the ability to conveniently run this example on our target hardware, so in the Create a launch profile section select Yes, but provide connection settings later. This will cause a launch configuration to be created with the default profile name provided. Launch configurations are used in Eclipse to describe how to run or debug the application, and for eCos applications, the most important aspect is that it provides information on how to connect to the remote target (serial parameters, TCP, …). By choosing to provide connection settings later, we will be prompted for the settings when we first use the launch configuration to run or debug the application.

    [Note]Note

    Connection settings do not apply to projects for the Linux synthetic target; the prompt does not appear in that case.

    [Tip]Tip

    Further launch configurations may be created by the shortcut in the eCos menu, or manually via the Debug Configurations dialog.

  8. Press Next. After a few seconds, the wizard starts presenting the pages required to create an eCos configuration project as illustrated in Figure 2.5, “New eCos Configuration project”.

    Figure 2.5. New eCos Configuration project

    New eCos Configuration project


  9. Specify a name for the configuration project. Again, you may set a non-default location if required. Press Next.

  10. If you have multiple eCosPro installations, the Profile Selection page appears as illustrated in Figure 2.6, “eCos profile selection”. The drop-down box contains the list of detected profiles associated with eCosPro releases installed on your system. You can find out more information about profiles in the eCos and eCosPro User Guide. Select the appropriate release for your hardware and press Next.

    Figure 2.6. eCos profile selection

    eCos profile selection


    [Tip]Tip

    eCosPro releases prior to 3.1.0 will not appear in this list. If you have an older release installed which set the ECOS_REPOSITORY environment variable, that setting is used as a further profile. However if you do so, you must ensure you have also set your PATH environment variable to include the eCos host tools, and the relevant GNU toolchain for your hardware.

  11. The Target and Template Selection page appears as illustrated in Figure 2.7, “eCos target and template selection”. The default hardware target and template for the selected profile are preselected as defaults. In this example, we are using the sam9263ek, but you should select the relevant target for your hardware.

    Figure 2.7. eCos target and template selection

    eCos target and template selection


  12. Note the option entitled Initially inhibit building this project in Figure 2.7, “eCos target and template selection”. When checked, this option prevents the configuration from being built. This is useful if you want to make further changes to your new eCos configuration before building it. For the purposes of this example, keep the option unchecked.

  13. Finally, press Finish. The two projects are created in your Eclipse workspace, and the link is set up from one to the other.

    [Note]Note

    You may notice some errors appearing in the Console and Problems views, if you have them open. These notifications are benign and will clear when the configuration project has been built.

    As we left the inhibit option unchecked, Eclipse automatically begins to build the eCos configuration in the background. Progress reporting appears in the bottom-right corner of the workbench window as illustrated in Figure 2.8, “Build Progress”. You can click on the progress bar circled in red in the figure to open up the indicated Progress view which has more detailed information, or even watch the build output on the Console view by selecting the Tab circled in blue.

    Figure 2.8. Build Progress

    Build Progress


  14. To manually build the application project select “Build All” in the Project menu, or right-click on the application project within the Project Explorer window and select “Build Project” as both illustrated in Figure 2.9, “Build Project Menu”:

    Figure 2.9. Build Project Menu

    Build Project Menu


  15. Once started, a foreground progress dialog will appear as illustrated in Figure 2.10, “Build Project Progress”. Wait a while for the build to complete; if the configuration build was still running, Eclipse schedules the application project build to happen next.

    Figure 2.10. Build Project Progress

    Build Project Progress


    The Eclipse CDT project builder is fully integrated with the Eclipse background builder so that both the application project as well as the associated eCos configuration project will be built in the background.

  16. Your application project has now built. Browsing it in the Project Explorer view you will notice the source directory, Debug (containing builds in the Eclipse "Debug" build mode, which is the default) and autogenerated lists of Binaries and Includes. You can also browse the configuration project's build and install directories, the configuration file ecos.ecc and (via an Eclipse filesystem link) the source repository. All the usual Eclipse CDT functionality, such as the Content Assist feature which provides a list of available functions (<Ctrl>+Space), function prototyping and descriptions as illustrated in Figure 2.11, “Project Explorer and Context Editor”.

    Figure 2.11. Project Explorer and Context Editor

    Project Explorer and Context Editor


The next chapter “Debugging eCos applications” provides a walkthrough showing how to download and debug the application you have just built.