New Project Setup Guide

This page will walk you through the process of setting up a totally blank project that uses Mbed CE.

Important

This already assumes you have the development environment set up - Toolchain-Setup-Guide.

Note

As an alternative to this process, you may clone and modify the Hello world project as well!

1. In your project folder, create an empty Git repo: git init

2. Optional: Add in a basic gitignore file

3. Add Mbed OS as a submodule: git submodule add --depth 1 https://github.com/mbed-ce/mbed-os.git mbed-os

4. Make sure that only the most recent commit of Mbed OS is cloned: git config -f .gitmodules submodule.mbed-os.shallow true. This step is optional for contributors and can be reverted by this .

5. Create a file called mbed_app.json5 (This file is used to configure various Mbed settings for your application.) in the project root directory with the following content:

      {
          "target_overrides": {
             "*": {
                "platform.stdio-baud-rate": 115200,
                "platform.stdio-buffered-serial": 1
             }
          }
       }

6. Create a file called main.cpp as empty program:

   #include "mbed.h"
   
   int main()
   {
      while(true) {}
   
      // main() is expected to loop forever.
      // If main() actually returns the processor will halt
      return 0;
   }

7. Create a basic CMakeLists.txt with build rules for your program:

   cmake_minimum_required(VERSION 3.19)
   cmake_policy(VERSION 3.19)
   
   set(MBED_APP_JSON_PATH mbed_app.json5)
   
   include(mbed-os/tools/cmake/app.cmake)
   
   add_subdirectory(mbed-os)
   
   project(MyMbedApp)
   
   add_executable(${CMAKE_PROJECT_NAME} main.cpp)
   target_link_libraries(${CMAKE_PROJECT_NAME} mbed-os) # Can also link to mbed-baremetal here
   mbed_set_post_build(${CMAKE_PROJECT_NAME})
   
   mbed_finalize_build()

   More advanced examples of top level CMakeLists.txt you can find in examples - HellowWorld or CustomTargets.

Note

Unlike Mbed OS 6, Mbed CE lets you create multiple executables, as well as STATIC and OBJECT libraries, in one CMake project.

Tip

However, if you create library targets, make sure to link them to mbed-core-flags, not mbed-os.

9. Now, you are ready to set up the CMake project for editing. We have three ways to do this:
   • On the command line
   • Using the CLion IDE
   • Using the VS Code IDE

Note: Converting the Mbed OS Submodule

These instructions cause the Mbed OS submodule to be cloned in shallow mode, which reduces the amount of space consumed by its history. However, this prevents you from making normal commits and contributions to Mbed OS. If you want to make contributions to Mbed, you will need to convert this repo to a full Git repo.

To do that, go into the mbed-os folder and run the following commands (from here):

git fetch --unshallow
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin
git checkout master
git reset --hard origin/master
git config -f .gitmodules submodule.mbed-os.shallow false

That will get you on a master branch that matches master branch on this repo, and you can make commits, PRs, and forks like normal.