[Lldb-commits] [lldb] r223550 - Add an initial description of the rules for constructing new SB API classes.

Jim Ingham jingham at apple.com
Fri Dec 5 16:28:06 PST 2014

Author: jingham
Date: Fri Dec  5 18:28:05 2014
New Revision: 223550

URL: http://llvm.org/viewvc/llvm-project?rev=223550&view=rev
Add an initial description of the rules for constructing new SB API classes.


Added: lldb/trunk/www/SB-api-coding-rules.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/SB-api-coding-rules.html?rev=223550&view=auto
--- lldb/trunk/www/SB-api-coding-rules.html (added)
+++ lldb/trunk/www/SB-api-coding-rules.html Fri Dec  5 18:28:05 2014
@@ -0,0 +1,69 @@
+<!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">
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+<link href="style.css" rel="stylesheet" type="text/css" />
+<title>LLDB Tutorial</title>
+    <div class="www_title">
+      The SB API Coding Rules
+    </div>
+<div id="container">
+	<div id="content">
+         <!--#include virtual="sidebar.incl"-->
+		<div id="middle">
+			<div class="post">
+				<h1 class ="postheader">SB API Coding Rules</h1>
+				<div class="postcontent">
+                                  <p>The SB APIs constitute the stable C++ API that lldb presents to external clients, 
+                                    and which get processed by SWIG to produce the Python bindings to lldb.  As such
+                                    it is important that they not suffer from the binary incompatibilities that C++ is
+                                    so susceptible to.  We've established a few rules to ensure that this happens.
+                                  <p>The classes in the SB API's are all called SB<SomeName>, where SomeName is in CamelCase
+                                      starting with an upper case letter.  The method names are all CamelCase with initial
+                                      capital letter as well.
+                                      <p>All the SB API classes are non-virtual, single inheritance classes.  They should only include
+                                        SBDefines.h or other SB headers as needed.  There should be no inlined method implementations
+                                        in the header files, they should all be in the implementation files.  And there should be no
+                                        direct ivar access.
+                                      <p>You also need to choose the ivars for the class with care, since you can't add or remove ivars
+                                        without breaking binary compatibility.  In some cases, the SB class is a thin wrapper around
+                                        an interal lldb_private object.  In that case, the class can have a single ivar, which is 
+                                        either a pointer, shared_ptr or unique_ptr to the object in the lldb_private API.  All the
+                                        lldb_private classes that get used this way are declared as opaque classes in lldb_forward.h,
+                                        which is included in SBDefines.h.  So if you need an SB class to wrap an lldb_private class
+                                        that isn't in lldb_forward.h, add it there rather than making a direct opaque declaration in
+                                        the SB classes .h file.  
+                                      <p>If the SB Class needs some state of its own, as well as the backing object, don't include that
+                                        as a direct ivar in the SB Class.  Instead, make an Impl class in the SB's .cpp file, and then
+                                        make the SB object hold a shared or unique pointer to the Impl object.  The theory behind this is
+                                        that if you need more state in the SB object, those needs are likely to change over time, 
+                                        and this way the impl class can pick up members without changing the size of the object.
+                                        An example of this is the SBValue class.
+                                      <p>In order to fit into the Python API's, we need to be able to default construct all the SB objects.
+                                        Since the ivars of the classes are all pointers of one sort or other, this can easily be done, but
+                                        it means all the methods must be prepared to handle their opaque implementation pointer being
+                                        empty, and doing something reasonable.  We also always have an "IsValid" method on all the SB 
+                                        classes to report whether the object is empty or not.
+                                      <p>Another piece of the SB API infrastructure is the Python (or other script interpreter) customization.  
+                                        SWIG allows you to add property access, iterators and documentation to classes, but to do that you have to use
+                                        a Swig interface file in place of the .h file. Those files have a different format than a straight C++ header file.  These 
+                                        files are called SB<ClassName>.i, and live in "scripts/Python/interface".  They are constructed by
+                                        starting with the associated .h file, and adding documentation and the Python decorations, etc.  We
+                                        do this in a decidedly low-tech way, by maintaining the two files in parallel.  That simplifies the
+                                        build process, but it does mean that if you add a method to the C++ API's for an SB class, you have
+                                        to copy the interface to the .i file.

Modified: lldb/trunk/www/lldb-coding-conventions.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/lldb-coding-conventions.html?rev=223550&r1=223549&r2=223550&view=diff
--- lldb/trunk/www/lldb-coding-conventions.html (original)
+++ lldb/trunk/www/lldb-coding-conventions.html Fri Dec  5 18:28:05 2014
@@ -16,7 +16,7 @@
          <!--#include virtual="sidebar.incl"-->
 		<div id="middle">
 			<div class="post">
-				<h1 class ="postheader">Getting Started</h1>
+				<h1 class ="postheader">LLDB Coding Conventions</h1>
 				<div class="postcontent">

Modified: lldb/trunk/www/sidebar.incl
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/sidebar.incl?rev=223550&r1=223549&r2=223550&view=diff
--- lldb/trunk/www/sidebar.incl (original)
+++ lldb/trunk/www/sidebar.incl Fri Dec  5 18:28:05 2014
@@ -46,6 +46,7 @@
       <li><a href="/source.html">Source</a></li>
       <li><a href="/build.html">Build</a></li>
       <li><a href="/lldb-coding-conventions.html">Coding Conventions</a></li>      
+      <li><a href="/SB-api-coding-rules.html">SB API Coding Rules</a></li>
       <li><a href="http://llvm.org/bugs">Bug Reports</a></li>
       <li><a href="http://llvm.org/svn/llvm-project/lldb/trunk">Browse SVN</a></li>
       <li><a href="http://llvm.org/viewvc/llvm-project/lldb/trunk">Browse ViewVC</a></li>

More information about the lldb-commits mailing list