Skip to content

Commit d590b2a

Browse files
author
Donatien Garnier
authored
Merge pull request #1441 from Patater/add-mbed-cli-2-migration-guide
mbed_cli_2: Add migration guide
2 parents 63c75f6 + 3fd85ee commit d590b2a

File tree

2 files changed

+283
-29
lines changed

2 files changed

+283
-29
lines changed

‎docs/tools/mbed_cli_2/migration_guide.md

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
# Migration guide
2+
3+
If you haven't already read the [introduction](./intro.md), then start from there.
4+
5+
The background color indicates:
6+
7+
* <span style="background-color:#ccffcc;">Green: New Functionality
8+
introduced in Mbed CLI 2 (mbed-tools)</span>
9+
* <span style="background-color:#ffe6cc;">Orange: Functionality
10+
modified in Mbed CLI 2 (mbed-tools) compared to Mbed CLI 1 (mbed-cli)</span>
11+
* <span style="background-color:#ffcccc;">Red: Functionality deprecated
12+
in Mbed CLI 2 (mbed-tools)</span>
13+
14+
## Installers
15+
<span style="background-color:#ffe6cc;">Windows, macOS and Linux
16+
installers may be made available at later point of time.</span><br>
17+
18+
## Commands
19+
20+
### Device management
21+
<span style="background-color:#ffcccc;">The subcommand `mbed-cli
22+
device-management` (device management) is deprecated. Refer to your cloud
23+
provider's documentation on how to cloud-manage your devices.</span><br>
24+
25+
### Repository management
26+
<span style="background-color:#ffcccc;">Support for Mercurial and the
27+
subcommand `mbed-cli publish` (publish program or library) is deprecated.
28+
Hosted repositories on "mbed.org" are not supported from Mbed CLI 2. Version
29+
control with git can be used as an alternative. Hosting for git repositories is
30+
available on [GitHub](https://github.com/).</span><br>
31+
32+
<span style="background-color:#ffcccc;">The subcommand `mbed-cli cache`
33+
(repository cache management) is deprecated. No replacement is
34+
supported.</span><br>
35+
36+
<span style="background-color:#ffcccc;">The subcommand `mbed-cli releases`
37+
(show release tags) is deprecated. We recommend using standard `git` commands
38+
instead, for example `git tag -l` to list all tagged releases.</span><br>
39+
40+
<span style="background-color:#ffe6cc;">The subcommand `mbed-cli
41+
update` (update to branch, tag, revision or latest) is not implemented. Use
42+
standard `git` commands instead. From your application directory: to check out
43+
a branch of Mbed OS, `git -C mbed-os checkout branchname`; to checkout the Mbed
44+
OS 6.8.0 release, `git -C mbed-os checkout mbed-os-6.8.0`; to check out Mbed OS
45+
revision `3e24a7ea9602`, `git -C mbed-os checkout 3e24a7ea9602`; to checkout
46+
the latest released version of Mbed OS `git -C mbed-os checkout
47+
latest`.</span><br>
48+
49+
<span style="background-color:#ffcccc;">The subcommand `mbed-cli export`
50+
(generate an IDE project) is deprecated. Use [CMake
51+
generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html)
52+
instead. While CMake supports many generators, including many not supported by
53+
Mbed CLI 1, not all of Mbed CLI 1's exporters have replacements available yet.
54+
The available project generators are listed below.</span><br>
55+
56+
- [CodeBlocks](https://cmake.org/cmake/help/latest/generator/CodeBlocks.html)
57+
- [Eclipse](https://cmake.org/cmake/help/latest/generator/Eclipse%20CDT4.html)
58+
- [Make](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id10)
59+
- [Qt Creator](https://doc.qt.io/qtcreator/creator-project-cmake.html)
60+
- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)
61+
62+
<span style="background-color:#ffcccc;">If you'd like to help us prioritize
63+
which CMake project generators to work on first, please give your thumbs up to
64+
the following issues you care most about, or [raise a merge request to
65+
CMake](https://gitlab.kitware.com/cmake/cmake/-/merge_requests):</span><br>
66+
67+
- [CrossCore® Embedded Studio](https://github.com/ARMmbed/mbed-tools/issues/249)
68+
- [e<sup>2</sup> studio](https://github.com/ARMmbed/mbed-tools/issues/250)
69+
- [Embitz](https://github.com/ARMmbed/mbed-tools/issues/251)
70+
- [IAR Embedded Workbench for Arm](https://github.com/ARMmbed/mbed-tools/issues/252)
71+
- [MCUXpresso](https://github.com/ARMmbed/mbed-tools/issues/253)
72+
- [NetBeans](https://github.com/ARMmbed/mbed-tools/issues/254)
73+
- [STM32CubeIDE](https://github.com/ARMmbed/mbed-tools/issues/257)
74+
- [Keil uVision](https://github.com/ARMmbed/mbed-tools/issues/256)
75+
76+
### Library management
77+
78+
<span style="background-color:#ffcccc;">The subcommands `mbed-cli add` (add
79+
library from URL) and `mbed-cli remove` (remove library) are deprecated.
80+
Instead, use `git clone` or `mbed-tools import` to clone a library. Then,
81+
manually create a `reponame.lib` file that contains a single line in the form
82+
`https://github.com/ARMmbed/reponame#branch-or-tag` to fetch a specific branch
83+
or tag. If you want to fetch the default branch, you don't need to add
84+
`#branch-or-tag-name`.</span><br>
85+
86+
<span style="background-color:#ffcccc;">The subcommand `mbed-cli new --library`
87+
(force creation of an Mbed library) is deprecated. Create a new Mbed library by
88+
creating a new folder and adding it to git version control. Then, create a
89+
`reponame.lib` in the application you wish to use the new library from, as
90+
described above (in the `mbed-cli add` paragraph).</span><br>
91+
92+
<span style="background-color:#ffcccc;">The subcommand `mbed-cli ls` (view
93+
dependency tree) is deprecated. The subcommand `mbed-tools deploy` will now
94+
display all dependencies.</span><br>
95+
96+
### Tool configuration
97+
<span style="background-color:#ffcccc;">The subcommand `mbed-cli config` (tool
98+
configuration) is deprecated. There is no need to configure an Mbed-specific
99+
compiler path in Mbed CLI 2; the compiler path is determined in a standard way
100+
by CMake instead. Other configuration options, like `target`, `toolchain`,
101+
`protocol`, `depth` and `cache`, are not supported in Mbed CLI 2.</span><br>
102+
103+
<span style="background-color:#ffcccc;">The subcommand `mbed-cli toolchain`
104+
(set or get default toolchain) is deprecated. Pass the desired toolchain on the
105+
command line when compiling with `mbed-tools compile --toolchain GCC_ARM`, to,
106+
for example, select `GCC_ARM` as the toolchain.</span><br>
107+
108+
<span style="background-color:#ffcccc;">The subcommand `mbed-cli target` (set
109+
or get default target) is deprecated. Pass the desired target on the command
110+
line when compiling with `mbed-tools compile --mbed-target
111+
DISCO_L475VG_IOT01A`, to, for example, select `DISCO_L475VG_IOT01A` as the
112+
Mbed target.</span><br>
113+
114+
115+
### Creating an Mbed program
116+
<span style="background-color:#ffe6cc;">The subcommand `mbed-tools new` creates
117+
a new Mbed program by default and supports only one command-line-option
118+
`--create-only` (create a program without fetching mbed-os). The following
119+
command-line options, previously supported in Mbed CLI 1, are deprecated:
120+
121+
* `--scm`: We now always use git.
122+
* `--program`: There is no need to specify this. `mbed-tools new` always
123+
creates a program by creating a top-level application CMakeLists.txt that
124+
invokes `add_executable()`.
125+
* `--library`: There is no need to specify this. `mbed-tools new` always
126+
creates a program. If you wish to create a library, you can edit the
127+
autogenerated top-level application CMakeLists.txt to replace
128+
`add_executable()` with `add_library()` and removing the call to
129+
`mbed_set_post_build()` for the CMake library target.
130+
* `--mbedlib`: Importing Mbed 2 is no longer supported.
131+
* `--depth`: This is no longer needed, as Mbed CLI 2 automatically uses the
132+
shallowest clone or fetch possible.
133+
* `--protocol`: This is now determined from the URL instead.
134+
* `--offline`: This is not needed, as there is no longer any Mbed-specific git
135+
cache.
136+
* `--no-requirements`: Mbed CLI 2 never automatically installs requirements.
137+
</span><br>
138+
139+
### Importing an Mbed program
140+
<span style="background-color:#ffe6cc;">The subcommand `mbed-tools
141+
import` clones an Mbed project and library dependencies. The following
142+
command-line-options supported in Mbed CLI 1 are deprecated:
143+
144+
* `--depth`: The new CLI opportunistically imports the most shallow repository
145+
possible. Running `git clone --depth <depth> <repo_url> | cd <repo_name> &&
146+
mbed-tools deploy` will create an Mbed project with the required depth.
147+
* `--protocol`: To select the protocol, use a URL with the
148+
desired protocol. For instance, you may import projects or libraries over SSH
149+
(Secure Shell) as follows `mbed-tools import
150+
git@github.com:ARMmbed/<some_driver>`, or with https `mbed-tools import
151+
https://github.com/ARMmbed/<some_driver>`. Alternatively, if you would prefer
152+
to always use SSH, even when your library or its dependencies specify https
153+
in their `.lib` files, you can add the following into your .gitconfig to
154+
force git to use SSH instead of https when fetching from GitHub.
155+
156+
```sh
157+
[url "ssh://git@github.com/"]
158+
insteadOf = https://github.com/
159+
```
160+
161+
* `--offline`: The new tool doesn't maintain a git cache so we don't have the
162+
option to use locally cached repositories.
163+
* `--no-requirements`
164+
* `--insecure`
165+
166+
</span><br>
167+
168+
### Configuring an Mbed program
169+
170+
<span style="background-color:#ccffcc;">The subcommand `mbed-tools configure`
171+
generates an Mbed OS config CMake file named `mbed_config.cmake` in the path
172+
`cmake_build/<TARGET_NAME>/<PROFILE>/<TOOLCHAIN>/`.</span><br>
173+
174+
### Compiling an Mbed program
175+
176+
<span style="background-color:#ffcccc;">The subcommand `mbed-tools
177+
compile` can be used to compile the program. The command-line-option `mbed
178+
compile --source` is deprecated. To control which libraries and directories you
179+
want to build either modify your application's `CMakeLists.txt` to add/exclude
180+
or use `cmake --build cmake_build --target <library_name> --target
181+
<other_library_name>` to add any number of targets to your build.</span><br>
182+
183+
<span style="background-color:#ffcccc;">The command-line-option `mbed
184+
compile --library` is deprecated. Use standard CMake `add_library()`
185+
instead.</span><br>
186+
187+
<span style="background-color:#ffcccc;">The command-line-option `mbed compile
188+
-DMACRO_NAME` is deprecated. Use `mbed-tools configure -m <TARGET_NAME> -t
189+
<TOOLCHAIN>` followed by `cmake -S . -B
190+
cmake_build/<TARGET_NAME>/<PROFILE>/<TOOLCHAIN> -GNinja -DMACRO_NAME` and
191+
`cmake --build cmake_build` or use
192+
[`target_compile_definitions()`](https://cmake.org/cmake/help/latest/command/target_compile_definitions.html)
193+
in your application's `CMakeLists.txt` the add the define.</span><br>
194+
195+
<span style="background-color:#ffcccc;">The command-line-option `mbed compile
196+
-m detect` to automatically build for the single target connected to your
197+
computer is deprecated. Run `mbed-tools detect` to see which targets are
198+
connected to your computer and then run `mbed-tools compile -m <TARGET_NAME> -t
199+
<TOOLCHAIN>` to build for the target you which to build for.</span><br>
200+
201+
<span style="background-color:#ffe6cc;">The command-line-option `mbed
202+
compile --build` will be supported at later point of time. Although we don't
203+
currently have the option to explicitly state the application's build path, we
204+
have a ticket open to track the issue
205+
[#184](https://github.com/ARMmbed/mbed-tools/issues/184).</span><br>
206+
207+
### Testing an Mbed program
208+
209+
<span style="background-color:#ffe6cc;">The subcommand `mbed test` will be
210+
supported at later point of time. Keep apprised of progress by following [the
211+
issue to support mbed test on
212+
GitHub](https://github.com/ARMmbed/mbed-tools/issues/151)</span><br>

‎docs/tools/mbed_cli_2/use.md

Lines changed: 71 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -149,33 +149,6 @@ The Mbed OS configuration system parses the configuration files in your project
149149
mbed_config.cmake has been generated and written to '/Users/UserName/Development/Blinky/cmake_build/K64F/develop/GCC_ARM/mbed_config.cmake'
150150
```
151151
152-
## Build the project
153-
154-
Use CMake to build your application:
155-
156-
1. Navigate to the project's root folder.
157-
1. Set the build parameters:
158-
159-
```
160-
cmake -S . -B cmake_build -GNinja -DCMAKE_BUILD_TYPE=<profile>
161-
```
162-
- `-S <path-to-source>`: Path to the root directory of the CMake project. We use `.` to indicate we're building from the current directory.
163-
- `-B <path-to-build>`: Path to the build output directory. If the directory doesn't already exist, CMake will create it. We use `cmake_build` as the output directory name; you can use a different name.
164-
- `-GNinja`: To use the Ninja tool.
165-
- `-DCMAKE_BUILD_TYPE`: Build type. The value (`profile`) can be `release`, `debug` or `develop`, as [explained in program setup](../program-setup/build-profiles-and-rules.html).
166-
167-
1. Build:
168-
169-
```
170-
cmake --build cmake_build
171-
```
172-
173-
This generates two files in the build output directory (`cmake_build` in this example): HEX and BIN.
174-
175-
Which format you flash to your device depends on your requirements. For example, use the BIN file if you want to completely replace the contents of the flash device. If you want to retain some of the flash devices contents, you'll need to flash to an address other than the flash's starting address, so you'll need to use the HEX file (which contains the starting address). Note that we assume your board is running DAPLink for flash programming. If you are using another tool, please check your tool's documentation for file type support.
176-
177-
1. Drag and drop the generated file to your board.
178-
179152
## Configure and build in a single step
180153
181154
You can use a single command to configure (set up your target and toolchain) and build the project at once:
@@ -187,12 +160,81 @@ mbed-tools compile -m <target> -t <toolchain>
187160
- `-t`: The toolchain you are using to build your project.
188161
- `-m`: A build target for an Mbed-enabled device.
189162
190-
Example for FRDM-K64F and GCC:
163+
Example for [DISCO-L475VG-IOT01A](https://os.mbed.com/platforms/ST-Discovery-L475E-IOT01A/) and GCC:
191164
192165
```
193-
mbed-tools compile -m K64F -t GCC_ARM
166+
mbed-tools compile -m DISCO_L475VG_IOT01A -t GCC_ARM
194167
```
195168
169+
170+
## Build the project with CMake (advanced)
171+
172+
We'll show how to build your project using CMake directly, which provides you
173+
with the full capabilities of CMake. You are no longer limited by what Mbed CLI
174+
2 has to offer.
175+
176+
For this example, we'll use the `GCC_ARM` toolchain with the Mbed target
177+
`DISCO_L475VG_IOT01A`.
178+
179+
To use CMake to build your application:
180+
181+
1. Navigate to the project's root folder.
182+
1. Translate from the Mbed configuration system to a form CMake can understand:
183+
184+
```
185+
mbed-tools configure -m DISCO_L475VG_IOT01A -t GCC_ARM
186+
```
187+
188+
This will create a build folder at `cmake_build/DISCO_L475VG_IOT01A/develop/GCC_ARM`
189+
190+
1. Set the build parameters:
191+
192+
```
193+
cmake -S . -B cmake_build/DISCO_L475VG_IOT01A/develop/GCC_ARM -GNinja
194+
```
195+
- `-S <path-to-source>`: Path to the root directory of the CMake project.
196+
We use `.` to indicate we're building from the current directory.
197+
- `-B <path-to-build-directory>`: Path to the
198+
build output directory. If the directory doesn't already exist, CMake
199+
will create it. We use `cmake_build/DISCO_L475VG_IOT01A/develop/GCC_ARM`
200+
as the output directory name. We match the path Mbed CLI 2 would use, so
201+
we don't need to manually move around the `mbed-tool configure` output
202+
`mbed_config.cmake`.
203+
- `-GNinja`: To use the Ninja build tool. You can tell CMake to use another
204+
build tool using any [CMake
205+
Generator](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html)
206+
your version of CMake supports. We like to use Ninja because it is fast.
207+
208+
1. Build:
209+
210+
```
211+
cmake --build cmake_build/DISCO_L475VG_IOT01A/develop/GCC_ARM
212+
```
213+
214+
Alternatively, if you are using the Ninja build tool (`-GNinja in the
215+
previous step`) and which to run it yourself, which you may want to do if
216+
you'd like to limit the number of jobs ninja uses (`ninja -j 1`) or pass
217+
other custom options (`ninja --help`)
218+
219+
```
220+
ninja -C cmake_build/DISCO_L475VG_IOT01A/develop/GCC_ARM
221+
```
222+
223+
The build generates two files in the build output directory
224+
(`cmake_build/DISCO_L475VG_IOT01A/develop/GCC_ARM` in this example): HEX and
225+
BIN.
226+
227+
Which format you flash to your device depends on your requirements. For
228+
example, use the BIN file if you want to completely replace the contents of
229+
the flash device. If you want to retain some of the flash devices contents,
230+
you'll need to flash to an address other than the flash's starting address,
231+
so you'll need to use the HEX file (which contains the starting address).
232+
Note that we assume your board is running DAPLink for flash programming. If
233+
you are using another tool, please check your tool's documentation for file
234+
type support.
235+
236+
1. Drag and drop the generated file to your board.
237+
196238
### Building for multiple targets
197239
198240
You can build an Mbed project for multiple targets, with different profiles and toolchains, without affecting other builds. The `compile` subcommand will create and build into a different subdirectory for each combination:

0 commit comments

Comments
 (0)