From 57082ed56dbe390202f287bdf3f733f42e57c116 Mon Sep 17 00:00:00 2001 From: "M.Schmidt" Date: Mon, 18 Dec 2023 14:59:51 +0100 Subject: [PATCH 01/12] trigger ci --- .github/workflows/gh-pages.yml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index cbe24ad0414..111ab5a21cd 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -34,15 +34,18 @@ concurrency: pages permissions: pages: write contents: write - pull-requests: write jobs: manage: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + fetch-tags: true + # to get tag information - - run: git fetch --prune --unshallow + #- run: git fetch --prune --unshallow - uses: actions/setup-python@v2 with: @@ -72,7 +75,7 @@ jobs: # on push to develop branch - keep a doc around for develop to show the current state - name: deploy doc in subdirectory if: github.event_name == 'push' - run: mike deploy develop + run: mike deploy develop --push # on PR events.. - name: deploy doc in subdirectory From a2a452dc1f05d9d32423b391d76aac260b72b085 Mon Sep 17 00:00:00 2001 From: "M.Schmidt" Date: Mon, 18 Dec 2023 15:18:44 +0100 Subject: [PATCH 02/12] test trigger ci --- .github/workflows/gh-pages.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 111ab5a21cd..61c29caf318 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -32,8 +32,7 @@ on: concurrency: pages permissions: - pages: write - contents: write + write-all # don't! jobs: manage: From 4535dd294e2fec3d0123a5465ba4f32f2f7284f9 Mon Sep 17 00:00:00 2001 From: "M.Schmidt" Date: Mon, 18 Dec 2023 15:23:44 +0100 Subject: [PATCH 03/12] test trigger ci --- .github/workflows/gh-pages.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 61c29caf318..27c55bf31c6 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -32,7 +32,10 @@ on: concurrency: pages permissions: - write-all # don't! + pages: write # to trigger a gh-pages build + deployments: write + contents: write # for creating files via mike/mkdocs + pull-requests: write # for commenting the link jobs: manage: From 2dcfd3811b70468e9af499f47c2c21b1d74e914d Mon Sep 17 00:00:00 2001 From: "M.Schmidt" Date: Mon, 18 Dec 2023 15:28:06 +0100 Subject: [PATCH 04/12] test trigger ci w/content change --- docs/tools.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/tools.md b/docs/tools.md index dc5e297e375..73b0bc776ff 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -1,4 +1,5 @@ # Who uses SootUp - [JimpleLsp](https://github.com/swissiety/JimpleLsp) +- [API_ASSIST](TODO://add_link_to_repo) - Maybe there is more to find via [Github Network Dependents](https://github.com/soot-oss/SootUp/network/dependents) - have a look at the individual modules. - Your tool is not on this list? Create a PR :-) \ No newline at end of file From a5f4a38f4c8b8b17e6a6bba8c8f9ddb6d6b314de Mon Sep 17 00:00:00 2001 From: "M.Schmidt" Date: Mon, 18 Dec 2023 16:30:03 +0100 Subject: [PATCH 05/12] update docs --- docs/tools.md | 2 +- mkdocs.yml | 9 ++++----- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/tools.md b/docs/tools.md index 73b0bc776ff..d11aa33b12f 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -1,5 +1,5 @@ # Who uses SootUp - [JimpleLsp](https://github.com/swissiety/JimpleLsp) -- [API_ASSIST](TODO://add_link_to_repo) +- [API_ASSIST](https://github.com/secure-software-engineering/API_ASSIST) - Maybe there is more to find via [Github Network Dependents](https://github.com/soot-oss/SootUp/network/dependents) - have a look at the individual modules. - Your tool is not on this list? Create a PR :-) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 68e7790d968..f95ae99b9ff 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,19 +5,18 @@ edit_uri: edit/develop/docs/ nav: - Home: index.md - - How to Start: - - Installation: installation.md - - Getting started: getting-started.md + - Installation: installation.md - General information: - Design Decisions: whatsnew.md + - Getting started: getting-started.md - Jimple: jimple.md - Call Graph Construction: call-graph-construction.md - Advanced Topics: advanced-topics.md + # - Writing Analyses: analyses.md - More information: - Javadoc: /SootUp/apidocs - FAQ: faq.md -# - Used by: tools.md -# - Analyses: analyses.md + - Used by: tools.md theme: palette: From b6641ee3c8faa92e94ae1aab7fe9d47300b691a8 Mon Sep 17 00:00:00 2001 From: "M.Schmidt" Date: Mon, 18 Dec 2023 16:38:03 +0100 Subject: [PATCH 06/12] add jitpack link to installation.md --- docs/installation.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/installation.md b/docs/installation.md index eeef216d977..2445de5a21e 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,4 +1,7 @@ # Installation +## Using the latest version on the develop branch +visit [SootUp on Jitpack.io](https://jitpack.io/#soot-oss/SootUp/develop-SNAPSHOT) for configuration options of your build tool. + ## Using the release SootUp is available in maven central, you can include it in your project as follows. From 37946f3c8369d3ec1238de9e247cab30f7a2e63b Mon Sep 17 00:00:00 2001 From: "M.Schmidt" Date: Mon, 18 Dec 2023 16:49:50 +0100 Subject: [PATCH 07/12] nothing changed, huh? --- .github/workflows/gh-pages.yml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 27c55bf31c6..7a8fc28c52e 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -44,10 +44,7 @@ jobs: - uses: actions/checkout@v3 with: fetch-depth: 0 - fetch-tags: true - - # to get tag information - #- run: git fetch --prune --unshallow + fetch-tags: true # to get tag information - uses: actions/setup-python@v2 with: @@ -82,7 +79,7 @@ jobs: # on PR events.. - name: deploy doc in subdirectory if: github.event_name == 'pull_request' - run: mike deploy ${{ env.DOC_VERSION_NAME }}_preview -t "PR Preview ${{ env.DOC_VERSION_NAME }}" && mike props ${{ env.DOC_VERSION_NAME }}_preview --set-string hidden=true --push + run: mike deploy ${{ env.DOC_VERSION_NAME }}_preview -t "PR Preview ${{ env.DOC_VERSION_NAME }}" --push && mike props ${{ env.DOC_VERSION_NAME }}_preview --set-string hidden=true --push - name: comment link to preview if: github.event_name == 'pull_request' && github.event.action != 'closed' From 3a693de3b1a1458570655afc730fd2faf6295dc4 Mon Sep 17 00:00:00 2001 From: "M.Schmidt" Date: Mon, 18 Dec 2023 17:24:51 +0100 Subject: [PATCH 08/12] restructure --- docs/advanced-topics.md | 164 +--------------------------------------- docs/write_analyses.md | 7 ++ mkdocs.yml | 26 +++++-- 3 files changed, 28 insertions(+), 169 deletions(-) create mode 100644 docs/write_analyses.md diff --git a/docs/advanced-topics.md b/docs/advanced-topics.md index 7126f4ad0fa..28e67ac89fc 100644 --- a/docs/advanced-topics.md +++ b/docs/advanced-topics.md @@ -1,166 +1,4 @@ -# Advanced Topics - -As a user of the SootUp framework, you can omit these topics which mostly explain how some of the concepts work internally. - -## Body Interceptors - -!!! info "Soot Equivalent" - - [BodyTransformer](https://github.com/soot-oss/soot/blob/develop/src/main/java/soot/BodyTransformer.java) - - -Almost in all use-cases you can simply *ignore* body interceptors. They are applied to each `Body` *by default* to create their rather normalized or leaner versions, e.g. -by eliminating unreachable code (`UnreachableCodeEliminator`), standardizing names of locals (`LocalNameStandardizer`), or removing empty switch statements (`EmptySwitchEliminator`) etc. - -Below, we show how these body interceptors work for the users who are interested in their internal workings. - -### LocalSplitter - -LocalSplitter is aBodyInterceptorthat attempts to identify and separate uses of a local variable (as definition) that are independent of each other by renaming local variables. - -Example 1: - -![LocalSplitter Example_1](./figures/LocalSplitter%20Example_1.png) - -As shown in the example above, the local variablel1is defined twice. It can be split up into two new local variables: l1#1 and l1#2 because the both definitions are independent of each other. - - - -Look for foldable navigation and tabs for showing old vs new - - -Example 2: - -![LocalSplitter Example_2](./figures/LocalSplitter%20Example_2.png) - -In the second example, the local variablel2is defined thrice. But it cannot be split up into three new local variables as in the first example, because its definitions in the if-branches are not independent of each other. Therefore, it can only be split up into two local variables as shown in the figure. - - - -### LocalPacker - -LocalPacker is aBodyInterceptorthat attempts to minimize the number of local variables which are used in body by reusing them, when it is possible. It corresponds to the inverse body transformation of LocalSplitter. Note: Every local variable's type should be assigned before running LocalPacker. - -Example: - -![LocalPacker Example](./figures/LocalPacker%20Example.png) - -In the given example above, the local variablesl1,l3are summarized to be one local variablel1, because they have the same type without interference with each other. Likewise, the local variablesl2,l4andl5are summarized to be another local variablel2. Although the local variablel0doesn't interfere any other local variables, it cannot be summed up with other local variables because of its distinctive type. - - - -### TrapTightener - -TrapTightener is aBodyInterceptorthat shrinks the protected area covered by each Trap in a Body. - -Example: - -![TrapTightener Example](./figures/TrapTightener%20Example.png) - -We assume in the example above that only theStmt:l2 := 2might throw an exception caught by theTrapwhich is labeled withlabel3. In the jimple body before running the TrapTightener, the protected area covered by the Trap contains threeStmts:l1 := 1; l2 := 2; l2 := 3. But an exception could only arise at theStmt:l2 := 2. After the implementation of TrapTightener, we will get a contractible protected area which contains only theStmtthat might throw an exception, namely theStmt:l2 := 2. - - - -### EmptySwitchEliminator - -EmptySwitchEliminator is aBodyInterceptorthat removes empty switch statements which contain only the default case. - -Example: - -![EmptySwitchEliminator Example](./figures/EmptySwitchEliminator%20Example.png) - -As shown in the example above, the switch statement in the jimple body always takes the default action. After running EmptySwitchEliminator, the switch statement is replaced with aGotoStmtto the default case. - - - -### UnreachableCodeEliminator - -UnreachableCodeEliminator is aBodyInterceptorthat removes all unreachable statements. - -Example: - -![UnreachableCodeEliminator Example](./figures/UnreachableCodeEliminator%20Example.png) - -Obviously, the code segmentl2 = 2; l3 = 3;is unreachable. It will be removed after running the UreachableCodeEliminator. - - - -### CopyPropagator - -CopyPropagator is aBodyInterceptorthat supports the global copy propagation and constant propagation. - -Example for global copy propagation: - -![UnreachableCodeEliminator Example](./figures/CopyPropagator%20Example_1.png) - -Consider a code segment in the following form: - -``` -a = b; -... -c = use(a); // a, b, c are local variables -``` - -According to the copy propagation's definition, the statementc = use(a)can be replaced withc = use(b)iff both conditions are met: - -* ais defined only one time on all the paths froma = btoc = use(a). -* There are no definitions ofbon any path froma = btoc = use(a). - -In the example for global copy propagation, the first usedl1is replaced withl0, but the second usedl1cannot be replaced withl3, because the second condition is not satisfied. - -Example for constant propagation: - -![CopyPropagator Example_1](figures/CopyPropagator%20Example_2.png) - -Constant propagation is similar to copy propagation. Consider a code segment in the following form: - -``` -a = const; -... -b = use(a); // a, b are local variables, const is a constant -``` - -After perfoming the constant propagation, the statementb = use(a)can be replaced withb = use(const)iffais not redefined on any of the paths froma = consttob = use(a). - -Therefore, the first usedl1in the second example can be replaced with the constant1, but the second usedl1cannot be replaced with the constant2, becausel1is redefined on the path froml1 = 2tol4 = use(l1). However, it can be replaced with local variablel2, because the both conditions of copy propagation are met. - -### LocalNameStandardizer - -LocalNameStandardizer is aBodyInterceptorthat assigns a generic name to each local variable. Firstly, it will sort the local variables' order alphabetically by the string representation of their type. If there are two local variables with the same type, then the LocalNameStandardizer will use the sequence of their occurrence in jimple body to determine their order. Each assigned name consists of two parts: - -* A letter to imply the local variable's type -* A digit to imply the local variable's order - -The following table shows the letter corresponding to each type: - -| Type of Local Variable | Letter | -| :---------------: | :---------: | -| boolean | z | -| byte | b | -| short | s | -| int | i | -| long | l | -| float | f | -| double | d | -| char | c | -| null | n | -| unknown | e | -| reference | r | - - -### StaticSingleAssignmentFormer - -StaticSingleAssignmentFormer is aBodyInterceptorthat transforms jimple body into SSA form, so that each local variable is assigned exactly once and defined before its first use. - -Example: - -![SSA Example_1](./figures/SSA%20Example_1.png) - -![SSA Example_2](./figures/SSA%20Example_2.png) - -In the given example, the StaticSingleAssignmentFormer assigns eachIdentityStmtandAssignStmtto a new local variable . And each use uses the local variable which is most recently defined. Sometimes, it is impossible to determine the most recently defined local variable for a use in a join block. In this case, the StaticSingleAssignmentFormer will insert aPhiStmtin the front of the join block to merge all most recently defined local variables and assign them a new local variable. - -## Tools +# Functionalities and Utilities #### LocalLivenessAnalyser diff --git a/docs/write_analyses.md b/docs/write_analyses.md new file mode 100644 index 00000000000..7ee09b1b10e --- /dev/null +++ b/docs/write_analyses.md @@ -0,0 +1,7 @@ +# Writing Analyses + +``` +// TODO improve tutorial! +``` + +If you wish to implement an interprocedural data-flow analysis via the IFDS or IDE Framework please have a look at the test cases in the sootup.analysis submodule. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index f95ae99b9ff..c3fa896d920 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,18 +5,32 @@ edit_uri: edit/develop/docs/ nav: - Home: index.md - - Installation: installation.md - - General information: + - Announcements: announce.md + - Used by: tools.md + + - Getting started: + - Installation: installation.md + + - Basics: - Design Decisions: whatsnew.md - Getting started: getting-started.md - Jimple: jimple.md + + - Advanced Topics: + - BodyInterceptors: bodyinterceptors.md - Call Graph Construction: call-graph-construction.md - - Advanced Topics: advanced-topics.md - # - Writing Analyses: analyses.md + - SootUp Utilities: advanced-topics.md + + - How to..: + - Write an Analysis: write_analyses.md + # - Modify a StmtGraph: mutable_stmtgraph.md + # - Modify a View: mutable_view.md + # - Implement a BodyInterceptor: body_interceptor.md + # - Implement an AnalysisTool: write_analysis_tool.md + - More information: - Javadoc: /SootUp/apidocs - - FAQ: faq.md - - Used by: tools.md + - Troubleshooting & FAQ: faq.md theme: palette: From 160a4caaebd7b84f80ccbe2199e34e81a80c867f Mon Sep 17 00:00:00 2001 From: "M.Schmidt" Date: Mon, 18 Dec 2023 18:01:36 +0100 Subject: [PATCH 09/12] restructure & improve texts --- README.md | 12 ++++++------ docs/index.md | 18 ++++++++---------- docs/whatsnew.md | 3 ++- mkdocs.yml | 19 +++++++++---------- 4 files changed, 25 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 6ef3e76bdec..d4845b0ad69 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,8 @@ A complete overhaul of the good, old static analysis framework [Soot](https://gi - Provides ClassHierarchy generation - CallGraph generation with different algorithms/precisions - Inter-procedural Data-flow Analysis with the IDE/IFDS framework enabled by [Heros](https://github.com/Sable/heros) -- Applies/Enables simple transformations on retrieving a methods Body (see BodyInterceptor) -- Provides serialization of the Jimple IR. +- Applies simple transformations on retrieving a methods Body (see `BodyInterceptor`) +- Provides parsing and serialization of the Jimple IR. ## Getting started [Documentation](https://soot-oss.github.io/SootUp/) and usage examples are available on Github pages. @@ -23,13 +23,13 @@ Do you have questions? Feel free to start a [Discussion](https://github.com/soot ## SootUp improvements #### (compared to its predecessor [Soot](https://github.com/soot-oss/soot).) -- [x] New Improved API (without Globals/Singletons) +- [x] New improved API (without Globals/Singletons) - [x] Fully-Parallelizable Architecture -- [x] Enables lazyloading of classes (no interleaved loading of used/dependent classes anymore) +- [x] Enables lazy loading of classes (no interleaved loading of used/dependent classes anymore) - [x] Fail early strategy - input validation while constructing/building objects -- [x] Up-to-Date (i.e. Java8!) Sourcecode Frontend +- [x] Up-to-Date (i.e. Java8!) Sourcecode Frontend (Beware: Can not handle try-catch inputs, yet!) - [x] Full Java 21 Support for Bytecode -- [x] Multiple Views (Scenes) +- [x] Multiple Views (no single static Scene anymore) - [x] Immutable Jimple IR Objects and Graphs - [ ] Incremental Updates of Program Representation diff --git a/docs/index.md b/docs/index.md index dd9d9df0d9c..cd61f29e954 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,21 +1,22 @@ # What's SootUp? SootUp is a complete overhaul of the good, old static analysis framework [Soot](https://github.com/soot-oss/soot). -- Transforms JVM bytecode (and other inputs!) to the intermediate representation Jimple. +- Transforms JVM bytecode to the intermediate representation Jimple. - Provides ClassHierarchy generation - CallGraph generation with different algorithms/precisions -- Inter-procedural Data-flow Analysis with the IDE/IFDS framework enabled by [Heros](https://github.com/Sable/heros) -- Applies/Enables simple transformations on retrieving a methods Body (see BodyInterceptor) +- Inter-procedural data-flow analysis with the IDE/IFDS framework enabled by [Heros](https://github.com/Sable/heros) +- Applies simple transformations on retrieving a methods Body (see BodyInterceptor) - Provides serialization of the Jimple IR. !!! important - SootUp is *not a version update* to Soot, it is instead a *completely new implementation* written from scratch that aims to be a leaner, more extensible equivalent of soot. + SootUp is *not a version update* to Soot, it is a *completely new implementation* written from scratch that aims to be a leaner, modernized and developer friendly successor of Soot. + It is not a Drop-In Replacement! The new architecture and API, renders it not trivial to update existing projects that were built on soot. + Therefore we recommend using SootUp for greenfield projects. We hope improved type safety and streamlined mechanisms will aide you implementing and debugging your analysis tool. + Unfortunately not every feature has been ported - If you miss something feel free to [contribute](https://github.com/soot-oss/SootUp/pulls) a feature you miss from good old Soot. -## Why SootUp? -#### [Click here to read our announcement on the first release of SootUp](announce.md) - +## Why SootUp? Over the 20+ years, SootUps predecessor Soot has evolved into a powerful framework, which is one of the most widely used tools in the static analysis community. This evolution was guided by the needs of the community and carried out with ad-hoc improvements. As a result, Soot has become a tool that can do a multitude of things, but it is heavy and hard to maintain and comprehend. @@ -26,9 +27,6 @@ removing the necessity of arcane knowledge, document it more and more - to make So we introduced [Design changes in SootUp](whatsnew.md), which aim to address Soot's shortcomings. The goal is a lighter library that can easily be understood and maintained to be included in other projects. -### Is this a drop-in replacement for Soot? -Not really. SootUp has a completely new architecture and API, so it is not trivial to update existing projects that build on soot. We recommend using SootUp for greenfield projects. - ## Supporters The development of SootUp is financed by generous support from the German Research Foundation (DFG) and diff --git a/docs/whatsnew.md b/docs/whatsnew.md index a54665ea15e..1665d2fa6e2 100644 --- a/docs/whatsnew.md +++ b/docs/whatsnew.md @@ -13,7 +13,8 @@ SootUp has a modular architecture, which enables its clients to include only the - [core module](https://github.com/soot-oss/SootUp/tree/develop/sootup.core) contains the core building blocks such as the jimple IR, control flow graphs, and frontend interfaces. The rest of the modules build on the core module. - [java.core module](https://github.com/soot-oss/SootUp/tree/develop/sootup.java.core) contains parts that are essential for analyzing Java code. - [java.bytecode module](https://github.com/soot-oss/SootUp/tree/develop/sootup.java.bytecode) contains the functionality that is necessary for taking as input java bytecode. -- [java.sourcecode module](https://github.com/soot-oss/SootUp/tree/develop/sootup.java.sourcecode) contains the functionality that is necessary for taking as input java source code. +- [java.sourcecode module](https://github.com/soot-oss/SootUp/tree/develop/sootup.java.sourcecode) contains the functionality that is necessary for taking as input java source code. +**Beware: The sourcecodefrontend is currently unable to handle inputs with exceptions (try/catch/finally)!** - [callgraph module](https://github.com/soot-oss/SootUp/tree/develop/sootup.callgraph) contains implementations of common call graph construction algorithms such as **CHA**, **RTA**. A reimplementation of **Spark** pointer analysis framework is in progress. - [jimple.parser module](https://github.com/soot-oss/SootUp/tree/develop/sootup.jimple.parser) contains the functionalty that is necessary for taking as input .jimple files. - [analysis module](https://github.com/soot-oss/SootUp/tree/develop/sootup.analysis) enables performing interprocedural dataflow analyses. diff --git a/mkdocs.yml b/mkdocs.yml index c3fa896d920..17430b0df4a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,13 +6,12 @@ edit_uri: edit/develop/docs/ nav: - Home: index.md - Announcements: announce.md + - Design Decisions: whatsnew.md - Used by: tools.md - - Getting started: - - Installation: installation.md - - Basics: - - Design Decisions: whatsnew.md + - Installation: installation.md +# - Configure your Input: analysisinputlocations.md - Getting started: getting-started.md - Jimple: jimple.md @@ -21,12 +20,12 @@ nav: - Call Graph Construction: call-graph-construction.md - SootUp Utilities: advanced-topics.md - - How to..: - - Write an Analysis: write_analyses.md - # - Modify a StmtGraph: mutable_stmtgraph.md - # - Modify a View: mutable_view.md - # - Implement a BodyInterceptor: body_interceptor.md - # - Implement an AnalysisTool: write_analysis_tool.md + - How to..: + - Write an Analysis: write_analyses.md + # - Modify a StmtGraph: mutable_stmtgraph.md + # - Modify a View: mutable_view.md + # - Implement a BodyInterceptor: body_interceptor.md + # - Implement an AnalysisTool: write_analysis_tool.md - More information: - Javadoc: /SootUp/apidocs From bd477009e4f4a535c5efbcde182c9a7579f69268 Mon Sep 17 00:00:00 2001 From: "M.Schmidt" Date: Mon, 18 Dec 2023 18:06:19 +0100 Subject: [PATCH 10/12] typo --- docs/bodyinterceptors.md | 158 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/bodyinterceptors.md diff --git a/docs/bodyinterceptors.md b/docs/bodyinterceptors.md new file mode 100644 index 00000000000..dbf482e24a7 --- /dev/null +++ b/docs/bodyinterceptors.md @@ -0,0 +1,158 @@ +# Body Interceptors + +!!! info "Soot Equivalent" + + [BodyTransformer](https://github.com/soot-oss/soot/blob/develop/src/main/java/soot/BodyTransformer.java) + + +BodyInterceptors are applied to each `Body` *by default* to improve or even normalize the raw Jimple that was produced in an earlier step e.g. +by eliminating unreachable code (`UnreachableCodeEliminator`), standardizing names of locals (`LocalNameStandardizer`), or removing empty switch statements (`EmptySwitchEliminator`) etc. + +Below, we show how these BodyInterceptors work for the users who are interested in their internal workings. + +### LocalSplitter + +LocalSplitter is aBodyInterceptorthat attempts to identify and separate uses of a local variable (as definition) that are independent of each other by renaming local variables. + +Example 1: + +![LocalSplitter Example_1](./figures/LocalSplitter%20Example_1.png) + +As shown in the example above, the local variablel1is defined twice. It can be split up into two new local variables: l1#1 and l1#2 because the both definitions are independent of each other. + + + +Look for foldable navigation and tabs for showing old vs new + + +Example 2: + +![LocalSplitter Example_2](./figures/LocalSplitter%20Example_2.png) + +In the second example, the local variablel2is defined thrice. But it cannot be split up into three new local variables as in the first example, because its definitions in the if-branches are not independent of each other. Therefore, it can only be split up into two local variables as shown in the figure. + + + +### LocalPacker + +LocalPacker is aBodyInterceptorthat attempts to minimize the number of local variables which are used in body by reusing them, when it is possible. It corresponds to the inverse body transformation of LocalSplitter. Note: Every local variable's type should be assigned before running LocalPacker. + +Example: + +![LocalPacker Example](./figures/LocalPacker%20Example.png) + +In the given example above, the local variablesl1,l3are summarized to be one local variablel1, because they have the same type without interference with each other. Likewise, the local variablesl2,l4andl5are summarized to be another local variablel2. Although the local variablel0doesn't interfere any other local variables, it cannot be summed up with other local variables because of its distinctive type. + + + +### TrapTightener +**WIP - currently not available!** + +TrapTightener is aBodyInterceptorthat shrinks the protected area covered by each Trap in a Body. + +Example: + +![TrapTightener Example](./figures/TrapTightener%20Example.png) + +We assume in the example above that only theStmt:l2 := 2might throw an exception caught by theTrapwhich is labeled withlabel3. In the jimple body before running the TrapTightener, the protected area covered by the Trap contains threeStmts:l1 := 1; l2 := 2; l2 := 3. But an exception could only arise at theStmt:l2 := 2. After the implementation of TrapTightener, we will get a contractible protected area which contains only theStmtthat might throw an exception, namely theStmt:l2 := 2. + + + +### EmptySwitchEliminator + +EmptySwitchEliminator is aBodyInterceptorthat removes empty switch statements which contain only the default case. + +Example: + +![EmptySwitchEliminator Example](./figures/EmptySwitchEliminator%20Example.png) + +As shown in the example above, the switch statement in the jimple body always takes the default action. After running EmptySwitchEliminator, the switch statement is replaced with aGotoStmtto the default case. + + + +### UnreachableCodeEliminator + +UnreachableCodeEliminator is aBodyInterceptorthat removes all unreachable statements. + +Example: + +![UnreachableCodeEliminator Example](./figures/UnreachableCodeEliminator%20Example.png) + +Obviously, the code segmentl2 = 2; l3 = 3;is unreachable. It will be removed after running the UreachableCodeEliminator. + + + +### CopyPropagator + +CopyPropagator is aBodyInterceptorthat supports the global copy propagation and constant propagation. + +Example for global copy propagation: + +![UnreachableCodeEliminator Example](./figures/CopyPropagator%20Example_1.png) + +Consider a code segment in the following form: + +``` +a = b; +... +c = use(a); // a, b, c are local variables +``` + +According to the copy propagation's definition, the statementc = use(a)can be replaced withc = use(b)iff both conditions are met: + +* ais defined only one time on all the paths froma = btoc = use(a). +* There are no definitions ofbon any path froma = btoc = use(a). + +In the example for global copy propagation, the first usedl1is replaced withl0, but the second usedl1cannot be replaced withl3, because the second condition is not satisfied. + +Example for constant propagation: + +![CopyPropagator Example_1](figures/CopyPropagator%20Example_2.png) + +Constant propagation is similar to copy propagation. Consider a code segment in the following form: + +``` +a = const; +... +b = use(a); // a, b are local variables, const is a constant +``` + +After perfoming the constant propagation, the statementb = use(a)can be replaced withb = use(const)iffais not redefined on any of the paths froma = consttob = use(a). + +Therefore, the first usedl1in the second example can be replaced with the constant1, but the second usedl1cannot be replaced with the constant2, becausel1is redefined on the path froml1 = 2tol4 = use(l1). However, it can be replaced with local variablel2, because the both conditions of copy propagation are met. + +### LocalNameStandardizer + +LocalNameStandardizer is aBodyInterceptorthat assigns a generic name to each local variable. Firstly, it will sort the local variables' order alphabetically by the string representation of their type. If there are two local variables with the same type, then the LocalNameStandardizer will use the sequence of their occurrence in jimple body to determine their order. Each assigned name consists of two parts: + +* A letter to imply the local variable's type +* A digit to imply the local variable's order + +The following table shows the letter corresponding to each type: + +| Type of Local Variable | Letter | +| :---------------: | :---------: | +| boolean | z | +| byte | b | +| short | s | +| int | i | +| long | l | +| float | f | +| double | d | +| char | c | +| null | n | +| unknown | e | +| reference | r | + + +### StaticSingleAssignmentFormer + +StaticSingleAssignmentFormer is aBodyInterceptorthat transforms jimple body into SSA form, so that each local variable is assigned exactly once and defined before its first use. + +Example: + +![SSA Example_1](./figures/SSA%20Example_1.png) + +![SSA Example_2](./figures/SSA%20Example_2.png) + +In the given example, the StaticSingleAssignmentFormer assigns eachIdentityStmtandAssignStmtto a new local variable . And each use uses the local variable which is most recently defined. Sometimes, it is impossible to determine the most recently defined local variable for a use in a join block. In this case, the StaticSingleAssignmentFormer will insert aPhiStmtin the front of the join block to merge all most recently defined local variables and assign them a new local variable. \ No newline at end of file From b9ce265d24c61d2fb7de0196ec755ac1e39b112e Mon Sep 17 00:00:00 2001 From: "M.Schmidt" Date: Mon, 18 Dec 2023 18:30:33 +0100 Subject: [PATCH 11/12] hide tools section --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 17430b0df4a..baf4d12f4bf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,7 +7,6 @@ nav: - Home: index.md - Announcements: announce.md - Design Decisions: whatsnew.md - - Used by: tools.md - Basics: - Installation: installation.md @@ -30,6 +29,7 @@ nav: - More information: - Javadoc: /SootUp/apidocs - Troubleshooting & FAQ: faq.md + # - Based on SootUp: tools.md theme: palette: From f887d6188703eb7df4f2881e7d98ab9fd849769e Mon Sep 17 00:00:00 2001 From: Stefan Schott <64211065+stschott@users.noreply.github.com> Date: Tue, 19 Dec 2023 09:51:02 +0100 Subject: [PATCH 12/12] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d4845b0ad69..57d8584baec 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Do you have questions? Feel free to start a [Discussion](https://github.com/soot - [x] Fully-Parallelizable Architecture - [x] Enables lazy loading of classes (no interleaved loading of used/dependent classes anymore) - [x] Fail early strategy - input validation while constructing/building objects -- [x] Up-to-Date (i.e. Java8!) Sourcecode Frontend (Beware: Can not handle try-catch inputs, yet!) +- [x] Up-to-Date (i.e. Java8!) Sourcecode Frontend (Beware: Cannot handle try-catch inputs, yet!) - [x] Full Java 21 Support for Bytecode - [x] Multiple Views (no single static Scene anymore) - [x] Immutable Jimple IR Objects and Graphs