add StmtGraph doc

docs/announce.md → docs/announcement.md

@@ -12,17 +12,18 @@ SootUp is a library that can easily be included in other projects, leaving those
 
 Below is an overview of what’s new. 
 
-* Library by default, framework as an option
-* Modular Architecture, no more singletons
-* New source code frontend
-* Immutable Jimple IR
-* Greatly increased testability and test coverage
+- Library by default, framework as an option
+- Modular Architecture, no more singletons
+- New source code frontend 
+- Immutable Jimple IR
+- Greatly increased testability and test coverage ![Coverage](https://camo.githubusercontent.com/adc4ab244f7c0c2b2f3fec0a6e5d778421ddc0be7f89a608c16533c9a964766f/68747470733a2f2f636f6465636f762e696f2f67682f736f6f742d6f73732f536f6f7455702f6272616e63682f646576656c6f702f67726170682f62616467652e7376673f746f6b656e3d454c4137553749415744)
 
 SootUp is not a drop-in replacement for Soot! Due to its completely new architecture and API it is essentially an almost complete rewrite. For a while, Soot and SootUp will coexist, as many existing tools depend on Soot, yet our maintenance efforts will henceforth be focused on SootUp, not Soot, and on extending SootUp with those capabilities that people still find missing. For now, we recommend using SootUp for greenfield projects.
 
 For more details, check out
-* The SootUp home page: https://soot-oss.github.io/SootUp/, and 
-* The SootUp repository: https://github.com/soot-oss/SootUp/
+- 
+- The SootUp home page: [This Page](https://soot-oss.github.io/SootUp/), and 
+- The SootUp repository: [https://github.com/soot-oss/SootUp/](https://soot-oss.github.io/SootUp/)
 
 We are very much looking forward to your feedback and feature requests. To this end, best create appropriate issues in the repository.
 

docs/css/customizetheme.css

@@ -11,6 +11,11 @@
     --md-accent-fg-color: rgba(255,140,0, 1);
 }
 
+.md-main__inner {
+    margin-top: 0;
+    margin-bottom: 5em;
+}
+
 .md-typeset{
     font-size: 12pt;
 }

docs/getting-started.md

@@ -2,19 +2,16 @@
 Before you get started with the SootUp library, it helps to learn about the following core data structures:
 
 - [`AnalysisInputLocation`]{It corresponds to the `cp` option, which specifies the classpath for Soot to find classes to be analyzed.}
-  : points to the target code to be analyzed.
+  : points to the target code that shall be loaded into the `View`.
 
-- [`View`]{Corresponds to the `Scene` class, but it is not a singleton. So it is possible to instantiate multiple views simultaneously.}: presents the code/classes under analysis. 
+- [`View`]{Corresponds to the `Scene` class, but it is not a singleton. So it is possible to instantiate multiple views simultaneously.}:
+handles the representation of the code you configured it to analyze.
 
-- `SootClass`: represents a class loaded into the `View`.
-
-- `SootMethod`: represents a method of a class.
-
-- `SootField`: represents a field of a class.
-
-- `Body`: represents a method body in Jimple.
-
-- `StmtGraph`: represents the control flow graph of a method body in Jimple statements.
+- `SootClass`: represents a class. Can be loaded from the View via a `ClassType` identifier.
+- `SootMethod`: represents a method of a class - loaded from the View via a `MethodSignature` identifier.
+- `SootField`: represents a field of a class - loaded from the View via a `FieldSignature` identifier.
+- `Body`: represents a method body of a `SootMethod`.
+- `StmtGraph`: represents the control flow graph of a `Body`. `Stmt`'s represent actual Instructions.
 
 ## Creating a View
 
@@ -31,11 +28,10 @@ You can use bytecode analysis typically when you do not have access to the sourc
 
 If you have access to the source code, it is also possible to create a view for analyzing source code. Following example shows how to create view for analyzing Java source code.
 
-!!! info "Experimental"
-
-    The source code frontend is experimental and should only be used for testing purposes. You should compile the code for analysis first and use the bytecode frontend instead.  
+!!! info "Experimental! - Create a view to analyze Java source code"
 
-!!! example "Create a view to analyze Java source code"
+    The source code frontend is experimental and should only be used for testing purposes. 
+    Usually you should compile the code for analysis first and use the bytecode frontend instead (see above). 
 
     ~~~java
     AnalysisInputLocation inputLocation = 
@@ -65,10 +61,10 @@ If you have a [Jimple](../jimple) file, you can create a view for analyzing jimp
 
 By default, whenever a class is retrieved, it will be permanently stored in a cache.
 If you do not want retrieved classes to be stored indefinetly, you can instead provide a different `CacheProvider` to the created view.
-To for example use an `LRUCache` instead, which stores at most 50 classes, and always replaces the least recently used class by a newly retrieved one, use the following call:
+To for example use an `LRUCache` instead, which stores at most e.g. 50 classes, and always replaces the least recently used class by a newly retrieved one, use the following call:
 
 ```java
-JavaView view = new JavaView(Collections.singletonList(inputLocation), new LRUCacheProvider(50));
+JavaView view = new JavaView(inputLocations, new LRUCacheProvider(50));
 ```
 
 
@@ -149,9 +145,11 @@ Once we have a `MethodSignature` that identifies the `main` method of the `Hello
     ```java
     Optional<SootMethod> opt = view.getMethod(methodSignature);
 
-    if(opt.isPresent()){
-      SootMethod method = opt.get();
+    if(!opt.isPresent()){
+        return;
     }
+    SootMethod method = opt.get();
+    System.out.println(method.getModifiers());
     ```
 Alternatively, we can also retrieve a `SootMethod` from `SootClass` that contains it.
 
@@ -173,7 +171,47 @@ Each `SootMethod` contains a Control-Flow Graph (CFG) which is represented via t
 !!! example "Retrieving the CFG of a SootMethod"
 
     ```java
-    sootMethod.getBody().getStmtGraph();
+    StmtGraph<?> graph = sootMethod.getBody().getStmtGraph();
+    ```
+
+
+## Using the StmtGraph
+
+=== "StmtGraph Stmts"
+    ```java
+    for( Stmt stmt : graph.nodes()){
+        // pseudo topological order as Stmts would be serialized to a Jimple file.
+    }
+
+    for( Stmt stmt : graph.nodes()){
+        // Stmts are unordered!
+    }
+    ```
+=== "StmtGraph Blocks"
+    ```java
+    List<BasicBlock<?>> blocks = graph.getBlocks();
+    for( BasicBlock<?> block : blocks){
+        // e.g. check if its a merge point
+        if(block.getPredecessors().size() > 1){
+            ...
+        }
+
+        // e.g. check if its a branching point
+        if(block.getSuccessors().size() > 1){
+            // or use block.getTail() instanceof BranchingStmt
+            ...
+        }
+
+        // e.g. check if thrown exceptions would be caught in this method
+        if(!block.getExceptionalSuccessors().isEmpty()){
+            ...
+        }
+    }
+    ```
+=== "StmtGraph DotExport"
+    ```java
+    String urlToWebeditor = DotExporter.createUrlToWebeditor(this);
+    System.out.println(urlToWebeditor);
     ```
 
 

mkdocs.yml

@@ -1,27 +1,26 @@
-site_name: SootUp
+site_name: ""
 site_url: https://soot-oss.github.io/SootUp/
 repo_url: https://github.com/soot-oss/SootUp/
 edit_uri: edit/develop/docs/
 
 nav:
-    - Home: index.md
-
     - Getting Started:
         - Installation: installation.md
         - First Steps: getting-started.md
         - Examples: examples.md
         - Configure your Inputs: analysisinputlocations.md
 
-    - Basics:
+    - Basics I:
       - Jimple IR: jimple.md
       - Jimple Body: jimple-body.md
       - Jimple Statements: jimple-stmts.md
       - Jimple Types: jimple-types.md
       - Jimple Values: jimple-values.md
 
+    - Basics II:
       - BodyInterceptors: bodyinterceptors.md
-      - Callgraph Construction: call-graph-construction.md
-      - Shipped Analyses: shipped-analyses.md
+      - Callgraphs: callgraphs.md
+      - BuiltIn Analyses: builtin-analyses.md
 
     - How to..:
       - Write a Dataflow analysis: write_analyses.md
@@ -33,7 +32,7 @@ nav:
     #  - From Prototype to Tool: tool_setup.md
 
     - Misc:
-        - Announcements: announce.md
+        - Announcements: announcement.md
         - Design Decisions: whatsnew.md
         - Migration Help: migrating.md