Eclipse IDE Survival Guide – KBA225399 *H

This document applies to ModusToolbox IDE v1.1. Version 1.0 has differences in UI and work flow. To see an earlier version of this document you must be logged in to the Community. Then:

  1. Click the Version identifier toward the top right of the document.
  2. In the comparison window that appears, on the left, pick the version you want to look at. You can ignore the rendering of differences on the right hand side.

Refer to version 32 of the document for ModusToolbox 1.0.

-----

ModusToolbox™ IDE is built on the Eclipse IDE. For those unfamiliar with an Eclipse IDE, this FAQ answers questions about how to get common tasks done.

If you are already familiar with an Eclipse IDE, you will find useful answers here on unique ModusToolbox IDE features such as the Quick Panel and how to build an application.

Questions are organized into the following categories:

  • Project Management
  • Editor
  • Build System
  • Program/Debug

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. A ModusToolbox IDE application usually consists of several Eclipse projects.

 

Project Management

How do I get started building an application using ModusToolbox IDE?

Use the Quick Panel New Application link (or select File > New > ModusToolbox IDE Application). Choose a kit (or a custom board and specify a device).

A list of available starter applications appears on the next screen. Select the one that most closely matches what you need. Or click Import to add a code example. See How do I get code example files onto my computer?

If this is the first application in a workspace, a PDL library project also appears. Second and subsequent applications reference the same PDL library project.

 

How do I share an application and its projects?

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 projects that make up 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.
  • To import projects from the file system, use File > Import > General > Existing projects into workspace; point to the root directory that contains the project(s) that make up the application. You must enable Copy project into workspace.

 

Pro Tip #1: Before archiving, select the projects in the project explorer. Then they are automatically selected for the archive.

 

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

 

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 ModusToolbox IDE use them?

In Eclipse, a perspective is the collection of panes and views visible in the user interface. The ModusToolbox IDE 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.

 

Where do I find code examples?

In the Quick Panel, click Search Online for Code Examples. This takes you to a Cypress GitHub repository that links to all available code examples for the ModusToolbox IDE. Read the ReadMe file that appears to find a code example of interest. The ReadMe file also has instructions for importing the code example into the IDE.

 

How do I get code example files onto my computer?

A code example is based on the project description in a file named modus.mk, and associated source code. So, this answer is really about how to get those files onto your computer.

First, in the IDE Quick Panel, click the Search Online for Code Examples link. That takes you to the Cypress GitHub site. Find the repository that contains the examples you want. Then click the Clone or download button.

There are three ways you can get the contents of this repository onto your machine.

Git Import

  1. Copy the URL on GitHub, and then select File > Import > Git > Projects from Git.
  2. Follow the steps in the import wizard. The URL appears automatically in the wizard. Provide your GitHub user name and password. Specify a destination directory on your hard drive. Use the Import as a general project option because there are no Eclipse projects in the repository.

The contents of the repository are cloned to your hard drive. As noted above, these are not Eclipse projects, so you can’t build them. But the modus.mk file for each example is there. The files also appear in the project explorer in the IDE. You can study them, copy and paste source code, and so on, without ever having to create or build the example as an application.

Git Clone

Copy the URL from GitHub and use the git clone command in your git environment (either desktop or command line. If you have the GitHub desktop client, click Open in Desktop.

Download a ZIP file

Click the Download Zip button. A zip file appears in the default download location for your web browser. You must unzip the package to use its contents.

 

How do I create an Eclipse project based on a code example?

First, you must have the required modus.mk file on your machine. See How do I get code example files onto my computer?

After you have the code example files, use the Quick Panel New Application link and pick a kit supported by the code example.

On the next Starter Application panel, click the Import button.

 

Navigate to the code example location on your computer and select the modus.mk file for the example you want to create. Then complete the application creation process.

Depending upon how you retrieved the code example repository, the modus.mk file may be in one of the following locations:

  • destination you chose (if you used Git Import)
  • your GitHub folder (if you used git clone)
  • destination you chose (if you downloaded and unzipped a zip file)

   If this is the first application in a workspace, a PDL library project also appears. Second and subsequent applications reference the same PDL library project.

 

 

How do I rename an application?

In the project explorer, right-click the <application name>_mainapp folder that belongs to the application. Then choose Rename and provide the new name..

 

 

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.

To delete the project permanently, enable the Delete project contents on disk option. Project deletion cannot be undone.

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. Use the View drop-down menu in the project explorer 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.

In the View menu you can make the working set the top-level element. Only selected working sets are visible. You can show 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.

Let us use an application and the PDL driver library as an example.

In the project explorer, right-click the main app and choose Properties. Click the Project References item. In the panel, select the projects on which the main app 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 in your workspace. 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 tiny 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 Mac OS 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 Eclipse.app &

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

 

What is the Quick Access field for?
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.

 

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.

At a minimum, do not check in these folders or their contents:

  • .metadata from the workspace
  • Debug from any project
  • Release from any project

You need to manage your version control system to exclude these files. For example, ensure that your .gitignore file lists these directories.

(The Debug and Release folders are the output folders for the standard build configurations defined for ModusToolbox projects. There are no source or original files in these directories.)

 

Editor

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 _mainapp project. In the Quick Panel click Build <appname> Application. This command ensures that the PDL library project is current, and build the library if necessary.

 

What does Build All actually 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 build just one Eclipse project?

Right-click on the project and choose Build Project. However, if there are dependent projects, they will build as well.

 

How do I add middleware?

In the project explorer, select the mainapp project. Then in the Quick Panel, click the Select Middleware link. A dialog with available middleware appears. Enable the middleware that you want added to the mainapp project.

 

Where do I find build settings?

These settings are in the project’s Properties window. There are at least three ways to get to this window.

  • Right click a project and choose Properties. Then navigate to the settings panel you need.
  • Select a project in the project explorer and choose Project > Properties. Then navigate to the settings panel you need.
  • Select a project in the project explorer. Then, in the Quick Panel click the Project Build Settings link.

The Quick Panel link opens the Properties window, and automatically opens the C/C++ Build > Settings panel in that window. This is where most of the compiler options are located, so the Quick Panel link is a good shortcut. There are multiple tabs and subpanels that allow you to set compiler options.

 

What is a build configuration?

A build configuration is a collection of all build settings. For example, you may set up a debug build, a release build, an optimized build, and so forth. Each would have different settings based on the needs of the build. You switch settings by switching build configurations.

 

How do I create a build configuration?

In the project explorer, select the project that you want to modify. Set the build settings as you wish them to be. Then use Project > Build Configurations > Manage. Click New to create and name the build configuration.

 

How do I switch to a different build configuration?

In the project explorer, select the project that you want to change. Then use Project > Build Configurations > Set Active and pick the configuration that you want to use.

You can also pick the build configuration to use from the Build icon in the toolbar, but that also starts a build.

 

Can I change the build configuration for multiple projects at once?

Yes. In the project explorer, select the projects. Then use Project > Build Configurations > Set Active and pick the configuration you want to use. The change applies to all selected projects.

 

Can I change a build setting for multiple projects at once?

No. Build settings apply to the project. If if you want to modify a build setting for multiple projects (change the optimization level for example), modify the setting in each project affected.

However, you can apply the change to all build configurations in the project (e.g. Debug and Release). In the Properties window, click the Configuration drop down menu, and pick All configurations.

 

Where do I specify compiler symbols and defines?

 

In the project Properties window, navigate to the C/C++ Build > Settings panel. Click the Tool Settings tab and select the GNU ARM Cross C Compiler > Preprocessor panel. You may wish to apply this change to all build configurations. Use the Configuration drop down menu in the Properties window.

 

How do I pick my version of the GNU ARM toolchain?

In the project Properties window, expand MCU and select ARM Toolchain Paths.

 

Where do I specify include paths?

In the project Properties window, navigate to C/C++ General > Paths and Symbols. Include paths are on the Includes tab. You may wish to apply this change to all build configurations. Use the Configuration drop down menu in the Properties window.

 

Where do I specify path variables?

In the project Properties window, navigate to Resource > Linked Resources, and click the Path Variables tab. You may wish to apply this change to all build configurations. Use the Configuration drop down menu in the Properties window.

 

 

Where do I manage paths for shared resources?

For a connected application, there is a <project name>_resources project. Right-click and choose Properties. In the properties dialog, click to display the Builders panel. Then select Generate Resources and click Edit.

You can then edit the configuration. The paths to resource files are in the Arguments section.

 

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.

 

What does the "no rule to make target" error mean, and what do I do about it?

This common Eclipse error usually means that the build system cannot find a file. More precisely, the project's make file no longer matches the contents of the project. A missing file is the most likely cause. Why it can't find the file is a whole other issue. But first, the solution, then the why.

 

The solution is usually simple. First, Clean the project. When you build, the make file is updated. This usually fixes the problem, but it may not.

If the error persists, delete the Debug folder from the project. This is the default build directory in the ModusToolbox IDE. Deleting this removes all output files, which include the automatically generated make file. When you build the code, a new make file is created.

At this point, if the error persists, there is probably a "structural" problem with the project. For example, include paths may be incorrect. You need to debug why the file noted in the error message is not being found.

 

Now, for the why:

By default, an Eclipse IDE creates make files automatically. The ModusToolbox IDE is no exception. However, if a project already has a make file, the IDE uses it. If the make file is outdated for some reason, this is the error you'll see.

For example, perhaps you imported a project from an archive, and it already has a make file that points to locations on someone else's computer. Especially when importing a project from someone else, always Clean first, ask questions later.

Finally, a rare cause of this problem is when, for some reason, an Eclipse IDE terminates unexpectedly and a make process that it spawned remains active. A symptom of this root cause is an inability to build or clean any project. If you suspect this edge case, first quit the IDE. Then use the appropriate tool (e.g. Windows Task Manager or Mac OS Activity Monitor) to see if there is still a make.exe running as a process on your host machine. If it is, terminate the process and try again.

 

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.

 

Program/Debug

The build process generates several .elf files. Which is the complete application?

This is documented in the "Generated HEX/ELF Files" section in the ModusToolbox IDE User Guide. See the User Guide for full details. For a PSoC 6 MCU application, mainapp_final.elf is the complete image. The IDE's run and debug configurations are set up to use the correct file.

 

 

What are launch, 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.

PSoC 6 MCU projects use these configurations. In the ModusToolbox IDE, an application includes configurations named Erase, Program, and Debug.

For details on how to program or debug either a PSoC 6 MCU project, see the Program/Debug with ModusToolbox IDE” chapter in the ModusToolbox IDE User Guide.

 

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.

A ModusToolbox IDE application typically has a Program and a Debug configuration. The Program configuration builds the code, downloads the code to flash and begins execution. The Debug configuration does the same but launches a debug session as well.

See the Program/Debug with ModusToolbox IDE” chapter in the ModusToolbox IDE 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.

 

Documentation has the full instructions, including where to find the tool: ModusToolbox IDE User Guide, Programming and Debugging chapter, KitProg Firmware Loader section. Note particularly that when using KitProg2, the firmware must be in the right operating mode for fw-loader to connect. This is all covered in the documentation.

 

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.

 

 

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 - 

Registers: near the Project Explorer - 

Memory: near the Console - 

 

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.

 

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.

The Quick Panel link opens the Properties window, and automatically opens the C/C++ Build > Settings panel in that window. This is where most of the compiler options are located, so the Quick Panel link is a good shortcut. There are multiple tabs and subpanels that allow you to set compiler options.

Pro Tip #1: Before archiving, select the projects in the project explorer. Then they are automatically selected for the archive.

 

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

Use the Quick Panel New Application link (or select File > New > ModusToolbox IDE Application). Choose a kit (or a custom board and specify a device).

 

How do I start debugging without downloading the executable again?

The debug configurations that come with ModusToolbox IDE download the executable. Turn off the Load executable option in the Debug configuration. For more information, see KBA226785.

 

How do I start debugging without downloading the executable again?

The debug configurations that come with ModusToolbox IDE download the executable. Turn off the Load executable option in the Debug configuration. For more information, see KBA226785.

KBA226785