Miscellaneous improvements (#112)

Author: josesimoes

content/building/build-esp32.md

@@ -1,8 +1,14 @@
 # How to Build, Flash and Debug the ESP32 nanoCLR on Windows using Visual Code
 
+⚠️ NOTE about the need to build .NET **nanoFramework** firmware ⚠️
+
+You only need to build it if you plan to debug the native code, add new targets or add new features at native level.
+If your goal is to code in C# you just have to flash your MCU with the appropriate firmware image.
+There are available ready to flash firmware images for several targets, please check the [Home](https://github.com/nanoframework/Home#firmware-for-reference-boards) repository.
+
 ## About this document
 
-This document describes how to build the required images for .NET **nanoFramework** for ESP32 targets.
+This document describes how to build the required images for .NET **nanoFramework** firmware for ESP32 targets.
 The build is based on CMake tool to ease the development in all major platforms.
 
 ## Using Dev Container
@@ -74,17 +80,17 @@ After cloning the repo, you need to setup the build environment. You can use the
 
 ![idf tools location](../../images/building/esp32/install-esp-idf-tools-location.png)
 
--**Step 5**: At the options screen, know that you don't have to install all the tools there. Follow the recomended option to be able to build .NET nanoFramework. Also note that you may want to install the toolchains only for the chip serie(s) that you're planning to build for.
+-**Step 5**: At the options screen, know that you don't have to install all the tools there. Follow the recommended option to be able to build .NET nanoFramework. Also note that you may want to install the toolchains only for the chip serie(s) that you're planning to build for.
 
 ![options](../../images/building/esp32/install-esp-idf-tools-options.png)
 
 -**Step 6**: The install step may prompt you for permission on installing drivers and launch secondary installers. And be aware that it can take a while to complete...
 
--**Step 7**: After the installer completes, open a command prompt at the IDF repository location with elevated permisssion and execute the script `install`. This will *hopefully* install all the requirements and prerequisites.
+-**Step 7**: After the installer completes, open a command prompt at the IDF repository location with elevated permission and execute the script `install`. This will *hopefully* install all the requirements and prerequisites.
 
--**Step 8**: Now execute the script `export`. This will *hopefully* update the path environement variable of your machine. You can check the success of the operation by opening another cmd prompt and print the content of the path variable.
+-**Step 8**: Now execute the script `export`. This will *hopefully* update the path environment variable of your machine. You can check the success of the operation by opening another cmd prompt and print the content of the path variable.
 
--**Step 9**: Calling the above scripts it's not 100% guaranteed to effectivelly install everything and updates the path. This can be because of permission issues, updating the path variable and others. Here's the image of the path on a machine where the update was succesfull so you can compare it.
+-**Step 9**: Calling the above scripts it's not 100% guaranteed to effectively install everything and updates the path. This can be because of permission issues, updating the path variable and others. Here's the image of the path on a machine where the update was successful so you can compare it.
 
 ![updated path](../../images/building/esp32/install-esp-idf-tools-path.png)
 

content/building/build-in-visual-studio.md

@@ -1,5 +1,11 @@
 # Building .NET **nanoFramework** in Visual Studio
 
+⚠️ NOTE about the need to build .NET **nanoFramework** firmware ⚠️
+
+You only need to build it if you plan to debug the native code, add new targets or add new features at native level.
+If your goal is to code in C# you just have to flash your MCU with the appropriate firmware image.
+There are available ready to flash firmware images for several targets, please check the [Home](https://github.com/nanoframework/Home#firmware-for-reference-boards) repository.
+
 ## Developing firmware for the nanoframework using Visual Studio 2019 community edition
 
 [(See below for VS2017)](#developing-firmware-for-the-nanoframework-using-visual-studio-2017-community-edition)

content/building/build-instructions.md

@@ -1,4 +1,4 @@
-# Building .NET **nanoFramework**
+# Building .NET **nanoFramework** firmware
 
 .NET **nanoFramework** build system is based in CMake. Please read the instructions specific to each target series.
 
@@ -7,9 +7,15 @@
 - [NXP](build-nxp.md)
 - [Using Dev Container](using-dev-container.md)
 
+⚠️ NOTE about the need to build .NET **nanoFramework** firmware ⚠️
+
+You only need to build it if you plan to debug the native code, add new targets or add new features at native level.
+If your goal is to code in C# you just have to flash your MCU with the appropriate firmware image.
+There are available ready to flash firmware images for several targets, please check the [Home](https://github.com/nanoframework/Home#firmware-for-reference-boards) repository.
+
 ## About this document
 
-This document describes how to build the required images for .NET **nanoFramework** to be flashed in a SoC or MCU.
+This document describes how to build the required images for .NET **nanoFramework** firmware 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
@@ -36,8 +42,8 @@ If you are using VS Code as your development platform we suggest that you use th
 
 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](https://tortoisesvn.net/downloads) seems to be a popular choice for Windows machines.
-- For ChibiOS a Git client. [GitHub Desktop](https://desktop.github.com/) seems to be a popular choice for Windows machines.
+- For ChibiOS a SVN client. [Tortoise SVN](https://tortoisesvn.net/downloads) seems to be a popular choice for Windows machines.
+- For all the other repositories a Git client. [Fork](https://git-fork.com/) it's a great visual git client packed with a lot of features or [GitHub Desktop](https://desktop.github.com/) seems to be a popular choice for Windows machines.
 
 ## Preparation
 
@@ -48,11 +54,11 @@ In case you need to clean up or start a fresh build all you have to do is simply
 
 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
+## Build a .NET **nanoFramework** firmware image
 
 The build script accepts the a number of parameters (some of them are mandatory). Please check the details about each parameter [here](cmake-tools-cmake-variants.md#content-explained).
 
-_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 1: The RTOSes currently supported (except for ESP32 target) are ChibiOS and FreeRTOS. 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.
@@ -87,12 +93,12 @@ cmake \
 -DCHIBIOS_BOARD=ST_NUCLEO144_F746ZG \
 -DTARGET_SERIES=STM32F7xx \
 -DNF_FEATURE_DEBUGGER=TRUE \
--DAPI_Windows.Devices.Gpio=ON \
+-DAPI_System.Device.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.
+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, System.Device.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.
 
@@ -106,9 +112,9 @@ Follows a brief explanation on the files you might want to tweak.
 - 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](https://gist.github.com/nfbot). :warning: Remember to update paths and other preferences according to your setup and machine configuration. :wink:
 - 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](https://vector-of-bool.github.io/docs/vscode-cmake-tools/variants.html#). We've made available Gists with cmake-variants.json for each of the reference targets. Grab yours from [here](https://gist.github.com/nfbot). :warning: Remember to update paths and other preferences according to your setup and machine configuration. :wink:
 
-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).
+To launch the build in VS Code check the status bar at the bottom. Select the build flavour and then click the build button (or hit <kbd>F7</kbd>).
 
-## .NET **nanoFramework** build deliverables
+## .NET **nanoFramework** firmware build deliverables
 
 After a successful build you can find the .NET **nanoFramework** image files in the *build* directory. Those are:
 

content/building/build-nxp.md

@@ -1,8 +1,14 @@
 # How to Build, Flash and Debug the NXP nanoBooter and nanoCLR on Windows using Visual Studio Code
 
+⚠️ NOTE about the need to build .NET **nanoFramework** firmware ⚠️
+
+You only need to build it if you plan to debug the native code, add new targets or add new features at native level.
+If your goal is to code in C# you just have to flash your MCU with the appropriate firmware image.
+There are available ready to flash firmware images for several targets, please check the [Home](https://github.com/nanoframework/Home#firmware-for-reference-boards) repository.
+
 ## About this document
 
-This document describes how to build the required images for .NET **nanoFramework** for NXP targets.
+This document describes how to build the required images for .NET **nanoFramework** firmware for NXP targets.
 The build is based on CMake tool to ease the development in all major platforms.
 
 ## Using Dev Container
@@ -42,7 +48,7 @@ To simplify: this guide we will put all our tools and source in easily accessibl
 
 1. Run the PowerShell script that's on the `install-scripts` folder that will download and install all the required tools.
   `.\install-stm32-tools.ps1 -Path 'C:\nftools'`
-   For best results, run in an elevated command prompt, otherwise setting system environnement variables will fail.
+   For best results, run in an elevated command prompt, otherwise setting system environment variables will fail.
 1. Review and adjust several JSON files to match your environment (as documented below)
 1. Restart Visual Studio Code (due to json changes)
 

content/building/build-stm32.md

@@ -1,8 +1,14 @@
 # How to Build, Flash and Debug the STM32 nanoBooter and nanoCLR on Windows using Visual Studio Code
 
+⚠️ NOTE about the need to build .NET **nanoFramework** firmware ⚠️
+
+You only need to build it if you plan to debug the native code, add new targets or add new features at native level.
+If your goal is to code in C# you just have to flash your MCU with the appropriate firmware image.
+There are available ready to flash firmware images for several targets, please check the [Home](https://github.com/nanoframework/Home#firmware-for-reference-boards) repository.
+
 ## About this document
 
-This document describes how to build the required images for .NET **nanoFramework** for STM32 targets.
+This document describes how to build the required images for .NET **nanoFramework** firmware for STM32 targets.
 The build is based on CMake tool to ease the development in all major platforms.
 
 ## Using Dev Container
@@ -41,7 +47,7 @@ To simplify: this guide we will put all our tools and source in easily accessibl
 
 1. Run the PowerShell script that's on the `install-scripts` folder that will download and install all the required tools.
   `.\install-nf-tools.ps1 -TargetSeries STM32 -Path 'C:\nftools'`
-   For best results, run in an elevated command prompt, otherwise setting system environnement variables will fail.
+   For best results, run in an elevated command prompt, otherwise setting system environment variables will fail.
 1. Review and adjust several JSON files to match your environment (as documented below)
 1. Restart Visual Studio Code (due to json changes)
 

content/building/build-win32.md

@@ -1,5 +1,11 @@
 # Building .NET nanoFramework - WIN32
 
+⚠️ NOTE about the need to build .NET **nanoFramework** firmware ⚠️
+
+You only need to build it if you plan to debug the native code, add new targets or add new features at native level.
+If your goal is to code in C# you just have to flash your MCU with the appropriate firmware image.
+There are available ready to flash firmware images for several targets, please check the [Home](https://github.com/nanoframework/Home#firmware-for-reference-boards) repository.
+
 The WIN32 version meant to be used for high level debugging, feature testing and Unit Testing for other projects.
 It's a VC++ solution which can be build using Visual Studio.
 

content/building/cmake/ninja-build.md

@@ -1,4 +1,4 @@
-# Using Ninja to build .NET **nanoFramework**
+# Using Ninja to build .NET **nanoFramework** firmware
 
 ## Inside VS Code using CMake Tools
 
@@ -10,7 +10,7 @@ To setup the CMake tools to build using Ninja you have to follow the following s
 4. Find a line for `"cmake.configureSettings"`. This is were the full path to the Nina executable should be set. Mind the forward slashes.
 If you don't have one just add a block like this: `"cmake.configureSettings": { "CMAKE_MAKE_PROGRAM": "E:/ninja/ninja.exe" },`
 
-And that is it! Hit F7 or click the build configuration options for CMake Tools at the bottom toolbar.
+And that is it! Hit <kbd>F7</kbd> or click the build configuration options for CMake Tools at the bottom toolbar.
 
 ## Performance comparison
 

content/building/index.md

@@ -1,6 +1,6 @@
 # Building .NET **nanoFramework**
 
-* [Building .NET **nanoFramework**](build-instructions.md)
+* [Building .NET **nanoFramework** firmware](build-instructions.md)
 * [Build using local source for RTOS](rtos-source-for-build.md)
 * [CMake variants for CMake tools](cmake-tools-cmake-variants.md)
 * [Building in Visual Studio](build-in-visual-studio.md)

content/building/rtos-source-for-build.md

@@ -1,30 +1,30 @@
-# Building .NET **nanoFramework** with local RTOS source vs RTOS source from repository
+# Building .NET **nanoFramework** firmware with local RTOS source vs RTOS source from repository
 
-When building .NET **nanoFramework** for a CMSIS target (currently only ChibiOS is supported) the developer has two options: either using a local path for the RTOS source code or downloading it from the official repository.
+When building .NET **nanoFramework** firmware the developer has two options: either using a local path for the RTOS source code or downloading it from the official repository.
 This document aims to give you an brief overview of the differences between these two so you can choose the option that best fits your use scenario.
 
 ## Source from official repository
 
-When running CMake, if the parameter `-DCHIBIOS_SOURCE` is not not specified CMake will connect to **nanoFrameworks** [ChibiOS mirror](https://github.com/nanoframework/ChibiOS) on GitHub and will clone the source from there. The time for this operation to complete will mostly depend on the speed of your internet connection.
+When running CMake, if the parameter `-DRTOS_SOURCE_FOLDER` is not not specified CMake will connect to the respective official repository and will clone the source from there. The time for this operation to complete will mostly depend on the speed of your internet connection.
 
-ChibiOS will be cached within the build directory so the full download won't happen again unless the build directory is cleared. A check for any changes in the repo is made whenever a build is run. If there are any, the changes will be downloaded and merged.
+The RTOS will be cached within the build directory so the full download won't happen again unless the build directory is cleared. A check for any changes in the upstream repository it's performed whenever a build is run. If there are any, the changes will be downloaded and merged.
 
-This option is good for automated builds or when you don't have (or don't want) the repo cloned to your local storage device.
+This option it's great for automated builds or when you don't have (or don't want) the repo cloned to your local storage device.
 
 Another advantage is that you don't have to manage the updates to the local clone yourself.
 
 An obvious disadvantage is that if the build folder is cleaned (required when switching between target boards) the 'cached' repo will be gone and a full download will occur when the project is next built.
 
 ## Source from local clone
 
-When running CMake, if the parameter `-DCHIBIOS_SOURCE="....."` is specified a local clone located at the designated path will be used when the build occurs.
-The only _timing penalty_ is the one necessary for CMake to copy the contents of the local ChibiOS repo to the build cache folder. This is a one time operation and it won't happen again unless the build folder is cleaned up.
+When running CMake, if the parameter `-DRTOS_SOURCE_FOLDER="....."` is specified, a local clone located at the designated path will be used when the build occurs.
+The only _timing penalty_ is the one necessary for CMake to copy the contents of the local RTOS repo to the build cache folder. This is a one time operation and it won't happen again unless the build folder is cleaned up.
 
-This option is good when you have a local clone of the repo and you don't want to increase the build time with checks on the repo and downloading it or wish to target a different branch (such as `master`).
+This option is preferable when you have a local clone of the repo and you don't want to increase the build time with checks on the repo and downloading it or wish to target a different branch.
 
-The downside is that you have to manage the update process for the ChibiOS repo yourself.
+The downside is that you have to manage the update process for the RTOS repo yourself.
 
-Another important aspect to consider is the branch **to _manually_ checkout**. Not doing this is synonym of using the 'master' branch that contains the development files and is not a stable version, which is probably not what you want to use.
-So, make sure that you checkout the branch matching the currently supported stable version. In doubt ask in the Discord channel.
+Another important aspect to consider is the branch or tag that you have to **to _manually_ checkout**. Not doing this is synonym of using the default branch that contains the development files and is not a stable version, which is probably not what you want to use.
+So, make sure that you checkout the branch or tag matching the currently supported stable version. In doubt ask in the Discord channel.
 
 Also here, if the build folder is cleaned the 'cached' repo will be gone.