Tutorial
Getting Started with the EWPtool

What is the EWPtool utility?

EWPtool is a lightweight sidekick that can help by speeding up the process of populating an IAR Embedded Workbench Project (.ewp) with an existing source code tree.

Currently the IDE allows adding source files from a single folder at a time, which is fine for a few folders. Although, this process can become time-consuming in cases where there are too many folders.

What does EWPtool do?

From the IDE, the EWPtool utility acts as an external tool that extends its functionality. When invoked, it asks for where the project's source tree can be found.Then EWPtool automates the task of populating the project with the source code tree. The bigger the selected source tree is, the more evident its yielded benefit becomes.

The EWPtool modifies the following entries in the .ewp project:

• Populates the project's tree layout, reflecting the selected source code tree layout in the filesystem.
• Fills the preprocessor search paths entries, for the active build configuration.
• Updates moved/renamed entries from the project tree layout.
• Removes stale entries from the project tree layout.

What does EWPtool not do?

Rest assured that:

• EWPtool does not modify your source files.
• EWPtool does not convert existing project files created by 3rd-party IDEs.

💡 About that, some target architectures of the IAR Embedded Workbench might offer built-in project converter tools able to deal with projects from 3rd-party IDEs. The EWPtool utility is not a requirement for when using those tools. In those cases, you can safely disregard this tutorial. Instead, please visit the Migration Guides section in the official Project Migration tools page for more information specific to those tools.

Installing

The EWPtool can be used with any reasonably recent versions of the IAR Embedded Workbench. Installing the tool simply means deploying its files on top of an existing instance of the IDE. Please follow the steps below:

1. Close all the instances of the IDE.
2. Download the archive with the latest release of the EWPtool utility. [Release notes]
3. Extract the zip archive contents inside the <path-to>/<iar-embedded-workbench-installation-folder>/common folder.
4. Launch the IDE.

⚠️ Please notice that, if multiple instances of the IAR Embedded Workbench are installed on independent locations, step 3. must be repeated for each instance in which the EWPtool is going to be used with.

Upgrading

For upgrading from previous EWPtool versions, replace the old files in the common folder and re-launch the IDE.

How to use it?

The project layout in the IAR Embedded Workbench is logical. This means that, whenever desired, source files could be added and grouped in a completely different way than the way they are actually arranged in the filesystem.

The EWPtool populates a project by reflecting the selected source tree layout, so the logical layout will initially match the layout from the filesystem.

Adding the project's sources

From this section onwards, we will use a fictional project containing many source folders as an example on how the EWPtool can be used.

⚠️ EWPtool does not create any sort of backup of the affected <project-name>.ewp. Before proceeding it is recommended to have a version control system in place or -at least- a backup copy of the project, in case you wish to rollback any performed changes.

• Create a New Empty Project by choosing Project → Create New Project → Empty Project → OK.

• A Save As dialog will show up. Save the <project-name>.ewp in the project's source tree top level folder.

💡 The tool can only act upon the contents it finds on the "disk". To avoid the need of re-scanning the selected source tree twice, remember to always save the project before invoking the EWPtool.

• Invoke the EWPtool: select Tools → Select source folder….

• A new window titled Browse for Folder will show up pointing initially to the folder where the .ewp file is. From there, select the desired source tree folder that will populate the active project. Usually the project's top directory will be chosen. For example:

⚠️ Please notice that the EWPtool is also able to add folders that are located on any upper or lower level relative to the .ewp file, as far as the chosen folder belongs to the same drive in which the project file is stored (i.e. C:, D:, etc.).

💡 The selected folder is saved in settings/<PROJ_FNAME>.cfg so it can be used later with the command Tools → Rescan selected source folder..., which will skip the Browse for folder dialog.

• The IDE will then tell you that the <path-to>/<project-name>.ewp project file has been modified on "disk" and will offer to reload the project. This happens because the EWPtool scanned the selected source tree, found changes, and updated entries in the project tree layout. Click on the Yes button to allow the IDE to reload the project.

• Reloading the project will recursively add the source files from the selected folder to the current build configuration ("Debug" in this example). The result can be verified by unfolding the groups, located in the project's Workspace window:

And this is what you need to know to start using the EWPtool utility.

The following sections will provide further information related to the project's customizations as well as some important migration details.

Appending extra source code

Many embedded software projects use 3rd-party source code to support the actual application. If these components were located within the project's source tree, they would be already appended to the project layout from the time the project's directory was selected.

That's not always the case. Let's consider one use case where pieces of the application might be located on a parent level, outside the project's source tree. Perhaps because these components are used on other projects and are maintained separately. If that's the case, the EWPtool utility can help on populating the project with them.

For this fictional example let's consider using the EWPtool a second time for adding another folder, named 3rd-party-components. The folder is located on the same level where the project's directory is located (../$PROJ_DIR$):

When selecting source folders located above $PROJ_DIR$, one or more groups named .. are created as reference to how many levels above the $PROJ_DIR$ the extra source folders are located, reflecting the arrangement of these source files on the filesystem. On the logical layout this grouping convention helps to identify where the extra source files are located relatively to the $PROJ_DIR$.

💡 $PROJ_DIR$ is an IDE's internal argument variable which translates to the absolute path for the location where the .ewp file is stored.

Source code detection

The EWPtool utility detects source file types from the selected source tree by their extension. The file extensions that are automatically detected are specified in the table below.

Source file type	Detected extensions
C sources	*.c
C++ sources	*.cc, *.cpp
Assembly sources	*.s, *.asm, *.msa, *.s90 (AVR), *.s51 (8051), *.s43 (430), *.s26 (78K), *.s85 (V850)

💡 If a project requires any pre-built static library (i.e. <library-name>.a), these must be manually added to the project (i.e. via Project Options (ALT+F7) → Linker → Libraries).

Customizations

Once we get all the desired files automatically appended to the project, the project can be customized from the IDE.

Rearranging project layout

The project's groups nodes can be customized from the Workspace window.

• Rearranging a group (or a file) node:

  • can performed through simple drag'n drop operation.

• Renaming a group node:

  • Click to highlight the desired group node.
  • Right-click for its context menu. Use the Rename command.

• Remove empty group node:

  • Click to highlight the undesired group node.
  • Remove it from the project using the DEL key.

Excluding sources from the active build configuration

There are cases where not every single source file present in a folder should be used on every build configuration at the same time. Perhaps due multiple implementations of the same functions but with different trade-offs. In those cases, a choice should be made.

In our fictional project example, this happens with the buffer component where a type choice must be made among the type A, type B and type C.

Let's say we decide that our project needs the type A buffer implementation. We need to exclude type B and type C from the current build configuration.

There are at least a couple of ways of accomplish this in the Workspace window:

• Remove the undesired files from the project layout:

  • Highlight each of the undesired file nodes (buffer_typeB.c and buffer_typeC.c).
  • Remove them from the project layout by pressing the DEL key. or...

• Exclude the undesired files from the build:

  • For each of the undesired file nodes: right-click and select: Options → Exclude from build. or...

• Create an "excluded" group:

  • Create a new group (i.e. excluded) inside the desired group.
  • Right-click on the excluded group and select: Options → Exclude from build.
  • While holding SHIFT, select multiple files (i.e. click on buffer_typeB.c followed by buffer_typeC.c).
  • Finally drag the selection and drop these files inside the excluded group. By consequence, they will be excluded from the current build configuration (the example depicts "Debug").

⚠️ Notice that when a group or a file is excluded from build, its icon becomes grayed.

⚠️ Excluding sources from the current build configuration does not propagate to other build configurations.

💡 Once the layout was customized, save the project by choosing File → Save All. Alternatively, click the Save All icon in the main toolbar.

Great! Now what?

As we have seen, the sole purpose of the EWPtool is to be one of the developer's sidekicks when it comes to quickly populate a new (or an existing) project with existing source folders.

Although, we are not done yet with the project preparation.

Creating a project from scratch essentially requires some adjustments, so it can get properly configured.

Typically, the project options need to be in accordance with, at least:

• the target device that will be used
• the runtime library configurations
• the C/C++ compiler optimizations
• the linker configuration
• the debugger configuration

Even so, the IAR Embedded Workbench IDE makes it straightforward to change such project configurations.

Now let's take a look at how to access such project options, alongside some ideas that might help you.

Target Device Selection

How to access:

• Open the project’s options with Project → Options (ALT+F7).
• Navigate to the General Options → Target tab.

The Target tab will allow you to select the target device. This tab will present itself slightly different depending on the IAR Embedded Workbench architecture in use. The screenshots below were taken from the Arm and RISC-V flavors, respectively:

Runtime library Configurations

How to access:

• Open the project’s options with Project → Options (ALT+F7).
• Navigate to the General Options → Library Configuration tab.

The Library Configuration tab allows us to configure the runtime library options such as locale support, multibytes in printf(), low-level interface implementation for stdout/stderr, etc.

This tab might be especially interesting for Arm users working with CMSIS-based projects; case in which the Use CMSIS option might have to be enabled.

C/C++ Compiler Optimizations

How to access:

• Open the project’s options with Project → Options (ALT+F7).
• Navigate to the C/C++ Compiler → Optimizations tab.

In the Optimizations tab you can easily choose the optimization level from None up to High.

When High is selected, it is possible to select among 3 different optimization objectives:

• Size means the smallest code size. This objective can be selected when minimizing the program memory consumption is more important than execution speed.

• Speed means code that executes faster. This objective can be selected when speed is more important than the code size.

• Balanced will use heuristics for making decisions on the transformations used for each piece of code. This objective can be selected to make the code run as fast as possible, whenever it doesn’t mean a toll in terms of code size.

The Enabled Transformations can be cherry-picked when higher optimization levels are selected. When enabled, these transformations significantly affect the code generation for the better.

💡 When debugging code, it is recommended to leave the compiler optimization level on None or Low, where those transformations do not happen, so the generated code will have a better correlation with the source code. A lower optimization level provides better visibility for debugging purposes. The "Debug" configuration uses the Low level as default.

💡 When the application is ready for its Release, with its source code already debugged, the compiler optimization level can be raised to High as in the "Release" build configuration. The Workspace window offers a build configuration drop-down box which allows to quickly switch back and forth between these build configurations:

💡 When the High/Speed level is selected, the check box No size constraints can be enabled. This option will generate code that executes as fast as possible.

C/C++ Compiler Preprocessor

How to access:

• Open the project’s options with Project → Options (ALT+F7).
• Navigate to the C/C++ Compiler → Preprocessor tab.

By default, a project created with the IAR Embedded Workbench will search for C/C++ header files in the toolchain's headers default locations ($TOOLKIT_DIR$/inc) as well as in the project directory ($PROJ_DIR$).

In this tab, it is possible to specify Additional Include Directories: (one per line) here.

💡 When one or more source folders are added to the project using the EWPtool, it will recursively detect any folders containing header files (any files with the .h or the .hpp extensions). Then it will fill the C/C++ Preprocessor entries accordingly.

💡 This is also where symbols could be specified. One possible scenario, for example, would be taking an originating Makefile in search of any application's required symbols. Once they are found, it is just about bringing these symbols to the Defined Symbols box. For example:

Linker configurations

Once the target device is selected:

• Open the project’s options with Project → Options (ALT+F7).
• Navigate to the Linkter → Config tab.

The linker configuration file (*.icf) will automatically change according to the selected target. The target's default linker configuration should be ready to use the programs with no specific flash partitioning requirements (as it would be, for example, in a bootloader application) to run with no issues. Even then, if a specific configuration is needed for the project, it is just about enabling Override default for the configuration:

Debugger Configurations

How to access:

• Open the project’s options with Project → Options (ALT+F7).
• Navigate to the Debugger → Setup tab.

In this tab you can switch to the Driver for of the supported debugging probes of your choice. The list of drivers changes according to the target architecture in use.

💡 For the optimal experience with Arm or RISC-V targets, we recommend the IAR I-jet probes.

💡 Each of the IAR Embedded Workbench brings an integrated simulator for its target architecture. The simulator makes possible for you to start debugging your project even when board isn’t there yet. To learn more about the IAR C-SPY simulator, its interrupt simulation capabilities and its powerful macro system, go to Help → Information Center → Product explorer and take a look on the related tutorials.

Source code migration

If the original source code was written using Standard C or Standard C++, it is likely that you are good to go.

💡 When migrating sources that use non-portable code (i.e. compiler-specific extensions), a developer needs to review and migrate such code manually. The steps involved in porting code are often architecture-dependent and these steps are beyond the scope of this tutorial. Device-specific startup files are, in many cases, bundled with the IAR Embedded Workbench project examples in the Information Center, accessible from the IDE's main menu: Help → Information Center → Example projects.

For more information, refer to the User Guides directly from the IAR Systems Support page. If you have the product already installed on your workstation, it is possible to access its User Guides from the IDE's main menu: Help → Information Center → User guides.

Issues

Found an issue or have a suggestion related to the EWPtool? Feel free to use the public issue tracker.

• Do not forget to take a look on earlier issues.
• If creating a new issue, please describe it in detail.

Summary

This short tutorial offered general guidelines with tips and shortcuts for developers willing to get a speedup factor when migrating a project, from scratch, to the IAR Embedded Workbench.