ModusToolbox Project Creator Guide¶
The Project Creator tool is used with the ModusToolbox software to create applications based on Board Support Packages (BSPs) and code examples. It is provided as a graphical user interface (GUI) and a command-line interface (CLI) to create applications for use in any software environment you prefer. The GUI provides a simple interface for users who do not want to use the CLI.
Manifest files determine which BSPs and code examples display for use in the Project Creator tool in order to create applications. These files are located by default on GitHub. If for some reason your system cannot access these manifest files, then you will not be able to create an application.
KBA230953 describes methods for working around this issue.
The Project Creator tool essentially runs a “git clone” command to create one or more applications onto your computer from a remote server. It also runs the “make getlibs” command to import the necessary libraries.
Different types of applications will have different files and directory structures. After creating the application(s), navigate to the specified root directory. Inspect the files and directories located there. Use these files to modify your application(s) as necessary in your preferred environment.
The Project Creator tool generates a log file named project-creator.log in the Application(s) Root Path. This log file captures all commands run by the tool. It will be overwritten if you create a new application in the same path.
Refer to the ModusToolbox User Guide for more details about make commands, BSPs, and the overall structure of ModusToolbox applications.
Library Management Flows¶
For ModusToolbox 2.2 and later, we implemented a new way of structuring applications, called the MTB flow. Using this flow, applications can share BSPs and libraries. If needed, different applications can use different versions of the same BSP/library. Shared BSPs, libraries, and versions are located in a directory named mtb_shared, which is adjacent to your application directories in the same root path. Refer to the Library Manager User Guide for details.
Looking ahead, most example applications will use the new MTB flow. However, there are still various applications that use the previous flow, now called the LIB flow. These applications generally do not share BSPs and libraries, and these BSPs and libraries are located in an application’s libs subdirectory. ModusToolbox fully supports both flows.
Launch the Project Creator¶
You can launch the Project Creator as a stand-alone GUI tool, from the Eclipse IDE for ModusToolbox, and from the command line.
If you prefer to use the Eclipse IDE, you should launch Project Creator tool from the Eclipse IDE included with ModusToolbox instead of as a stand-alone tool or from the command line.
As a Stand-Alone GUI Tool¶
You can launch the Project Creator as a stand-alone GUI tool. By default, it is installed here:
On Windows, launch the GUI tool from the Start menu. For other operating systems, navigate to the install location and run the project-creator executable.
From Eclipse IDE¶
The Eclipse IDE included with ModusToolbox provides links and menu items to launch the Project Creator tool and create a project that applies to Eclipse.
As a Command-Line Tool¶
To run the Project Creator as a stand-alone tool, navigate to the install location and run the project-creator-cli executable. By default, it is installed here:
For more information about command-line options, run the project-creator-cli executable using the -h option. See CLI Description later in this document for an example.
The Project Creator GUI provides a series of pages used to create a project. The GUI executes the CLI options based on your selections.
Choose BSP Page¶
When you first launch the GUI, it displays the “Choose Board Support Package (BSP)” page that lists the available BSPs.
The “Choose BSP” page provides an Import button to select any custom BSPs you may have created or received from a colleague. You can then create a new application for that custom BSP. After clicking the Import button, the Find Directory dialog opens to select the appropriate custom BSP. Navigate to the appropriate directory containing the BSP to import and click Choose.
The tool checks that the BSP to be imported has a makefile, but it does not validate the makefile for correctness.If the selected BSP has a makefile, it is added to the list with all the other BSPs.
If the BSP does not have a makefile, a message displays asking whether to continue with the selected BSP or not. Select Yes to proceed with the selected BSP. Select No to close the dialog, and then either navigate to another directory to find the BSP or cancel the import operation.
Custom BSPs created using the make bsp command include .mtbx files that provide pre-fetched library information. The Project Creator tool converts .mtbx files into .mtb files that are processed by the make getlibs command to acquire the necessary libraries.
For information about creating custom BSPs, refer to the ModusToolbox User Guide.
Select Application Page¶
Select a board on the Choose BSP page and click Next > to display the “Select Application” page.
On this page:
Specify the Application(s) Root Path, or leave it as the default. All files and folders from the application(s) with a selected check box will be copied to this location in a folder with the Application Name(s).
Optionally pick an item from the Target IDE pull-down menu, which will generate the necessary files for the selected target. For more details, refer to the “Export to IDEs” chapter in the ModusToolbox User Guide.
If you launch the Project Creator tool from the Eclipse IDE, “Eclipse IDE for ModusToolbox” is the only option available and it cannot be changed.
Select one or more check boxes for applications in the list. You can click on the check box or use the right-click context menu. See Select Multiple Applications for more details.
Type a New Application Name for the application(s) with a selected check box, or leave the name as the default.
The “Select Application” page contains a toolbar with options to assist with the process, including:
Search – Shows applications that include the text as entered. See Using Search for more details.
Import – Allows you to add other applications to the list. See Import Application.
Show/Hide – Toggle to show only the applications with check boxes selected or show all applications. If there is search text, then only applications with check boxes selected and applications with matching search text will be shown instead of all.
Select All – Select the check boxes for all applications currently shown in the list.
Unselect All – Unselect the check boxes for all applications currently shown in the list.
Select Multiple Applications¶
The “Select Application” page allows you to select multiple applications, as follows:
Click multiple check boxes next to the applications.
Click to highlight an application, then press and hold [Ctrl] and click additional applications.
Click to highlight an application, then press and hold [Shift] to select a range applications.
When you have multiple applications highlighted, right-click to open the context menu Select Highlighted Applications.
Enter text in the Search field above the list of applications to limit the number of applications shown. This can make it easier to decide which application(s) to select. Text entered in this field is searched against keywords in the application’s manifest, title, and description. Along with applications that match the search, any imported applications are included at the beginning of the list, and any applications with a selected check box are included at the end of the list.
You can enter text with spaces, and they are treated as separate search terms. You can also use a quoted phrase, such as “psoc 6”, which is treated as a single term.
The Select Application page also provides an Import button to select other applications you may have created or received from a colleague. After clicking the Import button, the Find Directory dialog opens. Navigate to the appropriate directory containing the application to import and click Choose.
Ensure that you only select an application supported by the BSP you selected on the Choose BSP page.
The tool checks that the application to be imported has a makefile, but it does not validate the makefile for correctness. If the selected application has a makefile, it is added to the list with the other applications.
If the application does not have a makefile, a message displays asking whether to continue with the selected application or not. Select Yes to proceed with the import. Select No to close the message without importing, and then navigate to another directory to find an application or cancel the import operation.
Create an Application¶
Click Create to start the process of creating a ModusToolbox application, and the GUI will display various messages showing the progress.
During the project creation process, the tool automatically selects the best pair of BSP and application versions from the manifest file. The selection process has the following preferences:
Versions that support the .mtb file flow (see Library Management Flows) are preferred over versions that support the .lib file flow.
Release versions are preferred over any custom name versions.
Using the command line (see CLI Description), you can manually select which version to use. If the BSP and application flow versions match, then the project-creator tool will create a project. If not, then it will show an error.
The GUI always shows applications that have at least one application version that is supported by at least one BSP version.
When the process competes, the tool will display a message similar to the following:
You can continue creating new projects from the “Select Application” page by selecting a new application and then clicking the Create button again. You can also go back to the “Choose BSP” page to select another BSP and then continue the project creation process as usual.
To close the tool, click the Close button or the X button at the top-right of the GUI.
If you launched the Project Creator tool from the Eclipse IDE, the Project Creator tool closes automatically upon completion, and the IDE will import the created application(s).
The CLI allows creating projects from a command-line prompt or from within batch files or shell scripts. The exit code for the CLI is zero if the operation is successful, or non-zero if the operation encounters an error.
Usage project-creator-cli [options]
To see a list of options, run the executable with the -h option.
–board-id CY8CKIT-062-WIFI-BT \
–app-id BlinkyLED \
–user-app-name MyLED \
This section lists and describes the changes for each version of this tool.
Redesigned the GUI to provide a better flow.
Added Settings and Help menus.
Added icon to indicate online/offline status.
Added Import BSP button.
Tool can be launched from Windows Start menu.
Updated versioning to support patch releases.
Updated to select and create multiple applications at one time.
Updated to provide information about new library management flow.
Updated versioning to allow for additional minor changes.
Updated the import process to check if the BSP/application includes a makefile.
Added Target IDE option to the GUI.
Added colors to the messages; red for error, yellow for warning, green for success.