src/third_party/llvm-project/lldb/www/adding-language-support.html - cobalt - Git at Google

 <!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>
	<!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>