Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

driver: replace getopt with cxxopts, replace -B, clean up help #4616

Merged
merged 1 commit into from
Oct 12, 2024

Conversation

widlarizer
Copy link
Collaborator

@widlarizer widlarizer commented Sep 26, 2024

Implements #4580.

In this PR I'm adding the cxxopts header-only library as a submodule. This allows me to introduce long option aliases such as --quiet for -q. Since -B was undocummented and is assumed not broadly used, I'm replacing it with --perffile. Behaviour of -- is retained as implemented in #3973. The behavior of yosys -help being special cased not to be equivalent to yosys -h -e -l -p is also retained. Help string indentation isn't retained since we're letting cxxopts generate it. Argument names like logfile are converted for consistency into <logfile> which is then used as is broadly the POSIX/GNU convention. Long options don't have to match the first letter of the short option if it's more logical that way, for example, -m is --plugin, I also changed the help string to load the specified <plugin> module since it was colliding with the concept of the HDL top module. The HDL top module selection option is now -r and --top and its help is elaborate the specified HDL <top> module. There's more minor differences in wording

The error reporting the usage of an unimplemented option such as -z now mentions that option. Before: Run 'yosys -h' for help. After:

Error parsing options: Option 'z' does not exist
Run 'yosys --help' for help.

From this PR onward, it should decision whether a flag gets to hog the top level namespace since we now have an alternative. On the other hand, it should make it easier to experiment by adding long-only options.

  • Manually test on Windows

@widlarizer
Copy link
Collaborator Author

widlarizer commented Sep 26, 2024

I've sorted the options into help groups. Bit iffy on the developer vs logging side. Current help string output:

Yosys Open SYnthesis Suite
Usage:
  ./yosys [OPTION...] [<infile> [..]]

 operation options:
  -b, --backend <backend>       use <backend> for the output file specified on the command line
  -f, --frontend <frontend>     use <frontend> for the input files on the command line
  -s, --scriptfile <scriptfile>
                                execute the commands in <scriptfile>
  -c, --tcl-scriptfile <tcl_scriptfile>
                                execute the commands in the TCL <tcl_scriptfile> (see 'help tcl' for details)
  -C, --tcl-interactive         enters TCL interactive shell mode
  -p, --commands <commands>     execute <commands> (to chain commands, separate them with semicolon + whitespace: 'cmd1; cmd2')
  -r, --top <top>               elaborate the specified HDL <top> module
  -m, --plugin <plugin>         load the specified <plugin> module
  -D, --define <define>[=<value>]
                                set the specified Verilog define to <value> if supplied via command "read -define"
  -S, --synth                   shortcut for calling the "synth" command, a default script for transforming the Verilog input to a gate-level netlist. For example: yosys -o output.blif -S input.v For more complex synthesis jobs it is recommended to use the read_* and write_* commands in a script file instead of specifying input and output files on the command line.
  -H                            print the command list
  -h, --help [<command>]        print this help message. If given, print help for <command>.
  -V, --version                 print version information and exit

 logging options:
  -Q                            suppress printing of banner (copyright, disclaimer, version)
  -T                            suppress printing of footer (log hash, version, timing statistics)
  -q, --quiet                   quiet operation. Only write warnings and error messages to console. Use this option twice to also quiet warning messages
  -v, --verbose <level>         print log headers up to <level> to the console. Implies -q for everything except the 'End of script.' message.
  -t, --timestamp               annotate all log messages with a time stamp
  -d, --detailed-timing         print more detailed timing stats at exit
  -l, --logfile <logfile>       write log messages to <logfile>
  -L, --line-buffered-logfile <logfile>
                                like -l but open <logfile> in line buffered mode
  -o, --outfile <outfile>       write the design to <outfile> on exit
  -P, --dump-design <header_id>[:<filename>]
                                dump the design when printing the specified log header to a file. yosys_dump_<header_id>.il is used as filename if none is specified. Use 'ALL' as <header_id> to dump at every header.
  -W, --warning-as-warning <regex>
                                print a warning for all log messages matching <regex>
  -w, --warning-as-message <regex>
                                if a warning message matches <regex>, it is printed as regular message instead
  -e, --warning-as-error <regex>
                                if a warning message matches <regex>, it is printed as error message instead
  -E, --deps-file <depsfile>    write a Makefile dependencies file <depsfile> with input and output file names

 developer options:
  -X, --trace                   enable tracing of core data structure changes. for debugging
  -M, --randomize-pointers      will slightly randomize allocated pointer addresses. for debugging
  -A, --abort                   will call abort() at the end of the script. for debugging
  -x, --experimental <feature>  do not print warnings for the experimental <feature>
  -g, --debug                   globally enable debug log messages
      --perffile <perffile>     write a JSON performance log to <perffile>


EDIT: updated to match latest commit

@widlarizer widlarizer mentioned this pull request Sep 26, 2024
kernel/driver.cc Show resolved Hide resolved
kernel/driver.cc Outdated Show resolved Hide resolved
kernel/driver.cc Outdated Show resolved Hide resolved
@widlarizer widlarizer added the merge-after-release Merge: PR should not be included in the next release label Sep 30, 2024
@widlarizer widlarizer merged commit 5c9b2df into main Oct 12, 2024
40 checks passed
@mmicko
Copy link
Member

mmicko commented Oct 12, 2024

Please switch to https link for submodule, could create issues later if not

@widlarizer
Copy link
Collaborator Author

dang, ok

@widlarizer widlarizer deleted the emil/cxxopts branch October 14, 2024 13:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
merge-after-release Merge: PR should not be included in the next release
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants