fbt: FBT_QUIET option; docs on environment (#2403)

* fbt: added FBT_QUIET to suppress toolchain version output; docs: added info on fbt environment
* docs: typo fixes
* fbt: fix for FBT_QUIET handling on *nix
* Add FBT_VERBOSE flag
* Add export
* Fix export
* docs: updates for FBT_VERBOSE

Co-authored-by: DrunkBatya <drunkbatya.js@gmail.com>
Co-authored-by: あく <alleteam@gmail.com>

.vscode/example/launch.json

@@ -11,9 +11,10 @@
             "args": {
                 "useSingleResult": true,
                 "env": {
-                    "PATH": "${workspaceFolder};${env:PATH}"
+                    "PATH": "${workspaceFolder};${env:PATH}",
+                    "FBT_QUIET": 1
                 },
-                "command": "./fbt get_blackmagic",
+                "command": "fbt get_blackmagic",
                 "description": "Get Blackmagic device",
             }
         }

documentation/fbt.md

@@ -3,17 +3,27 @@
 FBT is the entry point for firmware-related commands and utilities.
 It is invoked by `./fbt` in the firmware project root directory. Internally, it is a wrapper around [scons](https://scons.org/) build system.
 
-## Requirements
+## Environment
 
-Install Python packages required by assets build scripts: `pip3 install -r scripts/requirements.txt`
+To use `fbt`, you only need `git` installed in your system.
 
-## NB
+`fbt` by default downloads and unpacks a pre-built toolchain, and then modifies environment variables for itself to use it. It does not contaminate your global system's path with the toolchain.
+ > However, if you wish to use tools supplied with the toolchain outside `fbt`, you can open an *fbt shell*, with properly configured environment.
+ >    - On Windows, simply run `scripts/toochain/fbtenv.cmd`.
+ >    - On Linux & MacOS, run `source scripts/toochain/fbtenv.sh` in a new shell.
+ 
+ If your system is not supported by pre-built toolchain variants or you want to use custom versions of dependencies, you can `set FBT_NOENV=1`. `fbt` will skip toolchain & environment configuration and will expect all tools to be available on your system's `PATH`. *(this option is not available on Windows)*
+ 
+ If `FBT_TOOLCHAIN_PATH` variable is set, `fbt` will use that directory to unpack toolchain into. By default, it downloads toolchain into `toolchain` subdirectory repo's root.
 
-- `fbt` constructs all referenced environments and their targets' dependency trees on startup. So, to keep startup time as low as possible, we're hiding the construction of certain targets behind command-line options.
-- `fbt` always performs `git submodule update --init` on start, unless you set `FBT_NO_SYNC=1` in the environment:
+If you want to enable extra debug output for `fbt` and toolchain management scripts, you can `set FBT_VERBOSE=1`.
+
+`fbt` always performs `git submodule update --init` on start, unless you set `FBT_NO_SYNC=1` in the environment:
   - On Windows, it's `set "FBT_NO_SYNC=1"` in the shell you're running `fbt` from
   - On \*nix, it's `$ FBT_NO_SYNC=1 ./fbt ...`
-- `fbt` builds updater & firmware in separate subdirectories in `build`, and their names depend on optimization settings (`COMPACT` & `DEBUG` options). However, for ease of integration with IDEs, the latest built variant's directory is always linked as `built/latest`. Additionally, `compile_commands.json` is generated in that folder (used for code completion support in IDE).
+
+ > There are more variables controlling basic `fbt` behavior. See `fbt` & `fbtenv` scripts' sources for details.
+
 
 ## Invoking FBT
 
@@ -23,6 +33,12 @@ To build with FBT, call it and specify configuration options & targets to build.
 
 To run cleanup (think of `make clean`) for specified targets, add the `-c` option.
 
+## Build directories
+
+`fbt` builds updater & firmware in separate subdirectories in `build`, and their names depend on optimization settings (`COMPACT` & `DEBUG` options). However, for ease of integration with IDEs, the latest built variant's directory is always linked as `built/latest`. Additionally, `compile_commands.json` is generated in that folder (it is used for code completion support in IDEs).
+ 
+`build/latest` symlink & compilation database are only updated upon *firmware build targets* - that is, when you're re-building the firmware itself. Running other tasks, like firmware flashing or building update bundles *for a different debug/release configuration or hardware target*, does not update `built/latest` dir to point to that configuration.
+
 ## VSCode integration
 
 `fbt` includes basic development environment configuration for VS Code. Run `./fbt vscode_dist` to deploy it. That will copy the initial environment configuration to the `.vscode` folder. After that, you can use that configuration by starting VS Code and choosing the firmware root folder in the "File > Open Folder" menu.

fbt

@@ -6,16 +6,21 @@ set -eu;
 
 # private variables
 SCRIPT_PATH="$(cd "$(dirname "$0")" && pwd -P)";
-SCONS_DEFAULT_FLAGS="-Q --warn=target-not-built";
-SCONS_EP="python3 -m SCons"
+SCONS_DEFAULT_FLAGS="--warn=target-not-built";
+SCONS_EP="python3 -m SCons";
 
 # public variables
 FBT_NOENV="${FBT_NOENV:-""}";
 FBT_NO_SYNC="${FBT_NO_SYNC:-""}";
 FBT_TOOLCHAIN_PATH="${FBT_TOOLCHAIN_PATH:-$SCRIPT_PATH}";
+FBT_VERBOSE="${FBT_VERBOSE:-""}";
 
 if [ -z "$FBT_NOENV" ]; then
-    . "$SCRIPT_PATH/scripts/toolchain/fbtenv.sh";
+    FBT_VERBOSE="$FBT_VERBOSE" . "$SCRIPT_PATH/scripts/toolchain/fbtenv.sh";
+fi
+
+if [ -z "$FBT_VERBOSE" ]; then
+    SCONS_DEFAULT_FLAGS="$SCONS_DEFAULT_FLAGS -Q";
 fi
 
 if [ -z "$FBT_NO_SYNC" ]; then

fbt.cmd

@@ -12,5 +12,10 @@ if [%FBT_NO_SYNC%] == [] (
     )
 )
 
-set "SCONS_DEFAULT_FLAGS=-Q --warn=target-not-built"
+set "SCONS_DEFAULT_FLAGS=--warn=target-not-built"
+
+if not defined FBT_VERBOSE (
+    set "SCONS_DEFAULT_FLAGS=%SCONS_DEFAULT_FLAGS% -Q"
+)
+
 %SCONS_EP% %SCONS_DEFAULT_FLAGS% %*

scripts/toolchain/fbtenv.cmd

@@ -36,7 +36,10 @@ if not "%REAL_TOOLCHAIN_VERSION%" == "%FLIPPER_TOOLCHAIN_VERSION%" (
     set /p REAL_TOOLCHAIN_VERSION=<"%FBT_TOOLCHAIN_VERSION_FILE%"
 )
 
-echo FBT: using toolchain version %REAL_TOOLCHAIN_VERSION%
+if defined FBT_VERBOSE (
+    echo FBT: using toolchain version %REAL_TOOLCHAIN_VERSION%
+)
+
 set "HOME=%USERPROFILE%"
 set "PYTHONHOME=%FBT_TOOLCHAIN_ROOT%\python"
 set "PYTHONPATH="

scripts/toolchain/fbtenv.sh

@@ -7,13 +7,14 @@ DEFAULT_SCRIPT_PATH="$(pwd -P)";
 SCRIPT_PATH="${SCRIPT_PATH:-$DEFAULT_SCRIPT_PATH}";
 FBT_TOOLCHAIN_VERSION="${FBT_TOOLCHAIN_VERSION:-"20"}";
 FBT_TOOLCHAIN_PATH="${FBT_TOOLCHAIN_PATH:-$SCRIPT_PATH}";
+FBT_VERBOSE="${FBT_VERBOSE:-""}";
 
 fbtenv_show_usage()
 {
     echo "Running this script manually is wrong, please source it";
     echo "Example:";
     printf "\tsource scripts/toolchain/fbtenv.sh\n";
-    echo "To restore your environment source fbtenv.sh with '--restore'."
+    echo "To restore your environment, source fbtenv.sh with '--restore'."
     echo "Example:";
     printf "\tsource scripts/toolchain/fbtenv.sh --restore\n";
 }
@@ -42,9 +43,9 @@ fbtenv_restore_env()
         PROMPT="$(echo "$PROMPT" | sed 's/\[fbt\]//g')";
     fi
 
-    PYTHONNOUSERSITE="$SAVED_PYTHONNOUSERSITE";
-    PYTHONPATH="$SAVED_PYTHONPATH";
-    PYTHONHOME="$SAVED_PYTHONHOME";
+    export PYTHONNOUSERSITE="$SAVED_PYTHONNOUSERSITE";
+    export PYTHONPATH="$SAVED_PYTHONPATH";
+    export PYTHONHOME="$SAVED_PYTHONHOME";
 
     unset SAVED_PYTHONNOUSERSITE;
     unset SAVED_PYTHONPATH;
@@ -122,7 +123,7 @@ fbtenv_get_kernel_type()
         TOOLCHAIN_ARCH_DIR="$FBT_TOOLCHAIN_PATH/toolchain/x86_64-linux";
         TOOLCHAIN_URL="https://update.flipperzero.one/builds/toolchain/gcc-arm-none-eabi-10.3-x86_64-linux-flipper-$FBT_TOOLCHAIN_VERSION.tar.gz";
     elif echo "$SYS_TYPE" | grep -q "MINGW"; then
-        echo "In MinGW shell use \"[u]fbt.cmd\" instead of \"[u]fbt\"";
+        echo "In MinGW shell, use \"[u]fbt.cmd\" instead of \"[u]fbt\"";
         return 1;
     else
         echo "Your system configuration is not supported. Sorry.. Please report us your configuration.";
@@ -273,7 +274,9 @@ fbtenv_download_toolchain()
 
 fbtenv_print_version()
 {
-    echo "FBT: using toolchain version $(cat "$TOOLCHAIN_ARCH_DIR/VERSION")";
+    if [ -n "$FBT_VERBOSE" ]; then
+        echo "FBT: using toolchain version $(cat "$TOOLCHAIN_ARCH_DIR/VERSION")";
+    fi
 }
 
 fbtenv_main()
@@ -297,14 +300,15 @@ fbtenv_main()
     PATH="$TOOLCHAIN_ARCH_DIR/protobuf/bin:$PATH";
     PATH="$TOOLCHAIN_ARCH_DIR/openocd/bin:$PATH";
     PATH="$TOOLCHAIN_ARCH_DIR/openssl/bin:$PATH";
+    export PATH;
 
-    SAVED_PYTHONNOUSERSITE="${PYTHONNOUSERSITE:-""}";
-    SAVED_PYTHONPATH="${PYTHONPATH:-""}";
-    SAVED_PYTHONHOME="${PYTHONHOME:-""}";
+    export SAVED_PYTHONNOUSERSITE="${PYTHONNOUSERSITE:-""}";
+    export SAVED_PYTHONPATH="${PYTHONPATH:-""}";
+    export SAVED_PYTHONHOME="${PYTHONHOME:-""}";
 
-    PYTHONNOUSERSITE=1;
-    PYTHONPATH=;
-    PYTHONHOME=;
+    export PYTHONNOUSERSITE=1;
+    export PYTHONPATH=;
+    export PYTHONHOME=;
 }
 
 fbtenv_main "${1:-""}";