maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

First pass on www docs: Adding Programming Language Support to LLDB 

We'll hook this up to the main page after Greg, Sean and others
iterate on it to a useful point.

llvm-svn: 251831
This commit is contained in:
Todd Fiala 2015-11-02 21:05:28 +00:00
parent 48c6b52f92
commit 0c3f8135be
1 changed files with 170 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
lldb/www/adding-language-support.html Normal file
View File

@ -0,0 +1,170 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link href="style.css" rel="stylesheet" type="text/css" />
<title>Adding Programming Language Support to LLDB</title>
</head>
<body>
<div class="www_title">
The <strong>LLDB</strong> Debugger
</div>
<div id="container">
<div id="content">
<!--#include virtual="sidebar.incl"-->
<div id="middle">
<div class="post">
<h1 class="postheader">Adding Programming Language Support to LLDB</h1>
<div class="postcontent">
<p>
LLDB has been architected to make it straightforward to
add support for a programming language. Only a small
enum in core LLDB needs to be modified to make LLDB
aware of a new programming language. Everything else can
be supplied in derived classes that need not even be
present in the core LLDB repository. This makes it
convenient for developers adding language support either
in branches or downstream repositories since it
practically eliminates the potential for merge
conflicts.
</p>
<p>
The basic steps needed are as follows:
<ul>
<li>Add the language to the LanguageType enum</li>
<li>Add a TypeSystem for the language</li>
<li>Add expression evaluation support</li>
</ul>
</p>
</div>
<div class="postfooter"></div>
</div>
<!-- block for adding a new section
<div class="post">
<h1 class="postheader">Section Title</h1>
<div class="postcontent">
<p>...</p>
</div>
<div class="postfooter"></div>
</div>
-->
<div class="post">
<h1 class="postheader">Add the Language to the LanguageType enum</h1>
<div class="postcontent">
<p>
The LanguageType enum
(see <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/lldb-enumerations.h">lldb-enumerations.h</a>)
contains a list of every language known to LLDB. It is
the one place where support for a language must live
that will need to merge cleanly with core LLDB if you
are developing your language support in a separate
branch. When adding support for a language previously
unknown to LLDB, start by adding an enumeration entry to
LanguageType.
</p>
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class="postheader">Add a TypeSystem for the Language</h1>
<div class="postcontent">
<p>
Both <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/Core/Module.h">Module</a>
and <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/Target/Target.h">Target</a>
support the retrieval of a TypeSystem instance via
GetTypeSystemForLanguage(). For Module, this method is
directly on the Module instance. For Target, this is
retrieved indirectly via the TypeSystemMap for the
Target instance.
</p>
<p>
The TypeSystem instance returned by the Target is
expected to be capable of evaluating expressions, while
the TypeSystem instance returned by the Module is not.
If you will support expression evaluation for your
language, you could consider following one of these
approaches:
<ul>
<li>
implement a single TypeSystem class that supports
evaluation when given an optional Target,
implementing all the expression evaluation methods
on the TypeSystem in this case, OR
</li>
<li>
create multiple TypeSystem classes, one for
evaluation and one for static Module usage.
</li>
</ul>
For clang and Swift, we chose to go with the latter,
primarily to make it clearer that evaluation with the
static Module-returned TypeSystem instances make no
sense, and have them error out on those calls. But
either approach is fine to pursue.
</p>
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class="postheader">Add Expression Evaluation Support</h1>
<div class="postcontent">
<p>
Expression Evaluation support is enabled by implementing
the relevant methods on a TypeSystem-derived class.
Search for "Expression" in the
<a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/Symbol/TypeSystem.h">TypeSystem header</a>
to find relevant
methods to implement.
</p>
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class="postheader">Type Completion</h1>
<div class="postcontent">
<p>
There are three levels of type completion, each
requiring more type information:
<ol>
<li>
Pointer size: when you have a forward decl or a
reference, and that's all you need. At this stage,
the pointer size is all you need.
</li>
<li>
Layout info: you need the size of an instance of the
type, but you still don't need to know all the guts
of the type.
</li>
<li>
Full type info. Here you need everything, because
you're playing with internals of it, such as
modifying a member variable.
</li>
</ol>
Ensure you never complete more of a type than is needed
for a given situation. This will keep your type system
from doing more work than necessary.
</p>
</div>
<div class="postfooter"></div>
</div>
<div class="post">
<h1 class="postheader">Creating Types</h1>
<div class="postcontent">
<p>
Your TypeSystem will need an approach for creating types
based on a set of Modules. If your type info is going
to come from DWARF info, you will want to subclass
<a href="http://llvm.org/svn/llvm-project/lldb/trunk/source/Plugins/SymbolFile/DWARF/DWARFASTParser.h">DWARFASTParser</a>.
</p>
</div>
<div class="postfooter"></div>
</div>
</div>
</div>
</div>
</body>
</html>