Author: JamesT_21 Version: *M
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 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 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.
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 > 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 fie: 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.
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:
- In the project explorer, first select all the projects you want in the working set.
- In the project explorer, use the View drop-down menu and choose Select Working Set.
- 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 tiny arrow. Like this.
How do I link to files instead of duplicating files in each project that uses them?
This is easy, but obscure. You can link to a single file, or an entire folder full of files.
Use File > New > Other, select Folder (or file) and click Next.
In the resulting dialog, specify the parent folder that will hold the new linked folder in the Project explorer. Click Advanced. Then Click Link to alternate location (Linked Folder). Click the Browse button and navigate to the folder you want to link to the project. Instead of an absolute path, you can use path Variables to specify the location. The folder name is set automatically, but you can rename it whatever you want.
Click Finish and you’re done. The project now has a link to the folder and its contents. All the files in the folder appear, you do not need to add them individually. If you change a file, any project that uses that file is affected. In the project explorer it looks like this:
The folder icon has a tiny arrow, which means this folder and its contents are linked, and not in the project folder.
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:
- Navigate to the application directory, for example: cd /Applications/eclipse/
- Open the app: open -n Eclipse.app &
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.
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.
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?
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.
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:
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.
How do I start debugging without downloading the executable again?
In Run > Debug Configurations, choose an Attach configuration.