diff options
Diffstat (limited to 'www/adding-language-support.html')
| -rw-r--r-- | www/adding-language-support.html | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/www/adding-language-support.html b/www/adding-language-support.html new file mode 100644 index 000000000000..b2bd5c5d1e8a --- /dev/null +++ b/www/adding-language-support.html @@ -0,0 +1,193 @@ +<!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="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 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> |