https://github.com/xzel23/cabe
Inject null-checks into Java-code
https://github.com/xzel23/cabe
bytecode instrumentation java jspecify null-check null-safe nullability
Last synced: 2 months ago
JSON representation
Inject null-checks into Java-code
- Host: GitHub
- URL: https://github.com/xzel23/cabe
- Owner: xzel23
- License: mit
- Created: 2021-11-08T08:32:40.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-29T13:46:52.000Z (over 1 year ago)
- Last Synced: 2024-12-12T06:50:22.482Z (over 1 year ago)
- Topics: bytecode, instrumentation, java, jspecify, null-check, null-safe, nullability
- Language: Java
- Homepage:
- Size: 1.12 MB
- Stars: 12
- Watchers: 3
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- License: LICENSE
Awesome Lists containing this project
README
Cabe [](LICENSE) [](https://github.com/topics/java)
====
A bytecode instrumentation tool that inserts null checks based on JSpecify annotations.
## TLDR
Add this to the Gradle build file of your project that uses JSpecify annotations to add automatic null-checks to the public API of your project and assertion based
null checks to the private API:
```kotlin
plugins {
id("com.dua3.cabe") version "3.3.0"
}
```
## Introduction
Cabe helps implement the [Fail-Fast Principle](https://www.martinfowler.com/ieeeSoftware/failFast.pdf) by automatically adding runtime checks for annotated method parameters. This provides several benefits:
- **Early Detection**: Violations of nullability contracts are detected immediately at the point of violation
- **Improved Debugging**: Clear error messages that identify the exact parameter that violated the contract
- **Reduced Boilerplate**: No need to manually write null checks for annotated parameters
- **Consistent Enforcement**: Ensures that nullability contracts are enforced consistently across your codebase
## Usage
### Gradle
1. Add the plugin to your build script:
```kotlin
plugins {
id("java")
id("com.dua3.cabe") version "3.3.0"
}
```
2. Add JSpecify dependency:
```kotlin
dependencies {
implementation("org.jspecify:jspecify:1.0.0")
}
```
3. Add JSpecify annotations to your code.
### Maven
1. Add the plugin to your POM:
```xml
com.dua3.cabe
cabe-maven-plugin
3.3.0
cabe
```
2. Configure the compiler to use a separate output directory:
```xml
org.apache.maven.plugins
maven-compiler-plugin
3.13.0
default-compile
${project.build.directory}/unprocessed-classes
```
3. Configure the Cabe plugin:
```xml
com.dua3.cabe
cabe-maven-plugin
3.3.0
${project.build.directory}/unprocessed-classes
1
STANDARD
cabe
```
4. Add JSpecify dependency:
```xml
org.jspecify
jspecify
1.0.0
```
5. Add JSpecify annotations to your code.
## Building from Source
To build Cabe from source, use the provided `build.sh` script:
```bash
./build.sh
```
This script automatically:
1. Builds the project
2. Runs processor and plugin tests
3. Publishes artifacts to the local Maven repository
4. Tests the Gradle plugin
5. Builds example projects
The script ensures that all components work correctly together and is the recommended way to build the project.
## Documentation
For detailed documentation, including configuration options, advanced usage, and examples, please refer to:
- [Cabe Documentation](https://xzel23.github.io/cabe/cabe.html)
- [JSpecify Project](https://jspecify.dev/)