Improve readme and add flag to turn debug info ON for libmbed

README.md

@@ -37,30 +37,63 @@ fork/exec /bin/arm-none-eabi-g++: no such file or directory
 ```
 To install ARM build tools, use the `Boards Manager` option in the Arduino IDE to add the `Arduino mbed-enabled Boards` package.
 
+## mbed-os-to-arduino script
 
-## Adding an mbed target
+The backbone of the packaging process is the https://github.com/arduino/ArduinoCore-mbed/blob/master/mbed-os-to-arduino script. It basically compiles a blank Mbed OS project for any supported target board, recovering the files that will be needed at compile time and copying them to the right location.
 
-Adding a target is a mostly automatic procedure that involves running https://github.com/arduino/ArduinoCore-mbed/blob/master/mbed-os-to-arduino after setting the `BOARDNAME` and `ARDUINOCORE` env variables.
-Actions marked as TODO must be executed manually.
+It can be used for a variety of tasks including:
+
+### Recompiling libmbed with source level debug support
+
+```
+cd $sketchbook/hardware/arduino-git/mbed
+./mbed-os-to-arduino -a -g PORTENTA_H7_M7:PORTENTA_H7_M7
+```
+
+In this case `-a` applies all the patches from `patches` folder into a mainline `mbed-os` tree, and `-g` restores the debug info.
+
+### Selecting a different optimization profile
+
+```
+cd $sketchbook/hardware/arduino-git/mbed
+PROFILE=release ./mbed-os-to-arduino -a NANO_RP2040_CONNECT:NANO_RP2040_CONNECT
+```
+
+The `PROFILE` environment variable tunes the compilation profiles (defaults to `DEVELOP`). Other available profiles are `DEBUG` and `RELEASE`.
+
+### Selecting a different Mbed OS tree
 
-**Minimum Example**:
 ```
 cd $sketchbook/hardware/arduino-git/mbed
-./mbed-os-to-arduino -r /home/alex/projects/arduino/cores/mbed-os-h747 PORTENTA_H7_M7:PORTENTA_H7_M7
+./mbed-os-to-arduino -r /path/to/my/mbed-os-fork NICLA_VISION:NICLA_VISION
 ```
 
-### How to build a debug version of the Arduino mbed libraries
-* Modify `mbed-os-to-arduino `
-```diff
-mbed_compile () {
--       PROFILE_FLAG=""
-        if [ x"$PROFILE" != x ]; then
-                PROFILE_FLAG=--profile="$ARDUINOVARIANT"/conf/profile/$PROFILE.json
-                export PROFILE=-${PROFILE^^}
-+       else
-+               export PROFILE="-DEBUG"
-+               PROFILE_FLAG="--profile=debug"
-        fi
+`-r` flag allows using a custom `mbed-os` fork in place of the mainline one; useful during new target development.
+
+### Adding a new target ([core variant](https://arduino.github.io/arduino-cli/latest/platform-specification/#core-variants))
+
+Adding a target is a mostly automatic procedure.
+
+For boards already supported by Mbed OS, the bare minimum is:
+
+```
+cd $sketchbook/hardware/arduino-git/mbed
+mkdir -p variants/$ALREADY_SUPPORTED_BOARD_NAME/{libs,conf}
+./mbed-os-to-arduino $ALREADY_SUPPORTED_BOARD_NAME:$ALREADY_SUPPORTED_BOARD_NAME
+# for example, to create a core for LPC546XX
+# mkdir -p variants/LPC546XX/{libs,conf}
+# ./mbed-os-to-arduino LPC546XX:LPC546XX
+```
+
+This will produce almost all the files needed. To complete the port, add the board specifications to [`boards.txt`](https://arduino.github.io/arduino-cli/latest/platform-specification/#boardstxt) (giving it a unique ID) and provide `pins_arduino.h` and `variants.cpp` in `variants/$ALREADY_SUPPORTED_BOARD_NAME` folder.
+Feel free to take inspirations from the existing variants :)
+
+For boards not supported by mainline Mbed OS, the same applies but you should provide the path of your Mbed OS fork
+
+```
+cd $sketchbook/hardware/arduino-git/mbed
+mkdir -p variants/$BRAND_NEW_BOARD_NAME/{libs,conf}
+./mbed-os-to-arduino -r /path/to/mbed-os/fork/that/supports/new/board $BRAND_NEW_BOARD_NAME:$BRAND_NEW_BOARD_NAME
 ```
 
 ## Using this core as an mbed library

mbed-os-to-arduino

@@ -112,6 +112,12 @@ apply_patches () {
 			cd -
 		fi
 		echo " done."
+		if [ "$RESTORE_GDB_INFO" -eq 1 ]; then
+			echo "Restoring gdb info (this increases libmbed binary size, not suitable for release)"
+			cd mbed-os
+			git checkout tools/profiles/develop.json
+			cd -
+		fi
 	fi
 }
 
@@ -277,11 +283,12 @@ patch_spi_h () {
 # MAIN LOOP #
 #############
 
-while getopts "cuar:b:p:" opt; do
+while getopts "cuagr:b:p:" opt; do
 	case $opt in
 	c ) export MBED_CLEAN=1 ;;
 	u ) export MBED_UPDATE=1 ;;
 	a ) export APPLY_PATCHES=1 ;;
+	g ) export RESTORE_GDB_INFO=1 ;;
 	r ) export LOCAL_REPO="$OPTARG" ;;
 	b ) export REMOTE_BRANCH="$OPTARG" ;;
 	p )
@@ -329,13 +336,15 @@ export MBED_CORE_LOCATION=${MBED_CORE_LOCATION:-$PWD}
 export MBED_CLEAN=${MBED_CLEAN:-0}
 export MBED_UPDATE=${MBED_UPDATE:-0}
 export APPLY_PATCHES=${APPLY_PATCHES:-0}
+export RESTORE_GDB_INFO=${RESTORE_GDB_INFO:-0}
 export LOCAL_REPO=${LOCAL_REPO:-""}
 export REMOTE_BRANCH=${REMOTE_BRANCH:-""}
 
 echo
 echo MBED_CLEAN=$MBED_CLEAN
 echo MBED_UPDATE=$MBED_UPDATE
 echo APPLY_PATCHES=$APPLY_PATCHES
+echo RESTORE_GDB_INFO=$RESTORE_GDB_INFO
 echo LOCAL_REPO="$LOCAL_REPO"
 echo REMOTE_BRANCH="$REMOTE_BRANCH"
 echo MBED_CORE_LOCATION="$MBED_CORE_LOCATION"