Stop empty source files `""` from being exported to json.
Move source path fixing to a separate function.
`ContentListing::to_json` now takes the source root, recursively calling the source path fixup function on all source paths in the content listing.
Make explicit the location for the `CMakeUserPresets.json` file.
Update docs tests documentation.
Move `BUILD_DIR` and `PROGRAM_PREFIX` comments into the functional tests todo.
Add cmake to MacPorts/FreeBSD install instructions.
Add ccache to example `CMakeUserPresets.json` (it isn't otherwise documented, and is no longer as obvious without an `ENABLE_CCACHE` makevar).
Addressing comments
The CMake refactor changes relative paths to absolute when calling `source_location::current()`. Use the path to `register.cc` to find the root yosys dir, and use that as the base for other paths.
Includes provisions for when plugins have a valid location; if it's not in the yosys source tree we shouldn't try to make the path relative, and we shouldn't try to auto group by path (since such groups will never be allocated, leaving them as unknown is preferable).
Limited to non wasm (I think that's the only one where we can't (easily) use `<filesystem>`). But where we do use `<filesystem>` we can also simplify the auto group to use `fs::path::parent_path()`.
`_content` vector owns elements so that when the `ContentListing` is deleted so is the content.
Remove `get_content()` method in favour of `begin()` and `end()` const iterators.
More `const` in general, and iterations over `ContentListing` use `&content` to avoid copying data.
Linking to optiongroups doesn't add *that* much, and is kind of a pain; meanwhile having the optiongroups adds an extra level of indentation.
Instead of options needing to be in an option group, they instead go in either the root node or nested in a usage node. Putting them in a usage node allows for more-or-less the previous behaviour but without making it the default.
Or at least all of the synth commands, because they have the same preceding text.
Except `synth_fabulous`, because that has unconditional `read_verilog`s at the start. Which seems like a bad idea and and not compatible with `-run`?
Keep techlibs folder hierarchy.
techlibs/* and passes/* groups are now nested under index_techlibs and index_passes respectively, with most (all?) of the passes/* pages getting proper headings, as well as backends/frontends/kernel. `index_passes_techmap` also references `index_techlibs`.
Split command reference toc in twain, one with maxdepth=2 and one with maxdepth=3, since passes and techlibs now have an extra level of nesting.
Move the `cmd_ref` link to the command reference, instead of top of the page.
Remove `index_internal` and `index_other` from the toc, and mark the pages as orphan. Internal commands get a note callout after the command reference toc (although this doesn't work for the pdf build), while other commands are linked in the warning for missing `source_location` (since that *should* be the only time when there are any commands in the "unknown" group).
Update autodoc extension versions, and mark the directives extension as not `parallel_read_safe` (it might be, but I'm not sure about how the xref lookups work if it is parallel so better to be safe).
Commands flagged as internal will display a warning, just like experimental commands.
Drop `passes/tests` group in favour of `internal` group, which is automatically assigned for any command without an assigned group which is flagged as internal.
Update experimental pass warnings to use a shared function. Reduces repetition, and also allows all of the warning flags to be combined (which at present is just experimental and the new internal).
Update `test_*` passes to call `internal()` in their constructors.
Content is now added to the `ContentListing` rather than the `PrettyHelp`.
`open_*` methods return the `ContentListing` that was added instead of leaving a hanging continuation.
This allows for (e.g.) options to be added directly to optiongroups, instead of requiring that groups be closed before continuation.
This also means that all `PrettyHelp`s are a listing, with the actual log being called by the default `Pass::help()`; making the mode field redundant.
Added `PrettyHelp::log_help()` which replaces the `PrettyHelp::Mode::LOG` logic.
Added `ContentListing::back()` which just returns the last element of the underlying content vector.
Some of the content tracking was made redundant and removed, in particular `PrettyHelp::_current_listing` and `ContentListing::parent`.
Converted `ContentListing` to a class instead of a struct, adjusting constructors to match.
Added `ContentListing` constructor that accepts a `source_location`.
Update `HelpPass::dump_cmds_json()` for new log_help.
Also output `pass->location.{file_name,line,function_name}()`.
If no group is given (i.e. it is "unknown"), attempt to automatically apply a group.
If we have source locations, this is based on path to the source file.
If we do not have source locations, try to match on the pass name instead.
- Command list for script passes
- Check buffer after loop
- Close options properly
- Ignore mismatched sigs e.g. `fsm_detect` on `fsm`
- Require double blank line before new signature
Current modes are `LOG` and `LISTING`, which `log()` and store for conversion to json respectively.
Add `ContentListing` listing struct to (recursively) contain help data for conversion to a json object to be exported and used elsewhere (e.g. the docs).
Rather than formatting as rst we can just export with type information and do the conversion at the destination (i.e. in the python code which loads the domain for autodoc).
Implement `PrettyHelp::has_content()`.
Provide `PrettyHelp::get_content()` which returns a read-only list of the current content.
`PrettyHelp` constructor takes optional `Mode` enum to define format of help content.
Updates `PrettyHelp` methods to use a switch case for checking current mode, calling `log_abort()` in the default case (i.e. unsupported mode).
Define `PrettyHelp` class with methods for declaring different parts of help message.
Currently able to produce standard help messages as expected.
Updates chformal to use (only) the new help_v2.
Currently makes use of a global static to track the current help context, allowing register.h to live in blissful ignorance and instead rely on help_v2 implementations calling `auto *help = PrettyHelp::get_current();` and `return true;` to minimise impact on rebuilds (i.e. not requiring every source file to be recompiled).
Add `doc_string` field to `Pass` constructor
Add `docs/util/newcmdref.py` to contain command domain
Update `docs/util/cmdref.py` with `cmd:usage` and `cmd:optiongroup` for describing commands.
Functional, but WIP.
Experimental new formatting for describing passes that can be rendered into the standard help format, as well as being more amenable to smarter formatting for web documentation.
Miodrag Milanovic
nella
Krystine Sherwin
Catherine
Emil J. Tywoniak
Robert O'Callahan
Robert O'Callahan
George Rennie
N. Engelhardt