Tagging the 2.3.0 release of the Soot project.

Author: Eric Bodden

trunk/CHANGES

@@ -0,0 +1 @@
+See index.html for the installation instructions.

trunk/COPYING-LESSER.txt

@@ -0,0 +1,61 @@
+In March 2003, we made several modifications to Soot to make it better
+suited to being used as a library or inside a GUI. The most significant
+change was moving all global variables to a single class called G, so
+that they could be reset in between different runs of Soot. In order to
+maintain interoperability as a library and with GUIs, the following
+coding rules have been imposed. A checker has been included which points
+out potential violations of these rules. To run it, enter:
+
+ant badfields
+
+Rules:
+
+1) System.out and System.err should not be used. G.v().out should be
+   used instead. It is normally mapped to System.out, but may be
+   remapped by a program using Soot as a library or by a GUI.
+   If you accidentally send stuff to System.out instead, the output
+   will not appear in Eclipse.
+
+2) There should be no calls to System.exit(). This will kill programs
+   using Soot as a library and GUIs. Instead, Soot should throw a
+   CompilationDeathException or a RuntimeException.
+
+3) Static fields should not be used, unless they are final AND of
+   an immutable type such as a primitive type, String, Object,
+   Integer or Boolean.
+
+4) Static initializers should not have any side-effects. In particular,
+   they should not read any static fields. In addition, in order to
+   ensure that static initializers have no side-effects, they should
+   not call any methods, except trivial ones known to have no side-effects.
+
+5) Singletons should be implemented as follows:
+   - add the name of the singleton to soot/src/singletons.list
+   - run soot/src/make_singletons > soot/src/soot/Singletons.java
+   - in your singleton, include the following two methods following
+     the model in soot.jimple.toolkits.base.Aggregator:
+
+    public Aggregator( Singletons.Global g ) {}
+    public static Aggregator v() { return G.v().Aggregator(); }
+
+     The Singletons.Global parameter to the only constructor ensures
+     that only the Singletons class may instantiate the singleton,
+     since only it can create a Singletons.Global. The v() method
+     fetches the singleton instance from the Singletons class.
+     THE SINGLETON SHOULD NOT HAVE ITS OWN STATIC FIELD CONTAINING
+     THE SINGLETON INSTANCE. soot.G is the only singleton holding
+     its own instance, meaning that all global variables and singletons
+     can be reset by resetting that one single instance.
+
+6) "ant badfields" should be run periodically to check that these rules
+   are being followed. It will report most violations. Unfortunately,
+   it also reports some false positives that must be checked by hand.
+   Many of these are final static arrays, whose elements are never
+   modified. Unfortunately, Java doesn't have a final keyword that
+   applies to elements of arrays. It must be checked by hand that these
+   elements are never written. Presumably Spark could be used to check
+   that elements of static arrays are not written, but this may make
+   the checker too clumsy; the intent is for the checker to be widely
+   used.
+
+EOF

trunk/README

@@ -0,0 +1,56 @@
+Dear Soot Users,
+
+We are pleased to announce that Soot version 2.3.0 is now available
+at: http://www.sable.mcgill.ca/soot/
+
+This release contains the following additions and improvements:
+
+1. Integrated new JastAdd-based frontend with support for Java 5
+   source code. Thanks to Torbjorn Ekman for contributing his
+   frontend and his implementation of Java2Jimple!
+   
+2. At the very least if -validate is on, Soot now checks that @this
+   is only assigned in the first statement of an instance method.
+   This has always been an implicit assumption for Jimple code
+   but up until now was not enforced. 
+   
+3. Integrated full support for preserving annotations in Jimple
+   and writing them to bytecode. SOURCE level annotations are
+   preserved if code is read from source and the flag
+   -p jb preserve-source-annotations is given. (does not hold for
+   package and local variable annotations) SOURCE level annotations
+   are not written into bytecode by Soot.
+   Annotations can easily be added to SootClass, SootMethod and
+   SootField instances using the utility class
+   soot.jimple.toolkits.annotation.j5anno.AnnotationGenerator.
+   (Thanks to Will Benton!)   
+ 
+4. Java 5 Annotations for fields, classes, parameters and methods
+   are now fully preserved in bytecode. Jasmin was changed to
+   implement this support.   
+   
+5. Ben Bellamy contributed a new implementation for the type assigner.
+   This is to be published under the title 'Efficient Local Type
+   Inference' at OOPSLA '08. The new type assigner is usually
+   faster (it is applied when processing bytecode), and sometimes
+   more precise. In particular it should always infer the most
+   narrow type possible.   
+   
+Also we incorporated fixes to numerous bugs. Thanks for reporting bugs
+and/or prividing fixes!   
+
+See http://www.sable.mcgill.ca/soot/CHANGES for details.
+
+As of version 2.2.0 the Soot bugzilla is available at:
+http://svn.sable.mcgill.ca/bugzilla/. We encourage you to add any Soot
+bugs there.
+
+Also, as of version 2.2.0 the Soot wiki is available at:
+http://svn.sable.mcgill.ca/wiki/index.php/SootProject. The Soot team
+will be using this site for discussing upcoming work, so if you would
+like to know what's going on look there.
+
+Regards,
+
+Eric Bodden 
+Sable Research Group, McGill University

trunk/README.coding_rules

@@ -0,0 +1,115 @@
+Todo (as of 2.0.1)
+
+VERY HIGH - fix problem that xml attribute tags are only generated if output == jimple (they should work if other output formats are selected also) - fixed
+
+VERY HIGH - fix the mechanism used to generate attributes in the source viewers in Eclipse - fixed - needs more work - fixed
+
+HIGH - finish coloring for stmts - fixed 
+
+HIGH - make visual attributes display in inner classes in source - done
+
+HIGH - implement getting the actual Soot Output dir from Soot so the plugin can find the xml attributes file (right now if you use a dir other then the default the attributes cannot be found) 
+
+HIGH - minimize amount of XML being generated - done
+
+HIGH - write documentation and howto's - done
+
+HIGH - implement running on all source files in project from project menu (currently can only run for all class files - unless process-dir is changed manually)
+- done
+
+HIGH - implement being able to run Soot on a package of java files (not classes) and being able to do more then just decompile when a package/folder is selected
+
+HIGH - fix the paths problems when plugin is automatically finding and adding to soot-class-path all jars required by the project (or all jars in the project) -
+- fixed 
+
+MEDIUM - when cloning a configuration, give the old name of the cloned configuration as a starting point for the new name for the new configuration - done
+
+MEDIUM - decide what to do while Soot is running
+    1) don't allow the user to do anything
+    2) don't allow the user to do Soot related things
+    3) don't restrict the user from doing anything
+
+MEDIUM - implement the Java to Jimple translations for assert and anon inner classes - done
+
+MEDIUM - implement analyses 
+
+MEDIUM - fix selection process so if multiple selections are made in package explorer/ navigator - have Soot run with list of classes selected (not just first one as currently happens) - done
+
+MEDIUM - implement a view with the key for colors when displaying color attributes
+
+MEDIUM - determine in soot why fields and methods don't have line number tags when starting from class files
+
+MEDIUM - add tooltips to the entries in the manage configurations dialog with the soot command line of what they save (w/o Eclipse defs in list)
+
+LOW - fix and start using: when dava runs creating a dava project automatically and copying the generated classes there
+                                     
+LOW - fix the problem of polyglot not being able to find classes in jars 
+
+LOW - implement import/export a set of options to plugin
+
+LOW - make long_desc be tooltips in pages in Options Dialog (currently the short descriptions are shown)
+
+LOW - Soot Output View possibly limiting the #characters in this view to something (wrapping)
+
+LOW - have dependencies for options dialog
+
+LOW - implement textlistener for updating content outliner as one types
+
+LOW - implement a progress monitor at bottom when running soot
+
+LOW - create better jimple and soot icons 
+
+LOW - fix the delete from managed configurations (the configuration name disappears from the list but the configuration never gets deleted from the underlying file where it is saved)
+
+VERY LOW - pop-up generated files after running Soot
+
+VERY LOW - have soot menu from right click on file (jimple only) - when in full screen
+
+VERY LOW - impl an option to run Dava in popup menu Open With ...
+
+VERY LOW - getting decompiled library classes to know their project
+
+Todo (as of 1.2.5)
+1. continued work on Spark (points-to) package, Ondrej
+2. SSA-Jimple (Navindra)
+3. Decompiler (Jerome)
+4. Solve UnitGraph for infinite loops (without exit points).
+5. More projects from CS621.
+6. Precise exception modelling (John)
+7. Refactor global variables.
+8. Clean up and document options.
+
+Todo (as of 1.2.4)
+1. continued work on Spark (points-to) package, Ondrej
+2. SSA-Jimple (Navindra)
+3. Decompiler (Jerome)
+4. Solve UnitGraph for infinite loops (without exit points).
+5. More projects from CS621.
+6. Precise exception modelling (John)
+7. Java 1.4 support.
+
+Todo (as of 1.2.3)
+1. Spark (points-to) package, Ondrej
+2. SSA-Jimple (Navindra)
+3. Decompiler (Jerome)
+4. Solve UnitGraph for infinite loops (without exit points).
+5. More projects from CS621.
+
+Todo (as of 1.2.2)
+1. waiting for more improvements on speed and memory usage
+   John is working on that.
+2. how soot works on other VMs ( such as Kaffe )
+
+Todo (as of 1.2.1)
+1. test new command line options provided by Fabien
+
+Open problems (as of 1.2.0):
+
+1. improve our naming scheme to make Soot run on Macintosh.
+2. improve the invoke graph builder.
+3. include an interprocedural flow analysis framework
+      and improve the whole-program analysis features.
+4. improve soot.toolkits.graph.Block so that we keep a state counter for
+      the Body and don't trample stuff; this is needed to keep the 
+      BlockLength up to date.  Actually, that is somewhat complicated.
+

trunk/Release_Notice

@@ -0,0 +1,31 @@
+## Location of JastAdd classes jar file to link Soot against
+#  This can be found at:
+#  svn+ssh://musketeer.comlab.ox.ac.uk/srv/svn/projects/trunk/JastAddExtensions/
+#  check out this url and then set thiss variable to <prefix>/JastAddExtensions/SootJastAddJ 
+#
+# NOTE: You ONLY need to check this out and set this parameter if you wish to regenerate
+# the JastAdd-generated files in generated/jastadd!
+# 
+#jastaddfrontend.loc=../JastAddExtensions/SootJastAddJ
+
+## Location of Polyglot classes jar file to link Soot against
+polyglot.jar=${user.home}/polyglotclasses.jar
+
+## Location of Jasmin classes jar file
+jasmin.jar=${user.home}/jasminclasses.jar
+
+## Location of Eclipse installation.
+## This should have a directory called plugins in it.
+eclipse.loc=/usr/share/eclipse
+
+## Version of Soot for tagging tarballs.
+soot.version=trunk
+
+## Location in which to generate Soot release tarballs.
+release.loc=lib
+
+## URL for Java API documentation, for resolving things like
+## {@link Iterator} when generating documentation from 
+## javadoc comments.
+javaapi.url=http://java.sun.com/j2se/1.5.0/docs/api/
+