Skip to content

Commit 45c0db5

Browse files
ShuMengZhang00ShuMengZhang00
committed
add a README for NullPath
1 parent 769aab2 commit 45c0db5

File tree

1 file changed

+55
-137
lines changed

1 file changed

+55
-137
lines changed

‎README.md‎

Lines changed: 55 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,153 +1,71 @@
1-
<div align="center">
2-
<img src="tai-e-logo.png" height="200">
3-
4-
# Tai-e
5-
6-
[![test](https://github.com/pascal-lab/Tai-e/actions/workflows/test.yml/badge.svg)](https://github.com/pascal-lab/Tai-e/actions/workflows/test.yml)
7-
[![java](https://img.shields.io/badge/Java-17-informational)](https://openjdk.java.net/)
8-
[![maven-central](https://img.shields.io/badge/dynamic/xml.svg?label=maven-central&color=f1834d&query=//metadata/versioning/latest&url=https://repo1.maven.org/maven2/net/pascal-lab/tai-e/maven-metadata.xml)](https://search.maven.org/artifact/net.pascal-lab/tai-e)
9-
[![codecov](https://codecov.io/gh/pascal-lab/Tai-e/branch/master/graph/badge.svg)](https://codecov.io/gh/pascal-lab/Tai-e)
10-
[![DOI](https://img.shields.io/badge/DOI-10.1145/3597926.3598120-blue)](https://doi.org/10.1145/3597926.3598120)
11-
</div>
12-
13-
## Table of Contents
14-
15-
- [What is Tai-e?](#what-is-tai-e)
16-
- [How to Obtain Runnable Jar of Tai-e?](#how-to-obtain-runnable-jar-of-tai-e)
17-
- [How to Include Tai-e in Your Project?](#how-to-include-tai-e-in-your-project)
18-
- [Stable Version](#stable-version)
19-
- [Latest Version](#latest-version)
20-
- [Documentation](#documentation)
21-
- [Reference Documentation](#reference-documentation)
22-
- [Changelog](#changelog)
23-
- [Tai-e Assignments](#tai-e-assignments)
24-
25-
## What is Tai-e?
26-
27-
Tai-e (Chinese: 太阿; pronunciation: [ˈtaɪə:]) is a new static analysis framework for Java (please see our [ISSTA 2023 paper](https://cs.nju.edu.cn/tiantan/papers/issta2023.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.
28-
Tai-e is easy-to-learn, easy-to-use, efficient, and highly extensible, allowing you to easily develop new analyses on top of it.
29-
30-
Currently, Tai-e provides the following major analysis components (and more analyses are on the
31-
way):
32-
33-
- Powerful pointer analysis framework
34-
- On-the-fly call graph construction
35-
- Various classic and advanced techniques of heap abstraction and context sensitivity for pointer analysis
36-
- Extensible analysis plugin system (allows to conveniently develop and add new analyses that interact with pointer analysis)
37-
- Configurable security analysis
38-
- Taint analysis, which allows to configure sources, sinks, taint transfers, and sanitizers
39-
- Detection of various information leakages and injection vulnerabilities
40-
- Various precision and efficiency tradeoffs (benefit from the pointer analysis framework)
41-
- Various fundamental/utility analyses
42-
- Fundamental analyses, e.g., reflection analysis and exception analysis
43-
- Modern language feature analyses, e.g., lambda and method reference analysis, and invokedynamic analysis
44-
- Utility tools like analysis timer, constraint checker (for debugging), and various graph dumpers
45-
- Control/Data-flow analysis framework
46-
- Control-flow graph construction
47-
- Classic data-flow analyses, e.g., live variable analysis, constant propagation
48-
- Your data-flow analyses
49-
- SpotBugs-like bug detection system
50-
- Bug detectors, e.g., null pointer detector, incorrect `clone()` detector
51-
- Your bug detectors
52-
53-
Tai-e is developed in Java, and it can run on major operating systems including Windows, Linux, and macOS.
54-
55-
As a courtesy to the developers, we expect that you **please [cite](CITATION.bib) the paper** from ISSTA 2023 describing the Tai-e framework in your research work:
56-
57-
Tian Tan and Yue Li. 2023.
58-
**Tai-e: A Developer-Friendly Static Analysis Framework for Java by Harnessing the Good Designs of Classics.**
59-
In Proceedings of the 32nd ACM SIGSOFT International Symposium on Software Testing and Analysis (ISSTA '23), July 17–21, 2023, Seattle, WA, USA ([pdf](https://cs.nju.edu.cn/tiantan/papers/issta2023.pdf), [bibtex](CITATION.bib)).
60-
61-
## How to Obtain Runnable Jar of Tai-e?
62-
The simplest way is to download it from [GitHub Releases](https://github.com/pascal-lab/Tai-e/releases).
63-
64-
Alternatively, you might build the latest Tai-e yourself from the source code. This can be simply accomplished via Gradle (be sure that Java 17 (or higher version) is available on your system).
65-
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.
66-
67-
## How to Include Tai-e in Your Project?
68-
Tai-e is designed as a standalone tool, but you also have the option to include it in your project as a dependency.
69-
It is available on Maven repositories, allowing you to easily integrate it into your Java projects using build tools such as Gradle and Maven.
70-
We maintain both stable and latest versions of Tai-e, and here are the corresponding coordinates in Gradle and Maven script formats:
71-
72-
### Stable Version
73-
For Gradle:
74-
75-
```kotlin
76-
dependencies {
77-
implementation("net.pascal-lab:tai-e:0.2.2")
78-
}
79-
```
1+
# NullPath
802

81-
For Maven:
3+
NullPath is a static analysis tool for Java designed to detect NullPointerException (NPE) issues. It leverages the [Tai-e static analysis framework](https://github.com/pascal-lab/Tai-e) to perform a deep and precise analysis of Java bytecode or source code. Compared to existing approaches, NullPath can efficiently discover much more NPE bugs while maintaining a reasonable precision. Statically finding NPEs is valuable because it helps prevent runtime errors, improves application reliability, and enhances overall software quality by identifying potential crashes before they occur in production.
824

83-
```xml
5+
## Getting Started
846

85-
<dependencies>
86-
<dependency>
87-
<groupId>net.pascal-lab</groupId>
88-
<artifactId>tai-e</artifactId>
89-
<version>0.2.2</version>
90-
</dependency>
91-
</dependencies>
92-
```
7+
As NullPath is built upon [Tai-e](https://github.com/pascal-lab/Tai-e), its prerequisites and fundamental build procedures are consistent with Tai-e. The primary difference in the build process is the addition of a specific Gradle task, `nullpath`, designed to generate a JAR file with `pascal.taie.analysis.bugfinder.pathsensnullpointer.NullPointerMain` as its main entry point.
938

94-
### Latest Version
9+
### Prerequisites
9510

96-
For Gradle:
11+
* **Java Development Kit (JDK):** NullPath requires Java 17 or higher, consistent with Tai-e. Please ensure your `JAVA_HOME` environment variable is set correctly.
9712

98-
```kotlin
99-
repositories {
100-
mavenCentral()
101-
maven { url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/") }
102-
}
13+
### Building NullPath
10314

104-
dependencies {
105-
implementation("net.pascal-lab:tai-e:0.5.1-SNAPSHOT")
106-
}
107-
```
15+
1. **Clone the Repository:**
16+
```bash
17+
git clone <YOUR_NULLPATH_REPOSITORY_URL> # Replace with your actual NullPath repository URL
18+
cd nullpath # Or your project's directory name
19+
```
20+
2. **Build the Project:**
21+
NullPath uses Gradle for its build system. To generate the specific NullPath JAR with `NullPointerMain` as the entry point, run:
22+
```bash
23+
./gradlew nullpath
24+
```
25+
The resulting JAR (e.g., `nullpath-[version].jar`) will typically be found in the `build/libs/` directory. For the command examples below, we'll refer to this as `nullpath.jar`. Please check your build output for the precise filename.
10826
109-
For Maven:
110-
111-
```xml
112-
<repositories>
113-
<repository>
114-
<id>snapshots</id>
115-
<name>Sonatype snapshot server</name>
116-
<url>https://s01.oss.sonatype.org/content/repositories/snapshots/</url>
117-
</repository>
118-
</repositories>
119-
120-
<dependencies>
121-
<dependency>
122-
<groupId>net.pascal-lab</groupId>
123-
<artifactId>tai-e</artifactId>
124-
<version>0.5.1-SNAPSHOT</version>
125-
</dependency>
126-
</dependencies>
127-
```
27+
For other build operations consistent with Tai-e (like generating a `tai-e-all.jar` if configured), you would use the standard Tai-e Gradle tasks (e.g., `./gradlew fatJar`).
28+
29+
## How to Run NullPath (command-line options)?
12830
129-
You can use these coordinates in your Gradle or Maven scripts to include the desired version of Tai-e in your project.
31+
As NullPath is built upon [Tai-e](https://github.com/pascal-lab/Tai-e), its command-line parameters and general usage align with Tai-e's conventions. For comprehensive details on all available Tai-e command-line options, please consult the [official Tai-e Command-Line Options Documentation](https://tai-e.pascal-lab.net/docs/current/reference/en/command-line-options.html).
13032

131-
## Documentation
33+
NullPath offers two primary ways to execute the NPE detection analysis:
13234

133-
### Reference Documentation
35+
### 1. Using `NullPointerMain` (Recommended for Standard NPE Detection)
36+
To simplify the execution of NPE detection, which involves a complex set of underlying analyses and parameters, NullPath provides a dedicated entry point: `pascal.taie.analysis.bugfinder.pathsensnullpointer.NullPointerMain`. This method conveniently bundles all the required analysis configurations.
13437

135-
We have provided detailed information of Tai-e in the [Reference Documentation](https://tai-e.pascal-lab.net/docs/current/reference/en/index.html), which covers various aspects such as [Setup in IntelliJ IDEA](https://tai-e.pascal-lab.net/docs/current/reference/en/setup-in-intellij-idea.html), [Command-Line Options](https://tai-e.pascal-lab.net/docs/current/reference/en/command-line-options.html), and [Development of New Analysis](https://tai-e.pascal-lab.net/docs/current/reference/en/develop-new-analysis.html).
38+
In most cases, you only need to specify the parameters related to the program you want to analyze (i.e., Tai-e's "Program options").
13639
137-
Please note that the reference documentation mentioned above pertains to *the latest version* of Tai-e.
138-
If you need documentation for a specific stable version, please refer to the [Documentation Index](https://tai-e.pascal-lab.net/docs).
139-
Additionally, the documentation is included within the repository and maintained alongside the source code.
140-
You can access the reference documentation for a particular version of Tai-e (in AsciiDoc format) by exploring the [docs/en](docs/en) directory, starting from [index.adoc](docs/en/index.adoc).
141-
This allows you to access version-specific documentation for Tai-e.
40+
**Command Example:**
41+
```bash
42+
java -jar build/libs/nullpath.jar -cp <path_to_java_project_classes_or_jar> -m <main_class_of_target_project> [other_program_options]
43+
```
44+
* `build/libs/nullpath.jar`: The runnable fat JAR for NullPath. Remember to use the actual filename generated in your `build/libs/` directory.
45+
* `-cp <path_to_java_project_classes_or_jar>`: This is the classpath for the Java project you want to analyze. This can be a path to a directory containing `.class` files, or a path to a JAR file.
46+
* `-m <main_class_of_target_project>`: The fully qualified name of the main class of the application you are analyzing (e.g., `com.example.MyApplication`). This helps Tai-e determine the entry points for the analysis.
47+
* `[other_program_options]`: Additional Tai-e program options, such as `-java <version>` to specify the Java version of the target project. Refer to the [Tai-e documentation](https://tai-e.pascal-lab.net/docs/current/reference/en/command-line-options.html) for defaults and available program options.
14248
143-
In addition to the reference
144-
documentation, [Javadocs](https://tai-e.pascal-lab.net/docs/current/api/index.html) for Tai-e are
145-
also available as a useful reference resource.
49+
This command will run the pre-configured set of analyses for NPE detection on the specified target program.
50+
51+
**Output:**
52+
The analysis results, including detected potential NullPointerExceptions, are typically printed to the console or logged to files (as configured by Log4j2 within Tai-e). The `NullPointerResultProcessor` component is responsible for formatting and presenting these findings.
53+
54+
### 2. Using Tai-e's `pascal.taie.Main` (For Advanced Control)
55+
If you require more fine-grained control over the analysis process (e.g., specifying parameters for pointer analysis, or modifying the analysis chain), you can directly use Tai-e's original Main class (`pascal.taie.Main`).
56+
57+
When using this approach, you will need to manually specify all relevant analysis options (the `-a` flags as used in Tai-e), including those specific to `path-sens-nullpointer`, its dependencies, and any custom configurations you require, in addition to the program options.
58+
59+
**Conceptual Example:**
60+
```bash
61+
java -cp build/libs/nullpath.jar pascal.taie.Main \\\
62+
-cp <path_to_java_project_classes_or_jar> \\\
63+
-m <main_class_of_target_project> \\\
64+
-a must-alias \\\n -a non-null \\\n -a icfg \\\n -a side-effect \\\n -a cg \\\n -a null-slice \\\n -a path-sens-nullpointer \\\n -a nullpointer-result-processor \\\n -a \"pta=cs:2-type;plugins:[pascal.taie.analysis.bugfinder.pathsensnullpointer.NullPointerAnalysis,pascal.taie.analysis.pta.plugin.NumberLiteralHandler];propagate-types:[reference,null,int,long,boolean];\" \\\
65+
[other_tai-e_options]
66+
```
67+
To get the exact list of analyses and their configurations as bundled in `NullPointerMain`, you can refer to the `src/main/java/pascal/taie/analysis/bugfinder/pathsensnullpointer/NullPointerMain.java` source file.
14668
147-
### Changelog
148-
Since we are actively developing and updating Tai-e, we record the notable changes we made, especially the new features and breaking changes, in [CHANGELOG](CHANGELOG.md).
149-
If you find something wrong after updating Tai-e, maybe you could check [CHANGELOG](CHANGELOG.md) for useful information.
69+
## Acknowledgements
15070
151-
## Tai-e Assignments
152-
In addition, we have developed an [educational version of Tai-e](https://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.
153-
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.
71+
* This project is built using the **Tai-e static analysis framework**. We extend our gratitude to the Tai-e developers and contributors for their excellent work. You can find the Tai-e framework at [https://github.com/pascal-lab/Tai-e](https://github.com/pascal-lab/Tai-e).

0 commit comments

Comments
 (0)