Quick start guide

From ERIKA WIKI
Jump to: navigation, search

Prerequisites

The following is the list of software that should be already be installed in your system before installing ERIKA v3:

Downloading ERIKA v3 and RT-Druid

  • RT-Druid can be downloaded using the download web page
  • To download RT-Druid, you have to accept the RT-Druid and the ERIKA v3 licenses
    • The ERIKA v3 license is a GPL v2, whereas the RT-Druid license is a proprietary license that allows you to use the provided version of RT-Druid at no cost
  • Here is possible to find more details about the release scheduling and build numbers of RT-Druid packaging.

Installing RT-Druid

RT-Druid is provided as a compressed archive, which can be unpacked in your user directories. On Windows machines, we typically unpack the tool under C:\Evidence\versionnumber, where 'versionnumber' is the build number.

Starting RT-Druid

  • Double-Click on eclipse.exe application located into eclipse folder extracted from the RT-Druid Package and then the workspace selection window will appear as shown the following figure:
Figure 1: RT-Druid Eclipse IDE workspace selection.
  • Browse the File-System to select Workspace folder and then click on the OK button to let the RT-Druid Eclipse IDE start as shown in the following figure:
Figure 2: RT-Druid Eclipse IDE welcome.
  • Click on Welcome tab-sheet close button to show the default RT-Druid Eclipse IDE C/C++ perspective as shown in the following figure:
Figure 3: RT-Druid Eclipse IDE C/C++ perspective.

RT-Druid Preferences

The RT-Druid code generator and the makefile it generates need to make reference to external values, typically named "preferences". These preferences typically store:

  • directories (e.g., for specifying the compiler path)
  • other configurations (e.g., as serial port numbers, baud rates, ...)

RT-Druid stores the preferences inside the workspace. The following screenshots show how to modify the RT-Druid preferences. Each preference is then described in the specific architecture port.

To open the preferences window, please click on Window->Preferences menu entry as shown in the following figure:

Figure 4: RT-Druid Eclipse Preferences.

The first setting page which can be altered is related to the location of the ERIKA v3 codebase. In particular, the codebase can be stored in various locations, and the tool needs to know where to retrieve the code. The possible options are:

  • Auto - the location is automatically defined by the tool (typically the ERIKA v3 source code is distributed inside an Eclipse plugin);
  • Manual - you can manually specify a root directory (useful in case you have a separate repository on your PC that you want to use;
  • ERIKA_FILES / common_oil.pref - in these two cases the tool will retrieve the location either from the ERIKA_FILES environment variable, or from the ERIKA_FILES variable specified in the preference file common_oil.pref
  • Plugins - In this case, the code will be pulled from the specific ERIKA v3 plugin installed in the current eclipse installation.


Figure 5: Erika Preferences.

The second setting page, as shown in the following figure, lists the available properties which can be modified by the user (you can double-click on a property to modify its value; on newer versions, properties have a hierarchy).

Figure 6: RT-Druid Eclipse Preferences OIL.

For more details about RT-Druid Configuration, see the RT-Druid configuration wiki page.

RT-Druid Project

To create an RT-Druid Project, please follow the steps below:

  • Click on File->New->RT-Druid v3 Oil and C/C++ Project menu entry as shown in the following figure:
Figure 7: RT-Druid v3 Oil and C/C++ Project.
  • The RT-Druid C/C++ Project Wizard will open as shown in the following figure:
Figure 8: RT-Druid C/C++ Project Wizard.
  • Type the name of the project in the Project name text-box: ArduinoEE3 for example.
  • If you are using Windows OS, you should select the Cygwin GCC toolchain, and then click on the Next button.
  • The wizard will show the window to select a project template as shown in the following figure:
Figure 9: RT-Druid Project Template Wizard.
  • Click on Create a project using one of these templates check-box to let the Template Wizard show the available templates as illustrated in the following figure:
Figure 10: RT-Druid Available Templates Wizard.
  • As an example, expand AVR8 and Arduino Uno entries and choose the desired template to instantiate: Full Demo 2 for example.
  • Finally, click on Finish button to instantiate an RT-Druid Eclipse project from a chosen template as shown in the following figure:
Figure 11: RT-Druid Eclipse Project.

Building a project

To build an RT-Druid Project, please follow the steps below:

  • Right-Click on your project, as example ArduinoEE3, shown in the Eclipse Project Explorer panel, and then click on Build Project context-menu entry as shown in the following figure:
Figure 12: Erika project build.
  • The build process starts as shown in the following figure:
Figure 13: Erika build process.
  • The build process ends successfully as shown in the following figure:
Figure 14: Erika build successfully.

ERIKA distribution clean

To completely clean your project, you have to remove both generated and compiled files. This is done using the Clean Erika functions, as explained below.

  • Right-Click on your project, as example ArduinoEE3, shown in the Eclipse Project Explorer panel, and then click on Clean Erika context-menu entry as shown in the following figure:
Figure 15: Erika Clean.
  • The Clean up Erika Files dialog window will appear as shown in the following figure:
Figure 16: Clean up Erika Files.
  • Click on Yes button to clean the entire Erika distribution.

NOTE: the distribution folder will be automatically regenerated, if the flag Build Automatically is enabled.

Figure 17: Build automatically flag.

NOTE: this operation may be necessary every time an Erika or RT-Druid configuration property is modified.

Anatomy of an ERIKA v3 Project

The structure of an ERIKA3 Project is as follows:

  • The application code and the OIL File are stored in the project directory
  • The compilation workflow is as follows:
    • RT-Druid reads the OIL file, and generates:
      • erika/pull/*
      • erika/makefile
      • erika/osSignature.oil
      • out/ee_applcfg.*
      • out/applSignature.oil
      • out/makefile
    • The out/makefile first builds the ERIKA library, and then compiles the application
    • The building of the ERIKA library has three phases:
      • Pull phase: based on erika/osSignature.oil, the system knows what to copy in the erika/inc and erika/src directories from the ERIKA repository (typically stored in the Eclipse plugins) for the library build
      • Doxygen Phase: based on the source code, the Doxygen documentation is generated
      • Compilation Phase: the ERIKA library is then compiled.
  • The compilation process creates at the end the following directories:
    • erika - This directory stores all the files related to ERIKA v3
      • dbg - Debug scripts (typically related to GDB, Lauterbach TRACE32, or to iSystem WinIDEA)
      • doc - Doxygen documentation, generated automatically when building the project (only if Doxygen is installed!)
      • inc - The ERIKA include files, copied in the local project
      • lib - The compiled libraries
      • mk - The makefiles used for compiling the library
      • obj - The object files used to assemble the library
      • pull - These are the only files generated by RT-Druid under ERIKA. all the rest is generated from the pull makefile!
      • src - The source code of ERIKA, copied in the local project
      • makefile - the main makefile for compiling the ERIKA library
      • osSignature.oil - the OIL file signature. This part is basically the "configuration" part of the library, and it is a subset of the application OIL file. RT-Druid re-generates the files ONLY if the signature does not match the current OIL file.
    • out - This directory stores all the files related to the application, included the final binaries
      • applSignature.oil - the application OIL signature, which is basically the OIL file re-exported by the tool
      • ee_applcfg.* - the application configuration generated by RT-Druid
      • makefile - the main application makefile

Per Architecture tutorials

See also