https://github.com/cvs0/bytecode-processor
Advanced bytecode processing library
https://github.com/cvs0/bytecode-processor
Last synced: 2 months ago
JSON representation
Advanced bytecode processing library
- Host: GitHub
- URL: https://github.com/cvs0/bytecode-processor
- Owner: cvs0
- Created: 2025-06-25T23:58:32.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-03-24T00:28:22.000Z (3 months ago)
- Last Synced: 2026-03-24T00:46:49.356Z (3 months ago)
- Language: Java
- Homepage:
- Size: 146 KB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Bytecode Processor
Java bytecode analysis and transformation on ASM’s tree API. Model a JAR as editable program classes and resources, analyze dependencies, and run coordinated rewrites (renames, descriptors, instructions, resources) through one `ClassTransformer` pipeline.
**Stack:** ASM `ClassNode` / `ProgramClass` model → `DependencyAnalyzer` and utilities → `ClassTransformer` + optional `Plugin`s. CLI is Picocli, shipped as a shaded JAR.
## Features
- Dependency graphs, cycles, reverse dependents, Graphviz DOT export
- Renames (class, method, field), package moves, instruction/LDC hooks, optional debug stripping
- Ordered plugins with `java.util.logging` diagnostics
- Picocli CLI for JAR analysis without embedding the library in your own code
## Requirements
JDK **21+** and Maven **3.6.3+** (enforced in the POM).
## Quick start
```bash
git clone https://github.com/cvs0/bytecode-processor.git
cd bytecode-processor
mvn clean verify
```
Artifacts in `target/` after `package` / `verify`:
| Output | Purpose |
|--------|---------|
| `bytecode-processor-${revision}.jar` | Library (`module bytecode.processor`). Does **not** bundle ASM or Picocli. |
| `bytecode-processor-${revision}-all.jar` | Runnable CLI (shaded). Use `java -jar …`. |
`${revision}` comes from `pom.xml` and is resolved at build time (flatten plugin).
### Maven dependency
Releases are on **Maven Central**. Replace `VERSION` with the latest release (see [Central](https://central.sonatype.com/) or repo tags).
```xml
io.github.cvs0
bytecode-processor
VERSION
```
**Shaded CLI** as a classified artifact:
```xml
all
```
**Snapshots** (e.g. `1.2.3-SNAPSHOT`) are published to [GitHub Packages](https://github.com/cvs0/bytecode-processor/packages) on pushes to `development`. Add the `https://maven.pkg.github.com/cvs0/bytecode-processor` repository and authenticate as [GitHub documents for Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry).
### IDE / modules
The project uses **Lombok** (`provided`). Install the [Lombok IDE support](https://projectlombok.org/setup/) for navigation.
Consumers need ASM on the module or classpath. The library `requires org.objectweb.asm.tree`, `java.logging`, and `info.picocli` (for the non-exported CLI package). Exported packages are listed in [`module-info.java`](src/main/java/module-info.java); `io.github.cvs0.bytecode.cli` is opened to Picocli only.
## Using the library
**Naming:** internal names use JVM slash form (`com/example/Foo`, inner classes `Outer$Inner`). Method rename keys are `className + "." + name + descriptor` (raw descriptor, e.g. `(I)V`). `renamePackage` accepts internal or dot prefixes.
**Typical flow:**
1. `JarMapping.fromJar(path)` — load classes and resources.
2. Analyze or inspect (`DependencyAnalyzer`, `JarStatistics`, etc.).
3. `ClassTransformer(mapping)` — queue changes, then **`applyTransformations()`** once.
4. `mapping.writeToJar(path)` — write the JAR.
**Details** (apply order, manifest/resource behavior, thread safety): see Javadoc on `ClassTransformer`, `JarWriter`, and `JarMapping`.
**Plugins:** implement `Plugin` (`initialize`, `process(JarMapping)`, `cleanup`, optional priority). Register with `PluginManager`. Reference configs live under `io.github.cvs0.bytecode.plugin.impl` (`OptimizationPlugin`, `ObfuscationPlugin`).
## CLI
```bash
java -jar target/bytecode-processor-*-all.jar [COMMAND] [ARGS]
```
Global options: `-h` / `--help`, `-V` / `--version`. Without a subcommand, usage is printed.
| Command | What it does |
|---------|----------------|
| `analyze ` | Full textual report (`JarAnalyzer`-style). Exit `2` if path is not a file. |
| `stats ` | Aggregates; add `--json` for one-line stats. Exit `2` if missing. |
| `deps ` | Dependency summary; `--dot ` for DOT; `--class ` for dependents (up to 50). Exit `2` if missing. |
## Development
```bash
mvn verify # tests + integration (shaded CLI) + JaCoCo + enforcer
mvn test # unit tests only
mvn package # library + shaded JAR
```
Coverage: `target/site/*/index.html` after `verify`.
**CI** ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)): `mvn -B verify` on pushes/PRs to `main`, `master`, `develop`, `development`, and `release/**`. Tags `v*` attach both JARs to a GitHub Release.
**Publish** ([`.github/workflows/publish.yml`](.github/workflows/publish.yml)): tag `v*` → Maven Central; push to `development` → snapshot to GitHub Packages.
**Optional git hooks:** `git config core.hooksPath .githooks` (on Unix, `chmod +x .githooks/pre-commit`). Pre-commit runs `mvn test`.
**Contributing:** `mvn verify` green; keep changes focused; match existing style ([`.editorconfig`](.editorconfig)). Version is `${revision}` in the POM (flattened); release tags should match the published version.
## License
MIT.