The output of a compilation with the -fdebug-unparse-with-modules option
comprises its normal unparsed output along with the regenerated contents
of any modules that were required from module files. This is handy for
producing stand-alone test cases.
The modules' contents are generated by the same code that writes module
files, so they can contain some USE associations to private entities in
other modules that are necessary to complete local declarations, usually
initializers. Such USE associations to private entities are not flagged
as fatal errors when modules are read from module files, but they
currently are caught when the output produced by this option is being
read back in to the compiler.
Handle this case by softening the error to a warning when one module
uses a private entity from another with an alias containing the
non-conforming '$' character. (I could have omitted the message
altogether, but there are other valid warnings that will occur due to
undefined function result variables; further, I didn't want to provide a
general hole around the protection of private names.)
The current module file documentation antedates the current
implementation of module files and contains many aspirational and
conditional statements, all of which can now be resolved with
descriptions of how things actually work.
The default CMake scripts had a copy operation to copy a compiled `.mod`
file to also be available with suffix `.f18.mod`. This seems no longer
needed. Also updated ModFiles.md to point to `-module-suffix`.
---------
Co-authored-by: Kiran Chandramohan <kiranchandramohan@gmail.com>
Add a new index page to be the Flang documentation mainpage instead of
Overview.md, which jumps straight into the compiler Design. The index file
needs to be in .rst format to use the toctree directive to create table of
contents.
Also use the sphinx_markdown_tables extension to generate html tables form
markdown.
A number of additional style changes to the existing docs were needed to make
this work well:
* Convert all headings to the # style, which works better with toctree's
titlesonly option. Ensure that there is only one top-level heading per
document.
* Add a title to documents that don't have one for rendering on the index.
* Convert the grammar docs from .txt to .md. for better rendering
* Fixed broken link to a section in another document - sphinx does not seem to
support anchor links in markdown files.
Depends on D87226
Reviewed By: sameeranjoshi
Differential Revision: https://reviews.llvm.org/D87242
