v. 1.1.0 release

(ASE journal 2016)

.gitignore

@@ -0,0 +1,10 @@
+.sconf_temp
+.scons-cache
+.scons-config
+.sconsign.dblite
+Release
+config.log
+csi-*.*.*
+csi-*.*.*.tar.gz
+
+**/*.pyc

COPYING

@@ -3,7 +3,7 @@ CSI Release License
 -------------------
 Apache License, Version 2.0
 
-Copyright (c) 2013 Peter J. Ohmann and Benjamin R. Liblit
+Copyright (c) 2016 Peter J. Ohmann and Benjamin R. Liblit
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

NEWS

@@ -1,3 +1,7 @@
+* csi-1.1.0
+
+** Build used for 2016 ASE journal paper.
+
 * csi-1.0.0
 
 ** Initial build used in ASE 2013 paper.

README.md

@@ -3,15 +3,15 @@
 An instrumenting compiler for lightweight program tracing. The mechanisms were originally proposed in
 
 > P. Ohmann and B. Liblit.
-“[Lightweight control-flow instrumentation and postmortem analysis in support of debugging](http://pages.cs.wisc.edu/~liblit/ase-2013/).”
-28th International Conference on Automated Software Engineering (ASE
-2013), Nov. 2013. IEEE and ACM.
+“[Lightweight control-flow instrumentation and postmortem analysis in support of debugging](http://pages.cs.wisc.edu/~liblit/ase-2016/).”
+Automated Software Engineering Journal, 2016.  Springer.
+DOI: 10.1007/s10515-016-0190-1
 
-Preprint: http://pages.cs.wisc.edu/~liblit/ase-2013/ase-2013.pdf
+Preprint: http://pages.cs.wisc.edu/~liblit/ase-2016/ase-2016.pdf
 
 ## Current Release
 
-[`csi-cc` v1.0.0](../../releases/tag/v1.0.0)
+[`csi-cc` v1.1.0](../../releases/tag/v1.1.0)
 
 ## Documentation
 
@@ -20,6 +20,15 @@ Documentation is included in the source download, or you can view the
 
 ## Changelog
 
+###[v. 1.1.0](../../releases/tag/v1.1.0)
+
+Release associated with the article from the Automated Software Engineering
+journal (2016).  Major changes include:
+
+- Support for function, call-site, and statement coverage instrumentation
+- Support for more customizable tracing (see the
+[online documentation](https://rawgit.com/liblit/csi-cc/master/doc/running_schemes.html))
+
 ###[v. 1.0.0](../../releases/tag/v1.0.0)
 
 Initial release.

SConstruct

@@ -3,18 +3,38 @@
 #  configurable options
 #
 
+from os import access, environ, X_OK
+
+def pathIsExecutable(key, val, env):
+    found = env.WhereIs(val)
+    if found: val = found
+    PathVariable.PathIsFile(key, val, env)
+    if not access(val, X_OK):
+        raise SCons.Errors.UserError('Path for option %s is not executable: %s' % (key, val))
+
+
 opts = Variables('.scons-config', ARGUMENTS)
 opts.AddVariables(
-    PathVariable(key='LLVMBIN',
-                 help='location of bin directory of LLVM installation',
-                 default=None,
-                 validator=PathVariable.PathIsDir),
+    PathVariable(key='LLVM_CONFIG',
+                 help='path to llvm-config executable for LLVM installation',
+                 default=WhereIs('llvm-config'),
+                 validator=pathIsExecutable),
     PathVariable(key='CXX_ALT',
                  help='path to alternate C++ compiler',
                  default=None,
-                 validator=PathVariable.PathIsFile),
-    )
-env = Environment(options=opts)
+                 validator=pathIsExecutable),
+    BoolVariable(key='DEBUG',
+                 help='Compile with extra information for debugging',
+                 default=False),
+    BoolVariable(key='MEMCHECK',
+                 help="Run instrumentor tests under Valgrind's memcheck tool",
+                 default=False),
+)
+env = Environment(
+    options=opts,
+    tools=('default', 'llvm'),
+    toolpath=('instrumentor',),
+)
 opts.Save('.scons-config', env)
 
 ########################################################################
@@ -23,7 +43,7 @@ opts.Save('.scons-config', env)
 #
 
 CacheDir('.scons-cache')
-SetOption('implicit_cache', True)
+#SetOption('implicit_cache', True)
 SetOption('max_drift', 1)
 
 
@@ -38,6 +58,7 @@ env = env.Clone(
         '-Wextra',
         '-Werror',
         '-Wformat=2',
+        '${("", "-g")[DEBUG]}',
     ),
 )
 
@@ -59,6 +80,8 @@ SConscript(dirs=[
     'tests',
 ])
 
+Default('Release')
+
 
 ########################################################################
 #
@@ -87,4 +110,4 @@ package = env.Package(
     source=sources,
 )[0]
 
-AddPostAction(package, [Chmod('$TARGET', 0644)])
+AddPostAction(package, Chmod('$TARGET', 0644))

doc/building_comments.html

@@ -28,8 +28,9 @@ <h3>Additional Comments and Suggestions</h3>
 
 <p>As noted, LLVM version 3.1 or newer is required.  If LLVM is not installed
 in a standard location, you will probably have to tell scons where to find the
-bin directory of your installation.  You can do this by a command like<br/>
-<kbd class="indent">scons LLVMBIN=/path/to/LLVMBIN-DIR</kbd></p>
+LLVM configuration helper for your installation.  You can do this by a command
+like<br/>
+<kbd class="indent">scons LLVM_CONFIG=/path/to/llvm-config</kbd></p>
 
 <p>If you get an error like<br/>
 <samp class="indent">/usr/bin/ld: cannot find -lLLVM-3.X</samp><br/>

doc/index.html

@@ -16,23 +16,26 @@ <h1>CSI: Crash Scene Investigation</h1>
 <h2>A guide for the instrumenting compiler</h2>
 <hr class="half"/>
 <h3>Summary</h3>
-<p>The CSI compiler instruments programs with two tracing strategies as described
-in [<a href="references.html#Ohmann-Liblit">1</a>]&mdash;Path Tracing and
-Callsite Coverage.</p>
+<p>The CSI compiler instruments programs with two forms of customizable tracing
+as described in
+[<a href="references.html#Ohmann-Liblit-Journal">1</a>,
+ <a href="references.html#Ohmann-Liblit">2</a>]&mdash;Path Tracing and
+Program Coverage.</p>
 <h3>Contents</h3>
 <ul class="contents">
   <li><a href="building.html">Building CSI</a><ul>
     <li><a href="building_comments.html">Comments</a></li>
     </ul>
   </li>
   <li><a href="running.html">Compiling with CSI</a><ul>
+    <li><a href="running_schemes.html">Tracing Schemes</a></li>
     <li><a href="running_comments.html">Comments</a></li>
     </ul>
   </li>
   <li><a href="output.html">CSI Output</a><ul>
     <li><a href="metadata.html">Metadata</a><ul>
       <li><a href="metadata_pt.html">Path Tracing</a></li>
-      <li><a href="metadata_cc.html">Call Coverage</a></li>
+      <li><a href="metadata_cc.html">Program Coverage</a></li>
       </ul></li>
     <li><a href="variables.html">Variables</a></li>
     </ul>

doc/metadata.html

@@ -35,17 +35,24 @@ <h3>Path Tracing</h3>
 <p>For details about the format of the Path Tracing metadata, please see the
 <a href="metadata_pt.html">Path Tracing</a> page.</p>
 
-<h3>Call Coverage</h3>
-<p>Call Coverage metadata is stored as text in the debug
-section <samp>.debug_CC</samp> of the object file or executable.  Note
-that in the case of multiple object files linked into a single
-executable, the executable contains the complete metadata consolidated
-from all object files.  To extract this data, use a command similar
+<h3>Program Coverage</h3>
+<p><kbd>csi-cc</kbd> currently supports three variants of program coverage
+instrumentation: function coverage, call-site coverage, and statement coverage.
+The metadata for each granularity of program coverage is stored as text in the
+respective debug section:
+<ul>
+<li><samp>.debug_FC</samp> (for function coverage)</li>
+<li><samp>.debug_CC</samp> (for call coverage)</li>
+<li><samp>.debug_BBC</samp> (for statement coverage)</li>
+</ul>
+Note that in the case of multiple object files linked into a single executable,
+the executable contains the complete metadata consolidated from all object
+files.  As an example, to extract call coverage data, use a command similar
 to<br/>
 <kbd class="indent">Tools/extract-section --require .debug_CC <var>myexe</var></kbd></p>
 
-<p>For details about the format of the Call Coverage metadata, please see the
-<a href="metadata_cc.html">Call Coverage</a> page.</p>
+<p>For details about the format of the Program Coverage metadata, please see the
+<a href="metadata_cc.html">Program Coverage</a> page.</p>
 
 <hr/>
 <table class="toptable"><tr>