|
1 | | -# Tai-e: An Easy-to-Learn/Use Static Analysis Framework for Java |
| 1 | +<div align="center"> |
| 2 | + <a href="https://tai-e.pascal-lab.net/"> |
| 3 | + <img src="https://cs.nju.edu.cn/tiantan/img/tai-e.png" height="200"> |
| 4 | + </a> |
2 | 5 |
|
3 | | -## Description |
4 | | -Tai-e is an easy-to-learn, easy-to-use, efficient and extensible static analysis framework for Java. |
| 6 | +## Tai-e |
| 7 | +</div> |
5 | 8 |
|
6 | | ---- |
7 | | -## How to Run Tai-e? |
| 9 | +## What is Tai-e? |
8 | 10 |
|
9 | | -### Prerequisites |
10 | | -Before running Tai-e, please finish following steps: |
| 11 | +Tai-e (Chinese: 太阿; pronunciation: [ˈtaɪə:]) is a new static analysis framework for Java (please see [our technique report](http://cs.nju.edu.cn/tiantan/taie.pdf) for details), which features arguably the "best" designs from both the novel ones we proposed and those of classic frameworks such as Soot, WALA, Doop, and SpotBugs. Tai-e is easy-to-learn, easy-to-use, and highly extensible, allowing you to easily develop new analyses on top of it. |
11 | 12 |
|
12 | | -- Install **Java 17** on your system (Tai-e is developed in pure Java, and it runs on all major operating systems including Windows/Linux/MacOS). |
13 | | -- Clone submodule `java-benchmarks` (it contains the Java libraries used by the analysis): |
14 | | -``` |
15 | | - git submodule update --init --recursive |
16 | | -``` |
| 13 | +Currently, Tai-e provides the following major analysis components (and more analyses are on the way): |
| 14 | +- Powerful pointer analysis framework |
| 15 | + - On-the-fly call graph construction |
| 16 | + - Various classic and advanced heap abstraction and context sensitivity for pointer analysis |
| 17 | + - Extensible analysis plugin system (allows to conveniently develop and add new analyses that interact with pointer analysis) |
| 18 | +- Various fundamental/client/utility analyses |
| 19 | + - Fundamental analyses, e.g., reflection analysis and exception analysis |
| 20 | + - Modern language feature analyses, e.g., lambda and method reference analysis, and invokedynamic analysis |
| 21 | + - Clients, e.g., configurable taint analysis (allowing to configure sources, sinks and taint transfers) |
| 22 | + - Utility tools like analysis timer, constraint checker (for debugging), and various graph dumpers |
| 23 | +- Control/Data-flow analysis framework |
| 24 | + - Control-flow graph construction |
| 25 | + - Classic data-flow analyses, e.g., live variable analysis, constant propagation |
| 26 | + - Your data-flow analyses |
| 27 | +- SpotBugs-like bug detection system |
| 28 | + - Bug detectors, e.g., null pointer detector, incorrect `clone()` detector |
| 29 | + - Your bug detectors |
17 | 30 |
|
18 | | ---- |
19 | | -The main class (entry) of Tai-e is `pascal.taie.Main`. Below we introduce its main options. |
| 31 | +Tai-e is developed in Java, and it can run on major operating systems including Windows, Linux, and macOS. |
20 | 32 |
|
21 | | -### Program Options |
22 | | -These options specify the program (say *P*) and Java library to be analyzed. |
23 | 33 |
|
24 | | -#### Class paths (-cp, --class-path): `-cp <path>;<path>;...` |
25 | | -Class paths for Tai-e to locate the classes of *P*. Currently, Tai-e supports following types of paths: |
| 34 | +## How to Obtain Runnable Jar of Tai-e? |
26 | 35 |
|
27 | | -- relative/absolute path to a jar file |
28 | | -- relative/absolute path to a directory which contains `.class` files |
| 36 | +The simplest way is to download it from [GitHub Releases](https://github.com/pascal-lab/Tai-e/releases). |
29 | 37 |
|
30 | | -Multiple paths are separated by path separator. Note that the path separator varies on different systems: it is `;` on Windows, and `:` on Unix-like systems. |
| 38 | +Alternatively, you might build Tai-e yourself from the source code. This can be simply done via Gradle (be sure that Java 17 (or higher version) is available on your system). You just need to run command `gradlew fatJar`, and then the runnable jar will be generated in `tai-e/build/`, which includes Tai-e and all its dependencies. |
31 | 39 |
|
32 | | -#### Main class (-m, --main-class): `-m <main-class>` |
33 | | -The main class (entry) of *P*. This class must declare a method with signature `public static void main(String[])`. |
34 | 40 |
|
35 | | -#### Java version (-java): `-java <version>` |
36 | | -Specify the version of Java library used in the analyses. When this option is given, Tai-e will locate the corresponding Java library in submodule `java-benchmarks` and add it to the class paths. Currently, we provide libraries for Java version 3, 4, 5, 6, 7, 8. |
| 41 | +## Documentation |
37 | 42 |
|
38 | | -#### Prepend JVM Class Path (-pp, --prepend-JVM) |
39 | | -Prepend the class path of the JVM (which runs Tai-e) to the analysis class path. This option will disable `-java` option, i.e., when `-pp` is enabled, Tai-e always analyzes the Java library of the JVM, no matter what `-java` is. |
| 43 | +We are hosting the documentation of Tai-e on [the GitHub wiki](https://github.com/pascal-lab/Tai-e/wiki), where you could find more information about Tai-e such as [Setup in IntelliJ IDEA](https://github.com/pascal-lab/Tai-e/wiki/Setup-Tai%E2%80%90e-in-IntelliJ-IDEA), [Command-Line Options](TODO:link), and [Development of New Analysis](TODO:link). |
40 | 44 |
|
41 | | -### Analysis Options |
42 | | -These options specify the analyses to be executed by Tai-e. To execute an analysis, you need to specify its *id* and *options* (if necessary). All available analyses in Tai-e and their information (e.g., *id* and available *options*) are listed in [the analysis configuration file](src/main/resources/tai-e-analyses.yml). |
43 | 45 |
|
44 | | -There are two mutually-exclusive approaches to specify the analyses, by options or by file, as described below. |
| 46 | +## Tai-e Assignments |
45 | 47 |
|
46 | | -#### Analyses (-a, --analysis): `-a <id>[=<key>:<value>;...]` |
47 | | -Specify analyses by options. If you need to run an analysis `A`, just use `-a A`. If you need to specify some analysis options for `A`, just append them to analysis id (connected by `=`), and separate them by `;`, for example: |
48 | | -``` |
49 | | --a A=enableX:true;threshold:100;log-level:info |
50 | | -``` |
51 | | -The option system is flexible, and it supports various types of option values, such as boolean, integer, and string. |
52 | | - |
53 | | -Option `-a` is repeatable, so that if you need to execute multiple analyses in one run of Tai-e, for example, analysis `A2` requires the result of analysis `A1`, just repeat `-a` like: `-a A1 -a A2`. |
54 | | - |
55 | | -#### Plan file (-p, --plan-file): `-p <file-path>` |
56 | | -Specify analyses by file. You can specify the analyses to be executed (called an analysis plan) in a plan file, and use `-p` to process the file. Similar to `-a`, you need to specify the *id* and *options* (if necessary) for each analysis in the file. The plan file should be written in YAML. |
57 | | - |
58 | | -Note that options `-a` and `-p` are mutually-exclusive, thus you *cannot* specify them simultaneously. |
59 | | - |
60 | | -(*TODO: elaborate more details about analysis system*) |
61 | | - |
62 | | -### Other Options |
63 | | -#### Help (-h, --help) |
64 | | -Print help information for all available options. This option will disable all other options, i.e., when it is enabled, Tai-e ignores other given options. |
65 | | - |
66 | | -#### Options file (--options-file): `--options-file <file-path>` |
67 | | -You can specify the options in a options file and use `--options-file` to process the file. When this option is given, Tai-e ignores all other command-line options, and only processes the options in the file. The options file should be written in YAML. |
68 | | - |
69 | | -### Putting It Together |
70 | | -We give an example of how to analyze a program by Tai-e. Suppose we want to analyze a program *P* as described below: |
71 | | - |
72 | | -- *P* consists of two jar files: `foo.jar` and `bar.jar` |
73 | | -- *P*'s main class is `baz.Main` |
74 | | -- *P* is analyzed together with Java 8 |
75 | | -- we run 2-object-sensitive pointer analysis and merge all string constants in *P* |
76 | | -- we run Tai-e on Windows |
77 | | - |
78 | | -Then the options would be: |
79 | | -``` |
80 | | -java pascal.taie.Main -cp foo.jar;bar.jar -m baz.Main -java 8 -a pta=cs:2-obj;merge-string-constants:true |
81 | | -``` |
82 | | -(for simplicity, we omit the Java options for Tai-e) |
83 | | - |
84 | | ---- |
85 | | -## How to Develop New Analyses Based on Tai-e? |
86 | | - |
87 | | -Please refer to [development guide](docs/development-guide.md). |
| 48 | +In addition, we have developed an [educational version of Tai-e](http://tai-e.pascal-lab.net/en/intro/overview.html) where eight programming assignments are carefully designed for systematically training learners to implement various static analysis techniques to analyze real Java programs. The educational version shares a large amount of code with Tai-e, thus doing the assignments would be a good way to get familiar with Tai-e. |
0 commit comments