Eclipse IDE Survival Guide

The IDE provided with ModusToolbox software is built on the Eclipse IDE. For those unfamiliar with an Eclipse IDE, this FAQ answers questions about how to get common tasks done. Most information specific to ModusToolbox (for example: How do I install or get started?) is in the ModusToolbox documentation, especially the ModusToolbox Installation Guide, the Quick Start Guide, and the User Guide.

If you are already familiar with an Eclipse IDE in general, you will find some useful answers here on unique IDE features such as the Quick Panel and how to build an application. However, most information unique to the Eclipse IDE for ModusToolbox (such as the Project Creator and Library Manager) is in the Eclipse IDE for ModusToolbox User Guide or other documentation.

Questions are organized into the following categories:

In this document, the term ” Application” means deployable firmware for the target hardware. To build an application, you require a collection of one or more Eclipse projects.

A “Project” is a compilation unit. An application may consist of several Eclipse projects but typically is a single project.

Project Management

For general information about how the Eclipse IDE for ModusToolbox creates and implements projects, see the “Getting Started” chapter of the Eclipse IDE for ModusToolbox User Guide.

Parts of the code example’s readme file are hard to read in the IDE. How do I fix that?

Cypress uses GitHub to deliver examples and libraries. We use GitHub-flavored markdown, which has some extensions (like support for tables) that are not understood by the Eclipse markdown editor. There are a few things you can do. You can look at the readme file on GitHub. You can right-click the document in the project explorer and choose “Open With…” to pick a different reader application. You can get a more capable markdown editor and install that. You can also modify the Eclipse IDE to open a markdown document in that editor.

How do I set up the IDE to use my preferred markdown editor?

If a document does not open the editor you want, use Window > Preferences > General > Editors > File Associations and set up the file association. For the *.md file type, assign it to your preferred markdown viewer. When you double-click a .md file in the Eclipse project explorer, it opens in your external editor.

How do I find the right Eclipse panel or option when I don’t know where anything is?

Use the Eclipse IDE Quick Access feature. This is a search engine that helps you find things in an Eclipse IDE. The IDE is a complex application with significant resources located in various menus, panels, windows, and so forth. The Quick Access field solves the problem of not knowing where things are.

Type a search term into the Quick Access field, and you are presented with hits. Each item is a link. Clicking a link either executes the command or takes you to the location in the Eclipse UI.


How do I rename an application?

In the project explorer, right-click the project name and choose Rename. However, launch configurations (used for programming and debugging the target) are linked to the original project name, so they disappear when you rename the project. See My launch configurations disappeared, what do I do?.

How do I share a project?

With an Eclipse IDE, there are two ways to do this: via an archive file, and from the file system.

  • Export an archive file: Select File > Export >General > Archive File. Select the project that represents the application. Send the archive to the person who needs the application. That person imports via File > Import > General >Existing projects into workspace and sets options to import the archive file.

  • If you have a folder that contains an Eclipse project, you can use File > Import > General > Existing projects into workspace; point to the root directory that contains the project(s) you want to import.

Pro Tip: When you archive a project, do not include the build folder. The IDE regenerates this information, you don’t need to include it. You will save many megabytes of space excluding the build folder.


What is a workspace?

Eclipse IDE always opens in association with a workspace. A workspace is a directory on the disk where Eclipse keeps projects. Within the workspace, each project has its own directory. You can have multiple projects in a single workspace. You can also have multiple workspaces. All projects associated with a workspace appear in the Project Explorer window. When you switch between workspaces, the projects of the new workspace appear.

Running the ModusToolbox executable prompts you to select the Workspace when launching the Eclipse IDE.


How do I create a new/empty workspace?

Choose File > Switch Workspace > Other… and then create the new workspace. You can do this by just entering a new name, or browsing and creating a folder.

How do I change workspaces?

Choose File > Switch Workspace, and then pick an existing workspace.

What is a perspective and how does the IDE use them?

In Eclipse, a perspective is the collection of panes and views visible in the user interface. The Eclipse IDE for ModusToolbox has its own perspective, which is what appears when you launch the IDE for the first time. This is called the ModusToolbox perspective. It contains views that enable project management, code creation, and debugging all in the same perspective. It also contains the Quick Panel, which contains one-click shortcuts to the most common tasks. By default, the IDE does not use the standard Eclipse C/C++ or Debug perspectives.

How can I change to a different perspective?

There are at least three ways.

Select Window > Perspective > Open Perspective and choose the one you want. You can also click the Open Perspective button in the toolbar. The icon for any perspective you open appears as a button on the toolbar.


To the right of that is a button for each of the perspectives you have used, such as the ModusToolbox perspective. Just click the button corresponding to the perspective you want to use.

How can I make my own perspective?

This is one of the most powerful features of an Eclipse IDE. You can open, close, or relocate any view in any panel. In effect, you can build your own UI. When the UI is set up to your liking, use Window > Perspective > Save Perspective As. Give it a name, and it is added to the list of available perspectives.

How do I remove or delete a project from the project explorer?

In the project explorer, select the project(s) you want to remove. Then press the Delete key, or right-click and choose Delete. The Delete Resources dialog appears.

To remove a project from the explorer, but keep the actual project, make sure that Delete project contents on disk is disabled. This is often the right thing to do, for example, when you point to a project outside your workspace that should continue to exist.

To delete the project permanently, enable the Delete project contents on disk option. Project deletion cannot be undone. This is often the right thing to do when you want to permanently remove the project from the workspace.


What are workspace settings?

Workspace settings are preferences that apply to the entire workspace. In general, these are set by changing options in Window > Preferences.

How do I share workspace settings across workspaces?

You can export preferences from one workspace and import them into another. Select File > Export > General > Preferences. This creates a preferences file. You can use the file as a backup of your preferences. You can switch to any workspace and import the preferences.

When creating a new workspace, expand the Copy Settings option and specify which preferences from the current workspace you want to use in the new workspace.


What is a working set and why would I want to use one?

A working set is a collection of Eclipse projects. Fundamentally it is just a group, but you can perform various operations that will affect all the projects in the group. For example, you can show, hide, or build a working set. This can make it easier to manage multiple related projects.

How do I create a working set?

To make things easy, do the following:

  1. In the project explorer, first select all the projects you want in the working set.

  2. In the project explorer, use the View drop-down menu and choose Select Working Set.


  3. Click New, and then select C/C++ and click Next. If you selected the projects first, they appear already selected in the New Working Set dialog. Otherwise, you can pick them one by one.

Pro Tip: In the View menu you can also make the working set the top-level element. Only selected working sets are visible. You can see projects that aren’t in the working set in the Other Projects collection.


How do I set up dependencies between projects?

When working with a set of applications, you may wish to ensure that if you build one, the projects it depends upon build first.

In the project explorer, right-click a project and choose Properties. Click the Project References item. In the panel, select the projects on which this project depends.


What does it mean to close a project, and how do I do it?

A closed project requires no resources and is not affected by any workspace command (e.g., Build All).

To close projects, select them, right-click, and choose Close.

You can also select one you want to keep open, right-click, and choose Close Unrelated Projects. Every project not related to your selected project will close.

What is the difference between a local file and a linked file, and how do I tell which is which?

A local file is a file that exists inside the project directory. It is unique to the project that owns the file. Any change you make to this file has local effect only. You are changing the file in the project.

A linked file is a file that the project refers to, but it does not maintain a local copy. Most commonly, linked files are library source files. However, it can be a file anywhere that is used by reference. The project points to the original file and does not have a local copy. That means, if you change the linked file, you change every project that uses that file.

How can you tell which is which? This is a particularly subtle part of the Eclipse UI. The icon for a linked file has a tinyx` arrow. Like this.


How do I launch multiple instances of Eclipse on macOS?

By design, macOS allows one instance of an app. There is a way around this from the terminal. This is a macOS issue, not an Eclipse problem. From the terminal, do the following:

  1. Navigate to the application directory, for example: cd /Applications/eclipse/

  2. Open the app: open -n &

The & immediately sends the app to the background, and you now have two instances of Eclipse running.

Can I use an Eclipse IDE with a version control system?

The short answer is yes. However, you need to be careful about what gets checked in. The IDE does not restrict what it checks in. The IDE can add everything in a project, not just the files you want. As a result way too many files, including binaries, can get checked in. This can cause grief.

Although the Eclipse egit plugin typically manages this automatically, even then you can have problems. If the project builds with an error, inappropriate files will be checked in when you add files to source code control.

For starters, never commit the entire workspace into a version control system. Any Eclipse IDE maintains workspace metadata that is easily corrupted if you revert changes. So, do not check in your workspace, but do check in some of the content in your project folder.

You do not need to check in any files created in the build process. For example, anything in the final Build folder. You need to manage your version control system to exclude these files. For example, ensure that your .gitignore file lists any file or directory that should not be included.


How do I show line numbers?

Select Window > Preferences > General > Editors > Text Editors and find the Show line numbers option.

How do I search across all files in a project or workspace?

Use the Search menu. When the dialog opens, control the scope of the search with the options near the bottom of the dialog.

How do I go from a file listed in the project explorer to the actual file in the file system?

In the project explorer, right-click the file, choose Properties. In the dialog, note the Location field. Click the button to the right of the location.


I have multiple files of the same name open in the editor. How do I tell which project each one belongs to?

There are at least two ways to do this.

  • Hover over the tab in the editor. The project and path within the project to the file appear.


  • Enable the Link with Editor option in the explorer pane. When this is enabled, the file with focus in the editor is highlighted in the project explorer.


Build System

How do I build an application?

In the project explorer, select the project. In the Quick Panel click Build <appname> Application. You can also right click the project and choose Build Project. If there are dependent projects those build as well.

What does Build All build?

The Project > Build All command builds every open project in a workspace. You probably don’t want to use this command if you have more than one application in a workspace.

In addition, open projects can be hidden in the project explorer. If you hide an application and its projects (using working sets for example), those projects will still be built if they are open.

How do I add middleware or a library to a project?

In the project explorer, select the project. Then in the Quick Panel, click the Library Manager link. Click the Libraries tab to see all available libraries. You can select the version you want, as well as the library.

How do I set up an application to run on a different kit?

In the project explorer, select the project. Then in the Quick Panel, click the Library Manager link. Click the BSPs tab to see all available kits. If you are working with a code example, make sure that the example supports the kit you want to use.

What is the project’s makefile and what does it do?

For ModusToolbox, every application has a makefile. That file fully describes the application, including what board or kit to use, what tool chain to use, what files to use, what libraries to include, what compiler and linker flags control the build, and so on. See Running ModusToolbox from the Command Line for detailed documentation. You can also go to a community KBA on how to manage the makefile.

Where do I find build settings?

In ModusToolbox, compiler and linker settings are controlled by the makefile that describes the application. They are not set in the Eclipse UI.

There are many settings in the project’s properties that you may want to adjust. To see a project’s properties, use Project > Properties or right-click a project and choose Properties. Then navigate to the panel you need.


What is a build configuration?

The ModusToolbox makefile has two default build configurations, Debug and Release. Use the CONFIG variable in the makefile to choose which to use. For example, CONFIG=Debug. Before switching to a new build configuration, Clean the project. This will remove all the folders/files associated with a particular build configuration. Once the project is built with the new build configuration, click Generate Launches in the Quick Panel to regenerate the launch configurations targeting the new build configuration.

In an Eclipse IDE, a build configuration is a collection of all the project properties and build settings. Because ModusToolbox uses a makefile to specify build options, changing the Eclipse build configuration has no effect on how the ModusToolbox application builds.

Where do I specify compiler symbols and defines?

In the makefile that defines the application. See Running ModusToolbox from the Command Line for detailed documentation. You can also go to a community KBA on how to manage the makefile.

How can I tell if a build was successful?

The easy way is to look in the Problems tab of the console pane. The console window shows any errors, but they can be hard to find in the console log.


How do I terminate a build?

When you start a build, a progress bar appears in the bottom-right corner of the window. There is a little button to the right.


Click the button; the Progress tab opens in the Console area. It looks like this.


Click the red terminate button; the build stops.

Advanced Tip: Some builds are very quick, and every time a build ends, focus shifts back to the Console tab, foiling your attempt to cancel the build. You can change that behavior. Go to Window > Preferences > C/C++ > Build > Console and disable Bring console to top when building (if present). The Progress tab will now keep focus when it’s open.

I have an error that a symbol (e.g. bool or uint32_t) could not be resolved. What’s going on and what do I do about it?

The odds are this is a false positive. Other symbols defined in the file are fine, but one shows up as an error. The code builds despite this error.


This is a problem with the Eclipse code indexer. You can force a reindexing of the application. Right-click a project in the project explorer and choose Index > Rebuild. The error may persist, even if you rebuild the index.

It is possible that the file that defines the symbol may not be in the #include hierarchy. This is a real problem. In this case you would see many errors, not just one or two, because every symbol in the header file would be unresolved. Make sure the header is included and the problem goes away.


What are run and debug configurations?

Each of these is a collection of settings that control how the target is programmed and debugged. A run configuration programs the target and begins execution. A debug configuration does the same, but launches the debugger and (typically) stops execution at the first line of main(). A launch configuration can execute a combination of run and debug configurations.

A ModusToolbox project uses these configurations. In the Eclipse IDE for ModusToolbox, an application typically includes configurations named Attach, Erase, Program, and Debug. For details on how to program or debug, see the Program and Debug” chapter in the Eclipse IDE for ModusToolbox User Guide.

Where can I view the run and debug configurations?

All the available configurations can be found by clicking Run Configurations or Debug Configurations in the Run menu. You can edit the existing configurations or add new configurations. The easiest option when creating a new configuration is to duplicate an existing one so that some of the common settings can be preserved. To do this, right click on the closest matching existing configuration and then click Duplicate.



On Windows, after importing an Mbed project, creating a new or opening any existing PyOCD Run/Debug configuration causes the system to hang for 15-30 seconds. This is a known problem with Eclipse PyOCD plugin as it tries to enumerate the connected PyOCD compatible devices. The suggested workaround is to unplug the kit before opening the Eclipse Run/Debug configuration window and reconnecting the kit back once all modifications are complete.

My launch configurations disappeared, what do I do?

This happens when a project gets a new name, either when importing or by renaming. There are two ways to solve this problem.

The easy way: in the Quick Panel, click the Generate Launches command to regenerate launch configurations. This creates a new set of default launch configurations linked to your project.

If you have custom launch configurations, you can re-link the project to existing launch configurations. This is a classic example of well-hidden functionality in the Eclipse IDE. Here’s how to get it done. In the screenshots that follow, we renamed MyCoolApp to MyHelloWorld, so launch configurations vanished.

In the Run menu, choose Debug Configurations. In the dialog, open the Filter menu and uncheck Filter Deleted/Unavailable Projects. This allows you to see the launch configurations for the original project.


Then open one of the folders in the left column that now contains the formerly-filtered configurations. Select the debug configuration you want to associate with the renamed project. On the right side of the window, click Browse, and then select the project you want to use.


When you are done, the launch configuration appears in the Quick Panel and is available to your project.


I copied my project, and now it has two sets of launch configurations. How do I fix that?

In the Eclipse Project Explorer you can copy and paste to duplicate a project. When you do, a bug in Eclipse results in your original project having a duplicate set of launch configurations. The new copy (which is renamed in the process) has none.

To solve the problem with the new copy not having any launch configurations, see My launch configurations disappeared, what do I do? That answer also tells you how to connect the new copy to a custom launch configuration, if you have one.

As for the original project, the duplicate configurations appear in the Quick Panel Launches area. They have the same names, and you cannot easily tell which is which.

The simple solution is to go to the Eclipse workspace folder. Open the <new copy name>/.mtbLaunchConfigs folder. Delete the contents. Problem solved. This will wipe out any custom configuration as well, so be careful if you have one.

You can accomplish the same result using the Eclipse UI, but it is more tedious. In the Eclipse Project Explorer, select the original project (with the duplicate launch configurations). Use Run > Debug Configurations to open the Debug Configurations dialog. Select the Common tab. Select a debug configuration on the left of the dialog, the path to that configuration appears. Delete those configurations that exist in the new copy. Do this for each duplicate – select to find out if it is in the new copy, and delete it when it is. Be aware that this process deletes the launch configuration file in the new copy. So be careful if you have a custom launch configuration that you want to keep.


How do I start a debug session?

The simple way is to scroll to the Launches section of the Quick Panel. Then click the desired configuration. See the Program and Debug” chapter in the Eclipse IDE for ModusToolbox User Guide for details.

When I try to program or debug I get a connection error. What do I do?

Sometimes the error is self-explanatory, sometimes not. Here’s a fairly common error where you might need a little help understanding what’s going on.

Error: unable to find CMSIS-DAP device

Error: No Valid JTAG Interface Configured

The most common cause, you don’t have a board connected, or the board doesn’t have power. Connect or power up the board, and you should be fine. Another error you may see is:

Error: KitProg firmware is out of date, please update to the latest version using fw-loader tool

Many Cypress boards come from the factory with the older KitProg2 installed. ModusToolbox does not work with KitProg2. You need to upgrade the communication firmware on the kit to KitProg3, and the fw-loader tool does that.

In a nutshell, the firmware loader is a command line tool that comes with ModusToolbox software. You can use it to determine what KitProg is on your kit, and upgrade to KitProg3. You can also go back to KitProg2 if you need to.

The firmware loader tool is installed with the IDE. You can get the latest directly from the Firmware-loader GitHub repository.

How do I step through assembly code?

The ability to do this is not visible in the ModusToolbox perspective. Use the Debug perspective, which has this capability enabled by default. Perspective icons are at the top right of the IDE’s window. If the icon is not visible, use Window > Perspective > Open Perspective.


Then, in the Debug perspective’s Debug panel, enable the Instruction Stepping Mode button.


Pro Tip: You can modify the ModusToolbox perspective to make this option visible. Use Window > Perspective > Customize Perspective. Click the Action Set Availability tab. Turn on C/C++ Debug. The Instruction Stepping icon now appears in the ModusToolbox perspective

I like the Debug perspective better. How do I use it by default when I debug?

Use Window > Preferences > Run/Debug > Perspectives. In that panel, locate the GDB OpenOCD Debugging launcher, and change to the Debug perspective.


When debugging, how do I see variables, registers, and memory?

All this information appears in various views within the IDE. In the default ModusToolbox perspective:

Variables, Expressions, Breakpoints: near the Quick Panel - image29

Registers: near the Project Explorer - image30

Memory: near the Console - image31

If a view is not visible, select Window > Show View, and pick the view that you want. You can drag views to new locations, maximize or minimize, and manage the arrangement of views as you wish.

How do I see local variables?

The Variables view shows local variables. Any variable that is in scope should appear automatically in this view. This view does not and cannot display global variables.

How do I see global variables?

Use the Expressions view to see global variables. You can drag the variable name into this view or click Add new expression and type in the name. You can also use this view to create and evaluate complex expressions.

How do I see Peripheral registers?

The Peripherals view does not contain any peripherals by default because you must provide the path to the device hardware description .SVD file. The .SVD file is part of the PDL library, so it is available to any project that uses the PDL.

  1. Open the Debug Configurations dialog and select the appropriate OpenOCD debug launch configuration.

  2. Select the SVD Path tab and provide path to the .SVD file. The following .SVD files are available in the project folder, with the path libs/psoc6pdl/devices/svd/

    • psoc6_01.svd

    • psoc6_02.svd

    • psoc6_03.svd

    • psoc6_04.svd

    If you are unsure which SVD file to use, locate the header file specific for your part number in psoc6pdl>devices>include. Find the line of code that includes the general header file for the part. It will be similar to this, #include “psoc6_01_config.h”, and will include one of these files:

    • psoc6_01_config.h

    • psoc6_02_config.h

    • psoc6_03_config.h

    • psoc6_04_config.h

    Use the corresponding SVD file.


  3. Click Apply and then click Debug. When the debugger halts, notice that the Peripherals view contains various peripherals to select, depending on the application. Select any peripheral and you should be able to see the corresponding registers in the Memory window. You can edit the values of these registers if needed.


How do I edit the values of the variables?

In the Memory window, add the address of the variable to monitor as shown below:


Once added, the address of the variable will be rendered and highlighted with its value. You can now edit this value to whatever needed.


You cannot use this method to edit the addresses corresponding to peripherals. For editing peripheral registers, see How do I see Peripheral registers?


On Linux, the updated values may take some time to render because of an Eclipse bug. There is no workaround available at the moment.

When I start a debug session, an editor window appears that tells me there is a break at an address with no debug information available. But the debug* session starts fine. What’s going on and what do I do about it?

Here’s a typical warning with this “error.” The address mentioned will vary.


This is the warning that appears when a source file can’t be found. Sometimes that’s an actual problem, although in this case (the debug session starts fine) it isn’t.

You can configure Eclipse preferences to show this warning less frequently. Click the Preferences button in this window. That takes you to the general debug settings panel in Eclipse preferences, as shown below. The default is to show this window all the time.

Enable the Only if source file name is known but not found option. Then the warning appears when, in fact, a source file can’t be found.


When I terminate a debug session, the processor stops. How do I stop debugging but leave the processor running

In the Debug view, right-click the openocd process, and select Terminate. This shuts down the debug connection and leaves the processor running.


You can also select the openocd thread, and then click the Terminate button in the toolbar.

How do I remove terminated debug sessions from the Debug view?

A terminated debug session remains visible in the Debug view.


You don’t need to do anything. It is removed automatically when you start the next debug session. However, if you want to remove terminated debug sessions manually:

  • Select one or more and press the Delete key.

  • Right-click and choose Remove All Terminated.

How do I start debugging without downloading the executable again?

In Run > Debug Configurations, choose an Attach configuration.

Document History

Document Title: Eclipse IDE Survival Guide - KBA225399

Document Number: 002-25399



Orig. of Change

Description of Change




Initial release





  • A symbol (e.g. bool or uint32_t) is unresolved, what do I do

  • Can I change build settings at the application level


  • How do I get started building an application

  • How do I pick a compiler > my version of the GNU ARM toolchain

  • Several questions involving access to the project Properties window

  • How do I stop debugging but leave the processor running – updated the screenshot





  • What is the difference between a local file and a linked file,

  • When I try to program or debug I get a connection error.

  • Can I change the build configuration for every project in the application?


  • Relocated some questions for better flow

  • Can I change build settings at the application level

  • Added reminder to apply build settings changes to all build configurations

  • How do I start a debug session





  • Can I use an Eclipse IDE with a version control system?


  • Removed WICED-related content and references





  • When I try to program or debug I get a connection error.

Added the KitProg firmware is out of date error, and how to fix it





  • How do I step through assembly code?

  • I like the Debug perspective better. How do I use it by default?


  • How do I share an application and its projects?




Changes for ModusToolbox 1.1


  • screenshots where UI changes require

  • question on “what do I build” to reflect simpler project structure.

  • questions that mention multiple projects, where use case still applies

Removed questions on

  • changing device or platform

  • working sets and working with multiple projects

  • multiple instances of GenerateSource

  • building multiple projects – no longer a common use case.

  • handling the console log for multiple projects.

  • dual core debugging





  • How do I see variables, registers, and memory


  • How do I see local variables

  • How do I see global variables

  • How do I set up dependencies between projects

Restored & updated (from Rev *E)

  • What is a working set and why would I want to use one

  • How do I create a working set





  • How do I start debugging without downloading the executable again





  • How do I link to files instead of duplicating files

  • Project Creator questions

  • Library manager questions

Updates throughout for MTB 2.0

  • how to find and instantiate code examples and applications

  • eliminate the concept of multiple projects and a main app

  • relocated some questions to keep the same concepts together

  • renamed the question on the Quick Access panel

  • eliminate most discussion of build configurations – handled in the makefile

  • eliminate discussion of “no rule to make target” because the Eclipse auto-generated makefile is no longer created or used




  • minor fixes to UI terminology and grammar

  • added info on how to find Library Manager, and link to documentation

  • updated “How to create a working set” to make it more clear




  • removed most info unique to Eclipse IDE for ModusToolbox and point to User Guide as single source of truth.

  • Updated question on renaming

  • added some very general guidance on using a version control system

  • Added question on what to do when launch configurations disappear.

  • Minor wording enhancements and updates throughout for ModusToolbox 2.1




  • Substituted “ModusToolbox” for PSoC 6 MCU in one place, MTB will soon support PSoC 4. Trivial change.

  • Corrected a typo under “How do I share a project?”, In the first bullet, “file” was spelled as “fie”.




  • Added question/answer on duplicate launch configurations





  • What is a build configuration?

  • Updated links and cross references


  • What is a workspace?

  • Where can I view the run and debug configurations?

  • How do I see the Peripheral Registers?

  • How do I edit the values of the variables?