[scons] Add option to relocate artifact store

.gitignore

@@ -31,6 +31,7 @@ CMakeLists.txt
 
 # ignore generated code in the example folder
 examples/**/modm
+examples/**/artifacts
 examples/**/compile_commands.json
 examples/**/SConstruct
 examples/**/Makefile

tools/build_script_generator/scons/module.lb

@@ -25,6 +25,9 @@ def prepare(module, options):
     module.add_option(
         PathOption(name="cache_dir", default="", empty_ok=True, absolute=True,
                    description=descr_cache_dir))
+    module.add_option(
+        PathOption(name="path.artifact", default="artifacts", absolute=True,
+                   description=descr_path_artifact))
     module.add_option(
         PathOption(name="image.source", default="", empty_ok=True, absolute=True,
                    description=descr_image_source))
@@ -161,6 +164,7 @@ def post_build(env):
     subs.update({
         "build_path": env.relative_outpath(env[":build:build.path"]),
         "cache_dir": env.relative_outpath(cache_dir) if len(cache_dir) else "",
+        "artifact_path": env.relative_outpath(env["path.artifact"]),
         "generated_paths": repositories,
         "is_unittest": is_unittest,
 
@@ -246,6 +250,13 @@ If value is `$cache`, the cache is placed into the top-level `build/` folder.
 You can disable CacheDir by setting an empty string.
 """
 
+descr_path_artifact = """# Path to Artifact Store
+
+The artifact folder contains ELF files named by their GNU build id hash. This
+allows identification of firmware on the device via serial output and is useful
+for archiving or post-mortem debugging.
+"""
+
 descr_image_source = """# Path to directory containing .pbm files"""
 
 descr_unittest_source = """# Path to directory containing unittests

tools/build_script_generator/scons/module.md

@@ -37,7 +37,7 @@ This module generates these SCons methods depending on the target.
 
 Defaults to **scons build**.
 
-You can add these arguments to any of the scons commands:
+You can add these arguments to any of the SCons commands:
 
 - `verbose=1`: gives a more verbose output, so you can, for example, check what
   options the compiler is called with.
@@ -52,6 +52,11 @@ module documentation.
     commands, especially `scons program profile=debug` and
     `scons debug profile=debug`!
 
+Some SCons commands take a `firmware={GNU Build ID or path/to/firmware.elf}`
+argument that specifies which firmware to use for the command. It is useful in
+combination with the `scons artifact` command to preserve a specific firmware
+version for later.
+
 
 #### scons build
 
@@ -78,7 +83,7 @@ Linking········ /build/{debug|release}/blink.elf
 #### scons size
 
 ```
-scons size profile={debug|release}
+scons size profile={debug|release} [firmware={hash or file}]
 ```
 
 Displays the static Flash and RAM consumption of your target.
@@ -104,7 +109,7 @@ Heap:     16.4 MiB
 #### scons program
 
 ```
-scons program profile={debug|release} [port={serial-port}]
+scons program profile={debug|release} [port={serial-port}] [firmware={hash or file}]
 ```
 
 Writes the executable onto your target via Avrdude or OpenOCD.
@@ -142,7 +147,7 @@ shutdown command invoked
 #### scons program-dfu
 
 ```
-scons program-dfu profile={debug|release}
+scons program-dfu profile={debug|release} [firmware={hash or file}]
 ```
 
 Writes the executable onto your target via Device Firmware Update (DFU) over USB.
@@ -200,7 +205,7 @@ scons: done building targets.
 #### scons program-bmp
 
 ```
-scons program-bmp profile={debug|release} [port={serial-port}]
+scons program-bmp profile={debug|release} [port={serial-port}] [firmware={hash or file}]
 ```
 
 [Black Magic Probe][bmp] is convenient tool to convert cheap USB ST-LINK V2 clones
@@ -247,7 +252,7 @@ scons: done building targets.
 #### scons program-remote
 
 ```
-scons program-remote profile={debug|release} [host={ip or hostname}]
+scons program-remote profile={debug|release} [host={ip or hostname}] [firmware={hash or file}]
 ```
 
 Writes the executable onto your target connected to a remote OpenOCD process
@@ -263,7 +268,7 @@ Compiles and executes your program on your computer.
 #### scons debug
 
 ```
-scons debug profile={debug|release} ui={tui|web}
+scons debug profile={debug|release} ui={tui|web} [firmware={hash or file}]
 ```
 
 Launches OpenOCD in the background, then launches GDB in foreground with the
@@ -288,7 +293,7 @@ This is just a convenience wrapper for the debug functionality defined in the
 #### scons debug-bmp
 
 ```
-scons debug-bmp profile={debug|release} ui={tui|web} port={serial-port}
+scons debug-bmp profile={debug|release} ui={tui|web} port={serial-port} [firmware={hash or file}]
 ```
 
 Launches GDB to debug via Black Magic Probe.
@@ -314,7 +319,7 @@ See the `:platform:fault` module for details how to receive the coredump data.
 #### scons program-remote
 
 ```
-scons debug-remote profile={debug|release} ui={tui|web} [host={ip or hostname}]
+scons debug-remote profile={debug|release} ui={tui|web} [host={ip or hostname}] [firmware={hash or file}]
 ```
 
 Debugs the executable via a remote OpenOCD process running on your own computer
@@ -403,13 +408,13 @@ Indexing······· {debug|release}/modm/libmodm.a
 #### scons symbols
 
 ```
-scons symbols profile={debug|release}
+scons symbols profile={debug|release} [firmware={hash or file}]
 ```
 
 Dumps the symbol table for your executable.
 
 ```
- $ scons symbols
+ $ scons symbols [firmware={hash or file}]
 Show symbols for '{debug|release}/blink.elf':
 536871656 00000001 b (anonymous namespace)::nextOperation
 536871657 00000001 b (anonymous namespace)::checkNextOperation
@@ -426,7 +431,7 @@ Show symbols for '{debug|release}/blink.elf':
 #### scons listing
 
 ```
-scons listing profile={debug|release}
+scons listing profile={debug|release} [firmware={hash or file}]
 ```
 
 Decompiles your executable into an annotated assembly listing.
@@ -463,7 +468,7 @@ main()
 #### scons bin
 
 ```
-scons bin profile={debug|release}
+scons bin profile={debug|release} [firmware={hash or file}]
 ```
 
 Creates a binary file of your executable.
@@ -477,7 +482,7 @@ Binary File···· {debug|release}/blink.bin
 #### scons hex
 
 ```
-scons hex profile={debug|release}
+scons hex profile={debug|release} [firmware={hash or file}]
 ```
 
 Creates a Intel-hex file of your executable.
@@ -495,7 +500,8 @@ scons artifact profile={debug|release}
 ```
 
 Caches the ELF and binary file of the newest compiled executable identified by
-the hash of the binary file in `{build_path}/artifacts/{hash}.elf`.
+the hash of the binary file in `artifacts/{hash}.elf`. You can change this path
+with the `modm:build:scons:path.artifact` option.
 
 ```
  $ scons artifact

tools/build_script_generator/scons/resources/SConstruct.in

@@ -17,7 +17,7 @@ CacheDir("{{ cache_dir | modm.windowsify(escape_level=1)}}")
 env = DefaultEnvironment(tools=[], ENV=os.environ)
 env["CONFIG_PROJECT_NAME"] = "{{ options[":build:project.name"] }}"
 env["CONFIG_BUILD_BASE"] = abspath("{{ build_path | modm.windowsify(escape_level=1)}}")
-env["CONFIG_ARTIFACT_PATH"] = join(env["CONFIG_BUILD_BASE"], "artifact")
+env["CONFIG_ARTIFACT_PATH"] = abspath("{{ artifact_path | modm.windowsify(escape_level=1)}}")
 generated_paths = {{ generated_paths }}
 
 # Building all libraries

tools/build_script_generator/scons/resources/build_target.py.in

@@ -15,6 +15,7 @@ from os.path import join, abspath, relpath
 def build_target(env, sources):
 	# Building application
 	program = env.Program(target=env["CONFIG_PROJECT_NAME"]+"{{ program_extension }}", source=sources)
+	chosen_program = env.ChooseFirmware(program)
 	# Clean additional artifacts
 	env.Clean(program, join(env["BUILDPATH"], env["CONFIG_PROJECT_NAME"]+".bin"))
 	env.Clean(program, join(env["BUILDPATH"], env["CONFIG_PROJECT_NAME"]+".hex"))
@@ -28,35 +29,35 @@ def build_target(env, sources):
 %% endif
 
 	env.Alias("qtcreator", env.QtCreatorProject(sources))
-	env.Alias("symbols", env.Symbols(program))
-	env.Alias("listing", env.Listing(program))
-	env.Alias("bin", env.Bin(program))
-	env.Alias("hex", env.Hex(program))
+	env.Alias("symbols", env.Symbols(chosen_program))
+	env.Alias("listing", env.Listing(chosen_program))
+	env.Alias("bin", env.Bin(chosen_program))
+	env.Alias("hex", env.Hex(chosen_program))
 	env.Alias("build", program)
 %% if platform in ["hosted"]
 	env.Alias("run", env.Run(program))
 	env.Alias("all", ["build", "run"])
 %% else
 	# The executable depends on the linkerscript
 	env.Depends(target=program, dependency="{{ linkerscript }}")
-	env.Alias("size", env.Size(program))
+	env.Alias("size", env.Size(chosen_program))
 	%% if core.startswith("cortex-m")
 	env.Alias("log-itm", env.LogItmOpenOcd())
 
 	env.Alias("artifact", env.CacheArtifact(program))
 		%% set artifact = ', "artifact"' if upload_with_artifact else ''
-	env.Alias("program-openocd", [env.ProgramOpenOcd(program){{ artifact }}])
-	env.Alias("program-remote", [env.ProgramGdbRemote(program){{ artifact }}])
-	env.Alias("program-bmp", [env.ProgramBMP(program){{ artifact }}])
-	env.Alias('program-dfu', [env.ProgramDFU(env.Bin(program)){{ artifact }}])
+	env.Alias("program-openocd", [env.ProgramOpenOcd(chosen_program){{ artifact }}])
+	env.Alias("program-remote", [env.ProgramGdbRemote(chosen_program){{ artifact }}])
+	env.Alias("program-bmp", [env.ProgramBMP(chosen_program){{ artifact }}])
+	env.Alias('program-dfu', [env.ProgramDFU(env.Bin(chosen_program)){{ artifact }}])
 		%% if platform in ["sam"]
-	env.Alias("program-bossac", [env.ProgramBossac(env.Bin(program)){{ artifact }}])
+	env.Alias("program-bossac", [env.ProgramBossac(env.Bin(chosen_program)){{ artifact }}])
 		%% endif
 
-	env.Alias("debug-openocd", env.DebugOpenOcd(program))
-	env.Alias("debug-remote", env.DebugGdbRemote(program))
-	env.Alias("debug-bmp", env.DebugBMP(program))
-	env.Alias("debug-coredump", env.DebugCoredump(program))
+	env.Alias("debug-openocd", env.DebugOpenOcd(chosen_program))
+	env.Alias("debug-remote", env.DebugGdbRemote(chosen_program))
+	env.Alias("debug-bmp", env.DebugBMP(chosen_program))
+	env.Alias("debug-coredump", env.DebugCoredump(chosen_program))
 
 	env.Alias("reset-openocd", env.ResetOpenOcd())
 	env.Alias("reset-bmp", env.ResetBMP())
@@ -68,8 +69,8 @@ def build_target(env, sources):
 	env.Alias("debug", "debug-openocd")
 
 	%% elif core.startswith("avr")
-	env.Alias("program-avrdude", env.ProgramAvrdude(program))
-	env.Alias("program-fuses", env.ProgramAvrdudeFuses(program))
+	env.Alias("program-avrdude", env.ProgramAvrdude(chosen_program))
+	env.Alias("program-fuses", env.ProgramAvrdudeFuses(chosen_program))
 	env.Alias("program", "program-avrdude")
 	%% endif
 

tools/build_script_generator/scons/site_tools/crashdebug.py

@@ -17,21 +17,10 @@
 from modm_tools import gdb, crashdebug
 
 def run_post_mortem_gdb(target, source, env):
-	source = str(source[0])
-
-	artifact = ARGUMENTS.get("firmware", None)
-	if artifact is None:
-		print("\n> Using the newest firmware may be inaccurate!\n"
-			  "> Use 'firmware={hash}' argument to specify a specific firmware.\n")
-	else:
-		artifact = artifact.lower()
-		artifactpath = os.path.join(env["CONFIG_ARTIFACT_PATH"], "{}.elf".format(artifact))
-		if os.path.isfile(artifactpath):
-			source = artifactpath
-		else:
-			print("\n> Unable to find artifact '{}' in build cache!\n"
-					"> Run without artifact argument to use newest firmware.\n".format(artifact))
-			return 1
+
+	if ARGUMENTS.get("firmware") is None:
+		print("\n> Using the latest firmware may be inaccurate!"
+			  "\n> Use the 'firmware={hash or file}' argument to point to a specific firmware.\n")
 
 	if not os.path.isfile(env["COREDUMP_FILE"]):
 		print("\n> Unable to find coredump file!"
@@ -43,7 +32,7 @@ def run_post_mortem_gdb(target, source, env):
 	backend = crashdebug.CrashDebugBackend(
 			binary_path=env.subst("$BASEPATH/modm/ext/crashcatcher/bins"),
 			coredump=env["COREDUMP_FILE"])
-	gdb.call(source=source, backend=backend, ui=ARGUMENTS.get("ui", "tui"),
+	gdb.call(source=source[0].path, backend=backend, ui=ARGUMENTS.get("ui", "tui"),
 			 config=map(env.subst, env.Listify(env.get("MODM_GDBINIT", []))),
 			 commands=map(env.subst, env.Listify(env.get("MODM_GDB_COMMANDS", []))))
 

tools/build_script_generator/scons/site_tools/utils.py

@@ -74,6 +74,16 @@ def phony_target(env, **kw):
         env.AlwaysBuild(env.Alias(target, [], action))
 
 
+def artifact_firmware(env, source):
+    firmware = ARGUMENTS.get("firmware", None)
+    if firmware:
+        try:
+            int(firmware, 16) # Validate hexadecimal string
+            source = os.path.join(env["CONFIG_ARTIFACT_PATH"], "{}.elf".format(firmware.lower()))
+        except:
+            source = firmware
+    return source
+
 # -----------------------------------------------------------------------------
 def generate(env, **kw):
     env.Append(ENV={'PATH': os.environ['PATH']})
@@ -86,6 +96,8 @@ def generate(env, **kw):
 
     env.AddMethod(listify, 'Listify')
 
+    env.AddMethod(artifact_firmware, 'ChooseFirmware')
+
 
 def exists(env):
     return True