From 304f1a7abfebba3793324671c2fd0760ad1d0f1d Mon Sep 17 00:00:00 2001 From: Markus Schmidt Date: Fri, 5 Jul 2024 12:34:25 +0200 Subject: [PATCH] add code examples --- docs/analysisinput.md | 138 ++++++++++++++++-- .../DefaultRTJarAnalysisInputLocation.java | 3 + .../OTFCompileAnalysisInputLocation.java | 1 - 3 files changed, 126 insertions(+), 16 deletions(-) diff --git a/docs/analysisinput.md b/docs/analysisinput.md index ad530b175b2..83091bca840 100644 --- a/docs/analysisinput.md +++ b/docs/analysisinput.md @@ -1,40 +1,148 @@ # Analysis Input -i.e. What should be analyzed - an `AnalysisInputLocation` points to code input SootUp can analyze. -We ship multiple Subclasses that can handle different code input. +i.e. What should be analyzed. An `AnalysisInputLocation` points to code input SootUp can analyze. +We ship multiple Implementations that can handle different input. -You can specify a SourceType - which e.g. determines how far an analysis will go. -Additionally you can specify a List of [BodyInterceptors](bodyinterceptors.md), which will optimize the raw Jimple IR that was transformed from the input. +Additionally you can specify a SourceType. This determines what is considered e.g. in the CallGraphs generation. +Further you can specify a List of [BodyInterceptors](bodyinterceptors.md), which will optimize the raw Jimple IR that was transformed from the input. ### Java Runtime -points to the runtime library of the executing JVM. - -- Java <=8: `DefaultRTJaAnalysisInputLocation` points to the rt.jar of the executing JVM. -- To include a different Java Runtime library point to any rt.jar via a `JavaClassPathAnalysisInputLocation` as its a usual .jar file. -- Java >=9: `JRTFilesystemAnalysisInputLocation` points to the jigsawed java runtime of the executing jvm. +#### Java <=8 +`DefaultRTJaAnalysisInputLocation` points to the rt.jar of the executing JVM. -If you have errors like Java.lang.String, Java.lang.Object, ... you are most likely missing this AnalysisInput. + +```java +// points to the runtime library of the current jvm +AnalysisInputLocation inputLocation = new DefaultRTJaAnalysisInputLocation(); +JavaView view = new JavaView(inputLocation); +``` + +To include a different Java Runtime library point to any rt.jar via a `JavaClassPathAnalysisInputLocation` as its a usual .jar file. + +#### Java >=9 +`JRTFilesystemAnalysisInputLocation` points to the jigsawed java runtime of the executing JVM. + +```java +// points to the runtime library of the current jvm +AnalysisInputLocation inputLocation = new JrtFileSystemAnalysisInputLocation(); +JavaView view = new JavaView(inputLocation); +``` + + +!!! info "If you have errors like Java.lang.String, Java.lang.Object, ... you are most likely missing this AnalysisInputLocation." ### Java Bytecode File-Extensions: `.class, .jar, .war` -- `JavaClassPathAnalysisInputLocation` - its the equivalent of the classpath you would pass to the java executable i.e. point to root(s) of package(s). +`JavaClassPathAnalysisInputLocation` its the equivalent of the classpath you would pass to the java executable i.e. point to root(s) of package(s). + +=== "Directory" + ```java + AnalysisInputLocation inputLocation = + new JavaClassPathAnalysisInputLocation("target/"); // points to + JavaView view = new JavaView(inputLocation); + ``` + +=== ".jar File" + ```java + AnalysisInputLocation inputLocation = new JavaClassPathAnalysisInputLocation("myCode.jar"); + JavaView view1 = new JavaView(inputLocation); + + // if you want to analyze a specific language level of a multi release jar + AnalysisInputLocation inputLocation = + new MultiReleaseJarAnalysisInputLocation("myCode.jar", new JavaLanguage(10) ); + JavaView view2 = new JavaView(inputLocation); + ``` + +=== ".class File" + ```java + // if you omit the package structure while pointing to a file, + // you have to pass the omitted directories as a parameter + AnalysisInputLocation inputLocation = new PathBasedAnalysisInputLocation. + ClassFileBasedAnalysisInputLocation("Banana.class", "packageName.subPackage", SourceType.Application); + JavaView view = new JavaView(inputLocation); + ``` + +=== "Complete class path" + ```java + String cp = "myCode.jar" + File.pathSeparator + "dependency.jar" + File.pathSeparator + "target/classes/"; + AnalysisInputLocation inputLocation = new JavaClassPathAnalysisInputLocation(cp); + JavaView view = new JavaView(inputLocation); + ``` ### Java Sourcecode File-Extensions: `.java` -- `OTFCompileAnalysisInputLocation` - you can point directly to .java files or pass a String with Java sourcecode, SootUp delegates to the `JavaCompiler` and transform the bytecode from the compiler to Jimple -- `JavaSourcePathInputLocation` [***experimental!***]{Has huge problems with exceptional flow!} - points to a directory that is the root source directory (containing the package directory structure). +`OTFCompileAnalysisInputLocation` +you can point directly to .java files or pass a String with Java sourcecode, SootUp delegates to the `JavaCompiler` and transform the bytecode from the compiler to Jimple + +=== "Single File" + ```java + AnalysisInputLocation inputLocation = new OTFCompileAnalysisInputLocation("Banana.java"); + JavaView view = new JavaView(inputLocation); + ``` + +=== "Multiple Files" + ```java + List files = Arrays.asList(Paths.get("Apple.java"), Paths.get("Banana.java")); + AnalysisInputLocation inputLocation = new OTFCompileAnalysisInputLocation(files); + JavaView view = new JavaView(inputLocation); + ``` +=== "File as String" + ```java + String content = "public class B{ }"; + AnalysisInputLocation location = new OTFCompileAnalysisInputLocation("B.java", content ); + JavaView view = new JavaView(location); + ``` + +`JavaSourcePathInputLocation` [***experimental!***]{Has huge problems with exceptional flow!} - points to a directory that is the root source directory (containing the package directory structure). ### Jimple File-Extensions: `.jimple` -- `JimpleAnalysisInputLocation` - needs a Path to a .jimple file or a directory. +`JimpleAnalysisInputLocation` needs a Path to a .jimple file or a directory. + +```java +Path path = Paths.get("Banana.java"); +AnalysisInputLocation jimpleLocation = new JimpleAnalysisInputLocation(path); +JavaView view = new JavaView(jimpleLocation); +``` + ### Android Bytecode File-Extensions: `.apk` -- `ApkAnalysisInputLocation` - currently uses dex2jar internally - A SootUp solution to directly generate Jimple is WIP! +`ApkAnalysisInputLocation` currently uses dex2jar internally - A SootUp solution to directly generate Jimple is WIP! + +```java +Path path = Paths.get("Banana.apk"); +AnalysisInputLocation inputLocation = new ApkAnalysisInputLocation(path); +JavaView view = new JavaView(inputLocation); +``` + + + +### Combining Multiple AnalysisInputLocations +But what if I want to point to multiple AnalysisInputLocations? + +```java +AnalysisInputLocation mainJar = new JavaClassPathAnalysisInputLocation("myCode.jar"); +AnalysisInputLocation jarA = new JavaClassPathAnalysisInputLocation("dependencyA.jar"); +AnalysisInputLocation jarB = new JavaClassPathAnalysisInputLocation("dependencyB.jar"); + +List inputlocationList = Arrays.asList(mainJar, jarA, jarB); + +JavaView view = new JavaView(inputlocationList); +``` +!!! note "Of course you can combine different types of `AnalysisInputLocation`s as well!" + + +### Maven Project as Analysis Input in SootUp +This uses `#!shell mvn compile` + `JavaClassPathAnalysisInputLocation` under the hood to include a maven project. +```java + TODO: let the code sail with the upstream boat to this doc. +``` +Unfortunately its harder to extract the path of the binary result of Gradle projects in a unified way for all kinds of models - If you have a solution are looking forward to merge your contribution :-). ### Java cli arguments to configure SootUp We created a [Utility](tool_setup.md) that parses a String of java command line arguments and configures SootUp respectively. \ No newline at end of file diff --git a/sootup.java.bytecode/src/main/java/sootup/java/bytecode/inputlocation/DefaultRTJarAnalysisInputLocation.java b/sootup.java.bytecode/src/main/java/sootup/java/bytecode/inputlocation/DefaultRTJarAnalysisInputLocation.java index 98850dbfbfb..c913764fc52 100644 --- a/sootup.java.bytecode/src/main/java/sootup/java/bytecode/inputlocation/DefaultRTJarAnalysisInputLocation.java +++ b/sootup.java.bytecode/src/main/java/sootup/java/bytecode/inputlocation/DefaultRTJarAnalysisInputLocation.java @@ -31,6 +31,9 @@ * Refers to the rt.jar from <=Java8 as an AnalysisInputLocation requires: JAVA_HOME to be set * and expects the jar in the "lib/" subdirectory. If you need to include the rt.jar from a custom * Location please make use of JavaClassPathAnalysisInputLocation. + * + *

Info: This only works if you are running java 8 or older. Otherwise use {@link + * JrtFileSystemAnalysisInputLocation}. */ public class DefaultRTJarAnalysisInputLocation extends ArchiveBasedAnalysisInputLocation { diff --git a/sootup.java.bytecode/src/main/java/sootup/java/bytecode/inputlocation/OTFCompileAnalysisInputLocation.java b/sootup.java.bytecode/src/main/java/sootup/java/bytecode/inputlocation/OTFCompileAnalysisInputLocation.java index 6bee2df6a38..c629fff6f11 100644 --- a/sootup.java.bytecode/src/main/java/sootup/java/bytecode/inputlocation/OTFCompileAnalysisInputLocation.java +++ b/sootup.java.bytecode/src/main/java/sootup/java/bytecode/inputlocation/OTFCompileAnalysisInputLocation.java @@ -108,7 +108,6 @@ public SourceType getSourceType() { @Nonnull @Override public List getBodyInterceptors() { - // hint: all referenced inputlocations have the same settings return inputLocation.getBodyInterceptors(); }