Configuring Mbed CLI
There are some configuration that you must set before you can work with Mbed CLI.
Mandatory: setting PATH variables
Mbed CLI requires adding the following to the system
- The paths for the Git and Mercurial executables (
Mandatory: toolchain selection
You need to tell Mbed CLI where to find the toolchains that you want to use for compiling. Mbed CLI supports the following toolchains:
- Arm Compiler 5. Use version 5.06 of Arm Compiler 5. Versions older than 5.06 might be incompatible with the tools.
- Arm Compiler 6. Use version 6.10 of Arm Compiler 6. Versions older than 6.10 might be incompatible with the tools.
- GNU Arm Embedded toolchain (GCC) version 6. Use version 6 of GCC Arm Embedded; version 5.0 or any older version might be incompatible with the tools.
- IAR EWARM 7. Use versions 7.70 to 7.80.x of the IAR EWARM; other versions might be incompatible with the tools.
You must inform Mbed CLI about the location of your compiler using one of the following methods.
- The Mbed CLI configuration command.
- Adding the compiler's directory to your PATH.
- Setting an environment variable.
mbed_settings.pyfile in the root of your program. The tools will automatically create this file if it doesn't already exist.
Note: You may configure more than one toolchain. However, you may only use one toolchain at a time. When using C++98 and GNU C99, the only difference between the toolchains is performance.
Through Mbed CLI configuration
Mbed CLI stores its own configuration about compiler locations both in project local settings, and user wide "global" settings. You may set and view these settings with the
mbed config command. For example, you set the Arm Compiler 5 location for your user with the command:
$ mbed config -G ARM_PATH "C:\Program Files\ARM" [mbed] C:\Program Files\ARM now set as global ARM_PATH
-G switch tells Mbed CLI to set this as a global setting, allowing all projects this user owns to compile with Arm Compiler 5. You may instead set the
ARM_PATH using a project local setting by omitting the
-G command-line switch.
Mbed CLI supports a setting for each toolchain path. Below is a list of these settings, along with a description of what path is expected in each setting.
ARM_PATH: The path to the base directory of your Arm Compiler installation. This should be the directory containing the directory containing the binaries for
armccand friends. For example, if your Arm Compiler 5 executable
armccis located at
/home/redacted/ARM_Compiler_5.06u5/bin/armcc, you set
IAR_PATH: The path to the base directory of your IAR EWARM Compiler installation. This should be the directory containing the binaries for
iccarmand friends. For example, if your IAR EWARM compiler executable is located at
C:/Program Files/IAR Systems/Embedded Workbench 7.5/arm/bin/iccarm.exe, you set
C:/Program Files/IAR Systems/Embedded Workbench 7.5/arm.
GCC_ARM_PATH: The path to the binary directory of your GCC Arm Embedded Compiler installation. This should be the directory containing the binaries for
arm-none-eabi-gccand friends. For example, if your Gcc Arm Embedded toolchain gcc executable is in
/usr/bin/arm-none-eabi-gcc, you set
Compiler detection through the
mbed compile command checks your
PATH for an executable that is part of the compiler suite in question. This check is the same as a shell would perform to find the executable on the command-line. When
mbed compile finds the executable it is looking for, it prefaces the executable name with the path it found. Mbed CLI does not prefix any executable found for
Set environment variable
Mbed CLI also detects compilers with specially named environment variables. These environment variables are the same as their corresponding configuration variable, with a prefix of
MBED_ added. For example, when configuring Arm Compiler 5, you set the
MBED_ARM_PATH environment variable to the base directory of your Arm Compiler 5 installation.
Mbed CLI also uses
mbed_settings.py to configure toolchains. This file must be a python module, and uses the exact same configuration variables as the Mbed CLI configuration.
mbed_settings.py contains local settings (possibly relevant only to a single OS on a single machine), you should not check it into version control.
Optional: configuring multiple toolchains
Mbed CLI has a few rules that allow you to seamlessly switch between different versions of the same toolchain when switching between different projects. The settings described in prior sections all can configure a different version of the same toolchain. When multiple settings are available for a single toolchain, Mbed CLI picks the most specific setting. The settings, from most specific to least specific are:
- Mbed CLI Local Configuration
- Mbed CLI Global Configuration
- Environment Variables
When resolving which setting is used for an individual
mbed compile or
mbed test invocation, Mbed CLI picks the lowest numbered present setting.
To use a standard toolchain for general purpose development, you may use any method 3 through 5. For overriding a toolchain version for a specific project, you may use methods 1 and 2. All of these methods for configuring a toolchain may coexist.
Optional: add Bash tab completion
mbed-cli bash tab completion:
- Navigate to the
- Copy the
mbedscript into your
- Reload your terminal.
The Mbed CLI configuration syntax is:
mbed config [--global] <var> [value] [--unset]
You can see the active Mbed CLI configuration via:
$ mbed config --list [mbed] Global config: ARM_PATH=C:\Program Files\ARM\armcc5.06 IAR_PATH=C:\Program Files\IAR Workbench 7.0\arm [mbed] Local config (D:\temp\mbed-os-program): No local configuration is set
||Defines the default behavior of Mbed CLI across programs unless overridden by local settings.|
|None||Any configuration done without
||Remove a setting.|
||List global and local configuration.|
||The default target for
||The default toolchain for
||Define the paths to Arm Compiler, GCC Arm and IAR Workbench toolchains.||No default.|
||The default protocol used for importing or cloning of programs and libraries. The possible values are
||The clone depth for importing or cloning and applies only to Git repositories. Note that though this option may improve cloning speed, it may also prevent you from correctly checking out a dependency tree when the reference revision hash is older than the clone depth. Read more about shallow clones.||No default.|
||The local path that stores small copies of the imported or cloned repositories. Mbed CLI uses it to minimize traffic and speed up future imports of the same repositories. Use
||Default: none (disabled).|