improved platformio.ini: better comments, added some parts of Almight…

…yFrog's "platformio build fails" issue

platformio.ini

@@ -16,28 +16,30 @@ board           = genericSTM32F103RC
 debug_tool      = stlink
 upload_protocol = stlink
 
+; Optional: use latest version of toolchain-gccarmnoneeabi: search for "toolchain-gccarmnoneeabi" on https://bintray.com/platformio/tool-packages and look at files-tab to get latest version number. If you are having problems disable it, older version should also work fine. https://launchpad.net/gcc-arm-embedded/+milestones
 platform_packages = 
-    toolchain-gccarmnoneeabi @ 1.90301.200702  # https://community.platformio.org/t/can-you-update-toolchain-gccarmnoneeabi/12733
+    toolchain-gccarmnoneeabi @ >=1.90301.200702
 
 ; Serial Port settings (make sure the COM port is correct)
 monitor_port    = COM3
 monitor_speed   = 38400
 
+board_build.ldscript=./STM32F103RCTx_FLASH.ld
+
 build_flags =
-    -I${PROJECT_DIR}/inc/
     -DUSE_HAL_DRIVER
-    -DSTM32F103xE
-    -Wl,-T./STM32F103RCTx_FLASH.ld
-    -Wl,-u,_printf_float  # enable float for printf
-    -Wno-comment  # surpress warnings for multi-line-comments
-    -Wno-parentheses
-    -fsingle-precision-constant  # do not use double precision (64 bit) by default
-    -g -ggdb        ; to generate correctly the 'firmware.elf' for STM STUDIO vizualization and gdb debugger
-#    -Wl,-lnosys
+    -DSTM32F103xE  ; set correct cpu
+    -Wl,-u,_printf_float  ; enable float for printf
+    ; -Wl,-lnosys  ; needed for some functions of libc
+    -Wno-comment  ; surpress warnings for multi-line-comments
+    -Wno-parentheses  ; surpress warnings for parentheses
+    -fsingle-precision-constant  ; do not use double precision (64 bit) by default
+    -g -ggdb  ; to generate correctly the 'firmware.elf' for STM STUDIO vizualization and gdb debugger
     -D VARIANT_BBCAR
-    ; -Og  # optimized for debugging, https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html
-    -O2  # optimized for speed
-    #-DGIT_BRANCH=´git rev-parse --abbrev-ref HEAD´
-    #-DDATE=´date´
+    ; -Og  ; optimized for debugging, https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html
+    -O2  ; optimized for speed
+    ; Tests for automatically adding git version to compiled binary:
+    ; -DGIT_BRANCH=´git rev-parse --abbrev-ref HEAD´
+    ; -DDATE=´date´
     ; https://docs.platformio.org/en/latest/projectconf/section_env_build.html#projectconf-dynamic-build-flags
-    #!echo "-DGIT_HASH="$(git describe --always --dirty)
+    ; !echo "-DGIT_HASH="$(git describe --always --dirty)