v. 1.4.0 release

(INFORMS JOC 2023 -- "A Set Covering Approach to Customized Coverage Instrumentation")

Author: pohmann

AUTHORS

@@ -1,2 +1,2 @@
-Peter Ohmann <ohmann@cs.wisc.edu>
+Peter Ohmann <pohmann001@csbsju.edu>
 Ben Liblit <liblit@cs.wisc.edu>

COPYING

@@ -3,7 +3,7 @@ CSI Release License
 -------------------
 Apache License, Version 2.0
 
-Copyright (c) 2017 Peter J. Ohmann and Benjamin R. Liblit
+Copyright (c) 2023 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.4.0
+
+** Build used for 2023 INFORMS JOC paper on optimal coverage optimization.
+
 * csi-1.3.0
 
 ** Build used for PLDI 2017 conference paper on program analysis.

README.md

@@ -11,15 +11,27 @@ Preprint: http://pages.cs.wisc.edu/~liblit/ase-journal-2016/ase-journal-2016.pdf
 
 ## Current Release
 
-[`csi-cc` v1.3.0](../../releases/tag/v1.3.0)
+[`csi-cc` v1.4.0](../../releases/tag/v1.4.0)
 
 ## Documentation
 
 Documentation is included in the source download, or you can view the
-[online documentation](https://rawgit.com/pohmann/csi-cc/master/doc/index.html).
+[online documentation](https://pohmann.github.io/csi-cc).
 
 ## Changelog
 
+### [v. 1.4.0](../../releases/tag/v1.4.0)
+
+Release associated with the 2023 INFORMS JOC paper
+"A Set Covering Approach to Customized Coverage Instrumentation."
+Major changes include:
+
+- Support for more LLVM releases (through 7.0)
+- A new, more efficient optimal coverage solver ("LEMON"), as proposed in
+the paper
+- Support for the GNU Indirect Function attribute for run-time selection
+among tracing schemes, as referenced in Peter Ohmann's PhD dissertation
+
 ### [v. 1.3.0](../../releases/tag/v1.3.0)
 
 Release associated with the PLDI 2017 paper "Control-Flow Recovery from

SConstruct

@@ -27,6 +27,14 @@ opts.AddVariables(
                  help='path to GAMS installation directory',
                  default=None,
                  validator=PathVariable.PathIsDir),
+    PathVariable(key='LEMONDIR',
+                 help='path to LEMON installation directory.  Requires GUROBIDIR',
+                 default=None,
+                 validator=PathVariable.PathIsDir),
+    PathVariable(key='GUROBIDIR',
+                 help='path to GUROBI installation directory',
+                 default=None,
+                 validator=PathVariable.PathIsDir),
     BoolVariable(key='DEBUG',
                  help='Compile with extra information for debugging',
                  default=False),
@@ -41,6 +49,10 @@ env = Environment(
 )
 opts.Save('.scons-config', env)
 
+if env.get('LEMONDIR', None) and not env.get('GUROBIDIR', None):
+    print 'Must specify both LEMONDIR and GUROBIDIR'
+    Exit(1)
+
 ########################################################################
 #
 # performance boosters

Tools/.gitignore

@@ -1,2 +1,2 @@
-extract-cfg
-extract_section.py
+/extract-cfg
+/extract_section.py

docs/.nojekyll

@@ -0,0 +1 @@
+

doc/building.html docs/building.htmldoc/building.html renamed to docs/building.html

@@ -38,10 +38,9 @@ <h3>Build Command</h3>
 
 <p>CSI is capable of aggressive optimization for some instrumentation schemes.
 See the <a href="building_comments.html">detailed build comments</a> for
-how to hook up with your installation of the
-<a href="https://www.gams.com/">GAMS</a> optimization framework.  For full
-optimization, the following non-standard packages are required:</p>
-<ul><li><a href="https://www.gams.com/">GAMS</a> 24.2.1+</li></ul>
+how to hook up with your installation of either the
+<a href="https://www.gams.com/">GAMS</a> optimization framework
+or <a href="https://www.gurobi.com">GUROBI</a> optimizer.
 
 <p>Having problems?  See some <a href="building_comments.html">additional
 comments</a>.</p>

doc/building_comments.html docs/building_comments.htmldoc/building_comments.html renamed to docs/building_comments.html

@@ -26,6 +26,8 @@ <h3>Optional Build Configuration, Additional Comments, and Suggestions</h3>
 places) for Clang and GCC versions 4.6+.  It is unlikely to build for
 GCC versions before 4.2.</p>
 
+<hr class="minorsep"/>
+
 <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
 LLVM configuration helper for your installation.  You can do this by a command
@@ -39,13 +41,26 @@ <h3>Optional Build Configuration, Additional Comments, and Suggestions</h3>
 when building LLVM should look something like<br/>
 <kbd class="indent">configure --enable-shared</kbd></p>
 
+<p>If you intend to use aggressive optimization (see below), you should
+also consider building LLVM with assertions enabled. The flags for this will
+vary with LLVM version, but, as an example, a standard build to use CSI with
+LLVM 4.0 would be:<br/>
+<kbd class="indent">cmake srcdir -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_ASSERTIONS=ON
+-DLLVM_ENABLE_RTTI=ON -DLLVM_LINK_LLVM_DYLIB=ON</kbd></p>
+
+<hr class="minorsep"/>
+
 <p>CSI is capable of aggressive optimization for program coverage
 instrumentation schemes.  Specifically, if you are hoping to use fully-optimal
 instrumentation for program coverage (see the
 <a href="running_optimization.html">coverage optimization</a> page), you will
-need to build CSI with support for connecting to the
-<a href="https://www.gams.com/">GAMS</a> optimization framework.  Naturally,
-you first need to have <a href="https://www.gams.com/">GAMS</a> installed.
+need to build CSI with support for connecting to one of the following:</p>
+<ul>
+  <li>the <a href="https://www.gams.com/">GAMS</a> optimization framework</li>
+  <li>the <a href="https://www.gurobi.com">GUROBI</a> optimizer AND the
+    <a href="https://lemon.cs.elte.hu/trac/lemon">LEMON</a> graph library</li>
+</ul>
+<p>For the first option, you first need to have <a href="https://www.gams.com/">GAMS</a> installed.
 Then, you can tell CSI where to find your
 <a href="https://www.gams.com/">GAMS</a> installation by a command like<br/>
 <kbd class="indent">scons GAMSDIR=/path/to/GAMS</kbd><br/>
@@ -54,6 +69,16 @@ <h3>Optional Build Configuration, Additional Comments, and Suggestions</h3>
 the <kbd>gams</kbd> executable, as well as a subdirectory called
 <kbd>apifiles/</kbd>.</p>
 
+<p>For the second option, you, again, need to up-to-date installations of
+<a href="https://www.gams.com/">GAMS</a> and
+<a href="https://lemon.cs.elte.hu/trac/lemon">LEMON</a>.
+Then, you can tell CSI where to find your installations by a command like<br/>
+<kbd class="indent">scons LEMONDIR=/path/to/lemon GUROBIDIR=/path/to/gurobi</kbd><br/>
+Again, these paths should point to the top-level directories of the installed
+tools, containing subdirectories like <kbd>bin</kbd> and <kbd>include</kbd>.
+
+<hr class="minorsep"/>
+
 <p>If building on OSX, note that many pre-packaged distributions of LLVM do not
 include a full LLVM shared object for linking with CSI.  If you see linker
 errors when building with pre-installed LLVM, please try building LLVM from