Author: tfiala
Date: Mon Nov 2 15:05:28 2015
New Revision: 251831
URL: http://llvm.org/viewvc/llvm-project?rev=251831&view=rev
Log:
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.
Added:
lldb/trunk/www/adding-language-support.html
Added: lldb/trunk/www/adding-language-support.html
URL:
http://llvm.org/viewvc/llvm-project/lldb/trunk/www/adding-language-support.html?rev=251831&view=auto
==============================================================================
--- lldb/trunk/www/adding-language-support.html (added)
+++ lldb/trunk/www/adding-language-support.html Mon Nov 2 15:05:28 2015
@@ -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>
_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
