About this document
This document describes how to build the required images for nanoFramework to be flashed in a SoC or MCU. The build is based on CMake tool to ease the development in all major platforms.
You'll need:
- GNU ARM Embedded Toolchain
- CMake (Minimum required version is 3.7)
- A build system for CMake to generate the build files to.
If you are using VS Code as your development platform we suggest that you use the CMake Tools extension. This will allow you to run the builds without leaving VS Code.
In case you specify an RTOS and you want its source to be downloaded from the official repository, you'll need:
- For FreeRTOS a SVN client. Tortoise SVN seems to be a popular choice for Windows machines.
- For ChibiOS a Git client. GitHub Desktop seems to be a popular choice for Windows machines.
It's highly recommended that run the build outside the source tree. This prevents you from cluttering the source tree with CMake artifacts, temporary files etc. In fact this is enforced and checked by the CMake script.
In case you need to clean up or start a fresh build all you have to do is simply delete the contents of the build directory.
As a suggestion we recommend that you create a directory named build in the repository root and run CMake from there.
The build script accepts the a number of parameters (some of them are mandatory). Please check the details about each parameter here.
Note 1: The RTOS currently supported (except for ESP32 target) is ChibiOS. If no source path is specified the source files will be downloaded from nanoFramework GitHub fork. Note 2: the very first build will take more or less time depending on the download speed of the Internet connection of the machine were the build is running. This is because the source code of the RTOS of your choice will be downloaded from its repository. On the subsequent builds this won't happen.
You can specify any generator that is supported in the platform where you are building. For more information on this check CMake documentation here.
If you are building from the command prompt, just go to your build directory and run CMake from there with the appropriate parameters. The following is a working example:
cmake \
-DTOOLCHAIN_PREFIX="E:/GNU_Tools_ARM_Embedded/5_4_2016q3" \
-DCHIBIOS_BOARD=ST_NUCLEO_F091RC \
-DTARGET_SERIES=STM32F0xx \
-DNF_FEATURE_DEBUGGER=TRUE \
-DAPI_Windows.Devices.Gpio=ON \
-DNF_FEATURE_RTC=ON \
-G "NMake Makefiles" ../
This will call CMake (on your build directory that is assumed to be under the repository root) specifying the location of the toolchain install, that the target board is named ST_NUCLEO_F091RC, that STM32F0xx is the series name that it belongs to, debugger feature is to be included, Windows.Devices.Gpio API is to be included and that the build files suitable for NMake are to be generated.
Another example:
cmake \
-DTOOLCHAIN_PREFIX="E:/GNU_Tools_ARM_Embedded/5_4_2016q3" \
-DCHIBIOS_SOURCE=E:/GitHub/ChibiOS \
-DCHIBIOS_BOARD=ST_NUCLEO144_F746ZG \
-DTARGET_SERIES=STM32F7xx \
-DUSE_FPU=TRUE \
-DNF_FEATURE_DEBUGGER=TRUE \
-DAPI_Windows.Devices.Gpio=ON \
-DNF_FEATURE_RTC=ON \
-G "NMake Makefiles" ../
This will call CMake (on your build directory that is assumed to be under the repository root) specifying the location of the toolchain install, specifying that ChibiOS sources to be used are located in the designated path (mind the forward slash and no ending slash), that the target board is named ST_NUCLEO144_F746ZG, that STM32F7xx is the series name that it belongs to, hardware floating point unit is to be used, debugger feature is to be included, Windows.Devices.Gpio API is to be included, RTC is used and that the build files suitable for NMake are to be generated.
After successful completion you'll have the build files ready to be used in the target build tool.
We've added the required files and configurations to help you launch your build from VS Code. Follows a brief explanation on the files you might want to tweak.
- settings.json (inside .vscode folder) here you can change the generator that CMake uses to generate the build. The default is
"cmake.generator": "NMake Makefiles". The recommendation is to use Ninja as the build tool because it's way faster than NMake. You'll also need to set the use of CMake Server to true, like this:"cmake.useCMakeServer" : true. - launch.json (inside .vscode folder) here you can set up your launch configurations, such as gdb path or OpenOCD configuration. We've made available Gists with launch.json for several of the reference targets. Grab yours from here.
⚠️ Remember to update paths and other preferences according to your setup and machine configuration. 😉 - cmake-variants.json (at the repository root) here you can add several build flavors. You can even add variants to each one. Check the documentation extension here. We've made available Gists with cmake-variants.json for each of the reference targets. Grab yours from here.
⚠️ Remember to update paths and other preferences according to your setup and machine configuration. 😉
To launch the build in VS Code check the status bar at the bottom. Select the build flavor and then click the build button (or hit F7).
After a successful build you can find the nanoFramework image files in the build directory. Those are:
-
nanoBooter image (not available for ESP32 builds):
- nanoBooter.bin (raw binary format)
- nanoBooter.hex (Intel hex format)
- nanoBooter.s19 (Motorola S-record format, equivalent to srec)
- nanoBooter.lst (source code listing intermixed with disassembly)
- nanoBooter.map (image map)
-
nanoCLR image:
- nanoCLR.bin (raw binary format)
- nanoCLR.hex (Intel hex format)
- nanoCLR.s19 (Motorola S-record format, equivalent to srec)
- nanoCLR.lst (source code listing intermixed with disassembly)
- nanoCLR.map (image map)