opencos-eda 0.3.16__py3-none-any.whl → 0.3.17__py3-none-any.whl

opencos/commands/flist.py

@@ -19,7 +19,7 @@ class CommandFList(CommandDesign):
 
     command_name = 'flist'
 
-    def __init__(self, config: dict):
+    def __init__(self, config: dict, **kwargs):
         CommandDesign.__init__(self, config=config)
 
         # If there's no tool attached, then we'll assume this flist is being created
@@ -38,31 +38,6 @@ class CommandFList(CommandDesign):
             'emit-cpp'           : True,
             'emit-non-sources'   : True, # as comments, from DEPS 'reqs'
             'emit-eda-args'      : not self.flist_has_tool, # no Tool means flist for eda.
-            'prefix-define'      : "+define+",
-            'prefix-parameter'   : "-G",
-            'prefix-incdir'      : "+incdir+",
-            'prefix-plusargs'    : "+",
-            'prefix-v'           : "",
-            'prefix-sv'          : "",
-            'prefix-vhd'         : "",
-            'prefix-cpp'         : "",
-            'prefix-non-sources' : "", # as comments anyway.
-            # NOTE - the defaults are for creating an flist that is suitable for 'eda', which for
-            # defines means: optionally single-quote the entire thing, double-quote string values
-            # only.
-            # Tool classes should override if they want to set safe-mode-defines=True.
-            # Tool classes may also avoid these args entirely in their derived CommandFList class
-            'safe-mode-defines'   : not self.flist_has_tool, # no Tool
-            'bracket-quote-define': False,
-            'single-quote-define': False,
-            'quote-define'       : self.flist_has_tool, # Tool, this is NOT for eda.
-            'equal-define'       : True,
-            'escape-define-value': False,
-            'quote-define-value' : False,
-            'bracket-quote-path' : False,
-            'single-quote-path'  : False,
-            'double-quote-path'  : False,
-            'quote-path'         : True,
             'build-script'       : "", # we don't want this to error either
 
             'print-to-stdout': False,
@@ -71,6 +46,49 @@ class CommandFList(CommandDesign):
             'emit-rel-path'  : False,
         }
 
+        # Derived classes many choose to not include ALL the args, so their --help is less
+        # cluttered, for features they don't or can't support.
+        # Note - take care when referencing them! Use self.args.get(key, '') or
+        # self.args.get(key, False). Do NOT use self.args[key]:
+        if kwargs.get('include_prefix_args', True):
+            self.flist_args.update({
+                'prefix-define'      : "+define+",
+                'prefix-parameter'   : "-G",
+                'prefix-incdir'      : "+incdir+",
+                'prefix-plusargs'    : "+",
+                'prefix-v'           : "",
+                'prefix-sv'          : "",
+                'prefix-vhd'         : "",
+                'prefix-cpp'         : "",
+                'prefix-non-sources' : "", # as comments anyway.
+            })
+        if kwargs.get('include_quote_args', True) or \
+           kwargs.get('include_format_define_args', True):
+            self.flist_args.update({
+                'quote-define'       : self.flist_has_tool, # Tool, this is NOT for eda.
+                'quote-define-value' : False,
+                'bracket-quote-define': False,
+                'single-quote-define': False,
+            })
+        if kwargs.get('include_quote_args', True):
+            self.flist_args.update({
+                # NOTE - the defaults are for creating an flist that is suitable for 'eda', which
+                # for defines means: optionally single-quote the entire thing, double-quote string
+                # values only.
+                'bracket-quote-path' : False,
+                'single-quote-path'  : False,
+                'double-quote-path'  : False,
+                'quote-path'         : True,
+            })
+        if kwargs.get('include_format_define_args', True):
+            self.flist_args.update({
+                # Tool classes should override if they want to set safe-mode-defines=True.
+                # Tool classes may also avoid these args entirely in their derived constructor
+                'safe-mode-defines'   : not self.flist_has_tool, # no Tool
+                'equal-define'       : True,
+                'escape-define-value': False,
+            })
+
 
         self.args.update({
             'eda-dir'            : 'eda.flist', # user can specify eda-dir if files are generated.
@@ -81,6 +99,9 @@ class CommandFList(CommandDesign):
             'print-to-stdout': "do not save file, print to stdout",
         })
 
+        self.info_tool_string = ''
+
+
     def process_tokens(
             self, tokens: list , process_all: bool = True, pwd: str = os.getcwd()
     ) -> list:
@@ -117,7 +138,7 @@ class CommandFList(CommandDesign):
         '''Returns formatted list of str for known defines'''
 
         ret = []
-        prefix = strip_all_quotes(self.args['prefix-define'])
+        prefix = strip_all_quotes(self.args.get('prefix-define', '+define+'))
         for d, value in self.defines.items():
 
             if value is None:
@@ -126,36 +147,39 @@ class CommandFList(CommandDesign):
 
             # else, value exists:
             safe_mode_guard_str_value = bool(
-                self.args['safe-mode-defines'] and isinstance(value, str) and ' ' in value
+                self.args.get('safe-mode-defines', False)
+                and isinstance(value, str)
+                and ' ' in value
             )
 
-            if self.args['bracket-quote-define']:
+            if self.args.get('bracket-quote-define', False):
                 qd1 = "{"
                 qd2 = "}"
-            elif self.args['single-quote-define']:
+            elif self.args.get('single-quote-define', False):
                 qd1 = "'"
                 qd2 = "'"
-            elif self.args['quote-define']:
+            elif self.args.get('quote-define', False):
                 qd1 = '"'
                 qd2 = '"'
             else:
                 qd1 = ''
                 qd2 = ''
 
-            if self.args['equal-define']:
+            if self.args.get('equal-define', False):
                 ed1 = '='
             else:
                 ed1 = ' '
 
-            if self.args['escape-define-value']:
+            if self.args.get('escape-define-value', False):
                 value = value.replace('\\', '\\\\').replace('"', '\\"')
-            if self.args['quote-define-value']:
+            if self.args.get('quote-define-value', False):
                 value = '"' + value + '"'
             if safe_mode_guard_str_value:
                 value = strip_outer_quotes(value.strip('\n'))
                 value = '"' + value + '"'
 
-            if self.args['quote-define'] and value.startswith('"') and value.endswith('"'):
+            if self.args.get('quote-define', False) and isinstance(value, str) and \
+               value.startswith('"') and value.endswith('"'):
                 # If you wanted your define to look like:
                 # +define+"NAME=VALUE", but VALUE also has double quotes wrapping it,
                 # it's unlikely to work so we'll optimistically so escape the " wrapping value.
@@ -181,16 +205,16 @@ class CommandFList(CommandDesign):
         '''
         ret = []
         for x in self.args.get('unprocessed-plusargs', []) + self.args.get('sim-plusargs', []):
-            if self.args['prefix-plusargs']:
+            if self.args.get('prefix-plusargs', '+'):
                 if x.startswith('+'):
                     x = x[1:] # strip leading +
-                x = self.args['prefix-plusargs'] + x
+                x = self.args.get('prefix-plusargs', '+') + x
             ret.append(x)
         return ret
 
     def get_flist_parameter_list(self) -> list:
         '''Returns formatted list of str for parameters'''
-        prefix = strip_all_quotes(self.args['prefix-parameter'])
+        prefix = strip_all_quotes(self.args.get('prefix-parameter', '-G'))
         return parameters_dict_get_command_list(
                 params=self.parameters, arg_prefix=prefix, for_flist=True
         )
@@ -256,16 +280,14 @@ class CommandFList(CommandDesign):
             return
 
         if self.config['tool']:
-            tool_string = f' (with --tool={self.config["tool"]})'
-        else:
-            tool_string = ''
+            self.info_tool_string = f' (with --tool={self.config["tool"]})'
 
         # if config['tool'] is set, but self.flist_has_tool is False, we're likely using
         # this default handler CommandFList and the Tool class hasn't defined what they
         # do. In this case, simply warn that this will emit a non-tool specific default flist
         # intended for use by `eda`:
         if self.config['tool'] and not self.flist_has_tool:
-            util.warning(f'For command="flist"{tool_string}, there is no tool',
+            util.warning(f'For command="flist"{self.info_tool_string}, there is no tool',
                          'specific handler for producing an flist. The default eda flist will',
                          'be emitted')
             # If this happens, you'll likely want the Tool based defines (that were never set
@@ -294,120 +316,153 @@ class CommandFList(CommandDesign):
         self.create_work_dir()
         self.run_dep_commands()
 
+        self.write_flist()
+
+        self.write_eda_config_and_args()
+        self.run_post_tool_dep_commands()
+
+
+    def write_flist(self) -> None:
+        '''Derived classes may override, uses self.args to decide if:
+
+        -- writing to stdout or file
+        -- all self.args knobs for how a define/incdir/file/parameter is presented
+
+        It may be more convenient to override CommandFList.get_write_flist_lines()
+        instead.
+        '''
+        if self.args['print-to-stdout']:
+            for line in self.get_write_flist_lines(add_comment_lines=False):
+                print(line)
+            print()
+        else:
+            util.debug(f"Opening {self.args['out']} for writing")
+            with open(self.args['out'], 'w', encoding='utf-8') as fo:
+                for line in self.get_write_flist_lines(add_comment_lines=True):
+                    print(line, file=fo)
+            util.info(f"Created file: {self.args['out']}")
+
+
+    def get_write_flist_lines(
+            self, add_comment_lines: bool = False
+    ) -> list:
+        '''Derived classes may override, uses self.args to decide if:
+
+        -- all self.args knobs for how a define/incdir/file/parameter is presented
+
+        Derived classes can override to ignore a lot of the self.args configuration,
+        and instead follow the basic flow of dumping an flist, but how they see fit
+        for a given Tool class
+        '''
+
+        ret = []
+
         pq1 = ""
         pq2 = "" # pq = path quote
-        if not self.args['quote-path']:
+        if not self.args.get('quote-path', False):
             pass # if we decide to make one of the below default, this will override
-        elif self.args['bracket-quote-path']:
+        elif self.args.get('bracket-quote-path', False):
             pq1 = "{"
             pq2 = "}"
-        elif self.args['single-quote-path']:
+        elif self.args.get('single-quote-path', False):
             pq1 = "'"
             pq2 = "'"
-        elif self.args['double-quote-path']:
+        elif self.args.get('double-quote-path', False):
             pq1 = '"'
             pq2 = '"'
 
-        if self.args['print-to-stdout']:
-            fo = None
-            print()
-        else:
-            util.debug(f"Opening {self.args['out']} for writing")
-            fo = open( # pylint: disable=consider-using-with
-                self.args['out'], 'w', encoding='utf-8'
-            )
-            print(f"## {self.args=}", file=fo)
+        if add_comment_lines:
+            ret.append(f"## {self.args=}")
 
             if self.args['emit-non-sources']:
                 if self.files_non_source:
-                    print('## reqs (non-source files that are dependencies):', file=fo)
-                    prefix = strip_all_quotes(self.args['prefix-non-sources'])
+                    ret.append('## reqs (non-source files that are dependencies):')
+                    prefix = strip_all_quotes(self.args.get('prefix-non-sources', ''))
                     for f in self.files_non_source:
                         if self.args['emit-rel-path']:
                             f = os.path.relpath(f)
-                        print('##    ' + prefix + pq1 + f + pq2, file=fo)
+                        ret.append('##    ' + prefix + pq1 + f + pq2)
 
         if self.args['emit-eda-args']:
             for newline in self.get_flist_eda_args_list():
-                print(newline, file=fo)
+                ret.append(newline)
 
         defines_lines = self.get_flist_defines_list()
         if not self.args['emit-define'] and defines_lines:
-            util.warning(f'Command "flist"{tool_string}, has defines present but they were not',
-                         f'included in the output flist: {defines_lines}')
+            util.warning(
+                f'Command "flist"{self.info_tool_string}, has defines present but they were not',
+                f'included in the output flist: {defines_lines}'
+            )
 
         parameter_lines = self.get_flist_parameter_list()
         if not self.args['emit-parameter'] and parameter_lines:
-            util.warning(f'Command "flist"{tool_string}, has parameters present but they were not',
-                         f'included in the output flist: {parameter_lines}')
+            util.warning(
+                f'Command "flist"{self.info_tool_string}, has parameters present but they were not',
+                f'included in the output flist: {parameter_lines}'
+            )
 
         plusarg_lines = self.get_flist_plusargs_list()
         if not self.args['emit-plusargs'] and plusarg_lines:
-            util.warning(f'Command "flist"{tool_string}, has plusargs present but they were not',
-                         f'included in the output flist: {plusarg_lines}')
+            util.warning(
+                f'Command "flist"{self.info_tool_string}, has plusargs present but they were not',
+                f'included in the output flist: {plusarg_lines}'
+            )
 
         if self.args['emit-define']:
             for newline in defines_lines:
-                print(newline, file=fo)
+                ret.append(newline)
 
         if self.args['emit-parameter']:
             for newline in parameter_lines:
-                print(newline, file=fo)
+                ret.append(newline)
 
 
         if self.args['emit-incdir']:
-            prefix = strip_all_quotes(self.args['prefix-incdir'])
+            prefix = strip_all_quotes(self.args.get('prefix-incdir', '+incdir+'))
             for i in self.incdirs:
                 if self.args['emit-rel-path']:
                     i = os.path.relpath(i)
-                print(prefix + pq1 + i + pq2, file=fo)
+                ret.append(prefix + pq1 + i + pq2)
 
         if self.args['emit-plusargs']:
             for newline in plusarg_lines:
-                print(newline, file=fo)
+                ret.append(newline)
 
 
         # Hook for derived classes to optionally print additional custom args, prior to
         # any files:
         for newline in self.get_additional_flist_args_list():
-            print(newline, file=fo)
+            ret.append(newline)
 
         if self.args['emit-v']:
-            prefix = strip_all_quotes(self.args['prefix-v'])
+            prefix = strip_all_quotes(self.args.get('prefix-v', ''))
             for f in self.files_v:
                 if self.args['emit-rel-path']:
                     f = os.path.relpath(f)
-                print(prefix + pq1 + f + pq2, file=fo)
+                ret.append(prefix + pq1 + f + pq2)
 
         if self.args['emit-sv']:
-            prefix = strip_all_quotes(self.args['prefix-sv'])
+            prefix = strip_all_quotes(self.args.get('prefix-sv', ''))
             for f in self.files_sv:
                 if self.args['emit-rel-path']:
                     f = os.path.relpath(f)
-                print(prefix + pq1 + f + pq2, file=fo)
+                ret.append(prefix + pq1 + f + pq2)
         if self.args['emit-vhd']:
-            prefix = strip_all_quotes(self.args['prefix-vhd'])
+            prefix = strip_all_quotes(self.args.get('prefix-vhd', ''))
             for f in self.files_vhd:
                 if self.args['emit-rel-path']:
                     f = os.path.relpath(f)
-                print(prefix + pq1 + f + pq2, file=fo)
+                ret.append(prefix + pq1 + f + pq2)
         if self.args['emit-cpp']:
-            prefix = strip_all_quotes(self.args['prefix-cpp'])
+            prefix = strip_all_quotes(self.args.get('prefix-cpp', ''))
             for f in self.files_cpp:
                 if self.args['emit-rel-path']:
                     f = os.path.relpath(f)
-                print(prefix + pq1 + f + pq2, file=fo)
+                ret.append(prefix + pq1 + f + pq2)
 
         # Hook for derived classes to optionally print additional flist items after
         # any files:
         for newline in self.get_additional_flist_files_list():
-            print(newline, file=fo)
-
-        if self.args['print-to-stdout']:
-            print() # don't need to close fo (None)
-        else:
-            fo.close()
-            util.info(f"Created file: {self.args['out']}")
+            ret.append(newline)
 
-        self.write_eda_config_and_args()
-        self.run_post_tool_dep_commands()
+        return ret

opencos/commands/shell.py

@@ -20,7 +20,7 @@ from opencos.utils import status_constants
 
 
 class CommandShell(CommandDesign):
-    '''Base class command handler for: eda sim ...'''
+    '''Base class command handler for: eda shell ...'''
 
     command_name = 'shell'
 

opencos/commands/sim.py

@@ -12,11 +12,11 @@ Note that CommandSim is also a base class for opencos.commands.elab.CommandElab.
 # pylint: disable=too-many-arguments
 
 import os
+from pathlib import Path
 import shlex
 
-from pathlib import Path
 
-from opencos import util, export_helper
+from opencos import export_helper, util
 from opencos.eda_base import CommandDesign, Tool
 from opencos.utils import status_constants
 
@@ -122,6 +122,8 @@ class CommandSim(CommandDesign): # pylint: disable=too-many-public-methods
             'license-queue': False,
             'library-map': [],
             'add-top-library': [],
+            'docker-run': False,
+            'docker-image': ''
         })
         self.args_help.update({
             'pre-sim-tcl': (
@@ -187,6 +189,16 @@ class CommandSim(CommandDesign): # pylint: disable=too-many-public-methods
                 ' you may need to --add-top-library=unisim.glbl for it to work with Xilinx'
                 ' based projects that require "glbl" to be present at simulation $root scope.'
             ),
+            'docker-run': (
+                'Run the simulation using "docker run" with image specified by'
+                ' --docker-image=NAME. Assumes the entrypoint can be /bin/bash and your --tool'
+                ' executable is installed in PATH. NOTE: docker-in-docker is not supported yet,'
+                ' if you are already in docker this option is not allowed and will fail checks.'
+            ),
+            'docker-image': (
+                'Used with arg --docker. IMAGE used by "docker run" for the sim, lint, or'
+                ' elab eda command.'
+            )
 
         })
 
@@ -544,7 +556,8 @@ class CommandSim(CommandDesign): # pylint: disable=too-many-public-methods
             compile_line_breaks: bool = True,
             elaborate_line_breaks: bool = False,
             simulate_line_breaks: bool = False,
-            simulate_sh_fname: str = 'simulate.sh'
+            simulate_sh_fname: str = 'simulate.sh',
+            all_sh_fname: str = 'all.sh'
     ) -> None:
         '''Writes compile.sh, elaborate.sh, simulate.sh (if present), all.sh to work-dir
 
@@ -554,9 +567,9 @@ class CommandSim(CommandDesign): # pylint: disable=too-many-public-methods
 
         all_lists = [] # list - of - (command-list)
         if self.has_pre_compile_dep_shell_commands:
-            all_lists = [
+            all_lists.append(
                 ['./pre_compile_dep_shell_commands.sh']
-            ]
+            )
 
         if compile_lists:
             util.write_shell_command_file(dirpath=self.args['work-dir'], filename='compile.sh',
@@ -577,11 +590,11 @@ class CommandSim(CommandDesign): # pylint: disable=too-many-public-methods
             all_lists.append(['./' + simulate_sh_fname])
 
         if self.has_post_tool_dep_shell_commands:
-            all_lists = [
+            all_lists.append(
                 ['./post_tool_dep_shell_commands.sh']
-            ]
+            )
 
-        util.write_shell_command_file(dirpath=self.args['work-dir'], filename='all.sh',
+        util.write_shell_command_file(dirpath=self.args['work-dir'], filename=all_sh_fname,
                                       command_lists=all_lists)
 
         self.write_eda_config_and_args()

opencos/commands/waves.py

@@ -53,7 +53,9 @@ class CommandWaves(CommandDesign):
             + ' to stdout',
         })
 
-    def get_versions_of_tool(self, tool: str) -> str:
+    def get_versions_of_tool( # pylint: disable=unused-argument
+            self, tool: str, **kwargs
+    ) -> str:
         '''Similar to Tool.get_versions(), returns the version of 'tool' for tools like:
 
         - vaporview

opencos/deps/defaults.py

@@ -1,11 +1,11 @@
 ''' opencos.deps.defaults -- pymodule for defaults referenced by other modules here'''
 
 
-DEPS_FILE_EXTS = set([
+DEPS_FILE_EXTS = [
     '.yml', '.yaml', '.toml', '.json',
     # Treat no extension DEPS as YAML.
     ''
-])
+]
 
 ROOT_TABLE_KEYS_NOT_TARGETS = set([
     "DEFAULTS",

opencos/deps/deps_file.py

@@ -12,7 +12,7 @@ import toml
 
 from opencos import util
 from opencos.deps.defaults import DEPS_FILE_EXTS, ROOT_TABLE_KEYS_NOT_TARGETS
-from opencos.util import debug, error
+from opencos.util import debug, error, warning
 from opencos.utils.markup_helpers import yaml_safe_load, toml_load_only_root_line_numbers, \
     markup_writer, markup_dumper
 from opencos.utils.str_helpers import fnmatch_or_re, dep_str2list, pretty_list_columns_manual, \
@@ -28,14 +28,27 @@ def deps_data_get_all_targets(data: dict) -> list:
     return [x for x in data.keys() if (x not in ROOT_TABLE_KEYS_NOT_TARGETS and
                                        is_valid_target_name(x))]
 
-
+_GET_DEPS_MARKUP_FILE_WARNINGS = set()
 def get_deps_markup_file(base_path: str) -> str:
     '''Returns one of DEPS.yml, DEPS.yaml, DEPS.toml, DEPS.json'''
+    found = False
+    deps_fpath = ''
     for suffix in DEPS_FILE_EXTS:
-        deps_file = os.path.join(base_path, 'DEPS' + suffix)
-        if os.path.isfile(deps_file):
-            return deps_file
-    return ''
+        fpath = os.path.join(base_path, 'DEPS' + suffix)
+        if os.path.isfile(fpath):
+            if not found:
+                found = True
+                deps_fpath = fpath
+            else:
+                if fpath not in _GET_DEPS_MARKUP_FILE_WARNINGS:
+                    warning(
+                        f'Ignoring DEPS file at "{fpath}", already found and using: {deps_fpath}'
+                    )
+
+            # add to global set if found or not (isfile(fpath) is True):
+            _GET_DEPS_MARKUP_FILE_WARNINGS.add(fpath)
+
+    return deps_fpath
 
 
 def deps_markup_safe_load(
@@ -53,7 +66,7 @@ def deps_markup_safe_load(
     '''
     data = {}
     _, file_ext = os.path.splitext(filepath)
-    if file_ext in ['', '.yml', 'yaml']:
+    if file_ext in ['', '.yml', '.yaml']:
         # treat DEPS as YAML.
         data = yaml_safe_load(filepath=filepath, only_root_line_numbers=only_root_line_numbers)
     elif file_ext == '.toml':

opencos/deps/deps_processor.py

@@ -532,10 +532,10 @@ class DepsProcessor: # pylint: disable=too-many-instance-attributes
                 with_args_matched_list = []
                 for k,v in with_args.items():
                     with_args_matched_list.append(False)
-                    if not apply_tag_items_tools:
+                    if not all((apply_tag_items_tools, apply_tag_items_commands)):
                         # If we didn't previously match with-tools (if with-tools was present),
-                        # then we may not match the args, b/c those are tool dependend in the
-                        # Command handling class.
+                        # or match with-commands, then we may not match the args, b/c those are
+                        # command + tool dependent in the Command handling class.
                         pass
                     elif k not in self.command_design_ref.args:
                         warning(f'{tagname=} in {self.caller_info}:',

opencos/eda.py

@@ -20,10 +20,11 @@ from pathlib import Path
 import opencos
 from opencos import util, eda_config, eda_base
 from opencos.eda_base import Command, Tool, which_tool, print_eda_usage_line
-from opencos.eda_tool_helper import pretty_info_handler_tools
+from opencos.eda_tool_helper import DOCKER_TOOL_NOTE, pretty_info_handler_tools, \
+    tool_loaded_but_flagged_as_docker_only, get_all_handler_commands
 from opencos.files import safe_shutil_which
 from opencos.util import safe_emoji, Colors
-from opencos.utils import vsim_helper, vscode_helper
+from opencos.utils import vsim_helper, vscode_helper, docker_checks
 from opencos.utils import status_constants, str_helpers, subprocess_helpers
 
 # Configure util:
@@ -99,9 +100,17 @@ def init_config(
 def get_all_commands_help_str(config: dict) -> str:
     '''Returns a str of help based on what commands eda supports, from config'''
     all_commands_help = []
+    all_handler_commands = get_all_handler_commands(config=config)
     max_command_str_len = max(len(s) for s in config.get('DEFAULT_HANDLERS_HELP', {}).keys())
     for key, value in config.get('DEFAULT_HANDLERS_HELP', {}).items():
-        all_commands_help.append(f'    {key:<{max_command_str_len}} - {value.strip()}')
+        all_commands_help.append(
+            f'    {Colors.bcyan}{key:<{max_command_str_len}}{Colors.normal} - {value.strip()}'
+        )
+        if key in all_handler_commands:
+            all_commands_help[-1] += (
+                f'\n    {" ":<{max_command_str_len}}   '
+                f'--tool: {Colors.cyan}{", ".join(all_handler_commands[key])}{Colors.normal}'
+            )
     if all_commands_help:
         all_commands_help = [
             f'Where {Colors.byellow}COMMAND{Colors.normal} is one of:',
@@ -277,13 +286,21 @@ def auto_tool_setup( # pylint: disable=too-many-locals,too-many-branches,too-man
             if not exe_path:
                 exe_path = p # set on first required exe
             if not p:
-                has_all_exe = False
+                # skip the fail (has_all_exe=False) if we can run via docker.
+                if tool_cfg.get('docker_support', None):
+                    if not docker_checks.docker_ok():
+                        has_all_exe = False
+                        util.debug("... No, missing docker requirements")
+                else:
+                    has_all_exe = False
                 util.debug(f"... No, missing exe {exe}")
             for req in tool_cfg.get('requires_in_exe_path', []):
                 if p and req and str(Path(req)) not in str(Path(p)):
                     has_all_in_exe_path = False
                     util.debug(f"... No, missing path requirement {req}")
 
+
+
         has_vsim_helper = True
         if tool_cfg.get('requires_vsim_helper', False):
             # This tool name must be in opencos.utils.vsim_helper.TOOL_PATH[name].
@@ -327,6 +344,9 @@ def auto_tool_setup( # pylint: disable=too-many-locals,too-many-branches,too-man
                 p = exe_path
             else:
                 p = safe_shutil_which(exe_list[0])
+            if not p and tool_cfg.get('docker_support', None) and docker_checks.docker_ok():
+                # Sets note that this tool is loaded, but only avail via docker:
+                p = DOCKER_TOOL_NOTE
             config['auto_tools_found'][name] = p # populate key-value pairs w/ first exe in list
             if name not in config['tools_loaded']:
                 config['tools_loaded'].append(name)
@@ -357,7 +377,7 @@ def auto_tool_setup( # pylint: disable=too-many-locals,too-many-branches,too-man
             )
         return config
 
-    # If --tool was not set, look at config['auto_tools_found'] should be populated based on
+    # If --tool was not set, look at config['auto_tools_order'] should be populated based on
     # config['tools'], and if we called this method (auto_tool_setup(...)) with tool= and command=
     # arg(s). Call set_command_handlers for each command/tool we need to:
     for _command, list_of_tools in config['auto_tools_order'].items():
@@ -365,6 +385,10 @@ def auto_tool_setup( # pylint: disable=too-many-locals,too-many-branches,too-man
         for _tool in list_of_tools:
             if _tool not in config['tools_loaded']:
                 continue
+            if tool_loaded_but_flagged_as_docker_only(tool=_tool, config=config):
+                # do not let this tool be the auto-handler for a command (aka, it is the
+                # chosen tool if --tool=TOOL arg not present) if it can only run via docker.
+                continue
 
             set_command_handler(
                 command=_command, tool=_tool, config=config, auto_setup=(not tool),