MIGRATING APPLICATIONS FROM MODUSTOOLBOX V2.0/2.1 TO V2.2 - KBA231080

Version 3

    Version: **

     

    Note: If you are migrating an application created for an older version of ModusToolbox® (v1.1) refer to Migrating from ModusToolbox v1.1 to v2.x - KBA229043.

     

    ModusToolbox 2.2 fully supports applications created using v2.0/2.1 of the tools. That is, existing applications can be used with v2.2 tools and configurators without requiring any application changes. The application dependencies like Board Support Packages (BSPs) and libraries can also be updated to latest available versions supported by ModusToolbox 2.2.

     

    Beginning with the ModusToolbox 2.2 release, a new way of structuring applications has been developed, 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. Sharing resources reduces the number of files on your computer and speeds up subsequent application creation time. Shared BSPs, libraries, and versions are located in a new mtb_shared directory by default adjacent to your application directories. You can easily switch a shared BSP or library to become local to a specific application, or back to being shared. Refer to the MTB Flow section in Library Manager User Guide for more details.

     

    Looking ahead, most example applications will use the new MTB flow. Applications that use the previous flow, now called the LIB flow, generally do not share BSPs and libraries. Applications can be migrated to the MTB flow to benefit from the new features like sharing libraries.

     

    The easiest way to migrate existing applications to the MTB flow is to start with a ModusToolbox 2.2 application closest to yours, and port the source code over:

     

    1. Use Project Creator (v1.2) or the Eclipse IDE for ModusToolbox v2.2 to create a new application using a similar BSP and code example to yours. Use “mtb-flow” keyword in the search field to show applications that are compatible with the MTB flow.

     

    2. Use the Library Manager (v1.2) and add any needed libraries.

    Notice that a new Shared checkbox is available, which can be used to place the selected library in a shared folder (when checked) or in a folder local to the application (when unchecked). Presence of the Shared checkbox indicates that the application uses the MTB flow.

     

    pastedImage_4.png

     

    3. Select the Version of the library if the default is not what you want. Only the versions compatible with the MTB flow are displayed. Click the ‘Update’ button after selecting all libraries.

    Note: Applications that use the MTB flow and target PSoC 6 BSPs need to use BSP version 2.0.0 or later (Latest 2.X release). PSoC 6 BSP v2.X is a major update to the v1.X release and is not backward compatible.

     

    4. Copy the source code and application configuration from the old application to the new one.

     

    This completes the application migration.

    The following section explains the changes in the structure and content of an application supporting the MTB flow, as compared to the LIB flow, for better understanding. These changes are already done as part of project creation using ModusToolbox 2.2 tools from a code example already updated to the MTB flow, if you followed the steps described above.

     

    Makefile

     

    1. For PSoC 6 applications, the following variable should be removed:

     

    # Relative path to the "base" library. It provides the core makefile build infrastructure.

    CY_BASELIB_PATH=libs/psoc6make

     

    For an application to be detected as using the MTB flow, the application makefile must contain the CY_GETLIBS_SHARED_NAME and CY_GETLIBS_SHARED_PATH make variables. These variables define the name and location of the shared directory where source code for all BSPs and libraries are placed. The values shown below puts the libraries in a mtb_shared folder by default. Also, by default, this shared directory is located adjacent to application directories in the same application root path. For more details about the ModusToolbox build system and make variables, refer to the ModusToolbox User Guide.

     

    # Relative path to the shared repo location.

    CY_GETLIBS_SHARED_PATH=../

     

    # Directory name of the shared repo location.

    CY_GETLIBS_SHARED_NAME=mtb_shared

     

    1. For applications that consist of multiple dependent projects (for example, a dual CPU application), some additional changes are required:

     

    a. Each dependent project usually resides within its own folder within the application folder. The CY_GETLIBS_SHARED_PATH variable should point to two levels up relative to the dependent project folder, if it’s required to share the libraries with other applications:

     

    CY_GETLIBS_SHARED_PATH=../../

     

    b. Remove the following variables, if they exist:

    # Link to the library folder

    CY_EXTAPP_PATH=../shared/libs

     

    # Link to the devicesupport.xml file

    CY_DEVICESUPPORT_PATH=$(CY_EXTAPP_PATH)/psoc6pdl

     

    # Get the absolute address where the Makefile is located

    mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST)))

    mkfile_dir := $(dir $(mkfile_path))

     

    # Set path to the shared folders

    CY_GETLIBS_PATH=$(mkfile_dir)/$(CY_EXTAPP_PATH)

     

    c. Add the following lines to the primary project's makefile. This enables running make getlibs on the primary project to automatically invoke getlibs on the secondary project. Replace <secondary_project_name> with the folder name of the secondary project.

     

    getlibs : getlibs_secondary

    getlibs_secondary:

    $(MAKE) -C ../<secondary_project_name>/ $(MAKECMDGOALS)

     

     

    CYIGNORE file

     

    Applications can use the. cyignore file to exclude code files or directories from the build process.

     

    If existing applications contain paths to standard libraries in the cyignore file, replace these paths with the corresponding SEARCH_<library name> variable.

    For example, replace "libs/psoc6cm0p" with $(SEARCH_psoc6cm0p).

     

    The values of SEARCH_<library name> variables are auto-generated as part of running make getlibs and are available in the mtb.mk file in the application libs folder.

     

    Note: The following library names have changed. Please use the new names indicated:

     

    Old name

    New name

    SEARCH variable

    psoc6pdl

    mtb-pdl-cat1

    $(SEARCH_mtb-pdl-cat1)

    psoc6hal

    mtb-hal-cat1

    $(SEARCH_mtb-hal-cat1)

    psoc6make

    recipe-make-cat1a

    $(SEARCH_recipe-make-cat1a)

     

     

    .mtb Files

     

    These files provide information about the associated BSP/library. Each .mtb file contains:

      • A URL to a git repository somewhere that is accessible by your computer such as GitHub.
      • A git Commit Hash or Tag that tells which version of the library that you want.
      • A path to where the library should be stored.

     

    An .mtb file contains a string that has the format <URI>#<COMMIT>#<LOCATION>, for example:

     

    https://github.com/cypresssemiconductorco/TARGET_CY8CPROTO-062-4343W#latest-v2.X#$$ASSET_REPO$$/TARGET_CY8CPROTO-062-4343W/latest-v2.X

     

    The variable $$ASSET_REPO$$ points to the path defined by CY_GETLIBS_SHARED_PATH/CY_GETLIBS_SHARED_NAME, so the default value is ../mtb_shared.

     

    If you want a library to be local to the application instead of shared, use $$LOCAL$$ instead of $$ASSET_REPO$$:

     

    https://github.com/cypresssemiconductorco/TARGET_CY8CPROTO-062-4343W#latest-v2.X#$$LOCAL$$/TARGET_CY8CPROTO-062-4343W

     

    There are two ways to create a .mtb file:

     

    1. Using the Library Manager (applicable if the BSP/library is provided by Cypress or is in a custom manifest file):

      • Open the Library Manager and navigate to the application directory.
      • Use the check boxes under the Shared column to indicate if a BSP/library should be shared or local and select the version from the Version column.
      • Click on the Update button to apply the changes.

     

    The .mtb files for the selected libraries are created in the application’s deps folder.

     

    2. Manually the create the .mtb file by editing a .lib files present in the deps folder of your existing application. Ensure the .mtb file content follows the correct format and change the file extension to .mtb.

     

    Note: An application can either contain .lib files or .mtb files to declare dependencies, but not both. If a .mtb file is found, .lib files will be ignored during the make getlibs process.

     

    Note: If a library is not in a manifest file, it will not appear in the Library Manager and will need to be managed manually. See the Manual Library Management section in the Library Manager User Guide for details.