Getting started with IAR EWPtool Utility

What is EWPtool?

The IAR Embedded Workbench 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 many folders involved.

EWPtool can speed up the process of populating an IAR Embedded Workbench Project file (*.ewp) by traversing an existing source code tree.

What does EWPtool do?

From the IDE, the IAR 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 selected 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 3^rd party IDEs.

Tip

About that, some target architectures of the IAR Embedded Workbench might offer built-in project converter tools able to deal with projects from 3^rd party IDEs. The IAR 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

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

1. Close all the instances of the IDE.
2. Download the archive (EWPtool-<version>.zip) available from the latest Release notes.
3. Extract the zip archive contents inside the <path-to>/<iar-embedded-workbench-installation-folder>/common folder.
4. Launch the IDE.

Note

When multiple instances of the IDE are installed on independent locations, repeat step 3 for each desired instance.

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 source folders to a project

This section describes the steps for when populating an IAR Embedded Workbench project from scratch with a pre-existing source code tree.

Tip

EWPtool does not create any sort of backup of the affected <project-name>.ewp file. It is recommended to have a backup copy or a version control system in place before proceeding for rolling back in case there are any undesired 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 top level folder.

• Choose Tools → Select source folder….

• A dialog window (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 the natural choice. For example:

Tip

Each time a source folder selection is made, the EWPtool configuration file for the project is updated ($PROJ_DIR$/settings/$PROJ_FNAME$.cfg). The selection is saved in the configuration file for later when use the menu command Tools → Rescan selected source folder(s) is invoked.

Warning

The folder selection is limited to the same drive (A:, ..., Z:) in which the project file (*.ewp) is located.

• 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 EWPtool scanned the selected source tree, found changes, and updated entries in the project tree layout. Click on the Yes button to reload the project.

Note

EWPtool can only act upon the contents it finds on the "disk". Always save the project (File → Save all) before using the tool.

• When the project is reloaded, it should be automatically populated with all the source files detected in the monitored folder(s). The result can be verified by unfolding group nodes in the Workspace window's project tree:

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

Proceed to the IAR EWPtool wiki for more information.

Issues

Found an issue or have a suggestion related to the EWPtool?

• Try the wiki.
• Check for earlier issues in the public issue tracker.
• If nothing helps, create a new issue, describing in detail.