API Manual ¶

This chapter describes how to navigate the command line tool integrated with STM32CubeIDE for Visual Studio Code.

Overview of Command Line ¶

The command line tool provides a convenient way to access help information for its various commands. This helps users understand the available commands and their usage without needing to refer to external documentation.

Usage ¶

To display help information for a specific command, use the following syntax:

            cube <command> --help

           

Here:

cube is the main command line tool executable.
<command> is the specific command you want help with.
--help is the option that triggers the display of usage information for the given command.

To list all of the bundles installed, use the following syntax:

            cube --list

           

Here:

cube is the main command line tool executable
--list is the command that triggers the display of all the installed bundles.

Example:

For instance, to get help on the pack command, you would run:

            cube pack --help

           

This will display detailed information such as:

Description of the pack command.
Available options and flags.
Examples of usage.
Any additional notes or requirements.

Installing a Specific Bundle Version ¶

To install a specific version of a bundle, use the following syntax:

            cube bundle install example-bundle@X.Y.Z

           

Here:

cube is the main command line tool executable.
bundle specifies the bundle management command.
install triggers the installation process for the specified bundle.
example-bundle@X.Y.Z represents the bundle name followed by the exact version number you want to install. Replace example-bundle with the desired bundle name and X.Y.Z with the version number.

Additional Documentation ¶

For some of the installed bundles there is additional documentation available through the Documentation field.

Example:

For instance, to get more detailed information about an installed bundle, you would run:

            cube --json bundle show <bundle>

           

This will display a more detailed view of the installed bundle. Some have a Documentation field with a link to its readme file.

DevOps Corner ¶

For more advanced use cases there are additional ways of automating the workflow through the cube commands.

QuickStart ¶

Setting up and sharing projects with the cube CLI tool involves initializing the project with required bundles and installing them consistently across developer and CI environments. Using:

cube bundle init --project [bundles] for project initialization.
cube bundle install --project <bundles> for local development.
cube bundle install --project for CI automation.

This workflow streamlines project management, testing, and deployment.

Developer Workflow ¶

This chapter explains how to set up a project using the cube command line tool and how to share it efficiently for testing and automation purposes. The process involves initializing the project with the required bundles and installing those bundles both locally (developer side) and in Continuous Integration (CI) environments.

Initialize a Project with Bundles ¶

To create a new project and specify the bundles it depends on, use the following command:

            cube bundle init --project [bundles]

           

--project specifies that you are working within a project context.
[bundles] is a space-separated list of bundle names you want to include in your project.

This command initializes the project configuration and records the bundles to be used, setting up the environment for development.

Install Bundles for the Project ¶

Once the project is initialized, you can install the specified bundles locally using:

            cube bundle install --project <bundles>

           

This installs the bundles listed for the project, ensuring your development environment has all necessary components.
You can specify bundles explicitly or rely on the project configuration to install all required bundles.

CI Workflow ¶

In Continuous Integration (CI) environments, the project bundles can be installed automatically to enable testing and automation workflows. Use the following command:

            cube bundle install --project

           

Running this command in CI installs all bundles defined in the project configuration.
This ensures consistency between developer environments and automated pipelines.
No need to specify bundles explicitly; the project configuration drives the installation.

Benefits of This Approach ¶

Consistency: Both developers and CI environments use the same bundle definitions, reducing “works on my machine” issues.
Automation: Simplifies setting up automated testing and deployment pipelines.
Scalability: Easily add or remove bundles from the project configuration without changing CI scripts.
Collaboration: Sharing the project setup via configuration files allows teams to synchronize dependencies effortlessly.