The Library Manager provides a GUI to select which Board Support Package (BSP) should be used when building a ModusToolbox™ application. The tool collects a list of available and currently selected BSPs and libraries, as well as all the necessary metadata from a webservice. The tool allows you to add and remove BSPs and libraries, as well as change their versions.

ModusToolbox™ 3.x vs. 2.x BSPs​

One of the major changes made for ModusToolbox™ version 3.x is that most BSPs are no longer Git repos when you create a version 3.x application. Instead, the BSP becomes owned by the application. This means you can change various aspects of the BSP as you see fit without having to create a custom BSP, because creating a version 3.x application effectively creates a custom BSP. As such, you will typically check the BSP into source control with the application.

ModusToolbox™ version 2.x BSPs are still Git repos, by default, and may be used by more than one application in a given workspace. In general, this means any change you make to a BSP creates a "dirty" repo, and those changes affect all the related applications. In this case, you will typically not check the version 2.x BSP into source control, since you can regenerate the BSP. For this reason, it is best to create a "custom BSP" for your needs.

Note:

BTSDK applications still default to shared BSPs, due to the nature of how BTSDK applications are structured and typical use cases.

Refer to the

ModusToolbox™ tools package user guide

for more details about ModusToolbox™ BSPs and applications.

This version of the Library Manager supports both ModusToolbox™ version 3.x and 2.x BSPs. The main difference is that the

Version

and

Type

fields are not applicable and cannot be changed for a 3.x BSP. See the

Properties tab

section later in this document for descriptions of these fields.

Specifying dependencies​

This document only applies to applications that use .mtb files to specify their dependencies, not .lib files. To find information for applications that use .lib files, refer to an

older version of this document

.

Applications can share libraries. If needed, different applications can use different versions of the same library. Sharing resources reduces the number of files on your computer and speeds up subsequent application creation time. Shared libraries and versions are located in a "mtb_shared" directory adjacent to your application directories. You can easily switch a shared library to become local to a specific application, or back to being shared.

The Library Manager runs the make getlibs command to process the .mtb files, pull the libraries from the specified git repos, and store them in the specified location. The system also creates a file called mtb.mk in the application's libs subdirectory. The build system uses that file to find all the libraries required by the application.

The following shows the Library Manager for a typical PSoC™ 6 BSP. The key items are the lock symbols for libraries that are included because they are dependencies of other libraries. See

Working with libraries

for more details about using the tool.


../figures/image4.png

The following concepts are key to understanding dependencies:

.mtb file​

This file provides information about the associated BSP/library. It 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.

A typical .

mtb

file looks like this:

https://github.com/Infineon/core-make#release-v3.0.0#$$ASSET_REPO$$core-make/release-v3.0.0

The variable

$$ASSET_REPO$$

points to the root of the shared location. If you want a library to be local to the application instead of shared, use

$$LOCAL$$

instead of

$$ASSET_REPO$$

.

Direct dependency​

This is a library that is directly referenced by an application. In some applications, there will be direct dependencies such as Wi-Fi or Bluetooth libraries. You may also have changed the location or version of an indirect library, which makes that library a direct dependency.

You manage the .mtb files for direct dependencies, and .mtb files should be checked into source control along with your application source code. A .mtb file for a direct dependency is typically stored in the application’s deps subdirectory by default. You can store it anywhere inside the application except in the application's libs subdirectory.

Indirect dependency​

This is a library that was included indirectly as a dependency of a BSP or another library. The system stores the code in the appropriate directory and resolves any potential conflicts with different library versions.

The system finds indirect dependencies for each library using information that is stored in a manifest file. For each indirect dependency found, the Library Manager places an .

mtb

file in the application's

libs

subdirectory. The tool also creates an

assetlocks.json

file in the application's

deps

subdirectory to record the locked release version of those libraries.

You do not manage .

mtb

files for indirect dependencies, and they do not need to be checked into source control. The .

mtb

file for an indirect dependency is stored in the application’s

libs

subdirectory and must not be moved.

Shared​

A shared library includes the code for the associated .

mtb

file, and the library can be shared by multiple applications in the same directory structure or workspace. When creating a new application, BSPs/libraries can be shared and placed in an

mtb_shared

directory adjacent to the application directory(ies), based on the "default_location" in the manifest file. When you add a BSP/library and specify it as shared, it is also included in the

mtb_shared

directory. These BSPs/libraries do not need to be checked into source control. All the code can be re-downloaded at any time from the information in the .

mtb

file.

You can change the name and location of the shared directory using make variables

CY_GETLIBS_SHARED_NAME

and

CY_GETLIBS_SHARED_PATH

. For more details about the ModusToolbox™ build system and make variables, refer to the

ModusToolbox™ tools package user guide

.

Local​

A local library includes the code for the associated .

mtb

file, and the BSP/library is used only for a specific application. The local BSP/library is stored in the

libs

subdirectory of the specific application. These BSPs/libraries do not need to be checked into source control. All the code can be re-downloaded at any time from the information in the .mtb file.

If you change libraries to be local to an application (see

Add library (single-core application)

later in this guide), then the source code for these are located in the

libs

subdirectory inside the application directory.

Including libraries and dependencies​

There are two basic ways of including a library and its dependencies into your application: using a manifest file or using manual methods. There is also a third method that is only used for custom BSPs. Each method is discussed separately below. The method you should use depends on whether or not the library and its dependencies are specified in a manifest file.

Including libraries that are specified in a manifest​

All libraries provided by Infineon are specified in manifest files that are automatically found by the tools. Manifests are XML files that tell the Library Manager how to discover the list of available BSPs, libraries, and library dependencies. The manifest can also specify specific versions of libraries and dependent libraries that are meant to work together. For more information, refer to the Manifest chapter in the

ModusToolbox™ tools package user guide

.

You can create your own manifest file(s) for your libraries so that they will show up in the Library Manager and will work just like the Infineon libraries. More information on manifest files and how to create and use your own manifests is covered in the ModusToolbox™ tools package user guide.

In order to manage libraries that are specified in a manifest file in the application, files with the extension mtb are used. Their location and behavior depend on whether the library is a direct dependency or an indirect dependency. Normally the Library Manager is used to create/modify

mtb

files so you won't need to change them or even view them, but it is worthwhile to understand what is in them.

Direct dependencies​

For direct dependencies, there will be one or more

mtb

files somewhere in your project (typically in the

deps

directory but could be anywhere except the

libs

directory). An

mtb

file is simply a text file with the extension mtb that has three fields separated by #:

  • 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 in the shared location (that is, the directory path underneath

    mtb_shared

    ).

A typical mtb file looks like this:

<a className="xref" href="https://github.com/cypresssemiconductorco/retarget-io/" rel="external noopener" target="_blank">
https://github.com/cypresssemiconductorco/retarget-io/#latest-v1.X#$$ASSET_REPO$$/retarget-io/latest-v1.X
</a>

The variable

$$ASSET_REPO$$

points to the root of the shared location - it is specified in the application's

Makefile

. If you want a library to be local to the app instead of shared, you can use

$$LOCAL$$

instead of

$$ASSET_REPO$$

in the mtb file before downloading the libraries. Typically, the version is excluded from the path for local libraries since there can only be one local version used in a given application. Using the above example, a library local to the app would normally be specified like this:

<a className="xref" href="https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012/" rel="external noopener" target="_blank">
https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012/#latest-v1.X#$$LOCAL$$/TARGET_CY8CKIT-062S2-43012
</a>

Note:

The examples above specify dynamic library versions (e.g. latest-v1.X). Normally in your application, you will want fixed library versions (e.g. release-v1.0.0). This behavior can be controlled using the Library Manager.

Indirect dependencies​

For indirect dependencies, an

mtb

file for each library is automatically created in the

libs

directory. The version of each dependent library is also captured in the file

assetlocks.json

in the

deps

directory.

Once all the

mtb

files are in the application (both direct and indirect), the libraries they point to are pulled in from the specified Git repos and stored in the specified location (that is,

mtb_shared

for shared libraries and

libs

for local libraries). Finally, a file called

mtb.mk

is created in the application's

libs

directory. That file is what the build system uses to find all the libraries required by the application.

Since the libraries are all pulled in using

make getlibs

, you don't typically need to check them in to a revision control system - they can be recreated at any time by re-running

make getlibs

. This includes both shared libraries (in

mtb_shared

) and local libraries (in

libs

) - they all get pulled from GitHub when you run

make getlibs

.

You also don't need to check in the

mtb

files for indirect references and the

mtb.mk

file which are stored in the

libs

directory. In fact, the default .

gitignore

file in our code examples excludes the entire

libs

directory since you should not need to check in any files from that directory – they can be recreated at any time.

Including libraries are not specified in a manifest​

If you a have your own custom libraries, you can create and include your own custom manifest files so that your libraries will show up in the Library Manager just like Infineon libraries. That method also allows you to specify the dependencies in the manifest so that they are automatically added as indirect dependencies when the dependent library is added to the application. Custom manifests are covered in the

ModusToolbox™ tools package user guide

.

Manually adding a library​

If you do not want to create a manifest file for your custom libraries, then you must manually include the library and its dependencies in each application that uses the library. You can include the library several different ways, such as:

  • git clone the version of the library that you want (or use some other revision control system) into the application's directory

  • unzip an archive file of the library into the application's directory

  • recursive copy the library into the application's directory

  • modify the

    SEARCH

    variable in the application's

    Makefile

    to point to the library

  • add an

    mtb

    file to the

    deps

    directory for the library and run

    make getlibs

    (requires that the library is in a Git repo)

For the first four methods, the library can go anywhere in the application's directory tree. Remember that if you put it in the

libs

directory it will not be checked into source control by default, so you will normally want put manually added libraries somewhere else.

If you use the

mtb

file (that is, the fifth method), there are two things to be aware of: the library will still not show up in the Library Manager; and latest locking will not be performed on that library so you should use a fixed version in the

mtb

file unless you want the dynamic update behavior.

Manually adding dependencies​

You can easily add dependencies using the Library Manager tool (for dependencies that are in a manifest file such as Infineon libraries). For dependencies that are not in a manifest file, you can use the same manual methods that are used for including the library itself.

Specifying dependencies for custom BSPs​

Custom BSPs use an alternate method to specify dependencies. The advantage is that the specification of the dependencies is self-contained within the custom BSP itself.

This method is accomplished by having files with the extension

mtbx

for each dependency in the

deps

directory inside the custom BSP. An

mtbx

file has the exact same content at an

mtb

file with a different file extension.

The process of getting dependencies from

mtbx

files only searches in the target BSP for the application, so if your application contains multiple custom BSPs, only the dependencies for the active target (as specified in the

TARGET

variable in the

Makefile

or on the command line) will be included in the application.

The

mtbx

files are automatically created for you, so you typically don't need to do anything with them unless you want to add or remove dependencies from your custom BSP. You can use the BSP Assistant to do this; for details, refer to the

BSP Assistant user guide

.

During

make getlibs

,

mtbx

files are treated just like indirect dependencies that are specified in a manifest file. That is, the process will copy each

mtbx

file to the application's

libs

directory and will lock the version in the

assetlocks.json

file in the

deps

directory. The libraries are then pulled down according to the information contained in the

mtb

files.