refactor: enhanced user interface

- wrappers
- keywords
- renaming
- nicer syntax for external libraries
- embed `updatedb()` in `set_board()`
- support build.opt
- changed default for REATIVE_MACRO (since 2.3.0)
- NDEBUG defined by default (since... whenever)
- added a generic setting to disable HAL modules

internally:
- added argparse to the scripts in CI/update

Author: massonal

CI/update/cmake_core.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 
+import argparse
 import sys
 from pathlib import Path
 from jinja2 import Environment, FileSystemLoader
@@ -8,25 +9,18 @@
 sys.path.append(str(script_path.parent))
 from utils.cmake_gen import *
 
-if len(sys.argv) != 2 :
-    print("Usage: cmake_core.py <.../cores/arduino>")
-    print("Generates a CMakeLists.txt describing a core")
-    print("The resulting static library will be named \"core\".")
+parser = argparse.ArgumentParser()
+parser.add_argument("corepath", type=Path, help="path to .../cores/arduino")
+
+shargs = parser.parse_args()
 
-rootdir = Path(sys.argv[1]).resolve()
-script_path = Path(__file__).parent.resolve()
 templates_dir = script_path / "templates"
 j2_env = Environment(
 loader=FileSystemLoader(str(templates_dir)), trim_blocks=True, lstrip_blocks=True
 )
 cmake_template = j2_env.get_template("CMakeLists.txt")
 
-if not (rootdir.exists() and rootdir.is_dir()) :
-    print(f"Can't find {rootdir}/")
-    exit(1)
-
-
-config = config_for_bareflat(rootdir, force_recurse=True)
+config = config_for_bareflat(shargs.corepath, force_recurse=True)
 config["target"] = "core"
 config["objlib"] = False
-render(rootdir, cmake_template, config)
+render(shargs.corepath, cmake_template, config)

CI/update/cmake_libs.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 
+import argparse
 import sys
 from pathlib import Path
 from jinja2 import Environment, FileSystemLoader
@@ -8,35 +9,31 @@
 sys.path.append(str(script_path.parent))
 from utils.cmake_gen import *
 
-if len(sys.argv) != 2 :
-    print("Usage: cmake_libs.py <.../libraries>")
-    print("Generates a CMakeLists.txt for each library in the folder")
-    print("Usage: cmake_libs.py <.../AwesomeArduinoLibrary>")
-    print("Generates a CMakeLists.txt for the specified library")
-    print("The resulting library targets will be named like their folders.")
+parser = argparse.ArgumentParser()
+input_dirs = parser.add_mutually_exclusive_group(required=True)
+input_dirs.add_argument("--library", "-l", type=Path, help="path to a single library to parse")
+input_dirs.add_argument("--libraries", "-L", type=Path, help="path to a folder of libraries")
+parser.add_argument("--depends", "-d", action="extend", nargs="*", default=list(), help="additional dependencies of the libraries to parse")
 
+shargs = parser.parse_args()
 
-rootdir = Path(sys.argv[1]).resolve()
-script_path = Path(__file__).parent.resolve()
 templates_dir = script_path / "templates"
 j2_env = Environment(
     loader=FileSystemLoader(str(templates_dir)), trim_blocks=True, lstrip_blocks=True
 )
 cmake_template = j2_env.get_template("CMakeLists.txt")
 
-if not rootdir.exists() :
-    print(f"Can't find {rootdir}/")
-    exit(1)
-
-if rootdir.name == "libraries" :
-    for lib in rootdir.iterdir() :
+if shargs.libraries is not None :
+    for lib in shargs.libraries.iterdir() :
         if not lib.is_dir() :
             continue
 
         config = autoconfig(lib)
         config["extra_libs"].add("core")
+        config["extra_libs"].update(shargs.depends)
         render(lib, cmake_template, config)
 else :
-    config = autoconfig(rootdir)
+    config = autoconfig(shargs.library)
     config["extra_libs"].add("core")
-    render(rootdir, cmake_template, config)
+    config["extra_libs"].update(shargs.depends)
+    render(shargs.library, cmake_template, config)

CI/update/cmake_variant.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 
+import argparse
 import sys
 from pathlib import Path
 from jinja2 import Environment, FileSystemLoader
@@ -8,24 +9,19 @@
 sys.path.append(str(script_path.parent))
 from utils.cmake_gen import *
 
-if len(sys.argv) != 2 :
-    print("Usage: cmake_variant.py <.../variants>")
-    print("Generates a CMakeLists.txt describing a variant folder")
-    print("The resulting static library will be named \"variant\".")
+parser = argparse.ArgumentParser()
+parser.add_argument("variantspath", type=Path, help="path to .../variants/")
+
+shargs = parser.parse_args()
 
-rootdir = Path(sys.argv[1]).resolve()
-script_path = Path(__file__).parent.resolve()
 templates_dir = script_path / "templates"
 j2_env = Environment(
     loader=FileSystemLoader(str(templates_dir)), trim_blocks=True, lstrip_blocks=True
 )
 cmake_template = j2_env.get_template("CMakeLists.txt")
 
-if not (rootdir.exists() and rootdir.is_dir()) :
-    print(f"Can't find {rootdir}/")
-    exit(1)
 
-for family in rootdir.iterdir() :
+for family in shargs.variantspath.iterdir() :
     if not family.is_dir() :
         continue
     for variant in family.iterdir() :

CMakeLists.txt

@@ -8,18 +8,6 @@ include(ensure_ctags)
 project("Arduino_Core_STM32" CXX C ASM)
 
 
-set(FEAT_NANOC ON CACHE BOOL "Use nano libc?")
-set(FEAT_FPF OFF CACHE BOOL "nanolibc: enable %f in printf?")
-set(FEAT_FSF OFF CACHE BOOL "nanolibc: enable %f in scanf?")
-set(FEAT_TIMER ON CACHE BOOL "Timer support")
-
-set(BUILD_OPT "s" CACHE STRING "Optimization level")
-set(BUILD_DBG OFF CACHE BOOL "Enable debug symbols")
-set(BUILD_LTO OFF CACHE BOOL "Enable Link-Time-Optimisations")
-set(BUILD_RELPATH ON CACHE BOOL "make __FILE__ be relative instead of absolute")
-set(BUILD_NDEBUG ON CACHE BOOL "define the NDEBUG macro?")
-
-
 set(BUILD_CORE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cores/arduino")
 set(BUILD_SYSTEM_PATH "${CMAKE_CURRENT_SOURCE_DIR}/system")
 set(BUILD_LIB_PATH "${CMAKE_CURRENT_SOURCE_DIR}/libraries")
@@ -34,67 +22,11 @@ ensure_ctags(${CTAGS_PATH} ${AUTODL_CTAGS})
 
 add_library(base_config INTERFACE)
 
-if(${BUILD_RELPATH})
-  # $<TARGET_PROPERTY:SOURCE_DIR> is evaluated by the final consumer, no base_config
-  target_compile_options(base_config INTERFACE
-    "-fmacro-prefix-map=$<TARGET_PROPERTY:SOURCE_DIR>=."
-  )
-endif()
-
-if(${BUILD_NDEBUG})
-  add_compile_definitions(base_config INTERFACE NDEBUG)
-endif()
-
-
-if (${FEAT_NANOC})
-	target_link_options(base_config INTERFACE
-		"--specs=nano.specs"
-	)
-	if (${FEAT_FPF})
-		target_link_options(base_config INTERFACE
-			"SHELL:-u _printf_float"
-		)
-	endif()
-	if(${FEAT_FSF})
-		target_link_options(base_config INTERFACE
-			"SHELL:-u _scanf_float"
-		)
-	endif()
-endif()
-
-if (${FEAT_TIMER})
-  target_compile_definitions(base_config INTERFACE
-    HAL_TIM_MODULE_ENABLE
-  )
-else ()
-  # triggers a user-directed warning
-  target_compile_definitions(base_config INTERFACE
-    HAL_TIM_MODULE_DISABLED
-  )
-endif()
-
-if (${BUILD_OPT} MATCHES "^[0-3gs]$")
-	target_compile_options(base_config INTERFACE
-		-O${BUILD_OPT}
-	)
-else()
-	message(SEND_ERROR "Bad value for BUILD_OPT: got `${BUILD_OPT}`, expected one of 0123gs.")
-endif()
-
-if (${BUILD_DBG})
-	target_compile_options(base_config INTERFACE
-		-g
-	)
-endif()
-
-if (${BUILD_LTO})
-	target_compile_options(base_config INTERFACE
-    -flto
-  )
-	target_link_options(base_config INTERFACE
-    -flto
-  )
-endif()
+# better than an if/else because these may be defined later
+target_link_libraries(base_config INTERFACE
+  $<TARGET_NAME_IF_EXISTS:user_settings>
+  $<TARGET_NAME_IF_EXISTS:board>
+)
 
 # generic compilation options
 target_link_libraries(base_config INTERFACE board)
@@ -145,8 +77,6 @@ target_include_directories(base_config INTERFACE
   "${BUILD_SYSTEM_PATH}/Middlewares/OpenAMP/open-amp/lib/include"
   "${BUILD_SYSTEM_PATH}/Middlewares/OpenAMP/libmetal/lib/include"
   "${BUILD_SYSTEM_PATH}/Middlewares/OpenAMP/virtual_driver"
-
-  "${BUILD_LIB_PATH}/SrcWrapper/src"
 )
 
 add_subdirectory(${BUILD_CORE_PATH})
@@ -156,11 +86,6 @@ add_subdirectory(${BUILD_LIB_PATH})
 
 add_library(stm32_runtime INTERFACE)
 target_link_libraries(stm32_runtime INTERFACE
-  # note: there may be recursive dependencies between core and SrcWrapper (v. <= 2.2.0)
-  # this would require some --Wl,--start-group / -Wl,--end-group
-  # but SrcWrapper is an object library, not an archive, so it isn't necessary
-  # (this means the linker takes all the object unconditionally, as opposed to an archive where it picks what it needs)
-  # note: SrcWrapper in particular MUST be an object library, due to possible weak+strong symbols (cf. library.properties)
   base_config
 
   SrcWrapper

cmake/build_sketch.cmake

@@ -0,0 +1,59 @@
+## core feature
+
+set(SCRIPTS_FOLDER ${CMAKE_CURRENT_LIST_DIR}/../scripts)
+include(sketch_preprocess_sources)
+include(convert_file)
+
+function(build_sketch)
+  cmake_parse_arguments(PARSE_ARGV 0 SKBD "" "TARGET" "SOURCES;DEPENDS")
+
+  if(DEFINED SKBD_UNPARSED_ARGUMENTS OR DEFINED SKBD_KEYWORDS_MISSING_VALUES)
+    message(SEND_ERROR "Invalid call to build_sketch(); some arguments went unparsed")
+  endif()
+
+  if(NOT DEFINED SKBD_TARGET)
+    message(SEND_ERROR "Invalid call to build_sketch(); please specify a TARGET")
+    return()
+  elseif(NOT DEFINED SKBD_SOURCES)
+    message(SEND_ERROR "Invalid call to build_sketch(); please specify some SOURCES")
+    return()
+  endif()
+
+  add_executable(${SKBD_TARGET})
+  target_include_directories(base_config INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})
+
+  foreach(SRCS IN LISTS SKBD_SOURCES)
+    sketch_preprocess_sources(OUTPUT_VARIABLE SRCS SOURCES ${SRCS})
+    target_sources(${SKBD_TARGET} PRIVATE ${SRCS})
+  endforeach()
+
+  target_link_libraries(${SKBD_TARGET} PRIVATE stm32_runtime)
+  if(DEFINED SKBD_DEPENDS)
+    target_link_libraries(${SKBD_TARGET} PRIVATE ${SKBD_DEPENDS})
+  endif()
+
+  get_target_property(OUTDIR ${SKBD_TARGET} BINARY_DIR)
+  set(MAPFILE ${OUTDIR}/${SKBD_TARGET}.map)
+
+  target_link_options(${SKBD_TARGET} PRIVATE
+    LINKER:-Map,${MAPFILE}
+  )
+
+  # this is here to make CMake et al. aware that the map file
+  # is generated along with the binary
+  add_custom_command(TARGET ${SKBD_TARGET} POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E true # essentially a no-op
+    BYPRODUCTS ${MAPFILE}
+  )
+
+  if(EXISTS ${PYTHON3})
+    add_custom_command(TARGET ${SKBD_TARGET} POST_BUILD
+      COMMAND ${PYTHON3} ${SCRIPTS_FOLDER}/sizereport.py -x ${CMAKE_SIZE} -f $<TARGET_FILE:${SKBD_TARGET}> --progmem ${BOARD_MAXSIZE} --datamem ${BOARD_MAXDATASIZE}
+    )
+  else() #  STREQUAL "PYTHON3-NOTFOUND"
+    message(WARNING "python3 not found; the final size report will not be displayed")
+  endif()
+
+  elf2bin(${SKBD_TARGET})
+  elf2hex(${SKBD_TARGET})
+endfunction()

cmake/convert_file.cmake

@@ -0,0 +1,27 @@
+
+function(elf2bin ELFTGT)
+  add_custom_command(TARGET ${ELFTGT} POST_BUILD
+    COMMAND ${CMAKE_OBJCOPY} -O binary $<TARGET_FILE:${ELFTGT}> $<TARGET_FILE:${ELFTGT}>.bin
+  )
+  set_property(TARGET ${ELFTGT} APPEND PROPERTY ADDITIONAL_CLEAN_FILES "$<TARGET_FILE:${ELFTGT}>.bin")
+endfunction()
+
+function(elf2hex ELFTGT)
+  add_custom_command(TARGET ${ELFTGT} POST_BUILD
+    COMMAND ${CMAKE_OBJCOPY} -O ihex $<TARGET_FILE:${ELFTGT}> $<TARGET_FILE:${ELFTGT}>.hex
+  )
+  set_property(TARGET ${ELFTGT} APPEND PROPERTY ADDITIONAL_CLEAN_FILES "$<TARGET_FILE:${ELFTGT}>.hex")
+endfunction()
+
+function(gv2svg GVFILE)
+  get_filename_component(ABSGV ${GVFILE} ABSOLUTE BASE_DIR ${CMAKE_CURRENT_BINARY_DIR})
+  get_filename_component(GVNAME ${GVFILE} NAME)
+
+  # HACK: all this to get the final SVG file as a visible target with the same name as the file
+  add_custom_target(${GVNAME}.svg DEPENDS ${ABSGV})
+  add_custom_command(TARGET ${GVNAME}.svg POST_BUILD
+    COMMAND ${SFDP} -Tsvg -o ${ABSGV}.svg ${ABSGV}
+  )
+  set_property(TARGET ${GVNAME}.svg APPEND PROPERTY ADDITIONAL_CLEAN_FILES ${ABSGV}.svg)
+
+endfunction()

cmake/external_library.cmake

@@ -1,15 +1,24 @@
 
 set(CI_FOLDER ${CMAKE_CURRENT_LIST_DIR}/../CI)
 
-function(external_library LIBPATH)
-  if(NOT EXISTS ${LIBPATH}/CMakeLists.txt)
+function(external_library)
+  cmake_parse_arguments(PARSE_ARGV 0 XLIB "FORCE" "PATH" "DEPENDS")
+
+  if(DEFINED XLIB_UNPARSED_ARGUMENTS OR DEFINED XLIB_KEYWORDS_MISSING_VALUES)
+    message(SEND_ERROR "Invalid call to external_library(); some arguments went unparsed")
+  endif()
+
+  if(NOT DEFINED XLIB_PATH)
+    message(SEND_ERROR "Invalid call to external_library(); please specify a PATH")
+    return()
+  endif()
+
+  if(NOT EXISTS ${XLIB_PATH}/CMakeLists.txt OR ${XLIB_FORCE})
     execute_process(
-      COMMAND ${PYTHON3} ${CI_FOLDER}/update/cmake_libs.py ${LIBPATH}
+      COMMAND ${PYTHON3} ${CI_FOLDER}/update/cmake_libs.py -l ${XLIB_PATH} -d ${XLIB_DEPENDS}
+      WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
     )
   endif()
-  get_filename_component(LIBNAME ${LIBPATH} NAME)
-  add_subdirectory(
-    ${LIBPATH}
-    ${CMAKE_CURRENT_BINARY_DIR}/${LIBNAME}
-  )
+  get_filename_component(LIBNAME ${XLIB_PATH} NAME)
+  add_subdirectory(${XLIB_PATH} ${LIBNAME})
 endfunction()