Clara

Applying Clara to a program is easy. Just proceed as follows. First download Clara. Unless you want to extend Clara with new analyses yourself, we recommend the JAR distribution.

A little test then yields…

$ java -jar clara-complete.jar -version
Clara 1.0.0
 with abc version 1.3.0.DEV
... with JastAdd frontend 0.2.0.DEV
 with EAJ (JastAdd version) 1.3.0.DEV
... using Soot toolkit version 2.3.0
... using Polyglot compiler toolkit version 1.3.0

You can get more help using:

$ java -jar clara-complete.jar -help
Usage:  java <java_options> abc.main.Main <abc_options> <filenames> 
   -or- abc <abc_options> <filenames>

   where a useful <java_option> is -Xmx512M, to provide a large heap
     and <filenames> should end in .java or .aj .

   <abc_options> are listed below.


...

  -static-analyses <stage1-stage2>
                               Specifies a hyphen separated list of 
                               static-analysis-stages to be executed. 
...

This will list several command-line options. Most options are abc specific and are explained here. However, there are some Clara-specific options as well. The probably most important one is the -static-analyses option. This option is followed by a hyphen-separated string that states the sequence of static typestate analyses that Clara should apply. For instance, the command line java -jar clara-complete.jar -static-analyses quick-osa-nsa will enable the Quick Check, followed by the Orphan-shadows analysis, followed by the Nop-shadows Analysis (see here for details). Currently, Clara comes with altogether four built-in analysis stages that are executed in the following order:

1. Quick Check (quick)
2. Orphan-shadows Analysis (osa)
3. Nop-shadows Analysis (nsa)
4. Dynamic code generation for Collaborative Runtime Verification (dyna)

Users can enable or disable every single analysis stage by simply denoting this stage in (or omitting the stage from) the  -static-analyses option. However, some combinations are illegal: Both the Nop-shadows analysis and the Dynamic code generation require the Orphan-shadows analysis to be applied as well. This is a current limitation of the analysis implementation. Clara will prevent you from executing an invalid configuration, though: the command line java -jar clara-complete.jar -static-analyses nsa yields Pass 'nsa' requires pass 'osa' but that pass is not enabled. Quitting.

Note that Clara’s default analyses cannot be re-ordered. In other words, the sequence quick-osa has the same effect as osa-quick. This is because the current implementations "don’t like" being executed in a different order. This may change in future versions of Clara.

The other options are just the default options to abc. For instance, the following command would take a monitoring aspect Monitor, weave this monitor aspect into program.jar, optimize the resulting program using the Quick Check and Orphan-shadows Analysis and emit the resulting program into out.jar:

java -jar clara-complete.jar –injars program.jar –outjar out.jar -static-analyses quick-osa Monitor.java

Cannot find class java.lang.Object / javax.crypto.Cypher

Clara performs a whole-program analysis, which includes the JDK. Therefore, Clara needs to know where your JDK is located. Clara usually does a good job by trying to locate the appropriate JAR files using your CLASSPATH and JAVA_HOME environment variables. However, when this fails then you will see one of two errors:

• cannot find class java.lang.Object: This indicates that Clara could not find classes.jar (on a Mac) or rt.jar (on any other OS).
• cannot find class javax.crypto.Cypher: This indicates that Clara could not find jce.jar.

To add the appropriate JAR files to Clara, set Clara’s classpath. On a Mac, use something along the lines of:

java -jar clara-complete.jar –cp .:/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Classes/classes.jar:/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Classes/jce.jar ...

You may also have to include ui.jar on MacOS. On other operating systems, locate rt.jar and jce.jar in our JDK installation (usually at jre/lib) and add these jar files accordingly. Note that we include “.” to include the current directory as well.