opencos-eda 0.2.28__py3-none-any.whl → 0.2.32__py3-none-any.whl

opencos/commands/export.py

@@ -1,6 +1,7 @@
 '''opencos.commands.export - Base class command handler for: eda export ...
 
-Intended to be overriden by Tool based classes (such as CommandExportVivado, etc)'''
+Intended to be overriden by Tool based classes (such as CommandExportVivado, etc), although
+`eda export` can be run without --tool.'''
 
 # Note - similar code waiver, tricky to eliminate it with inheritance when
 # calling reusable methods.

opencos/commands/flist.py

@@ -34,9 +34,17 @@ class CommandFList(CommandDesign):
             'prefix-vhd'         : "",
             'prefix-cpp'         : "",
             'prefix-non-sources' : "", # as comments anyway.
+            # TODO(simon): make the define quoting work like the paths quoting
+            'bracket-quote-define': False,
             'single-quote-define': False,
             'quote-define'       : True,
-            'xilinx'             : False, # convience arg for Vivado tools
+            'equal-define'       : True,
+            'escape-define-value': False,
+            'quote-define-value' : False,
+            'bracket-quote-path' : False,
+            'single-quote-path'  : False,
+            'double-quote-path'  : False,
+            'no-quote-path'      : False,
             'build-script'       : "", # we don't want this to error either
 
             'print-to-stdout': False, # do not save to file, print to stdout.
@@ -102,6 +110,20 @@ class CommandFList(CommandDesign):
         self.create_work_dir()
         self.run_dep_commands()
 
+        pq1 = ""
+        pq2 = "" # pq = path quote
+        if self.args['no-quote-path']:
+            pass # if we decide to make one of the below default, this will override
+        elif self.args['bracket-quote-path']:
+            pq1 = "{"
+            pq2 = "}"
+        elif self.args['single-quote-path']:
+            pq1 = "'"
+            pq2 = "'"
+        elif self.args['double-quote-path']:
+            pq1 = '"'
+            pq2 = '"'
+
         if self.args['print-to-stdout']:
             fo = None
             print()
@@ -119,7 +141,7 @@ class CommandFList(CommandDesign):
                     for f in self.files_non_source:
                         if self.args['emit-rel-path']:
                             f = os.path.relpath(f)
-                        print('##    ' + prefix + f, file=fo)
+                        print('##    ' + prefix + pq1 + f + pq2, file=fo)
 
         if self.args['emit-define']:
             prefix = util.strip_all_quotes(self.args['prefix-define'])
@@ -127,44 +149,59 @@ class CommandFList(CommandDesign):
                 if value is None:
                     newline = prefix + d
                 else:
-                    if self.args['single-quote-define']:
-                        quote = '\''
+                    if self.args['bracket-quote-define']:
+                        qd1 = "{"
+                        qd2 = "}"
+                    elif self.args['single-quote-define']:
+                        qd1 = "'"
+                        qd2 = "'"
                     elif self.args['quote-define']:
-                        quote = '"'
+                        qd1 = '"'
+                        qd2 = '"' # rename this one when things calm down
+                    else:
+                        qd1 = ''
+                        qd2 = ''
+                    if self.args['equal-define']:
+                        ed1 = '='
                     else:
-                        quote = ''
-                    newline = prefix + quote + f"{d}={value}" + quote
+                        ed1 = ' '
+                    if self.args['escape-define-value']:
+                        value = value.replace('\\', '\\\\').replace('"', '\\"')
+                    if self.args['quote-define-value']:
+                        value =f'"{value}"'
+                    newline = prefix + qd1 + f"{d}{ed1}{value}" + qd2
                 print(newline, file=fo)
+
         if self.args['emit-incdir']:
             prefix = util.strip_all_quotes(self.args['prefix-incdir'])
             for i in self.incdirs:
                 if self.args['emit-rel-path']:
                     i = os.path.relpath(i)
-                print(prefix + i, file=fo)
+                print(prefix + pq1 + i + pq2, file=fo)
         if self.args['emit-v']:
             prefix = util.strip_all_quotes(self.args['prefix-v'])
             for f in self.files_v:
                 if self.args['emit-rel-path']:
                     f = os.path.relpath(f)
-                print(prefix + f, file=fo)
+                print(prefix + pq1 + f + pq2, file=fo)
         if self.args['emit-sv']:
             prefix = util.strip_all_quotes(self.args['prefix-sv'])
             for f in self.files_sv:
                 if self.args['emit-rel-path']:
                     f = os.path.relpath(f)
-                print(prefix + f, file=fo)
+                print(prefix + pq1 + f + pq2, file=fo)
         if self.args['emit-vhd']:
             prefix = util.strip_all_quotes(self.args['prefix-vhd'])
             for f in self.files_vhd:
                 if self.args['emit-rel-path']:
                     f = os.path.relpath(f)
-                print(prefix + f, file=fo)
+                print(prefix + pq1 + f + pq2, file=fo)
         if self.args['emit-cpp']:
             prefix = util.strip_all_quotes(self.args['prefix-cpp'])
             for f in self.files_cpp:
                 if self.args['emit-rel-path']:
                     f = os.path.relpath(f)
-                print(prefix + f, file=fo)
+                print(prefix + pq1 + f + pq2, file=fo)
 
         if self.args['print-to-stdout']:
             print() # don't need to close fo (None)

opencos/commands/multi.py

@@ -6,8 +6,8 @@ These are not intended to be overriden by child classes. They do not inherit Too
 import argparse
 import glob
 import os
-import re
 import shutil
+from pathlib import Path
 
 from opencos import util, eda_base, deps_helpers, eda_config, export_helper, \
     eda_tool_helper
@@ -21,25 +21,43 @@ class CommandMulti(CommandParallel):
 
     def __init__(self, config: dict):
         CommandParallel.__init__(self, config=config)
-        self.args.update({
+
+        self.multi_only_args = {
             'fake': False,
             'parallel': 1,
             'single-timeout': None,
             'fail-if-no-targets': False,
             'export-jsonl': False,
-        })
+            'print-targets': False,
+        }
+
+        self.args.update(self.multi_only_args)
         self.args_help.update({
             'single-timeout': ('shell timeout on a single operation in multi, not the entire'
                                'multi command'),
             'fail-if-no-targets': 'fails the multi command if no targets were found',
             'export-jsonl': ('If set, generates export.jsonl if possible, spawns single commands'
                              'with --export-json'),
+            'print-targets': 'Do not run jobs, prints targets to stdout',
         })
         self.single_command = ''
         self.targets = [] # list of tuples (target:str, tool:str)
         self.resolve_target_command = ''
 
 
+    def path_hidden_or_work_dir(self, path: str) -> bool:
+        '''Returns True if any portion of path is hidden file/dir or has a work-dir
+
+        such as  "eda.work" (self.args['eda-dir'])'''
+
+        path_obj = Path(os.path.abspath(path))
+        if self.args['eda-dir'] in path_obj.parts:
+            return True
+        if any(x.startswith('.') and len(x) > 1 for x in path_obj.parts):
+            return True
+        return False
+
+
     def resolve_target_get_command_level(self, level: int = -1) -> (str, int):
         '''increments level, returns tuple of (command str, level int)'''
         command = self.resolve_target_command
@@ -49,13 +67,55 @@ class CommandMulti(CommandParallel):
             level += 1
         return command, level
 
-    @staticmethod
-    def resolve_target_get_path_parts(target: str) -> (str, list):
-        '''Returns (target, path part list).
 
-        Strips outer " and splits on / (POSIX file path only)'''
-        target = target.strip('"').strip("'")
-        return target, target.split("/")
+    def resolve_path_and_target_patterns(
+            self, base_path: str, target: str, level: int = -1
+    ) -> dict:
+        '''Returns a dict of: key = matching path, value = set of matched targets.
+
+        Looks at globbed paths from base_path/target, and looks for DEPS markup targets
+        matching target_pattern (using fnmatch or re.match)
+        '''
+        def debug(*text):
+            util.debug(f'resolve_target() {level=} {base_path=}', *text)
+
+        # join base_path / target
+        #   - if target = ./some_path/**/*test
+        # split them again so we can do all globbing on the path_pattern portion:
+        path_pattern, target_pattern = os.path.split(os.path.join(base_path, target))
+        debug(f'{path_pattern=}, {target_pattern=}')
+
+        if target_pattern == '...':
+            # replace bazel style target ... with '*' for fnmatch.
+            target_pattern = '*'
+
+        matching_targets_dict = {}
+
+        # resolve the path_pattern portion using glob.
+        # we'll have to check for DEPS markup files in path_pattern, to match the target_wildcard
+        # using fnmatch or re.
+        for path in glob.glob(path_pattern, recursive=True):
+
+            if self.path_hidden_or_work_dir(path):
+                continue
+
+            deps_markup_file = deps_helpers.get_deps_markup_file(path)
+            if deps_markup_file:
+                data = deps_helpers.deps_markup_safe_load(deps_markup_file)
+                deps_targets = deps_helpers.deps_data_get_all_targets(data)
+                rel_path = os.path.relpath(path)
+
+                debug(f'in {rel_path=} looking for {target_pattern=} in {deps_targets=}')
+
+                for t in deps_targets:
+                    if deps_helpers.fnmatch_or_re(pattern=target_pattern, string=t):
+                        if rel_path not in matching_targets_dict:
+                            matching_targets_dict[rel_path] = set()
+                        matching_targets_dict[rel_path].add(t)
+
+        debug(f'Found potential targets for {target_pattern=}: {matching_targets_dict=}')
+        return matching_targets_dict
+
 
     def resolve_target(self, base_path: str, target: str, level: int = -1) -> None:
         '''Returns None, recursively attempts to determine the validity of a base_path/target,
@@ -66,37 +126,36 @@ class CommandMulti(CommandParallel):
         '''
 
         def debug(*text):
-            util.debug('resolve_target() {level=} {base_path=}', *text)
+            util.debug(f'resolve_target() {level=} {base_path=}', *text)
 
         command, level = self.resolve_target_get_command_level(level)
 
         debug(f"Enter/Start: target={target}, command={command}")
 
-        target, target_path_parts = self.resolve_target_get_path_parts(target)
-
-        if len(target_path_parts) == 1:
-            debug(f"{target} is a single-part target, look for matches in here")
-
-            target_pattern = "^" + target_path_parts.pop(0) + "$"
-            target_pattern = target_pattern.replace("*", r"[^\/]*")
-            debug(f"{target_pattern=}")
-            self.resolve_target_single(base_path=base_path, target=target_pattern, level=level)
+        # Strip outer quote on target, in case it was passed this way from CLI:
+        for x in ['"', "'"]:
+            target = target.lstrip(x).rstrip(x)
 
-        else:
+        matching_targets_dict = self.resolve_path_and_target_patterns(
+            base_path=base_path, target=target, level=level
+        )
 
-            self.resolve_target_path_parts(base_path=base_path, target=target, level=level)
+        for path, targets in matching_targets_dict.items():
+            self.resolve_target_single_path(base_path=path, targets=targets, level=level)
 
 
-    def resolve_target_single( # pylint: disable=too-many-locals
-            self, base_path: str, target: str, level: int = -1
+    def resolve_target_single_path( # pylint: disable=too-many-locals
+            self, base_path: str, targets: list, level: int = -1
     ) -> None:
-        '''Returns None, called by resolve_target(..) if we have a single target,
+        '''Returns None, called by resolve_target(..) if we have a single base_path,
 
-        and need to resolve it via path and DEPS.[markup] file information.
+        and multiple targets (list), and need to resolve it via base_path and DEPS.[markup]
+        file information. There should be no remaining wildcard information in targets
+        (that was handled earlier with fnmatch and re.)
         '''
 
         def debug(*text):
-            util.debug('resolve_target() {level=} {base_path=}', *text)
+            util.debug(f'resolve_target() {level=} {base_path=}', *text)
 
         command, level = self.resolve_target_get_command_level(level)
 
@@ -110,20 +169,15 @@ class CommandMulti(CommandParallel):
         if data is None:
             data = {}
 
+        deps_targets = deps_helpers.deps_data_get_all_targets(data)
         deps_file_defaults = data.get('DEFAULTS', {})
 
         # Loop through all the targets in DEPS.yml, skipping DEFAULTS
-        for target_node, entry in data.items():
-
-            # Skip upper-case targets, including 'DEFAULTS':
-            if target_node == target_node.upper():
+        for target_node in targets:
+            if target_node not in deps_targets:
                 continue
 
-            m = re.match(target, target_node)
-            if not m:
-                # If the target_node in our deps_file doesn't
-                # match the pattern, then skip.
-                continue
+            entry = data[target_node]
 
             # Since we support a few schema flavors for a target (our
             # 'target_node' key in a DEPS.yml file) santize the entry
@@ -182,96 +236,9 @@ class CommandMulti(CommandParallel):
 
             for tool in all_multi_tools:
                 if tool not in multi_ignore_skip_this_target_node:
-                    debug(f"Found dep {target_node=} {tool=} matching",
-                          f"{target=} {entry=}")
+                    debug(f"Found dep {target_node=} {tool=} matching, {entry=}")
                     self.targets.append( tuple([os.path.join(base_path, target_node), tool]) )
 
-    def resolve_target_path_parts( # pylint: disable=too-many-branches
-            self, base_path: str, target: str, level: int = -1
-    ) -> None:
-        '''Returns None, recursively attempts to determine the validity of a base_path/target,
-
-        operates on a directory, will re-invoke resolve_target(...).
-        '''
-
-        _, level = self.resolve_target_get_command_level(level)
-
-        def debug(*text):
-            util.debug('resolve_target() {level=} {base_path=}', *text)
-
-        target, target_path_parts = self.resolve_target_get_path_parts(target)
-
-        # let's look at the first part of the multi-part target path, which should be a dir
-        part = target_path_parts.pop(0)
-        if part == ".":
-            # just reprocess this directory (matches "./some/path" and retries as "some/path")
-            debug(f"processing {part}, recursing here")
-            self.resolve_target(
-                base_path=base_path, target=os.path.sep.join(target_path_parts),
-                level=level
-            )
-
-        elif part == "..":
-            # reprocess from the directory above (../some/path --> change base_path, some/path)
-            debug(f"processing {part}, recursing above at ../")
-            new_base_path = os.path.abspath(os.path.join(base_path, part))
-            self.resolve_target(
-                base_path=new_base_path, target=os.path.sep.join(target_path_parts),
-                level=level
-            )
-
-        elif part == "...":
-            # support ... as bazel-style all subdirs.
-            debug(f"processing {part}, recursing to check here")
-            # first we check this dir: {"<base>",".../target"} should match "target" in <base>,
-            # so we call {"<base>","target"}
-            self.resolve_target(
-                base_path=base_path, target=os.path.sep.join(target_path_parts),
-                level=level
-            )
-            # now we find all dirs in <base> ...
-            debug(f"processing {part}, looking through dirs...")
-            for e in os.listdir(base_path):
-                debug(f"{e=}, isdir={os.path.isdir(os.path.join(base_path,e))}")
-                if e in ('eda.work', self.args['eda-dir']):
-                    debug(f"processing {part}, skipping work dir {e}")
-                elif os.path.islink(os.path.join(base_path, e)):
-                    debug(f"processing {part}, skipping link dir {e}")
-                elif os.path.isdir(os.path.join(base_path,e)):
-                    debug(f"processing {part}, recursing into {e}")
-                    self.resolve_target(
-                        base_path=os.path.join(base_path, e), target=target,
-                        level=level)
-        elif part.startswith("."):
-            debug(f"processing {part}, skipping hidden")
-        elif part == self.args['eda-dir']:
-            debug(f"processing {part}, skipping eda.dir")
-        elif os.path.isdir(os.path.join(base_path, part)):
-            # reprocess in a lower directory (matches "some/...",
-            # enters "some/", and retries "...")
-            debug(f"processing {part}, recursing down")
-            self.resolve_target(
-                base_path=os.path.join(base_path, part),
-                target=os.path.sep.join(target_path_parts), level=level
-            )
-        elif part == "*":
-            # descend into every directory, we only go in if there's a DEPS though
-            debug(f"processing {part}, looking through dirs...")
-            for e in os.listdir(base_path):
-                debug(f"{e=}")
-                if os.path.isdir(e):
-                    debug(f"looking for ={os.path.join(base_path, e, 'DEPS-markup-file')}")
-                    deps_markup_file = get_deps_markup_file(os.path.join(base_path, e))
-                    if self.config['deps_markup_supported'] and deps_markup_file:
-                        self.resolve_target(
-                            base_path=os.path.join(base_path, e),
-                            target=os.path.sep.join(target_path_parts),
-                            level=level)
-        else:
-            # This is not a warning/error, just means we didn't find what we were looking
-            # for on expanding a path part with * and ... in the target.
-            debug(f"processing {part} ... but not sure what to do with it?")
-
 
     def process_tokens( # pylint: disable=too-many-locals, too-many-branches, too-many-statements
             self, tokens: list, process_all: bool = True, pwd: str = os.getcwd()
@@ -294,9 +261,7 @@ class CommandMulti(CommandParallel):
         # only run it on a subset of our self.args:
         parsed, unparsed = self.run_argparser_on_list(
             tokens=tokens,
-            parser_arg_list=[
-                'fake', 'parallel', 'single-timeout', 'fail-if-no-targets', 'export-jsonl'
-            ],
+            parser_arg_list=list(self.multi_only_args.keys()),
             apply_parsed_args=True
         )
 
@@ -372,10 +337,16 @@ class CommandMulti(CommandParallel):
             mylist = get_pretty_targets_tuple_as_list(self.targets)
             util.info( ", ".join(mylist), start="")
 
-        util.debug("Multi: converting list of targets into list of jobs")
-        self.jobs = []
-        self.append_jobs_from_targets(args=arg_tokens)
-        self.run_jobs(command)
+        if self.args['print-targets']:
+            util.info('Multi print-targets (will not run jobs): -->')
+            for t in self.targets:
+                # t = tuple of (target:str, tool:str), we just want the target.
+                print(f'  {t[0]}')
+        else:
+            util.debug("Multi: converting list of targets into list of jobs")
+            self.jobs = []
+            self.append_jobs_from_targets(args=arg_tokens)
+            self.run_jobs(command)
 
         # Because CommandMulti has a custom arg parsing, we do not have 'export' related
         # args in self.args (they are left as 'unparsed' for the glob'ed commands)

opencos/commands/synth.py

@@ -102,7 +102,6 @@ class CommandSynth(CommandDesign):
         deps_file_args = []
         for a in self.get_command_line_args():
             if any(a.startswith(x) for x in [
-                    '--xilinx',
                     '--optimize',
                     '--synth',
                     '--idelay',

opencos/commands/upload.py

@@ -5,9 +5,9 @@ Intended to be overriden by Tool based classes (such as CommandUploadVivado, etc
 
 import os
 
-from opencos.eda_base import CommandDesign, Tool
+from opencos.eda_base import Command, Tool
 
-class CommandUpload(CommandDesign):
+class CommandUpload(Command):
     '''Base class command handler for: eda upload ...'''
 
     CHECK_REQUIRES = [Tool]
@@ -15,16 +15,16 @@ class CommandUpload(CommandDesign):
     command_name = 'upload'
 
     def __init__(self, config: dict):
-        CommandDesign.__init__(self, config=config)
+        Command.__init__(self, config=config)
+        self.unparsed_args = []
 
     def process_tokens(
             self, tokens: list, process_all: bool = True, pwd: str = os.getcwd()
     ) -> list:
 
-        unparsed = CommandDesign.process_tokens(
-            self, tokens=tokens, process_all=process_all, pwd=pwd
+        self.unparsed_args = Command.process_tokens(
+            self, tokens=tokens, process_all=False, pwd=pwd
         )
         self.create_work_dir()
-        self.run_dep_commands()
         self.do_it()
-        return unparsed
+        return []

opencos/commands/waves.py

@@ -30,9 +30,24 @@ class CommandWaves(CommandDesign):
         '.wdb', '.vcd', '.wlf', '.fst'
     ]
 
+    VSIM_TOOLS = set([
+        'questa',
+        'modelsim_ase',
+    ])
+
+    VSIM_VCD_TOOLS = set([
+        'questa',
+    ])
 
     def __init__(self, config: dict):
         CommandDesign.__init__(self, config=config)
+        self.args.update({
+            'test-mode': False,
+        })
+        self.args_help.update({
+            'test-mode': 'Do not run the command to open the located wave file, instead print' \
+            + ' to stdout',
+        })
 
 
     def get_wave_files_in_dirs(self, wave_dirs: list, quiet: bool = False) -> list:
@@ -62,6 +77,9 @@ class CommandWaves(CommandDesign):
         wave_dirs = []
         tokens = CommandDesign.process_tokens(self, tokens=tokens, process_all=False, pwd=pwd)
 
+        if self.args['test-mode']:
+            self.exec = self._test_mode_exec
+
         while tokens:
             if os.path.isfile(tokens[0]):
                 if wave_file is not None:
@@ -87,8 +105,8 @@ class CommandWaves(CommandDesign):
                 wave_dirs.append('.')
             all_files = self.get_wave_files_in_dirs(wave_dirs)
             if len(all_files) > 1:
-                all_files.sort(os.path.getmtime)
-                util.info(f"Choosing: {self.args['file']} (newest)")
+                all_files.sort(key=os.path.getmtime)
+                util.info(f"Choosing: {all_files[-1]} (newest)")
             if all_files:
                 wave_file = all_files[-1]
             else:
@@ -106,17 +124,18 @@ class CommandWaves(CommandDesign):
                 tcl_name = wave_file + '.waves.tcl'
                 with open( tcl_name, 'w', encoding='utf-8') as fo :
                     print( 'current_fileset', file=fo)
-                    print( f'open_wave_database {wave_file=}', file=fo)
+                    print( f'open_wave_database {wave_file}', file=fo)
                 command_list = [ 'vivado', '-source', tcl_name]
                 self.exec(os.path.dirname(wave_file), command_list)
             else:
                 self.error(f"Don't know how to open {wave_file} without Vivado in PATH")
         elif wave_file.endswith('.wlf'):
-            if 'questa' in self.config['tools_loaded'] and shutil.which('vsim'):
+            if self._vsim_available():
                 command_list = ['vsim', wave_file]
                 self.exec(os.path.dirname(wave_file), command_list)
             else:
-                self.error(f"Don't know how to open {wave_file} without Questa in PATH")
+                self.error(f"Don't know how to open {wave_file} without one of",
+                           f"{self.VSIM_TOOLS} in PATH")
         elif wave_file.endswith('.fst'):
             if 'gtkwave' in self.config['tools_loaded'] and shutil.which('gtkwave'):
                 command_list = ['gtkwave', wave_file]
@@ -124,24 +143,36 @@ class CommandWaves(CommandDesign):
             else:
                 self.error(f"Don't know how to open {wave_file} without GtkWave in PATH")
         elif wave_file.endswith('.vcd'):
-            if 'questa' in self.config['tools_loaded'] and shutil.which('vsim'):
-                command_list = ['vsim', wave_file]
-                self.exec(os.path.dirname(wave_file), command_list)
-            elif 'vivado' in self.config['tools_loaded'] and shutil.which('vivado'):
-                # I don't think this works, this is a placeholder, I'm sure Vivado can open a VCD
-                # Also this would be a great place to start adding some open source (GTKWAVE)
-                # support...
-                tcl_name = wave_file + '.waves.tcl'
-                with open( tcl_name, 'w', encoding='utf-8') as fo :
-                    print( 'current_fileset', file=fo)
-                    print( f'open_wave_database {wave_file=}', file=fo)
-                command_list = [ 'vivado', '-source', tcl_name]
-                self.exec(os.path.dirname(wave_file), command_list)
             if 'gtkwave' in self.config['tools_loaded'] and shutil.which('gktwave'):
                 command_list = ['gtkwave', wave_file]
                 self.exec(os.path.dirname(wave_file), command_list)
+            elif self._vsim_available(from_tools=self.VSIM_VCD_TOOLS):
+                # TODO(drew): untested, may not work, may need to use fst2vcd converter first
+                # (from gtkwave install)
+                command_list = ['vsim', wave_file]
+                self.exec(os.path.dirname(wave_file), command_list)
             else:
                 self.error(f"Don't know how to open {wave_file} without Vivado,",
-                           "Questa, or gtkwave in PATH")
+                           f"gtkwave, or {self.VSIM_VCD_TOOLS} in PATH")
 
         return tokens
+
+    def _vsim_available( # pylint: disable=dangerous-default-value
+            self, from_tools: list = VSIM_TOOLS
+    ) -> bool:
+        '''Returns True if 'vsim' is available (Questa or Modelsim)'''
+        return bool(shutil.which('vsim')) and \
+            any(x in self.config['tools_loaded'] for x in from_tools)
+
+
+    def _test_mode_exec( # pylint: disable=unused-argument
+            self, work_dir: str,
+            command_list: list,
+            **kwargs
+    ) -> None:
+        '''Override for Command.exec if arg --test-mode was set, does not run
+
+        the command_list, instead prints to stdout'''
+
+        util.info(f'waves.py: test_mode exec stdout: {" ".join(command_list)};',
+                  f'   ({work_dir=}')