# jbuild
**Cargo for Java** - A modern, fast, and user-friendly build system for Java projects.
[]()
[]()
[]()
[]()
> **🎉 Major Milestone**: 706+ tests passing with comprehensive implementation!
> See [Implementation Complete](IMPLEMENTATION_COMPLETE.md) for details.
>
> **☕ Java 24 Support**: jbuild supports all Java versions from 8 to 24 and beyond!
> See [Java Version Support](docs/JAVA_VERSION_SUPPORT.md) for details.
## The Problem
Java developers face significant friction with existing build tools:
- **Slow startup**: Maven takes 500ms+ and Gradle 1000ms+ just to start, even for simple commands
- **High memory usage**: JVM-based tools consume 200-300MB+ of RAM
- **Complex configuration**: Verbose XML (Maven) or DSL learning curve (Gradle)
- **Poor developer experience**: No simple `add dependency` command, manual XML editing required
- **Tool fragmentation**: Different commands and concepts between Maven and Gradle
**Every `mvn compile` or `gradle build` wastes seconds waiting for the JVM to start.**
## The Solution
jbuild is a **native Rust implementation** that brings the Cargo experience to Java:
| **Startup** | ~10ms | ~500ms | ~1000ms |
| **Memory** | ~50MB | ~200MB | ~300MB |
| **Add Dependency** | `jbuild add pkg` | Edit XML manually | Edit DSL manually |
| **Create Project** | `jbuild new app` | `mvn archetype:generate` (interactive) | `gradle init` |
## Key Advantages
1. **50x Faster Startup** - Native binary, no JVM warmup
2. **5x Less Memory** - Efficient Rust implementation
3. **Parallel Builds** - 3-5x faster multi-module builds with intelligent parallelization
4. **Smart Caching** - 10-50x faster incremental builds with persistent cache
5. **Unified CLI** - Same commands for Maven and Gradle projects
6. **Modern UX** - Simple commands like `add`, `remove`, `search`, `tree`
7. **Zero Config** - Works with existing `pom.xml` or `build.gradle`
8. **Code Quality Built-in** - Integrated Checkstyle linting
9. **Multi-Language** - Java, Kotlin, Scala support with annotation processing
10. **All Java Versions** - Supports Java 8 through 24 and beyond
## Quick Start
```bash
# Install (coming soon)
cargo install jbuild
# Create a new project
jbuild new my-app
cd my-app
# Build and run
jbuild build
jbuild run # Auto-detect and run main class
jbuild run --main-class com.example.App # Specify main class
jbuild run arg1 arg2 # Pass arguments to application
# Manage dependencies
jbuild search slf4j # Search Maven Central
jbuild add org.slf4j:slf4j-api:2.0.9
jbuild remove org.slf4j:slf4j-api
jbuild tree # Show dependency tree
jbuild info org.slf4j:slf4j-api # Show package details
jbuild outdated # Check for outdated dependencies
jbuild update # Update all dependencies
```
# Code quality
jbuild lint # Run Checkstyle checks
jbuild test # Run tests
```
## Usage
### Project Management
```bash
jbuild new my-app # Create new Maven project
jbuild new my-app -b gradle # Create new Gradle project
jbuild new my-lib -t lib # Create library project
jbuild init # Initialize in existing directory
```
### Workspace Support (Multi-Project Builds)
```bash
jbuild workspace new my-workspace # Create new workspace
cd my-workspace
jbuild new core -t lib # Create core library
jbuild new app # Create application
jbuild workspace add core # Add projects to workspace
jbuild workspace add app
jbuild workspace list # List workspace members
jbuild workspace build # Build all projects in dependency order
jbuild workspace build compile # Build with specific goals
```
### Building & Running
```bash
jbuild build # Compile + test + package
jbuild compile # Compile only
jbuild check # Check code (compile without artifacts)
jbuild test # Run tests
jbuild run # Build and run main class
jbuild watch # Watch for changes and auto-rebuild
jbuild watch --test # Watch and run tests on change
jbuild # Uses pom.xml/build.gradle or jbuild.toml (auto-converts to pom)
jbuild clean # Clean build outputs
```
### Dependency Management
```bash
jbuild add group:artifact # Add dependency (auto-detects latest version)
jbuild add group:artifact:version # Add dependency with specific version
jbuild add group:artifact --dev # Add test dependency
jbuild remove group:artifact # Remove dependency
jbuild tree # Show dependency tree
jbuild tree # Shows transitive dependencies
jbuild search <query> # Search Maven Central
jbuild info group:artifact # Show package details and versions
jbuild outdated # Show outdated dependencies
jbuild update # Update all dependencies to latest
jbuild update group:artifact # Update specific dependency
jbuild info group:artifact # Show package details and versions
```
### Configuration
```bash
# Use jbuild.toml (auto-converted to pom.xml for build execution)
cat > jbuild.toml <<'EOF'
[package]
name = "my-app"
version = "0.1.0"
java = "21"
[dependencies]
"org.slf4j:slf4j-api" = "2.0.9"
[dev-dependencies]
"org.junit.jupiter:junit-jupiter" = "5.10.0"
EOF
jbuild build # will generate pom.xml from jbuild.toml if no pom/build.gradle present
# jbuild.lock is auto-created from jbuild.toml for reproducible builds
```
### Workspace Configuration
```toml
# jbuild-workspace.toml - Workspace configuration
members = [
"core",
"api",
"app"
]
default_members = [
"core",
"app"
]
[resolver]
version_resolution = "Highest" # Highest, Lowest, Fail
conflict_resolution = "Highest" # Highest, Lowest, Fail
[package]
name = "my-workspace"
version = "1.0.0"
description = "Multi-project Java workspace"
```
### Code Quality
```bash
jbuild lint # Run Checkstyle (9 checks)
jbuild lint -c checkstyle.xml # Use custom config
jbuild lint src/main/java # Check specific directory
```
## Comparison: jbuild vs Maven vs Gradle
| **Language** | Rust | Java | Groovy/Kotlin (JVM) |
| **Startup Time** | ~10ms | ~500ms | ~1000ms |
| **Memory Usage** | ~50MB | ~200MB+ | ~300MB+ |
| **Build File** | pom.xml / build.gradle | pom.xml | build.gradle(.kts) |
| **Add Dependency** | `jbuild add` | Manual XML edit | Manual DSL edit |
| **Search Packages** | `jbuild search` | ❌ | ❌ |
| **Remove Dependency** | `jbuild remove` | Manual XML edit | Manual DSL edit |
| **Dep Tree** | `jbuild tree` | `mvn dependency:tree` | `gradle dependencies` |
| **Package Info** | `jbuild info` | ❌ | ❌ |
| **Check Outdated** | `jbuild outdated` | ❌ | ❌ |
| **Update Dependencies** | `jbuild update` | Manual edit | Manual edit |
| **Linting** | `jbuild lint` | Plugin required | Plugin required |
| **Project Creation** | `jbuild new` | `mvn archetype:generate` | `gradle init` |
| **Multi-module** | ✅ Both systems | ✅ Reactor | ✅ Composite builds |
| **Incremental Builds** | ✅ Built-in | ✅ Plugin-based | ✅ Native |
| **Parallel Resolution** | ✅ 2-5x faster | ❌ | ⚠️ Limited |
| **Persistent Cache** | ✅ 10-50x faster | ⚠️ Local only | ✅ Build cache |
| **Kotlin Support** | ✅ Native | ✅ Plugin | ✅ Native |
| **Scala Support** | ✅ Native | ✅ Plugin | ✅ Plugin |
| **Annotation Processing** | ✅ Built-in | ✅ Built-in | ✅ Built-in |
## Project Structure
The project is organized as a **single crate** with all modules under `src/`:
- **model/**: Maven POM model, property interpolation, and model building logic
- **artifact/**: Artifact handling and coordinates
- **core/**: Core execution engine, lifecycle management, and build optimization
- **resolver/**: Dependency resolution (transitive, conflict, version range)
- **settings/**: Maven settings.xml parsing and configuration
- **plugin_api/**: Plugin API definitions and compatibility
- **compiler/**: Java compiler integration (javac invocation, classpath management)
- **packaging/**: JAR/WAR file creation and packaging
- **testing/**: Test discovery, execution, and reporting
- **cli.rs**: CLI definition (Clap structs)
- **runner/**: Command implementation logic (modularized into submodules)
- **main.rs**: CLI dispatcher (minimal entry point)
## Status
This is an ongoing project. Both Maven and Gradle support are implemented with shared infrastructure.
**Key Features Implemented:**
- ✅ Maven POM parsing and model building
- ✅ Dependency resolution (local and remote repositories)
- ✅ Plugin loading and descriptor parsing
- ✅ Plugin dependency resolution
- ✅ Java compiler integration
- ✅ Lifecycle execution framework
- ✅ Plugin execution framework (with classpath setup)
- ✅ JNI integration for Java plugin execution (optional feature)
- ✅ External Maven process fallback for plugin execution
- ✅ JAR/WAR file packaging with manifest generation
- ✅ Test discovery and execution (JUnit, TestNG)
- ✅ Test reporting
- ✅ Profile activation logic
- ✅ Property interpolation
- ✅ Model validation
- ✅ Advanced dependency resolution (version ranges, conflicts, exclusions)
- ✅ Build optimization (incremental compilation, parallel execution)
- ✅ **Parallel dependency resolution** (2-5x faster with rayon)
- ✅ **Persistent build cache** (10-50x faster incremental builds)
- ✅ **Reactor optimization** (parallel multi-module builds)
- ✅ Plugin compatibility and configuration inheritance
- ✅ **Gradle build script parsing (Groovy/Kotlin DSL)**
- ✅ **Gradle task execution (clean, compileJava, test, jar, build)**
- ✅ **Build system detection and unified CLI**
- ✅ **Gradle dependency resolution** (integrated with shared resolver)
- ✅ **Multi-project builds** (settings.gradle support)
- ✅ **Checkstyle integration** (`jbuild lint` command with 9 checks)
- ✅ **Multi-language support** (Kotlin, Scala compilers integrated)
- ✅ **Annotation processing** (Lombok, MapStruct, Dagger, AutoValue, Immutables)
- ✅ **Performance optimizations** (parallel builds, caching, incremental compilation)
- ✅ **Checkstyle integration** (9 built-in checks with tree-sitter parser)
- ✅ **706+ tests passing** - Comprehensive test coverage
See [TODO.md](TODO.md) for the current list of remaining work items and [MIGRATION.md](MIGRATION.md) for migration details.
## Example Projects
The `examples/` directory contains sample projects demonstrating jbuild capabilities:
### Maven Examples
```
examples/
├── simple-java-project/ # Single-module Maven project
│ ├── pom.xml
│ └── src/main/java/...
└── multi-module-maven/ # Multi-module Maven project
├── pom.xml # Parent POM
├── core/ # Core utilities module
├── api/ # API interfaces module
└── app/ # Application module
```
**Sample Maven POM (`examples/simple-java-project/pom.xml`):**
```xml
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>simple-java-project</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging>
<properties>
<maven.compiler.source>21</maven.compiler.source>
<maven.compiler.target>21</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.13.2</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>
```
### Gradle Examples
```
examples/
├── simple-gradle-project/ # Single-module Gradle project
│ ├── build.gradle
│ └── src/main/java/...
└── multi-module-gradle/ # Multi-module Gradle project
├── settings.gradle # Project settings
├── build.gradle # Root build script
├── core/ # Core utilities module
├── api/ # API interfaces module
└── app/ # Application module
```
**Sample Gradle build script (`examples/simple-gradle-project/build.gradle`):**
```groovy
plugins {
id 'java'
}
group = 'com.example'
version = '1.0.0'
sourceCompatibility = '21'
targetCompatibility = '21'
repositories {
mavenCentral()
}
dependencies {
testImplementation 'junit:junit:4.13.2'
}
```
**Sample settings.gradle (`examples/multi-module-gradle/settings.gradle`):**
```groovy
rootProject.name = 'multi-module-gradle'
include ':core'
include ':api'
include ':app'
```
## Building
```bash
# Build without JNI (uses external Maven process for plugins)
cargo build --release
# Build with JNI support (enables direct Java class loading)
cargo build --release --features jni
```
## Running
```bash
# Modern Cargo-like commands (auto-detects build system)
jbuild build # Compile the project
jbuild run # Build and run main class
jbuild test # Run tests
jbuild clean # Clean build outputs
jbuild lint # Check code style (Checkstyle)
# Dependency management
jbuild add org.slf4j:slf4j-api # Add dependency (latest version)
jbuild add org.slf4j:slf4j-api:2.0.9 # Add specific version
jbuild remove org.slf4j:slf4j-api # Remove dependency
jbuild tree # Show dependency tree
jbuild outdated # Show outdated dependencies
# Project creation
jbuild new my-app # Create new app project
jbuild new my-lib --template lib # Create new library project
jbuild init # Initialize in existing directory
# Legacy mode (explicit build file)
jbuild --file pom.xml compile
jbuild --file build.gradle build
# Generate shell completions
jbuild completions bash > /etc/bash_completion.d/jbuild
jbuild completions zsh > ~/.zsh/completions/_jbuild
jbuild completions fish > ~/.config/fish/completions/jbuild.fish
```
### Supported Tasks/Goals
| `compile` | `compileJava` | Compile Java sources |
| `test-compile` | `compileTestJava` | Compile test sources |
| `test` | `test` | Run tests |
| `package` | `jar` | Create JAR file |
| `clean` | `clean` | Clean build outputs |
| `install` | - | Install to local repository |
| - | `build` | Full build (compile + test + jar) |
### Code Quality: `jbuild lint`
The `lint` command runs Checkstyle checks on Java source files:
```bash
# Check all Java files in src/main/java and src/test/java
jbuild lint
# Check specific files or directories
jbuild lint src/main/java
jbuild lint src/main/java/com/example/App.java
# Use custom Checkstyle configuration
jbuild lint -c checkstyle.xml
```
**Available Checks:**
- **EmptyCatchBlock** - Detects empty catch blocks
- **EmptyStatement** - Detects empty statements (standalone semicolons)
- **MissingSwitchDefault** - Detects switch statements without default case
- **MultipleVariableDeclarations** - Detects multiple variable declarations per statement
- **SimplifyBooleanReturn** - Detects boolean returns that can be simplified
- **PackageName** - Validates package naming conventions
- **TypeName** - Validates type naming conventions
- **RedundantImport** - Detects redundant imports
- **LineLength** - Detects lines exceeding maximum length (default: 120)
## Testing
The project includes comprehensive unit tests and integration tests:
```bash
# Run all tests
cargo test
# Run only unit tests
cargo test --lib
# Run integration tests
cargo test --test example_project
# Run with output
cargo test -- --nocapture
```
### Test Structure
- **Unit tests**: Located in `src/` modules with `#[test]` attributes
- **Integration tests**: Located in `tests/` directory
- **Mocks and fixtures**: `src/testing_utils.rs` provides mock implementations for testing
### Testing Utilities
The codebase provides several testing utilities in `testing_utils`:
- `MockArtifactRepository`: In-memory artifact repository for testing
- `MockDependencyResolver`: Mock dependency resolver for controlled testing
- `TestProjectBuilder`: Fluent builder for creating test projects
Example usage:
```rust
use jbuild::{MockArtifactRepository, ArtifactRepository};
#[test]
fn test_artifact_resolution() {
let repo = MockArtifactRepository::new();
repo.add_artifact("com.example", "lib", "1.0.0", "/path/to/lib.jar".to_string());
assert!(repo.exists("com.example", "lib", "1.0.0"));
}
```
## Architecture & Design
jbuild follows **Domain-Driven Design (DDD)** principles with clean architecture:
```
┌─────────────────────────────────────┐
│ Presentation Layer (CLI) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Application Layer ✅ │
│ - BuildOrchestrationService │
│ - ProjectInitializationService │
│ - DependencyManagementService │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Domain Layer ✅ │
│ - Aggregates (MavenProject, etc) │
│ - Domain Services (5 services) │
│ - Value Objects (15+ objects) │
└─────────────────────────────────────┘
↓
┌─────────────────────────────────────┐
│ Infrastructure Layer ✅ │
│ - LocalRepository │
│ - RemoteRepository │
└─────────────────────────────────────┘
```
### DDD Implementation Status
**Completed Phases (1-6):**
- ✅ **Phase 1**: Shared Kernel (Version, FilePath, JavaVersion)
- ✅ **Phase 2**: Value Objects (15+ domain objects)
- ✅ **Phase 3**: Aggregate Roots (MavenProject, GradleProject)
- ✅ **Phase 4**: Domain Services (5 services)
- ✅ **Phase 5**: Repository Implementations (3 repositories)
- ✅ **Phase 6**: Application Services (3 services)
**Test Coverage**: 285 tests passing (100% pass rate)
### Documentation
- [ARCHITECTURE.md](ARCHITECTURE.md) - Overall architecture
- [SPEC.md](SPEC.md) - Technical specification
- [IMPLEMENTATION_COMPLETE.md](IMPLEMENTATION_COMPLETE.md) - Implementation summary
- [Architecture Diagram](docs/ARCHITECTURE_DIAGRAM.md) - Visual system overview
- [DDD Architecture](docs/DDD_ARCHITECTURE.md) - Domain model details
- [Performance Optimizations](docs/PERFORMANCE_OPTIMIZATIONS.md) - Parallel builds, caching, incremental compilation
- [Multi-Language Support](docs/MULTI_LANGUAGE_SUPPORT.md) - Kotlin, Scala, annotation processing
- [Java Version Support](docs/JAVA_VERSION_SUPPORT.md) - Java 8-24+ support
- [TODO.md](TODO.md) - Remaining work items
### Key Design Patterns
- **Repository Pattern**: Trait-based abstraction for artifact storage
- **Aggregate Pattern**: Consistency boundaries (MavenProject, GradleProject)
- **Value Object Pattern**: Immutable, validated domain objects
- **Domain Service Pattern**: Stateless business logic encapsulation
- **Dependency Injection**: Trait-based for testability
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
The codebase follows Domain-Driven Design principles. See [DDD Migration Guide](docs/DDD_MIGRATION_GUIDE.md) for contributing guidelines.
## License
Licensed under the Apache License, Version 2.0.