diff --git a/docs/source/conf.py b/docs/source/conf.py index d85e198..ad037b8 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -39,3 +39,4 @@ html_theme_options = { } extensions = ['sphinx.ext.autosectionlabel'] +extensions += ['sphinxarg.ext'] diff --git a/docs/source/index.rst b/docs/source/index.rst index fbe43c5..ab67043 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,6 +16,7 @@ formal tasks: install.rst quickstart.rst + usage.rst reference.rst autotune.rst verilog.rst diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt index a95ae18..0e4756e 100644 --- a/docs/source/requirements.txt +++ b/docs/source/requirements.txt @@ -1 +1,2 @@ furo +sphinx-argparse diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..5a3bf79 --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,11 @@ +Using `sby` +=========== + +Once SBY is installed and available on the command line as `sby`, either built from source or using +one of the available CAD suites, it can be called as follows. Note that this information is also +available via `sby --help`. For more information on installation, see :ref:`install-doc`. + +.. argparse:: + :filename: ../sbysrc/sby_cmdline.py + :func: parser_func + :prog: sby diff --git a/sbysrc/sby.py b/sbysrc/sby.py index 20ae345..986fb9d 100644 --- a/sbysrc/sby.py +++ b/sbysrc/sby.py @@ -17,88 +17,16 @@ # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. # -import argparse, json, os, sys, shutil, tempfile, re +import json, os, sys, shutil, tempfile, re ##yosys-sys-path## +from sby_cmdline import parser_func from sby_core import SbyConfig, SbyTask, SbyAbort, SbyTaskloop, process_filename, dress_message from sby_jobserver import SbyJobClient, process_jobserver_environment import time, platform, click process_jobserver_environment() # needs to be called early -class DictAction(argparse.Action): - def __call__(self, parser, namespace, values, option_string=None): - assert isinstance(getattr(namespace, self.dest), dict), f"Use ArgumentParser.set_defaults() to initialize {self.dest} to dict()" - name = option_string.lstrip(parser.prefix_chars).replace("-", "_") - getattr(namespace, self.dest)[name] = values - -parser = argparse.ArgumentParser(prog="sby", - usage="%(prog)s [options] [.sby [tasknames] | ]") -parser.set_defaults(exe_paths=dict()) - -parser.add_argument("-d", metavar="", dest="workdir", - help="set workdir name. default: or _. When there is more than one task, use --prefix instead") -parser.add_argument("--prefix", metavar="", dest="workdir_prefix", - help="set the workdir name prefix. `_` will be appended to the path for each task") -parser.add_argument("-f", action="store_true", dest="force", - help="remove workdir if it already exists") -parser.add_argument("-b", action="store_true", dest="backup", - help="backup workdir if it already exists") -parser.add_argument("-t", action="store_true", dest="tmpdir", - help="run in a temporary workdir (remove when finished)") -parser.add_argument("-T", metavar="", action="append", dest="tasknames", default=list(), - help="add taskname (useful when sby file is read from stdin)") -parser.add_argument("-E", action="store_true", dest="throw_err", - help="throw an exception (incl stack trace) for most errors") -parser.add_argument("-j", metavar="", type=int, dest="jobcount", - help="maximum number of processes to run in parallel") -parser.add_argument("--sequential", action="store_true", dest="sequential", - help="run tasks in sequence, not in parallel") - -parser.add_argument("--autotune", action="store_true", dest="autotune", - help="automatically find a well performing engine and engine configuration for each task") -parser.add_argument("--autotune-config", dest="autotune_config", - help="read an autotune configuration file (overrides the sby file's autotune options)") - -parser.add_argument("--yosys", metavar="", - action=DictAction, dest="exe_paths") -parser.add_argument("--abc", metavar="", - action=DictAction, dest="exe_paths") -parser.add_argument("--smtbmc", metavar="", - action=DictAction, dest="exe_paths") -parser.add_argument("--witness", metavar="", - action=DictAction, dest="exe_paths") -parser.add_argument("--suprove", metavar="", - action=DictAction, dest="exe_paths") -parser.add_argument("--aigbmc", metavar="", - action=DictAction, dest="exe_paths") -parser.add_argument("--avy", metavar="", - action=DictAction, dest="exe_paths") -parser.add_argument("--btormc", metavar="", - action=DictAction, dest="exe_paths") -parser.add_argument("--pono", metavar="", - action=DictAction, dest="exe_paths", - help="configure which executable to use for the respective tool") -parser.add_argument("--dumpcfg", action="store_true", dest="dump_cfg", - help="print the pre-processed configuration file") -parser.add_argument("--dumptags", action="store_true", dest="dump_tags", - help="print the list of task tags") -parser.add_argument("--dumptasks", action="store_true", dest="dump_tasks", - help="print the list of tasks") -parser.add_argument("--dumpdefaults", action="store_true", dest="dump_defaults", - help="print the list of default tasks") -parser.add_argument("--dumptaskinfo", action="store_true", dest="dump_taskinfo", - help="output a summary of tasks as JSON") -parser.add_argument("--dumpfiles", action="store_true", dest="dump_files", - help="print the list of source files") -parser.add_argument("--setup", action="store_true", dest="setupmode", - help="set up the working directory and exit") - -parser.add_argument("--init-config-file", dest="init_config_file", - help="create a default .sby config file") -parser.add_argument("sbyfile", metavar=".sby | ", nargs="?", - help=".sby file OR directory containing config.sby file") -parser.add_argument("arg_tasknames", metavar="tasknames", nargs="*", - help="tasks to run (only valid when .sby is used)") +parser = parser_func() args = parser.parse_args() diff --git a/sbysrc/sby_cmdline.py b/sbysrc/sby_cmdline.py new file mode 100644 index 0000000..a75c273 --- /dev/null +++ b/sbysrc/sby_cmdline.py @@ -0,0 +1,79 @@ +import argparse + +class DictAction(argparse.Action): + def __call__(self, parser, namespace, values, option_string=None): + assert isinstance(getattr(namespace, self.dest), dict), f"Use ArgumentParser.set_defaults() to initialize {self.dest} to dict()" + name = option_string.lstrip(parser.prefix_chars).replace("-", "_") + getattr(namespace, self.dest)[name] = values + +def parser_func(): + parser = argparse.ArgumentParser(prog="sby", + usage="%(prog)s [options] [.sby [tasknames] | ]") + parser.set_defaults(exe_paths=dict()) + + parser.add_argument("-d", metavar="", dest="workdir", + help="set workdir name. default: or _. When there is more than one task, use --prefix instead") + parser.add_argument("--prefix", metavar="", dest="workdir_prefix", + help="set the workdir name prefix. `_` will be appended to the path for each task") + parser.add_argument("-f", action="store_true", dest="force", + help="remove workdir if it already exists") + parser.add_argument("-b", action="store_true", dest="backup", + help="backup workdir if it already exists") + parser.add_argument("-t", action="store_true", dest="tmpdir", + help="run in a temporary workdir (remove when finished)") + parser.add_argument("-T", metavar="", action="append", dest="tasknames", default=list(), + help="add taskname (useful when sby file is read from stdin)") + parser.add_argument("-E", action="store_true", dest="throw_err", + help="throw an exception (incl stack trace) for most errors") + parser.add_argument("-j", metavar="", type=int, dest="jobcount", + help="maximum number of processes to run in parallel") + parser.add_argument("--sequential", action="store_true", dest="sequential", + help="run tasks in sequence, not in parallel") + + parser.add_argument("--autotune", action="store_true", dest="autotune", + help="automatically find a well performing engine and engine configuration for each task") + parser.add_argument("--autotune-config", dest="autotune_config", + help="read an autotune configuration file (overrides the sby file's autotune options)") + + parser.add_argument("--yosys", metavar="", + action=DictAction, dest="exe_paths") + parser.add_argument("--abc", metavar="", + action=DictAction, dest="exe_paths") + parser.add_argument("--smtbmc", metavar="", + action=DictAction, dest="exe_paths") + parser.add_argument("--witness", metavar="", + action=DictAction, dest="exe_paths") + parser.add_argument("--suprove", metavar="", + action=DictAction, dest="exe_paths") + parser.add_argument("--aigbmc", metavar="", + action=DictAction, dest="exe_paths") + parser.add_argument("--avy", metavar="", + action=DictAction, dest="exe_paths") + parser.add_argument("--btormc", metavar="", + action=DictAction, dest="exe_paths") + parser.add_argument("--pono", metavar="", + action=DictAction, dest="exe_paths", + help="configure which executable to use for the respective tool") + parser.add_argument("--dumpcfg", action="store_true", dest="dump_cfg", + help="print the pre-processed configuration file") + parser.add_argument("--dumptags", action="store_true", dest="dump_tags", + help="print the list of task tags") + parser.add_argument("--dumptasks", action="store_true", dest="dump_tasks", + help="print the list of tasks") + parser.add_argument("--dumpdefaults", action="store_true", dest="dump_defaults", + help="print the list of default tasks") + parser.add_argument("--dumptaskinfo", action="store_true", dest="dump_taskinfo", + help="output a summary of tasks as JSON") + parser.add_argument("--dumpfiles", action="store_true", dest="dump_files", + help="print the list of source files") + parser.add_argument("--setup", action="store_true", dest="setupmode", + help="set up the working directory and exit") + + parser.add_argument("--init-config-file", dest="init_config_file", + help="create a default .sby config file") + parser.add_argument("sbyfile", metavar=".sby | ", nargs="?", + help=".sby file OR directory containing config.sby file") + parser.add_argument("arg_tasknames", metavar="tasknames", nargs="*", + help="tasks to run (only valid when .sby is used)") + + return parser