forked from OSchip/llvm-project
194 lines
8.6 KiB
HTML
194 lines
8.6 KiB
HTML
<!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>
|
|
<p>
|
|
Additionally, you may want to create a Language and LanguageRuntime plugin for your language, which enables support for advanced features like dynamic typing and data formatting.
|
|
</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="https://github.com/llvm/llvm-project/blob/master/lldb/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="https://github.com/llvm/llvm-project/blob/master/lldb/include/lldb/Core/Module.h">Module</a>
|
|
and <a href="https://github.com/llvm/llvm-project/blob/master/lldb/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="https://github.com/llvm/llvm-project/blob/master/lldb/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="https://github.com/llvm/llvm-project/blob/master/lldb/source/Plugins/SymbolFile/DWARF/DWARFASTParser.h">DWARFASTParser</a>.
|
|
</p>
|
|
</div>
|
|
<div class="postfooter"></div>
|
|
</div>
|
|
|
|
<div class="post">
|
|
<h1 class="postheader">Language and LanguageRuntime plugins</h1>
|
|
<div class="postcontent">
|
|
<p>
|
|
If you followed the steps outlined above, you already have taught LLDB a great deal about your language. And if your language's runtime model and fundamental data types don't differ much from the C model, you are pretty much done.
|
|
<br/>
|
|
However, it is likely that your language offers its own data types for things like strings, arrays, ..., and probably has a notion of dynamic types, where the effective type of a variable can only be known at runtime.
|
|
</p>
|
|
<p>
|
|
These tasks are covered by two plugins:
|
|
<ul>
|
|
<li>a LanguageRuntime plugin, which provides LLDB with a dynamic view of your language; this plugin answers questions that require a live process to acquire information (e.g. dynamic type resolution)</li>
|
|
<li>a Language plugin, which provides LLDB with a static view of your language; questions that are statically knoawble and do not require a process are answered by this plugin (e.g. data formatters)</li>
|
|
</ul>
|
|
</p>
|
|
</div>
|
|
<div class="postfooter"></div>
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|