Building .NET nanoFramework
.NET nanoFramework build system is based in CMake. Please read the instructions specific to each target series.
About this document
This document describes how to build the required images for .NET nanoFramework to be flashed in a SoC or MCU. The build is based on CMake tool to ease the development in all major platforms.
Using Dev Container
If you want a simple, efficient way, we can recommend you to use Dev Container to build your image. This has few requirements as well like Docker Desktop and Remote Container extension in VS Code but it is already all setup and ready to run!
If you prefer to install all the tools needed on your Windows machine, you should continue this tutorial.
- 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.
Build a .NET nanoFramework image
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.
Building from the command prompt
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" \ -DCMAKE_TOOLCHAIN_FILE=CMake/toolchain.arm-none-eabi.cmake \ -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.
cmake \ -DTOOLCHAIN_PREFIX="E:/GNU_Tools_ARM_Embedded/5_4_2016q3" \ -DCMAKE_TOOLCHAIN_FILE=CMake/toolchain.arm-none-eabi.cmake \ -DCHIBIOS_SOURCE=E:/GitHub/ChibiOS \ -DCHIBIOS_BOARD=ST_NUCLEO144_F746ZG \ -DTARGET_SERIES=STM32F7xx \ -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, 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.
Building from VS Code (using CMake Tools extension)
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).
.NET nanoFramework build deliverables
After a successful build you can find the .NET 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.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)
When working with self built nanoCLR you may get the following message while deploying a new app:
Found assemblies mismatches when checking for deployment pre-check.
This is because the BUILD_VERSION value of your custom built nanoCLR doesn't match the one nanoframework.CoreLibrary expects.
BUILD_VERSION can be set cmake-variants.json. The value defaults to
Change that to the one you need at the moment, like
Don't forget to:
- make this change under appropriate target block, as described here
- make sure you understood that VSCode have to be reloaded to these json changes have effect.
- make sure you understood that the build folder have to be removed to these changes have effect.
- re-select the CMake target (VSCode bottom line) to reconfigure the build.