New Project Setup Guide

This page will walk you through the process of setting up a totally blank project that uses Mbed CE. You can also watch these steps in video version - Youtube guide

Note

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

Important

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

1. Create a project folder, navigate the system console to this directory and generate 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) # here you can change your project name
   
   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()

   Click here for more advanced examples of top level CMakeLists.txt

   #
   # Mbed CE Hello World Project
   #
   cmake_minimum_required(VERSION 3.19)
   cmake_policy(VERSION 3.19)
   
   #### Initialize Mbed OS build system. ####
   ######################################################################################################
   ### Block of including .json5 files. Files of this block must be included before the app.cmake
   
   #[[ Set path of mbed_app.json (necessary everytime if mbed_app.json5 is in project) ]]
   set(MBED_APP_JSON_PATH mbed_app.json5)
   
   ###--------------------------------------------------------------------------------------------------- 
   #[[ This part is dedicated for custom targets only! Settings below activate targets from
   custom_targets.json5 and upload method config, otherwise functions below should be commented. ]]
   
   #[[ Here set path for custom_targets.json5 (this is our default) ]]
   #set(CUSTOM_TARGETS_JSON_PATH custom_targets/custom_targets.json5) 
   
   #[[ Here you can set path for custom upload config .cmake (optional example) ]]
   #set(CUSTOM_UPLOAD_CFG_PATH ${CMAKE_SOURCE_DIR}/${MBED_TARGET}/${MBED_TARGET}.cmake)
   
   #[[ Note: For custom target you need also an upload method and we have few options how you can do that
   - use the variable CUSTOM_UPLOAD_CFG_PATH above
   - use default expected path for custom targets upload methods where you create your own config
   MY_PROJECT/custom_targets/upload_method_cfg
   - of course you can do it by yourself directly via cmake in this file
   For more visit https://github.com/mbed-ce/mbed-os/wiki/Upload-Methods ]]
   ### End of block
   ######################################################################################################
   
   ### include app.cmake (necessary everytime) ###
   include(mbed-os/tools/cmake/app.cmake)
   
   ######################################################################################################
   ### Block of including project folders
   
   #[[ If using a custom target, the subdirectory containing the custom target must be included before 
   the mbed-os subdir, otherwise the next line should be commented]]
   #add_subdirectory(custom_targets)
   
   ###--------------------------------------------------------------------------------------------------
   ## Add mbed-os subdirectory (necessary everytime)
   add_subdirectory(mbed-os)
   
   ###--------------------------------------------------------------------------------------------------
   ## Add another subdirectory, for example subdirectory of a library (if needed)
   #add_subdirectory(YourLibrary)
   
   ### End of block
   ######################################################################################################
   
   ### Set up your project name (necessary everytime)
   project(MbedCEHelloWorld)
   
   ### add executable (necessary everytime)
   add_executable(${CMAKE_PROJECT_NAME} main.cpp)
   
   ######################################################################################################
   ### Link libraries block
   #[[For more about this configuraion visit wiki page MbedOS-configuration
   https://github.com/mbed-ce/mbed-os/wiki/MbedOS-configuration#configuration-via-cmake-files]]
   
   #[[link MbedOS and its libraries (necessary everytime)]]
   target_link_libraries(${CMAKE_PROJECT_NAME}  mbed-os) 
   
   ### link user library (if needed)
   #target_link_libraries(${CMAKE_PROJECT_NAME} YourLibrary) 
   
   ### End of block
   ######################################################################################################
   
   ### Set post build (necessary everytime)
   mbed_set_post_build(${CMAKE_PROJECT_NAME})
   #[[Or in case of custom linker script which should be placed like this
   directory PROJECT_NAME/custom_targets/MBED_TARGET/MBED_TARGET.ld]]
   #mbed_set_post_build(${CMAKE_PROJECT_NAME}  ${CMAKE_SOURCE_DIR}/custom_targets/${MBED_TARGET}/${MBED_TARGET}.ld)
   
   ### Build finalize does necessary configuration for debug in most cases (necessary everytime)
   mbed_finalize_build()

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.