Project Configuration

Initial Configuration

Here's how to initially set up mbed-cmake for your processor and compile a hello world. You only need to do this once when you initially create a project!

Before doing this, follow the first steps of the Getting Started guide, then follow the steps on the Toolchain Setup page to install the GNU Arm toolchain on your machine.

1. Install the dependencies for MBed OS's build system. You should be able to do this with python3 -m pip install -r mbed-cmake/mbed-src/requirements.txt, though this may not work on all Python versions (On Windows you will need to replace python3 with python). If it doesn't work, you can will need to open the requirements file and read the list of dependencies and install them manually.
2. Optional: set up your mbedignore by editing .mbedignore. Info about how to use this file can be found here.
   • A template mbedignore has been provided for you, you can edit this or create a completely new one.
   • It is highly recommended to add files and directories in Mbed OS that you don't need to your mbedignore as this speeds up the build significantly. You can always unignore them later!
3. Optional: configure Mbed OS's preferences by editing mbed_app.json. Info about these settings can be found here.
4. Find the correct Mbed name for your target board or processor. How to do this varies somewhat -- if you have an MBed board you can find your board here and look in the top right for the target name. If you are using an MBed-enabled processor on your own board, you will usually want to use the name of the dev board for that processor, unless you have set up a custom target.
   • If you are using a custom target, you can add it by passing a directory to the -x option in the next step. This will look for a custom_targets.json file in the passed directory.
   • For a custom target named Foo, the build system will also search for a directory named TARGET_FOO in the passed directory. Put all your source files for the custom target here. If this folder exists, all files in it will be added to the build, overriding any Mbed OS files with the same names.
5. Configure mbed-cmake by running python3 mbed-cmake/configure_for_target.py -a mbed_app.json -i .mbedignore <target names...>. This will activate MBed OS's build system and generate the configuration files needed by CMake for each of the targets you have provided.
6. Create a build directory (don't build in the source code!) and cd into it. Then run CMake for the initial configuration: cmake <path/to/source/dir>. As long as your toolchain is installed properly, CMake will configure the project for building.
   • If you configured the build system for multiple targets, you will need to pass the -DTARGET=... option to CMake to select which Mbed target you want to configure this build directory for.
   • On Windows, if using mingw32-make use cmake "-GMinGW32 Makefiles <path/to/source/dir>" as your initial CMake command, and then use mingw32-make in place of make in all commands.
7. We've included a hello world program in the project as-is. You can compile it (and MBed OS itself) with: make -j2 hello_world.

Done! Your hello world program should build as a .bin and a .hex file in your source dir. To set up automatic uploading, refer to the Upload Methods section for instructions on how to configure this feature.

Subsequent Setup

Once a project has been initially configured following the steps above, setup on other computers is much easier. All that you need to do after cloning the project is install the toolchain and run the CMake configuration (see Step 6 above).

Rerunning Configuration

If you change your MBed ignore or config files, or if you want to switch to a different MBed target, then you will need to rerun the initial configuration process. First, follow the initial configuration guide through step 6 to regenerate the config files. Then, you need to delete and recreate your CMake build directories. This is very important, if you don't do this it can lead to your code being built with the wrong flags for your processor. Then, you can recreate new build directories from scratch and compile as before.