Merge pull request #1395 from bitcraze/bldocs

Building and flashing guide improvements

docs/building-and-flashing/build.md

@@ -15,36 +15,32 @@ install some ARM toolchain.
 Our policy for toolchain is to follow what is available in the oldest [Ubuntu Long Term Support release](https://wiki.ubuntu.com/Releases) and treat that as the oldest supported version. At the time of writing this (September 6 2021) the oldest LTS release is 18.04. And in Ubuntu 18.04 (bionic) the version of gcc-arm-none-eabi is 6.3.
 
 This means that if the firmware can not be compiled using gcc 6.3, **or anything newer**, it should be considered a bug.
-#### OS X
-```bash
-$ brew tap PX4/homebrew-px4
-$ brew install gcc-arm-none-eabi
-```
-
-#### Debian/Ubuntu
 
+##### Ubuntu
 For Ubuntu 20.04 and 22.04:
-
-```bash
+```
 $ sudo apt-get install make gcc-arm-none-eabi
 ```
 
 For Ubuntu 18.04:
-
-```bash
+```
 $ sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
 $ sudo apt-get update
 $ sudo apt install gcc-arm-embedded
 ```
 
-#### Arch Linux
-
-```bash
+##### Arch Linux
+```
 $ sudo pacman -S community/arm-none-eabi-gcc community/arm-none-eabi-gdb community/arm-none-eabi-newlib
 ```
 
-#### Windows
+##### macOS
+```
+$ brew tap PX4/homebrew-px4
+$ brew install gcc-arm-none-eabi
+```
 
+##### Windows
 The supported way to build the Crazyflie on Windows is to use the Windows Subsystem for Linux (WSL) on Windows 10+.
 This means that developement happens in a Linux environment.
 Flashing is handled by installing Python and the Crazyflie client on Windows launched from linux.
@@ -61,7 +57,7 @@ Then follow the [install instruction for Ubuntu 20.04](#debianubuntu) above to i
 For [flashing](#flashing) you need to install [Python](https://www.python.org/downloads/windows/) (=>version 3.7) and the [CFclient](https://github.com/bitcraze/crazyflie-clients-python) **on Windows**.
 When installing Python, the checkbox to add python to the Path should be checked and then the CFclient can be installed with pip in a `powershell` or `cmd` window:
 ```
-pip.exe install cfclient
+$ pip.exe install cfclient
 ```
 
 The Crazyflie makefile will automatically use the Windows python when running in WSL.
@@ -70,7 +66,7 @@ The Crazyflie makefile will automatically use the Windows python when running in
 
 This repository uses git submodules. Clone with the `--recursive` flag
 
-```bash
+```
 $ git clone --recursive https://github.com/bitcraze/crazyflie-firmware.git
 ```
 
@@ -79,7 +75,7 @@ $ git clone --recursive https://github.com/bitcraze/crazyflie-firmware.git
 If you already have cloned the repo without the `--recursive` option, you need to
 get the submodules manually
 
-```bash
+```
 $ cd crazyflie-firmware
 $ git submodule init
 $ git submodule update
@@ -88,39 +84,43 @@ $ git submodule update
 
 ## Compiling
 
-### Building the default firmware
+### Configuration
 
-Before you can build the firmware, you will need to configure it. To get the default configuration you can write:
+Before you can build the firmware, you will need to configure it. To use a platform default configuration, run the following command:
 
-```bash
+#### Crazyflie 2.x
+```
 $ make cf2_defconfig
-$ make -j 12
 ```
-
-or with the toolbelt:
-
-```bash
-$ tb make cf2_defconfig
-$ tb make
+#### Crazyflie 2.1 Brushless
 ```
-
-Build artifacts, including binaries, will end up in the `build` directory.
-
-### Bolt and Roadrunner
-We have some ready-to-go config files in the `configs/` directory. So, for example, if you want to build the Roadrunner (tag) you can go:
-
-```bash
-$ make tag_defconfig
-$ make -j 12
+$ make cf21bl_defconfig
+```
+#### Crazyflie Bolt
+```
+$ make bolt_defconfig
 ```
 
-Or for the bolt you can go:
+### Building the firmware
+Then build the firmware with:
 
-```bash
-$ make bolt_defconfig
-$ make -j 12
+#### Linux/WSL
+```
+$ make -j$(nproc)
+```
+#### macOS
+```
+$ make -j$(sysctl -n hw.ncpu)
 ```
 
+>  Alternatively, to configure and build with the toolbelt, prepend `tb` to the make commands as follows:
+>  
+>  ```
+>  $ tb make cf2_defconfig
+>  $ tb make
+>  ```
+
+Build artifacts, including binaries, will end up in the `build` directory.
 
 ### Customize the firmware with kbuild (Advanced)
 
@@ -136,11 +136,11 @@ There are certain functions, like the high level commander and controllers, that
 
 First make sure that you have [SWIG](https://swig.org/) installed on your system. Then execute the following commands in the terminal
 
-```bash
-make cf2_defconfig
-make bindings_python
-cd build
-python3 setup.py install --user
+```
+$ make cf2_defconfig
+$ make bindings_python
+$ cd build
+$ python3 setup.py install --user
 ```
 
 ## Make targets
@@ -199,7 +199,7 @@ The supported way to flash when developping for the Crazyflie is to use the Craz
 * Start the Crazyflie in bootloader mode by pressing the power button for 3 seconds. Both the blue LEDs will blink.
 * In your terminal, run
 
-```bash
+```
 $ make cload
 ```
 
@@ -228,37 +228,49 @@ You need:
 
 In your terminal, run
 
-`make flash`
+```
+$ make flash
+```
 
 ## Unit testing
 
 ### Running all unit tests
 
 With the environment set up locally
 
-        make unit
+```
+$ make unit
+```
 
 with the docker builder image and the toolbelt
 
-        tb make unit
+```
+$ tb make unit
+```
 
 ### Running one unit test
 
 When working with one specific file it is often convenient to run only one unit test
 
-       make unit FILES=test/utils/src/test_num.c
+```
+$ make unit FILES=test/utils/src/test_num.c
+```
 
 or with the toolbelt
 
-       tb make unit FILES=test/utils/src/test_num.c
+```
+$ tb make unit FILES=test/utils/src/test_num.c
+```
 
 ### Running unit tests with specific build settings
 
 Defines are managed by make and are passed on to the unit test code. Use the
 normal ways of configuring make when running tests. For instance to run test
 for Crazyflie 1
 
-      make unit LPS_TDOA_ENABLE=1
+```
+$ make unit LPS_TDOA_ENABLE=1
+```
 
 ### Dependencies