Add a few cross-references among TableGen documents.
Differential Revision: https://reviews.llvm.org/D90186
Add cross-references between TableGen documents.
This new TableGen Programmer's Reference document replaces the current Language Introduction and Language Reference documents. It brings all the TableGen reference information into one document.
As an experiment, I numbered the sections in the document. See what you think about that.
Reviewed By: lattner
Differential Revision: https://reviews.llvm.org/D85838
(changes by Nicolai Hähnle <nicolai.haehnle@amd.com>:
- fixed build error due to toctree in docs/LangRef/index.rst
- fixed reference to ProgRef)
Change-Id: Ifbdfa39768b8a460aae2873103d31c7b347aff00
The aim of this backend is to output everything TableGen knows about
the record set, similarly to the default -print-records backend. But
where -print-records produces output in TableGen's input syntax
(convenient for humans to read), this backend produces it as
structured JSON data, which is convenient for loading into standard
scripting languages such as Python, in order to extract information
from the data set in an automated way.
The output data contains a JSON representation of the variable
definitions in output 'def' records, and a few pieces of metadata such
as which of those definitions are tagged with the 'field' prefix and
which defs are derived from which classes. It doesn't dump out
absolutely every piece of knowledge it _could_ produce, such as type
information and complicated arithmetic operator nodes in abstract
superclasses; the main aim is to allow consumers of this JSON dump to
essentially act as new backends, and backends don't generally need to
depend on that kind of data.
The new backend is implemented as an EmitJSON() function similar to
all of llvm-tblgen's other EmitFoo functions, except that it lives in
lib/TableGen instead of utils/TableGen on the basis that I'm expecting
to add it to clang-tblgen too in a future patch.
To test it, I've written a Python script that loads the JSON output
and tests properties of it based on comments in the .td source - more
or less like FileCheck, except that the CHECK: lines have Python
expressions after them instead of textual pattern matches.
Reviewers: nhaehnle
Reviewed By: nhaehnle
Subscribers: arichardson, labath, mgorny, llvm-commits
Differential Revision: https://reviews.llvm.org/D46054
llvm-svn: 336771
Summary:
The new rules are straightforward. The main rules to keep in mind
are:
1. NAME is an implicit template argument of class and multiclass,
and will be substituted by the name of the instantiating def/defm.
2. The name of a def/defm in a multiclass must contain a reference
to NAME. If such a reference is not present, it is automatically
prepended.
And for some additional subtleties, consider these:
3. defm with no name generates a unique name but has no special
behavior otherwise.
4. def with no name generates an anonymous record, whose name is
unique but undefined. In particular, the name won't contain a
reference to NAME.
Keeping rules 1&2 in mind should allow a predictable behavior of
name resolution that is simple to follow.
The old "rules" were rather surprising: sometimes (but not always),
NAME would correspond to the name of the toplevel defm. They were
also plain bonkers when you pushed them to their limits, as the old
version of the TableGen test case shows.
Having NAME correspond to the name of the toplevel defm introduces
"spooky action at a distance" and breaks composability:
refactoring the upper layers of a hierarchy of nested multiclass
instantiations can cause unexpected breakage by changing the value
of NAME at a lower level of the hierarchy. The new rules don't
suffer from this problem.
Some existing .td files have to be adjusted because they ended up
depending on the details of the old implementation.
Change-Id: I694095231565b30f563e6fd0417b41ee01a12589
Reviewers: tra, simon_tatham, craig.topper, MartinO, arsenm, javed.absar
Subscribers: wdng, llvm-commits
Differential Revision: https://reviews.llvm.org/D47430
llvm-svn: 333900
Should be a harmless trimming of trailing whitespace from a
documentation file.
(There are other instances of trailing whitespace in this file alone.
I've only fixed one of them, on the basis that that way the rest are
still available for other people's commit-access tests :-)
llvm-svn: 330567
Lots of blocks had "llvm" or "nasm" syntax types but either weren't following
the syntax, or the syntax has changed (and sphinx hasn't keep up) or the type
doesn't even exist (nasm?).
Other documents had :options: what were invalid. I only removed those that had
warnings, and left the ones that didn't, in order to follow the principle of
least surprise.
This is like this for ages, but the buildbot is now failing on errors. It may
take a while to upgrade the buildbot's sphinx, if that's even possible, but
that shouldn't stop us from getting docs updates (which seem down for quite
a while).
Also, we're not losing any syntax highlight, since when it doesn't parse, it
doesn't colour. Ie. those blocks are not being highlighted anyway.
I'm trying to get all docs in one go, so that it's easy to revert later if we
do fix, or at least easy to know what's to fix.
llvm-svn: 276109
Making the new TableGen documentation official and marking the old file as
"Moved". Also, reverting the original LangRef as the normative formal
description of the language, while keeping the "new" LangRef as LangIntro
for the less inlcined to reading language grammars.
We should remove TableGenFundamentals.rst one day, but for now, just a
warning that it moved will have to do, while we make sure there are no more
links to it from elsewhere.
llvm-svn: 205289
This is mainly a movement of content around to give place to new content
allowing different people to add bits to it in the right place. There is some
new content, but mostly to fill the gaps left by text movement.
I'm dropping the old syntax documentation as it has the problem of being
quickly outdated by changes and largely unnecessary to people not involved
in creating the language, but using it, which is the whole point of the
documentation.
llvm-svn: 204351
