[script] reworked top-level makefile: add help desk, support build types

Makefile

@@ -1,26 +1,65 @@
-# Makefile
+# 
+# Top Makefile
+# ------------
+#
+# Top-level makefile to compile the codebase
+#
+# Following options are available
+# 
+# .. option:: BUILD_TYPE=<string>
+#
+#  Pick the type of compilation. Can be either ``release`` or ``debug``. By default, release mode is selected (full optimization on runtime).
+#
+# .. option:: CMAKE_FLAGS=<string>
+#
+#  Force compilation flags for CMake to generate Makefiles
 
+BUILD_TYPE ?= release
+# Convert to lower case for consistency
+BUILD_TYPE := $(shell echo ${BUILD_TYPE} | tr '[:upper:]' '[lower]')
+# Trim any _pgo or _strict in the build type name (since it would not match any of CMake's standard build types
+CMAKE_BUILD_TYPE := $(shell echo ${BUILD_TYPE} | sed 's/_\?pgo//' | sed 's/_\?strict//')
+
+# Allow users to pass parameters to cmake, without defining build types
+# e.g. make CMAKE_FLAGS="-DCMAKE_CXX_COMPILER=g++-9'
+override CMAKE_FLAGS := -DCMAKE_BUILD_TYPE=${BUILD_TYPE} -G 'Unix Makefiles' ${CMAKE_FLAGS}
+
+# Find CMake command from system variable, otherwise use a default one
 ifeq ($(origin CMAKE_COMMAND),undefined)
 CMAKE_COMMAND := cmake
 else
 CMAKE_COMMAND := ${CMAKE_COMMAND}
 endif
 
+# Define python executable
+PYTHON_EXEC ?= python3
+
+# Put it first so that "make" without argument is like "make help".
+export COMMENT_EXTRACT
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@${PYTHON_EXEC} -c "$$COMMENT_EXTRACT"
+
 .PHONY: all checkout compile
 
 all: checkout
+# Update all the submodules and compile the codebase
 	mkdir -p build && cd build && $(CMAKE_COMMAND) ${CMAKE_FLAGS} ..
 	cd build && $(MAKE)
 
 checkout: 
+# Update all the submodules
 	git submodule init
 	git submodule update --init --recursive
 
 compile:
+# Compile the code base
 	mkdir -p build && cd build && $(CMAKE_COMMAND) ${CMAKE_FLAGS} ..
 	cd build && $(MAKE)
 
 clean:
+# Remove current build results
 	rm -rf build yosys/install
 
 build/Makefile:
@@ -30,3 +69,13 @@ build/Makefile:
 
 %: build/Makefile
 	cd build && $(MAKE) $@
+
+# Functions to extract comments from Makefiles
+define COMMENT_EXTRACT
+import re
+with open ('Makefile', 'r' ) as f:
+    matches = re.finditer('^([a-zA-Z-_]*):.*\n#(.*)', f.read(), flags=re.M)
+    for _, match in enumerate(matches, start=1):
+        header, content = match[1], match[2]
+        print(f"  {header:10} {content}")
+endef