add build dir option and document tbb tool

docs/development/09_building.rst

@@ -2,6 +2,13 @@
 Building the Firmware
 *********************
 
+There are multiple ways to build and flash TBB applications:
+
+- using an IDE with the provided dev container (advised option)
+- using an IDE without a dev container (requires installing all dependencies)
+- in terminal using provided build container
+- in terminal not using the build container (requires installing all dependencies)
+
 The easiest way to build the firmware is using the TBD  `dev container <https://containers.dev/>`_
 provided by the TBD repo. This offers the following advantages:
 
@@ -48,8 +55,7 @@ project root dir as
 
 .. code-block:: shell
 
-    docker run -it -v$PWD:/code tbddev tbb dada configure
-    docker run -it -v$PWD:/code tbddev tbb dada build
+    docker run -it -v$PWD:/code tbddev tbb dada configure build
 
 Note that in order to build any other TBD variant just replace ``dada`` with the desired 
 variant.
@@ -74,8 +80,54 @@ You can then view the device log using
     docker run --device /dev/ttyUSB0 -it -v$PWD:/code tbddev tbb dada monitor
 
 
-Building the Firmware without Helpers
-=====================================
+Building the Firmware without Docker
+====================================
+
+Building using tbb Helper
+-------------------------
+
+The ``tbb`` tool is a small utility that helps building for different platforms, without
+having to enter long ``cmake`` invocations. The tool is located in ``tools/bin``. Add
+the tool to your system ``PATH`` or enter full path to tool.
+
+To setup and build use
+
+.. code-block:: shell
+
+    tbb some_platform configure build
+
+tbb Tool Arguments
+------------------
+
+Usage: ``tbb [-p DIR] [-b DIR] [--silent] stage1 [stage2 ...]``
+
+You need to specify at least one or multiple build stages as arguments. The order of those
+arguments does not have any effect and build stages will be performed in the required order.
+Build stages can be
+
+- ``configure``: rum cmake to generate build description
+- ``build``: build the binaries and on embedded platforms create binary image
+
+Options
+.......
+
+``--silent`` do not show processing output
+  The processing steps generate a lot of output. To hide this output set this flag.
+
+``-p DIR``, ``--project-dir DIR`` project directory
+  The root directory of the TBD source code. If this option is not present the directory
+  will be determined in the following order:
+
+  1. value of the ``TBD_PROJECT_DIR`` environment variable
+  2. root of the Git repository containing the current working directory
+  3. current working directory
+
+``-b DIR``, ``--build-dir DIR`` shared root directory for all builds
+  Default is ``build/`` relative to the current working directory.  
+
+
+Building Manually using CMake
+-----------------------------
 
 This can be done from the dev container or from your host system (if all required dependencies
 for building are installed). First set up the build files using CMake from your project

tools/bin/tbb

@@ -219,6 +219,7 @@ tbd_logging_tag="tbd build"
 
 comands=
 tbd_cmd_verbosity=VERBOSE
+build_dir=build
 
 # @brief parse command line options
 #
@@ -232,6 +233,10 @@ parse_args() {
                 project_dir=$2
                 shift
                 ;;
+            -b|--build-dir)
+                build_dir=$2
+                shift
+                ;;
             --silent)
                 tbd_cmd_verbosity="SILENT"
                 ;;
@@ -265,6 +270,10 @@ if ! tbd_is_project_root "$project_dir"; then
   tbd_abort "not a valid project root: $project_dir"
 fi
 
+if [ -z "$build_dir"]; then
+  tbd_abort "build directory not specified"
+fi
+
 if ! tbd_is_valid_platform "$project_dir" "$platform"; then
   tbd_abort "no such platform: $platform"
 fi
@@ -284,12 +293,12 @@ fi
 
 if tbd_is_item_in_list "configure" $commands; then
   tbd_logi "configuring build"
-  tbd_run cmake -GNinja -Bbuild/"$platform" -DTBD_PLATFORM="$platform"
+  tbd_run cmake -GNinja -B"$build_dir/$platform" -DTBD_PLATFORM="$platform"
 fi
 
 if tbd_is_item_in_list "build" $commands; then
   tbd_logi "building project"
-  tbd_run cmake --build build/"$platform"
+  tbd_run cmake --build "$build_dir/$platform"
 fi
 
 if tbd_is_item_in_list "flash" $commands; then

tools/resources/src/tbb.sh

@@ -9,6 +9,7 @@ tbd_logging_tag="tbd build"
 
 comands=
 tbd_cmd_verbosity=VERBOSE
+build_dir=build
 
 # @brief parse command line options
 #
@@ -22,6 +23,10 @@ parse_args() {
                 project_dir=$2
                 shift
                 ;;
+            -b|--build-dir)
+                build_dir=$2
+                shift
+                ;;
             --silent)
                 tbd_cmd_verbosity="SILENT"
                 ;;
@@ -55,6 +60,10 @@ if ! tbd_is_project_root "$project_dir"; then
   tbd_abort "not a valid project root: $project_dir"
 fi
 
+if [ -z "$build_dir"]; then
+  tbd_abort "build directory not specified"
+fi
+
 if ! tbd_is_valid_platform "$project_dir" "$platform"; then
   tbd_abort "no such platform: $platform"
 fi
@@ -74,12 +83,12 @@ fi
 
 if tbd_is_item_in_list "configure" $commands; then
   tbd_logi "configuring build"
-  tbd_run cmake -GNinja -Bbuild/"$platform" -DTBD_PLATFORM="$platform"
+  tbd_run cmake -GNinja -B"$build_dir/$platform" -DTBD_PLATFORM="$platform"
 fi
 
 if tbd_is_item_in_list "build" $commands; then
   tbd_logi "building project"
-  tbd_run cmake --build build/"$platform"
+  tbd_run cmake --build "$build_dir/$platform"
 fi
 
 if tbd_is_item_in_list "flash" $commands; then