Fix echo in top-level Makefile for some environments (#1737)

* Makefile: fix echo for some environments by replacing escape chars with explicit formatting by spaces and new lines

* Dockerfile: extend comments for documentation purpose & switch WORKDIR to IronOS source tree root dir for the seamless workflow

Makefile

@@ -49,42 +49,44 @@ MKDOCS_YML=$(CURDIR)/scripts/IronOS-mkdocs.yml
 # default target to show help
 help:
 	@echo
-	@echo "Welcome!\nThis is $(INFO)"
+	@echo "Welcome!"
+	@echo "This is $(INFO)"
 	@echo "To read more about supported commands (aka \"targets\"), type \"make list\"."
 	@echo "But if you're impatient then just type \"make docker-build\" - it will:"
-	@echo "\t * download, configure & start docker container"
-	@echo "\t * compile builds of IronOS firmware for all supported models inside that container"
-	@echo "\t * export generated binaries to \"scripts/ci/artefacts/\" local directory"
+	@echo "  * download, configure & start docker container"
+	@echo "  * compile builds of IronOS firmware for all supported models inside that container"
+	@echo "  * export generated binaries to \"scripts/ci/artefacts/\" local directory"
 	@echo "Patches are welcome. Happy Hacking!"
 	@echo
 
 # target to list supported targets with additional info
 list:
-	@echo ""
+	@echo
 	@echo "Supported top-level targets:"
-	@echo "\t * help         - shows short basic help"
-	@echo "\t * list         - this output"
-	@echo "\t * docker-shell - start docker container with shell inside to work on IronOS with all tools needed"
-	@echo "\t * docker-build - compile builds of IronOS for supported models inside docker container and place them to \"scripts/ci/artefacts/\""
-	@echo "\t * docker-clean - delete created docker container (but not pre-downloaded data for it)"
-	@echo "\t * docs         - generate \"site\"/ directory with documentation in a form of static html files using ReadTheDocs framework and $(MKDOCS_YML) local config file"
-	@echo "\t * docs-deploy  - generate & deploy docs online to gh-pages branch of current github repo"
-	@echo "\t * clean-build  - delete generated files & dirs produced during builds EXCEPT generated docker container image"
-	@echo "\t * clean-full   - delete generated files & dirs produced during builds INCLUDING generated docker container image"
+	@echo "  * help         - shows short basic help"
+	@echo "  * list         - this output"
+	@echo "  * docker-shell - start docker container with shell inside to work on IronOS with all tools needed"
+	@echo "  * docker-build - compile builds of IronOS for supported models inside docker container and place them to \"scripts/ci/artefacts/\""
+	@echo "  * docker-clean - delete created docker container (but not pre-downloaded data for it)"
+	@echo "  * docs         - generate \"site\"/ directory with documentation in a form of static html files using ReadTheDocs framework and $(MKDOCS_YML) local config file"
+	@echo "  * docs-deploy  - generate & deploy docs online to gh-pages branch of current github repo"
+	@echo "  * clean-build  - delete generated files & dirs produced during builds EXCEPT generated docker container image"
+	@echo "  * clean-full   - delete generated files & dirs produced during builds INCLUDING generated docker container image"
 	@echo ""
 	@echo "NOTES on supported pass-trough targets:"
-	@echo "\t * main Makefile is located in source/ directory and used to build the firmware itself;"
-	@echo "\t * this top-level Makefile supports to call targets from source/Makefile;"
-	@echo "\t * if you set up development environment right on your host, then to build firmware locally, you can just type right from here:"
+	@echo "  * main Makefile is located in source/ directory and used to build the firmware itself;"
+	@echo "  * this top-level Makefile supports to call targets from source/Makefile;"
+	@echo "  * if you set up development environment right on your host, then to build firmware locally, you can just type right from here:"
 	@echo
-	@echo "\t> make firmware-LANG_ID model=MODEL_ID"
+	@echo " $$ make firmware-LANG_ID model=MODEL_ID"
 	@echo
 	@echo "Full list of current supported IDs:"
-	@echo "\t * LANG_ID: BE BG CS DA DE EL EN ES FI FR HR HU IT JA_JP LT NB NL_BE NL PL PT RO RU SK SL SR_CYRL SR_LATN SV TR UK VI YUE_HK ZH_CN ZH_TW"
-	@echo "\t * MODEL_ID: TS100 TS101 TS80 TS80P MHP30 Pinecil Pinecilv2 S60"
+	@echo "  * LANG_ID: BE BG CS DA DE EL EN ES FI FR HR HU IT JA_JP LT NB NL_BE NL PL PT RO RU SK SL SR_CYRL SR_LATN SV TR UK VI YUE_HK ZH_CN ZH_TW"
+	@echo "  * MODEL_ID: TS100 TS101 TS80 TS80P MHP30 Pinecil Pinecilv2 S60"
 	@echo
 	@echo "For example, to make a local build of IronOS firmware for TS100 with English language, just type:"
-	@echo "\n\t> make firmware-EN model=TS100"
+	@echo
+	@echo " $$ make firmware-EN model=TS100"
 	@echo
 
 # bash one-liner to generate langs for "make list":
@@ -132,5 +134,6 @@ clean-build:
 # global clean-up target
 clean-full: clean-build  docker-clean
 
+# phony targets
 .PHONY:  help  list  docker-check  docker-shell  docker-build  docker-clean  docs  docs-deploy  clean-build  clean-full
 

scripts/IronOS.Dockerfile

@@ -1,13 +1,18 @@
+# Default Reference Distro for development env & deploy:
+# * Alpine Linux, version 3.16 *
 FROM alpine:3.16
 LABEL maintainer="Ben V. Brown <ralim@ralimtek.com>"
 
-WORKDIR /build
-# Installing the two compilers, python3, python3 pip, clang format
-# Compilders ->gcc-* newlib-*
-# Python3 -> py*
-# Misc -> findutils make git
-# musl-dev is required for the multi lang firmwares
-# clang is required for clang-format (for dev)
+# Default current dir when container starts
+WORKDIR /build/source
+
+# Installing the two compilers (ARM & RISCV), python3 & pip, clang tools:
+## - compilers: gcc-*, newlib-*
+## - python3: py*, black (required to check Python code formatting)
+## - misc: findutils, make, git
+## - musl-dev (required for the multi lang firmwares)
+## - clang (required for clang-format to check C++ code formatting)
+
 ARG APK_COMPS="gcc-riscv-none-elf gcc-arm-none-eabi newlib-riscv-none-elf \
                newlib-arm-none-eabi"
 ARG APK_PYTHON="python3 py3-pip black"
@@ -17,12 +22,13 @@ ARG APK_DEV="musl-dev clang bash clang-extra-tools"
 # PIP packages
 ARG PIP_PKGS='bdflib'
 
+# Install system packages using alpine package manager
 RUN apk add --no-cache ${APK_COMPS} ${APK_PYTHON} ${APK_MISC} ${APK_DEV}
 
-# Install Python3 packages
-
+# Install Python3 packages as modules using pip
 RUN python3 -m pip install ${PIP_PKGS}
-# Git trust
+
+# Git trust to avoid related warning
 RUN git config --global --add safe.directory /build/source
 
 COPY . /build/source