Code Doctorship recommends version-controlling all relevant documentation directly within your code repositories — rather than isolating it in a separate CMS.

Why?

• 📂 Docs live alongside the code they describe
• ⚡ Engineers can update them quickly, just like code
• 🔍 No need to context-switch into another platform
• 🔁 Documentation stays in sync with the codebase automatically

This principle is at the core of scalable engineering teams — and AsciiDoc is the best tool to make it happen.

While many default to Markdown for its simplicity, AsciiDoc offers a richer, more robust foundation that evolves with your team, tooling, and documentation needs.

✅ The Clean Documentation Imperative

Modern engineering teams need documentation that:

• ✅ Stays current without becoming a maintenance burden
• ✅ Scales consistently across projects and teams
• ✅ Integrates seamlessly into development workflows
• ✅ Outputs reliably across web, PDF, and mobile
• ✅ Maintains semantic structure — not just visual formatting

Documentation is no longer an afterthought. It’s a first-class citizen in codebases that ship quality software.

💡 Why AsciiDoc Wins

🔧 Predictable, Standardized Syntax

Markdown has multiple incompatible flavors — GitHub, CommonMark, MultiMarkdown — each with subtle differences. This leads to inconsistent rendering across platforms.

AsciiDoc, on the other hand, provides one clean, unified syntax:

= Main Title
== Section Header
=== Subsection

[source,python]
----
def clean_code():
    return "readable and maintainable"
----

No guessing. No inconsistencies.

🧠 Rich Semantic Markup Without HTML Bloat

Need to highlight a tip, warning, or cross-reference?

AsciiDoc provides semantic blocks out of the box:

NOTE: This endpoint requires authentication.

TIP: Use batch requests for better performance.

WARNING: This operation cannot be undone.

See <<api-reference>> for complete details.

In Markdown? You’re forced into HTML hacks — making your docs fragile and harder to maintain.

🖨️ Enterprise-Grade Multi-Format Publishing

AsciiDoc, combined with Asciidoctor, outputs clean:

• 📄 HTML5
• 📕 PDF
• 📱 EPUB
• 📘 DocBook

All without format-specific hacks or third-party converters.
Your docs stay consistent and professional across all outputs.

🔧 Mature Tooling Ecosystem

AsciiDoc isn’t new. It’s battle-tested and comes with a thriving ecosystem:

• 🧩 Editor support: Live preview in VS Code, IntelliJ, Atom, and more
• 🔁 CI/CD integrations: GitHub Actions, GitLab CI, Jenkins
• 🧱 Modular sites: Antora enables versioned, multi-project documentation
• 📋 Linting tools: Vale, alex, and others ensure consistent tone & structure

🧪 Format Comparison at a Glance

Markdown

• Pros: Simple syntax, widely supported, native GitHub rendering.
• Cons: Lacks standardization (multiple flavors), limited semantic markup, poor scalability for large projects. Markdown often requires HTML embeds for advanced features, breaking portability.
• Use Case: Best for small projects like READMEs or simple wikis.

reStructuredText (reST)

• Pros: Strong for Python documentation, good tooling (Sphinx), semantic directives.
• Cons: Complex syntax (e.g., variable-length underlines for headings), steep learning curve, limited GitHub support.
• Use Case: Ideal for Python projects or when Sphinx is already in use.

Lightweight DITA (LwDITA)

• Pros: XML-based, strong for enterprise content reuse, supports complex structures.
• Cons: Verbose syntax, high learning curve, requires specialized tools (DITA-OT), no GitHub rendering.
• Use Case: Suitable for large-scale, multi-channel enterprise documentation.

Challenges and Mitigations with AsciiDoc

While AsciiDoc is powerful, it has some challenges:

• Learning Curve: Slightly steeper than Markdown due to its richer syntax. Mitigation: Provide team training and use cheat sheets or editors with syntax highlighting.
• Tooling Setup: Requires configuration for CI/CD or static site generation. Mitigation: Use pre-built templates (e.g., Antora) or Asciidoctor plugins.
• Community Size: Smaller than Markdown’s. Mitigation: Leverage Asciidoctor’s active community and documentation.

Recommended Best Option: AsciiDoc with Asciidoctor and Antora

For clean code engineering documentation, AsciiDoc paired with Asciidoctor and Antora is the best choice. Here’s why:

• AsciiDoc provides a consistent, extensible, and semantically rich markup language that scales from small to large projects.
• Asciidoctor offers powerful rendering capabilities, real-time previews, and CI/CD integration, aligning with docs-as-code workflows.
• Antora is a static site generator tailored for AsciiDoc, supporting modular, versioned, and multi-repository documentation — perfect for engineering teams managing complex software projects.

Implementation Steps

1. Adopt AsciiDoc: Store documentation in .adoc files in a Git repository.
2. Set Up Asciidoctor: Use Asciidoctor CLI or plugins for editors like VS Code.
3. Use Antora: Configure Antora for static site generation, enabling versioned documentation.
4. Integrate CI/CD: Automate builds with GitHub Actions or GitLab CI, using Asciidoctor to generate HTML/PDF outputs.
5. Lint and Validate: Use tools like Vale or Asciidoctor extensions for style and syntax checks.

🆚 Real-World Example

Let’s document an API authentication section:

✅ AsciiDoc (Clean and Semantic)

== Authentication
:api-version: v2.1

All requests require authentication via API key.

[IMPORTANT]
====
Store API keys securely. Never commit them to version control.
====

=== Quick Start
[source,bash]
----
curl -H "Authorization: Bearer YOUR_KEY" \
     https://api.example.com/{api-version}/users
----

For details, see <<security-best-practices>>.

⚠️ Markdown (HTML Workarounds)

## Authentication

All requests require authentication via API key.

<div class="important">
<strong>Important:</strong> Store API keys securely. Never commit them to version control.
</div>

### Quick Start
```bash
curl -H "Authorization: Bearer YOUR_KEY" \
     https://api.example.com/v2.1/users

For details, see Security Best Practices.

**AsciiDoc wins** with better structure, semantic roles, and maintainability — especially at scale.

---

## 🛠️ Recommended Toolchain for Engineering Teams

| Purpose                          | Tool                  |
|----------------------------------|------------------------|
| Authoring                       | `.adoc` files in Git   |
| Conversion & Preview            | [Asciidoctor](https://asciidoctor.org) |
| Multi-project Docs              | [Antora](https://antora.org) |
| Linting & Style Checking        | [Vale](https://vale.sh), [alex](https://github.com/get-alex/alex) |
| CI/CD Publishing                | GitHub Actions, GitLab CI |

This stack gives your team a **professional documentation pipeline** — just like your code.

---

## 🚀 Making the Switch

Start with a small win:  
✅ Convert your `README.md` or a single API section to `.adoc`  
✅ Install Asciidoctor CLI or VS Code plugin  
✅ See the improvements in rendering, structure, and reuse

### 🙋‍♀️ Common Concerns

- **Learning Curve?**  
  Easier than it looks. Most devs are productive in a few hours.

- **Tooling?**  
  Modern IDEs and CI tools support AsciiDoc out of the box.

- **GitHub?**  
  GitHub renders `.adoc` files natively using Asciidoctor.

---

## 🩺 Code Doctors for Legacy Documentation Overhaul

Many engineering teams are sitting on **years of undocumented or Markdown-spaghetti tech debt** — with README files patched over time, fragile HTML hacks, and inconsistent structures across repos.

That’s where the **Code Doctorship** from [ShivohamAI](http://www.shivohamai.com/services) steps in.

### 👨‍⚕️ What the Code Doctors Do:
- **Diagnose** outdated or fragmented documentation systems  
- **Migrate** legacy Markdown, HTML, or custom formats to AsciiDoc — cleanly and quickly  
- **Refactor** doc structures for modularity, reuse, and CI/CD integration  
- **Prescribe** best practices for scalable tooling: Antora, Asciidoctor, Vale, GitOps  
- **Treat** your documentation as a living system — not a last-minute checklist

### 🧬 Why It Matters:
Just like legacy code, **legacy documentation** slows down onboarding, increases errors, and weakens product understanding — especially in regulated or fast-moving environments.

By partnering with Code Doctorship, teams can:
- 🧹 Eliminate inconsistent syntax and broken formats  
- 🚀 Accelerate product delivery through clearer internal and external documentation  
- 🔄 Align documentation updates with code releases  
- 🧠 Empower both engineers and stakeholders with searchable, readable knowledge  

---

## 📌 The Bottom Line

**Documentation debt is technical debt.**  
Markdown works for small projects. But for teams that care about **scale**, **structure**, and **professional output**, **AsciiDoc is the clear winner**.

It’s not just a markup language.  
It’s a mindset:  
🧠 *Treating docs like code.*  
🧰 *Using the right tools for the job.*  
📈 *Scaling with your ambitions.*

---

### 💬 Ready to Upgrade Your Docs?

AsciiDoc is more than markup. It's your team's commitment to engineering excellence.

> *Documentation that scales should be as rigorous as the systems it describes.*

—

Need help migrating from Markdown or CMS-based documentation?  
👉 **[Let Code Doctorship help.](http://www.shivohamai.com/services)**

Conclusion

AsciiDoc outperforms Markdown, reST, and LwDITA for clean code engineering documentation due to its consistent syntax, rich semantic markup, extensibility, and robust tooling. While Markdown is simpler for small projects, it lacks the scalability and portability needed for complex engineering documentation. reST and LwDITA, while powerful, have steeper learning curves and less seamless integration with modern developer workflows. By adopting AsciiDoc with Asciidoctor and Antora, engineering teams can create documentation that is as clean, maintainable, and collaborative as their code, ensuring long-term success in software development.

🩺 Code Doctors for Legacy Documentation Overhaul

Many engineering teams are sitting on years of undocumented or Markdown-spaghetti tech debt — with README files patched over time, fragile HTML hacks, and inconsistent structure across repos.

That’s where the Code Doctorship from ShivohamAI steps in.

👨‍⚕️ What the Code Doctors Do:

• Diagnose outdated or fragmented documentation systems
• Migrate legacy Markdown, HTML, or custom formats to AsciiDoc — cleanly and quickly
• Refactor doc structures for modularity, reuse, and CI/CD integration
• Prescribe best practices for scalable tooling: Antora, Asciidoctor, Vale, GitOps
• Treat your documentation as a living system — not a last-minute checklist

🧬 Why It Matters:

Just like legacy code, legacy documentation slows down onboarding, increases errors, and weakens product understanding — especially in regulated or fast-growing environments.

By partnering with Code Doctorship, teams can:

• 🧹 Eliminate inconsistent syntax and broken formats
• 🚀 Accelerate product delivery through clearer internal and external documentation
• 🔄 Align documentation updates with code releases
• 🧠 Empower both engineers and stakeholders with searchable, readable knowledge

💡 Your Docs Deserve a Second Opinion

You wouldn’t let a 2025-era Java app ship without cleanup.
Don’t let your docs lag behind either.

Reach out to ShivohamAI to give your documentation a full check-up and chart a clean path forward — from chaos to clarity.

📢 Disclosure

🧠 This article was co-created using AI tools and curated by experts from ShivohamAI.
AI-assisted drafting helped accelerate the writing process, but all technical insights, toolchain choices, and formatting practices are grounded in real-world engineering experience.

🔄 This document is a living artifact.
It will continue to evolve based on feedback, community input, and advancements in tooling — just like good documentation should.

Have suggestions or spotted something we can improve?
We welcome contributions and insights to make this even more useful.

Introduction

Publishing artifacts is a critical part of modern software development, whether you’re sharing a library on Maven Central, releasing a Gradle plugin, or deploying to a private repository. Gradle, as a flexible build tool, has evolved its publishing capabilities to meet diverse needs. In this article, I’ll explore four well-known Gradle publishing plugins, tracing their evolution and comparing their strengths, weaknesses, and ideal use cases. These plugins are:

• Maven Plugin (Deprecated): Gradle’s original solution for Maven repository publishing.
• Maven-Publish Plugin: Gradle’s modern, official plugin for Maven-compatible publishing.
• Gradle Plugin Publish Plugin: A specialized plugin for publishing Gradle plugins to the Gradle Plugin Portal.
• Vanniktech Gradle Maven Publish Plugin: A third-party plugin that simplifies publishing to Maven Central and Nexus.

Let’s dive into how these plugins have shaped Gradle’s publishing landscape and when to use each.

1. Maven Plugin (Deprecated)

Overview

The maven plugin was Gradle’s original solution for publishing artifacts to Maven repositories or generating Maven-compatible project structures (e.g., POM files). It was designed to bridge Gradle projects with Maven-based ecosystems.

Evolution

• Introduced: Early Gradle versions (pre-2012) to support Maven repository publishing and project conversion.
• Functionality: Provided tasks like uploadArchives to publish JARs and generate POM files. It allowed basic POM customization but was limited in scope.
• Limitations:
• Verbose configuration for repositories and artifacts.
• No support for modern Gradle features like the publishing DSL or Gradle Module Metadata.
• Poor handling of complex projects (e.g., multi-module or non-Java artifacts).
• Deprecation: Superseded by maven-publish in Gradle 4.8 (2018) due to its inflexibility and lack of support for advanced publishing needs.

Strengths

• Simple for basic Java projects in early Gradle versions.
• Familiar to Maven users transitioning to Gradle.

Weaknesses

• Outdated and unsupported since 2018.
• Limited customization and no support for modern repository requirements (e.g., signing, Gradle Module Metadata).
• Error-prone for complex builds.

When to Use

• Not Recommended: Only for maintaining legacy projects pre-2018 that haven’t migrated to maven-publish.
• Use Case: Rarely used today; primarily for old builds needing basic Maven repository publishing.

How to Use

pply plugin: 'maven'

uploadArchives {
    repositories {
        mavenDeployer {
            repository(url: 'https://my-repo.com') {
                authentication(userName: 'user', password: 'pass')
            }
            pom.groupId = 'org.example'
            pom.artifactId = 'my-library'
            pom.version = '1.0.0'
        }
    }
}

2. Maven-Publish Plugin

Overview

The maven-publish plugin is Gradle’s modern, official solution for publishing artifacts to Maven repositories. Introduced as a replacement for the maven plugin, it uses a declarative publishing DSL to define publications and repositories.

Evolution

• Introduced: Around Gradle 2.x (2013–2014), with significant improvements by Gradle 4.8 (2018).
• Key Features:
• Publications: Define MavenPublication objects to specify artifacts (e.g., JARs, sources, Javadoc) and POM metadata.
• Repositories: Configure MavenArtifactRepository for remote (e.g., Maven Central, Nexus) or local (mavenLocal) publishing.
• POM Customization: Modify POM files via pom.withXml or direct properties (e.g., groupId, artifactId).
• Task Generation: Creates tasks like publishPubNamePublicationToRepoNameRepository and aggregate tasks (publish, publishToMavenLocal).
• Component Support: Publishes components (e.g., components.java) from plugins like java or java-library.
• Gradle Module Metadata: Since Gradle 6.0 (2019), includes metadata for better dependency resolution in Gradle builds.
• Advancements:
• Added signing support for Maven Central (via signing plugin).
• Improved integration with plugins like kotlin-multiplatform and com.android.library.
• Enhanced DSL for multi-module projects and custom artifacts.
• Challenges:
• Requires manual setup for signing, sources, and Javadoc.
• Maven Central publishing involves complex configuration (e.g., staging, credentials).
• Steeper learning curve for beginners.

Strengths

• Flexibility: Supports custom artifacts, multiple repositories, and detailed POM customization.
• Official Support: Actively maintained, compatible with modern Gradle features.
• Broad Compatibility: Works with Java, Kotlin, Android, and multiplatform projects.

Weaknesses

• Complexity: Requires understanding of Gradle’s publishing model.
• Manual Overhead: Maven Central publishing needs additional setup (e.g., signing, staging).
• Verbose for Simple Cases: Basic publishing requires more code than specialized plugins.

When to Use

• Use Case: Projects needing fine-grained control over publishing, such as custom artifacts, multiple repositories, or non-Maven Central targets.
• Examples:
• Publishing a multi-module Java project to a private Nexus repository.
• Customizing POM files for specific dependency requirements.
• Publishing to mavenLocal for local testing.
• How to Use:

plugins {
    id 'maven-publish'
}

publishing {
    publications {
        maven(MavenPublication) {
            groupId = 'org.example'
            artifactId = 'my-library'
            version = '1.0.0'
            from components.java
        }
    }
    repositories {
        maven {
            url 'https://my-repo.com'
            credentials {
                username 'user'
                password 'pass'
            }
        }
    }
}

Run gradle publish or gradle publishToMavenLocal.

3. Gradle Plugin Publish Plugin (gradle-plugin-publish)

Overview

The gradle-plugin-publish plugin (likely what you meant by publish-plugin) is designed specifically for publishing Gradle plugins to the Gradle Plugin Portal. It builds on maven-publish to simplify the process for plugin authors.

Evolution

• Introduced: Around 2016 by Gradle, Inc., to streamline publishing to the Gradle Plugin Portal.
• Purpose: Simplifies publishing Gradle plugins by automating POM generation, plugin metadata, and portal-specific requirements.
• Key Features:
• Plugin Metadata: Configures plugin descriptors (e.g., id, implementation-class) via a gradlePlugin block.
• Automatic POM: Generates a POM file tailored for the Gradle Plugin Portal, including plugin-specific metadata.
• Single Repository: Targets the Gradle Plugin Portal (https://plugins.gradle.org/m2) by default.
• Tasks: Provides publishPlugins to publish to the portal and publishToMavenLocal for testing.
• Integration: Works with the java-gradle-plugin plugin to define plugins and their implementation.
• Advancements:
• Simplified plugin ID registration and authentication via API keys.
• Improved error messages and validation for portal requirements.
• Support for modern Gradle versions and plugin types (e.g., Kotlin-based plugins).
• Challenges:
• Limited to Gradle Plugin Portal; not suitable for general Maven repositories.
• Requires a registered plugin ID and API keys from the portal.
• Less flexible than maven-publish for custom publishing scenarios.

Strengths

• Simplicity: Streamlines publishing Gradle plugins with minimal configuration.
• Portal-Specific: Tailored for the Gradle Plugin Portal’s requirements.
• Integration: Works seamlessly with java-gradle-plugin for plugin development.

Weaknesses

• Narrow Scope: Only for Gradle Plugin Portal, not general Maven repositories.
• Dependency on maven-publish: Inherits some complexity for edge cases.
• Setup Overhead: Requires portal registration and API key management.

When to Use

• Use Case: Publishing Gradle plugins to the Gradle Plugin Portal.
• Examples:
• Releasing a custom Gradle plugin for build automation.
• Publishing a Kotlin-based Gradle plugin to the portal.

How to Use:

plugins {
    id 'java-gradle-plugin'
    id 'com.gradle.plugin-publish' version '1.2.1'
}

gradlePlugin {
    plugins {
        myPlugin {
            id = 'org.example.my-plugin'
            implementationClass = 'org.example.MyPlugin'
            displayName = 'My Gradle Plugin'
            description = 'A plugin for custom build tasks'
            tags = ['build', 'automation']
        }
    }
}

pluginBundle {
    website = 'https://example.com'
    vcsUrl = 'https://github.com/example/my-plugin'
}

Add credentials to gradle.properties:

properties

gradle.publish.key=your-key
gradle.publish.secret=your-secret

Run gradle publishPlugins to publish.

4. Vanniktech Gradle Maven Publish Plugin

Overview

The com.vanniktech.maven.publish plugin is a third-party plugin that enhances maven-publish to simplify publishing to Maven Central and other Nexus repositories, particularly for Java, Kotlin, Android, and multiplatform projects.

Evolution

Origin: Evolved from Chris Banes’ plugin (2018) to address maven-publish limitations for Android and Kotlin.

Milestones:

• 2018–2020: Added support for Android, Kotlin, and automatic sources/Javadoc generation.
• 2020–2022: Extended to Kotlin Multiplatform and Gradle plugins, with CI-friendly signing.
• 2023–2025: Adapted to Maven Central’s Central Portal (post-OSSRH deprecation in June 2025), added automatic releasing, and improved Javadoc handling.

Key Features:

• Maven Central Automation: Simplifies signing, staging, and releasing with options like publishToMavenCentral() and automaticRelease.
• In-Memory Signing: Uses environment variables for GPG keys, ideal for CI/CD.
• Cross-Platform: Supports Java, Kotlin, Android, Kotlin Multiplatform, and Gradle plugins.
• Base Variant: Offers com.vanniktech.maven.publish.base for manual configuration.
• Configuration: Uses gradle.properties for credentials and metadata, reducing build script complexity.

Strengths

• Automation: Handles Maven Central requirements (signing, staging, releasing) with minimal setup.
• Broad Support: Works with Java, Kotlin, Android, multiplatform, and Gradle plugins.
• CI-Friendly: In-memory signing and property-based configuration simplify pipelines.
• Active Maintenance: Regularly updated for Gradle and Maven Central changes.

Weaknesses

• Maven-Centric: Less suitable for non-Maven repositories.
• Base Plugin Complexity: Manual configuration in base variant can be complex.
• Dependency on maven-publish: Inherits some underlying complexities.

When to Use

• Use Case: Publishing to Maven Central or Nexus, especially for Java, Kotlin, Android, or multiplatform projects with automated workflows.
• Examples:
• Releasing an Android library to Maven Central with sources and Javadoc.
• Automating CI/CD for a Kotlin Multiplatform library.

How to Use:

plugins {
    id 'com.vanniktech.maven.publish' version '0.32.0'
}

mavenPublishing {
    publishToMavenCentral()
    signAllPublications()
}

In gradle.properties:

mavenCentralUsername=username
mavenCentralPassword=password
signing.keyId=12345678
signing.password=some_password
signing.secretKeyRingFile=/path/to/secring.gpg

Run gradle publishToMavenCentral or enable automaticRelease = true.

Comparison and Decision Matrix

When to Choose Each

1. Maven Plugin:

• When: Only for legacy projects pre-2018 that haven’t migrated.
• Why: Deprecated, lacks modern features, and is unsupported.

2. Maven-Publish Plugin:

• When: You need full control over publishing (e.g., custom artifacts, multiple repositories) or target non-Maven Central repositories.
• Why: Flexible, officially supported, but requires more configuration.
• Example: Publishing to a private Nexus repository with custom POM metadata.

3. Gradle Plugin Publish Plugin:

• When: You’re publishing a Gradle plugin to the Gradle Plugin Portal.
• Why: Tailored for the portal, simplifies plugin metadata and publishing.
• Example: Releasing a custom Gradle plugin for build automation.

4. Vanniktech Plugin:

• When: Targeting Maven Central or Nexus with minimal setup, especially for Java, Kotlin, Android, or multiplatform projects.
• Why: Automates Maven Central workflows, supports modern project types, and is CI-friendly.
• Example: Publishing an Android library to Maven Central with automatic signing

Recommendations

• New Projects: Use gradle-plugin-publish for Gradle plugins targeting the Gradle Plugin Portal, or Vanniktech’s plugin for Maven Central/Nexus publishing. Use maven-publish for custom or non-standard repository needs.
• Legacy Projects: Migrate from maven plugin to maven-publish or Vanniktech for modern features.
• Testing: Use publishToMavenLocal (available in maven-publish, gradle-plugin-publish, and Vanniktech) for local testing.
• CI/CD: Leverage Vanniktech’s in-memory signing and gradle.properties for secure, automated pipelines.
• Maven Central: Prefer Vanniktech for its automation, but use maven-publish if you need custom POM tweaks or non-standard artifacts.

🛠️ Final Notes

This article is intended to highlight key Gradle publishing options and share insights on choosing the best plugin to start with.
Please note: some of the script samples were generated using ChatGPT and may require validation before production use.

🩺 Need Help Migrating Legacy Gradle Publishing?

If you’re using older plugins like maven or facing complexity with your current publishing setup, we recommend connecting with the experts at Code Doctorship.

They specialize in:

• 🚑 Migration from deprecated plugins to modern publishing flows
• 🔧 Refactoring legacy Gradle scripts for clarity and maintainability
• 🔍 Ensuring smooth publication to Maven Central, GitHub Packages, or the Gradle Plugin Portal
• ⚙️ Automating release pipelines and CI/CD publishing tasks

➡️ Learn more at shivohamai.com/services

Software development environment, multiple teams often collaborate on various projects, making version control a critical aspect of the development lifecycle. Auto-generated version control can significantly enhance productivity and ensure seamless integration across teams. This article explores how to implement auto-generated version control using the GrabVer library and demonstrates its importance through practical examples.

The Importance of Auto-Versioning in Corporate Software Development

1. Enhancing Collaboration

Auto-versioning ensures that all team members are on the same page, reducing the risk of conflicts and miscommunications. It allows for instant integration, which is crucial in large organizations where multiple teams depend on each other’s work.

2. Reducing Technical Debt

By automating the versioning process, teams can focus on delivering high-quality code rather than managing version numbers manually. This reduces technical debt and ensures that the codebase remains clean and maintainable.

3. Ensuring Consistency

Auto-versioning helps maintain consistency across different projects and teams. It ensures that all dependencies are up-to-date and that any changes are immediately reflected in the dependent projects.

Where teams produce and consume each other’s libraries, auto-generated versioning ensures instant integration without chaos. This article walks you through how to:

• Apply semantic versioning automatically using GrabVer
• Enable immediate feedback loops between producers and consumers
• Use latest.integration effectively
• Apply all this in real-world projects like:

AssertsCounter

JUnit5Exit

By the end, you’ll not only love auto-versioning but also see why it’s a cornerstone of collaboration and agility in large engineering orgs.

🚨 The Problem: Manual Versioning Slows You Down and bound to errors at Integration time

Imagine a world where:

• Team A builds a reusable test utility.
• Team B consumes it and starts development.
• One day, Team A pushes a bug fix.

But Team B never gets the fix unless someone bumps the version manually, publishes it, and updates the consumer side.

Now scale this across 10s of teams, multiple services, parallel timelines, and non-synced releases. Welcome to Versioning, Merge & Integration Hell!

✅ The Solution: Auto-Versioning with GrabVer

GrabVer is a Gradle plugin that:

• Derives versions from Git history (no manual bumping)
• Supports semver with branches and tags
• Works seamlessly with Maven Central, GitHub Packages, JitPack, etc.

It essentially transforms your build into a version-aware, self-publishing artifact factory.

🎯 Goals of This Article

• Show you how to integrate auto-versioning with GrabVer
• Demonstrate real Gradle Kotlin DSL examples
• Link two real-world projects to show producer-consumer integration
• Highlight CI/CD automation with a single Gradle command

Project Setup: Meet the Producer

Our producer project is AssertsCounter.

It’s a Gradle Plugin that counts JUnit 5 assertions and logs results — a helpful tool for test quality metrics.

Step 1: Add GrabVer to build.gradle.kts

plugins {
    id("java")
    id("eu.davidea.grabver") version "2.0.3"
}

versioning {
    preRelease = "SNAPSHOT"
    saveOn = "publish" // Save version to file only when publishing
}

Step 2: Configure the Group & Publishing

group = "com.shivohamai.cc"
version = versioning.name  // GrabVer generates version!

publishing {
    publications {
        create<MavenPublication>("mavenJava") {
            from(components["java"])
            versionMapping {
                usage("java-api") {
                    fromResolutionOf("runtimeClasspath")
                }
            }
        }
    }
    repositories {
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/nagkumar/java")
            credentials {
                username = System.getenv("GITHUB_ACTOR")
                password = System.getenv("GITHUB_TOKEN")
            }
        }
    }
}

Step 3: Publish with Version Awareness

Run this on every change to auto-publish:

./gradlew clean build test publish

This simple config lets you:

• Auto-bump versions based on commit history or CI context.
• Tag releases automatically.
• Generate pre-releases when testing.

Result?

Instead of maintaining this manually:

version = "1.4.2-alpha-1"

GrabVer can auto-generate:

version = "1.4.3-SNAPSHOT" // on CI, based on your git status

💡 GrabVer detects the current version and assigns a unique semver like 1.0.0-beta+001.

🔁 Enter the Consumer: JUnit5Exit

Your JUnit5Exit project consumes the published AssertsCounter.

Here’s how you connect it:

Add the plugin:

plugins {
    id("asserts-counter-plugin") version "latest.integration"
}

latest.integration tells Gradle: "Get me the most recently published version—even if it's a snapshot."

Fetch Updates Immediately

To ensure you’re consuming the very latest version, run:

gradle --rerun-tasks --refresh-dependencies --no-parallel --stacktrace

⚠️ Without --refresh-dependencies, you might still be using a cached older version!

🧠 Why It Matters in Corporate Engineering

In a large engineering organization with tens or hundreds of developers, the dynamics are different.

Traditional Way (aka Pain):

• Manual versioning
• Missed patches
• Merge conflicts over build.gradle.kts
• CI build flakiness
• QA asking “which version do I test?”

Auto-Versioning Way (aka Sanity):

• Teams produce and publish as they go
• Other teams always consume the latest published version
• No need to “agree” on version numbers
• Git becomes the version source of truth

🧪 Real World Dev Workflow

Dev pushes to main

→ GrabVer computes version 1.2.0+sha1234

CI runs:

gradle clean build test publish

→ Artifact published to GitHub Packages or Maven Central

Another team runs:

gradle --refresh-dependencies

→ Instantly gets the updated lib

🖼️ Image: Auto-Versioning Lifecycle

Imagine a DevOps flow diagram that shows:

💥 Bonus: Zero Merge Conflicts in build.gradle.kts

If every team uses latest.integration, then no one needs to argue over:

- testImplementation("x:lib:1.1.2")
+ testImplementation("x:lib:1.1.3")

Everyone is always aligned with the published truth.

🔚 Final Words

Auto-generated version control is a critical aspect of modern software development, especially in large organizations where multiple teams collaborate on various projects. By implementing auto-versioning using the GrabVer library, you can enhance collaboration, reduce technical debt, and ensure consistency across your projects. If you’re struggling with technical debt or legacy code, consider reaching out to Code Doctorship services for expert assistance.

Auto-generated versioning with GrabVer is not just a “nice to have.” It’s how modern teams integrate seamlessly, avoid drift, and ship confidently.

By connecting producer-consumer workflows with latest.integrationYou ensure:

• Faster feedback
• Sane dependency graphs
• Clean release pipelines

And most importantly — peace of mind for everyone from engineers to execs.

👨‍⚕️ Code Doctorship to treat Your Product CODE Mess

If your org has devs buried under excuses like:

• “We can’t release; it’s not tested.”
• “No one bumped the version.”
• “We have too much tech debt.”
• “Legacy code doesn’t allow this.”

Then it’s time for Code Doctorship.

Visit 👉 www.shivohamai.com/services
We provide:

• Instant assessment of your versioning and publishing processes
• Cleanup of untested legacy libs
• Setup of CI/CD workflows with auto-versioning
• Teaching teams how to be producers, not just consumers

💬 Let’s Talk

If this article resonates with your org’s challenges,
💌 connect with me at shivohamai.com/services
We fix legacy messes. We stop the excuse trains. We empower engineers.

📎 Related Links

• GrabVer on GitHub
• AssertsCounter
• JUnit5Exit
• ShivohamAI Services

☕ Too Much Gradle Scripts, Not Enough Time

Let’s admit it — Gradle build scripts have a reputation. Some love their declarative freedom; others feel like they’ve entered an Indiana Jones booby-trapped cave every time they open build.gradle.kts.

Now picture this: You’ve built a JVM agent — let’s call it acagent — that counts all assert* calls in unit tests (you know, to see if your tests are really verifying the business objects' state). It’s useful, lightweight, and elegant…

Until you try to wire it into every test task of every project using Gradle.

Your nice little agent turns into a scripting nightmare.

I lived this. And that’s why I built a plugin to fix it — and then published both the agent and plugin to Gradle Packages so you don’t have to touch a line of test task of GradlejvmArgs("-javaagent:...") again.

This post walks through:

• 🧠 The pain of duplicating template scripts in each project of Gradle
• 🧪 What acagent does and why it exists
• 🔌 How the plugin simplified everything
• 📦 How I published both to Gradle’s ecosystem like a boss

Let’s start with the mess.

🧨 Gradle Scripting: The Default State of Suffering

You’ve probably seen (or written) code like this:

tasks.test {
    jvmArgumentProviders.add(CommandLineArgumentProvider {
 var dd = configurations.testRuntimeClasspath.get().files.find {
     it.name.contains("asserts-agent")
 }
 listOf("-javaagent:${dd}")
    })
}kot

Sounds simple, right?

But wait… where is agentJar coming from? What if you're using multiple test tasks? What if you need the agent version to match across modules?

Soon you’re playing with:

• configurations.create(...)
• dependencies.add(...)
• .getSingleFile()
• and possibly passing properties from the command line or gradle.properties

And that’s when you’re just trying to run your unit tests.

This was the problem I faced with acagent.
🧰 Building the Plugin: Simplicity Is the Real Power

Plugins are reusable Gradle behaviors. So I turned my JVM agent injection logic into this tiny bit of code:

plugins {
    id("com.shivohamai.testing.tools.junit5.assertscounter.plugin") version "1.0.0"
}

Boom 💥 — no more custom scripts, no need to think about agent paths, nodoFirst, nojvmArgs, no brittle hacks.

🚚 Publishing It All: Agent + Plugin, the Clean Way

Publishing Gradle artifacts — especially plugins — can feel like deciphering ancient runes. But with the right tools, it’s elegant.

The Strategy

I published both:

• asserts-counter-agent – to Maven Central / GitHub Packages
• asserts-counter-plugin – to Gradle Plugin Portal + GitHub Packages

✅ Everything uses the same version number, to keep compatibility simple.

🚚 Tooling Used & Publishing Snippet

a) 🔧 Agent: ACAgent

The original implementation is not built as a Gradle plugin — it’s a standalone Java agent project packaged with plain Gradle (and optional Maven). It uses bytecode transformation and emits output via a shutdown hook, logging the total assertion count.

There’s no Gradle plugin marker artifact or Gradle Plugin Portal publication. Instead, you:

1. Build the agent JAR (`asserts-counter-agent-xx-SNAPSHOT`)
2. Place or publish it in your GitHub Packages artifact repository

No Gradle plugin infrastructure is defined — only building and testing logic for the agent itself.

b) 🔧 Plugin: ACPlugin

🎼 The Conductor: How ACPlugin.kt Orchestrates Everything

Welcome to the heart of our Gradle plugin: the ACPlugin.kt file.

If our plugin were a stage play, this file would be the director. It doesn’t have many lines of its own, but its job is to make sure every other piece of logic performs its role at the exact right time. It’s the main entry point that Gradle calls when a user applies our plugin in their build.gradle.kts file.

Let’s look at the apply method — the "main script" that our director follows. It’s a simple, three-step recipe.

🧠 The Code: ACPlugin.kt

open class ACPlugin : Plugin<Project> {
    override fun apply(aProject: Project) {
        // Step 1: Apply bonus plugins for the user
        AddExtraPlugins().apply(aProject)

        // Step 2: Prepare a special place for our Java Agent
        val lAgentJARConf = prepareAgentJARConf(aProject)

        // Step 3: Find all test tasks and tell them to use the agent
        prepareTestTask(aProject, lAgentJARConf)
    }
}

🛠️ Step 1: AddExtraPlugins() – The Bonus Toolbelt

The first thing our plugin does is give the developer a little something extra.

The AddExtraPlugins class (from AddExtraPlugins.kt) automatically applies two popular community plugins:

• com.github.ben-manes.versions
  ➤ Run ./gradlew dependencyUpdates to see which of your dependencies have new versions.
• se.patrikerdes.use-latest-versions
  ➤ Run ./gradlew useLatestVersions to automatically update your dependencies.

By including these, our plugin becomes a “convention plugin”, bundling helpful tools and saving developers from repetitive update of jars.

🧰 Step 2: prepareAgentJARConf() – A Private Toolbox for the Agent

Next, we prep our Java Agent, a special JAR that can instrument code at runtime.

But we can’t just throw this agent into the project’s regular dependencies. That would:

• Risk version conflicts
• Pollute the user’s classpath

So prepareAgentJARConf (from PrepareAgentJARConf.kt) solves this elegantly.

It creates a private, isolated Gradle Configuration — think of it as a secret toolbox that only our plugin knows about. We place the agent JAR in this toolbox and return a handle to it, safely isolated from the user’s codebase.

🎯 Step 3: prepareTestTask() – The Main Event

With the agent tucked away safely in its private toolbox, it’s time to get to work.

The prepareTestTask function (from PrepareTestTask.kt) performs two crucial jobs:

1. Finds all test tasks
   ➤ It scans the project for every task of type Test.
2. Instruments them
   ➤ For each test task, it appends the -javaagent:<agent-path> argument to the JVM command line — pointing to our previously stored agent.

This is what activates the assertion-counting magic. When the user runs:

gradlew test

… the JVM spins up with our agent attached, ready to count every assertion made during the test run.

🎬 In Summary: A Clean 3-Step Playbook

The ACPlugin class doesn’t do heavy lifting itself. Instead, it acts as a conductor, delegating each responsibility to specialist helpers. Its execution pattern is both clear and extensible:

1. Enhance → Add helpful tools for developers
2. Isolate → Safely prepare the agent
3. Activate → Wire the agent into the test tasks

This clean separation of concerns makes the plugin easier to understand, maintain, and evolve — whether you’re debugging, adding features, or onboarding new contributors.

🎁 Bonus: Want to Add Your Own “Instruments”?

Because of how modular this setup is, adding new functionality — like reporting, dashboards, or alternate agents — is as simple as dropping a new “player” into the orchestra and letting ACPlugin cue them in.

Stay tuned for more behind-the-scenes of how this orchestra plays in perfect harmony. 🎻

🪜 From Script to Plugin: Why It Matters

You might wonder — is it worth making a plugin for something so “small”?

Absolutely. Here’s why:

Plugins are like npm packages for your Gradle world — little reusable spells that prevent madness.

To understand its usage in real projects, refer to how it’s implemented in my other project: sout2log.
You can find more details in this article: Hacking the Console – 3 Sneaky JUnit 5 Tricks to Tame System.out (No Legacy Code Harmed).

🧙‍♂️ Final Words: Plugins = Developer Sorcery

When Gradle Scripts Get Ugly, Write a Plugin: the Clean Way

What started as a neat agent became a shareable plugin, and the journey from scripting to plugin taught me:

• Gradle plugins aren’t just for big infra
• Tiny plugins can vastly improve DX
• If you’re copying 5+ lines across projects, stop and pluginize

📧 Reach Me

Want to improve legacy code maintainability, CI pipelines, or Gradle automation?

Think of me as a Code Doctor. For 20+ years, I’ve helped CxOs and engineers bring old codebases back to life — reviewing over 8 billion lines of code and applying precision tooling to modernize them for the future.

Let’s talk: shivohamai.com | LinkedIn

Ah, the sweet sound of success.

You hit Run Tests, and in mere seconds…

✅ Green Bar. All tests passed. High-fives all around. Ship it!

But wait…

What if I told you that the green bar is lying?

Yes, dear developer. You may be the victim of one of the oldest scams in unit testing history.

The Green Bar Fallacy.

🚨 The Illusion of “Passing” Tests

JUnit is amazing.
It’s the rock-solid foundation beneath countless Java projects. But it has one tiny little flaw:

It doesn’t care whether your test actually tests anything.

Let’s peek at this totally “passing” test:

@Test
void shouldProcessDataWithoutErrors() {
    MyService service = new MyService();
    InputData data = new InputData("test");
    service.process(data);
    // That's it? No asserts? Nothing?
}

When you run this, JUnit nods approvingly.
“One test passed! ✅ as JUnit counts every method annotated as @Test”

But what did it really prove?

• Did we check any results?
• Did we verify the state changed?
• Did we make sure it didn’t do something evil, like delete the database?

Nope.

We just said, “Run this code… and hope for the best.”

It’s like going to a doctor, and the doctor just says:
“You walked in without falling over? Looks like you’re healthy!”

🧟‍♂️ Beware the Zombie Tests

These “assertion-less” tests are everywhere.
Especially in old, sprawling codebases full of patchwork patches and quick fixes.

They haunt your test suite. They pass. Always.

They give a false sense of safety — and worse, your code coverage tools might even say you’re at 100%!

But without assertions, those tests are just… wasting time.

✅ A Better Way: Count Assertions

Forget test count. Forget line coverage.

Want a real measure of test quality?

Count how many assertions actually ran.

That’s it. That’s the whole magic.

If you’ve got 1,000 tests and only 120 assertions, you don’t need more tests — you need better ones.

🤔 “Okay, but… how do I count assertions?”

You could manually sprinkle counters into every assertEquals, assertTrue, and assertThat...

😒 But come on, that’s tedious.

Let’s do it the fun, powerful, JVM-hacking way.
Java Agent to the easy rescue

JVM Magic: Using a Java Agent

A Java Agent is like a secret spellbook.
It lets you change bytecode as classes load — without touching source code!

So here’s the plan:

1. Wait for JUnit’s Assertions class to load.
2. Inject a tiny line of code into every assert method.
3. Increment a counter every time an assertion runs.

Boom! You now have a stealthy assertion counter running across your entire test suite.

Let’s Build the Agent!

1. The Entry Point: AssertsAgent.java

public class AssertsAgent {
    public static void premain(String agentArgs, Instrumentation inst) {
        System.out.println("✅ Starting AssertsAgent to count JUnit 5 assertions...");
        inst.addTransformer(new AssertsTransformer());
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
            System.out.println("-------------------------------------------------");
            System.out.printf("📊 Total JUnit assertions executed: %d%n", AssertsCounter.getCount());
            System.out.println("-------------------------------------------------");
        }));
    }
}

This is the heart of your agent.
It hooks into the JVM before anything runs.

2. The Counter: AssertsCounter.java

import java.util.concurrent.atomic.AtomicInteger;
public class AssertsCounter {
    private static final AtomicInteger counter = new AtomicInteger(0);
    public static void count() {
        counter.incrementAndGet();
    }
    public static int getCount() {
        return counter.get();
    }
}

Simple. Thread-safe. Just does the job.

3. The Transformer: AssertsTransformer.java

This is where the bytecode trickery happens.
We use Javassist to modify the Assertions class.

public class AssertsTransformer implements ClassFileTransformer {
    private static final String JUNIT5_ASSERTIONS_CLASS = "org.junit.jupiter.api.Assertions";
@Override
    public byte[] transform(ClassLoader loader, String className, Class<?> classBeingRedefined,
                            ProtectionDomain protectionDomain, byte[] classfileBuffer) {
        if (!className.replace('/', '.').equals(JUNIT5_ASSERTIONS_CLASS)) {
            return null;
        }
        try {
            ClassPool cp = ClassPool.getDefault();
            CtClass cc = cp.get(JUNIT5_ASSERTIONS_CLASS);
            for (CtMethod method : cc.getDeclaredMethods()) {
                method.insertBefore("com.yourcompany.asserts.AssertsCounter.count();");
            }
            return cc.toBytecode();
        } catch (Exception e) {
            System.err.println("❌ Failed to transform class " + className);
            e.printStackTrace();
            return null;
        }
    }
}

Don’t forget to update the package com.yourcompany.asserts to your actual one.

🛠️ How to Run It

1. Package everything into a JAR (e.g., asserts-agent.jar)
2. Run your tests with jvm org option:

-javaagent:/path/to/asserts-agent.jar

Example Output:

✅ Starting AssertsAgent to count JUnit 5 assertions...
[INFO] Tests run: 6, Failures: 0
-------------------------------------------------
📊 Total JUnit assertions executed: 17
-------------------------------------------------

testing\junit5\assertcounter\AssertsAgent>gradle --rerun-tasks clean jar test
=== Assert Method Usage Report ===
com.shivoham.tools.junit5.assertcounter.tests.TestAssertJAsserts#assertJAssertionsLoop : 1
org.assertj.core.api.Assertions#assertThat                   : 150
org.assertj.core.api.AssertionsForClassTypes#assertThat      : 150
org.hamcrest.MatcherAssert#assertThat                        : 30
org.junit.jupiter.api.AssertEquals#assertEquals              : 23
org.junit.jupiter.api.AssertFalse#assertFalse                : 23
org.junit.jupiter.api.AssertNotEquals#assertNotEquals        : 23
org.junit.jupiter.api.AssertNotNull#assertNotNull            : 23
org.junit.jupiter.api.AssertTrue#assertTrue                  : 23
org.junit.jupiter.api.Assertions#assertEquals                : 23
org.junit.jupiter.api.Assertions#assertFalse                 : 23
org.junit.jupiter.api.Assertions#assertNotEquals             : 23
org.junit.jupiter.api.Assertions#assertNotNull               : 23
org.junit.jupiter.api.Assertions#assertTrue                  : 23
-------------------------------------------------------
Total assert* method calls: 561

> Task :test
🔍 Test Summary:
 - 3 tests executed
 - 3 succeeded
 - 0 failed
 - 0 skipped

Just like that — you’re seeing your real test signal.

Pro Tip: Fail If Total Assertions in the build are == 0

Want to catch empty test files automatically?

Add a post-test check. If assertion count == 0, fail the build.

Because a test suite with 500 empty tests isn’t quality — it’s cargo cult testing.

🎯 Why This Matters

Tests aren’t about running code.
They’re about verifying it behaves correctly.

A test without an assertion is just a demo.

By counting assertions, you’re measuring actual verification, not just motion.

But Wait… Assertion Count Can Lie Too?

So, we’ve added an agent that counts assertions. We feel good. The green bar is no longer tricking us.

But then… someone does this:

@Test
void shouldAlwaysPass() {
    assertTrue(true);  // 🙄 Come on, man.
}

Or worse:

assertEquals("", "", "empty");  // What are we even verifying here?

👉 These assertions are syntactically fine, but semantically useless.

This is like installing a smoke detector — and gluing the “no fire” light on.

So yes, even assert count can lie if the assertions are meaningless.

We’ve traded one false sense of security for another.

🧠 Next Level: Expression-Aware Assertion Analysis (Agent++)

Here’s where things get really cool (and a little nerdy):

We can enhance our Java Agent to not just count assertions but also log what was being asserted.

Think of it like:

• ✅ assertEquals(expected, actual) — Okay, real test!
• ❌ assertTrue(true) — Throw this into the trash.
• ❓ assertNotNull("string") — Hmm, maybe, but suspicious.

To do this, we can:

• Use Javassist or ASM to capture method arguments.
• Log the types, constants, and maybe even stringified expressions being asserted.
• Flag suspicious patterns like:
• assertEquals("some literal", "some literal")
• assertTrue(true)
• assertNotNull("abc")

Yes, this isn’t trivial — we’re not working with source code but bytecode — but with some clever stack tracing and class metadata, we can get a lot of insight.

Imagine a test report that not only says “You ran 37 assertions,” but also warns:
“⚠️ 12 of them are useless.”

Boom. Assertion quality meets observability.

🔥 Coming Soon from #CodeDoctors…

We’re cooking up an extended version of this agent — let’s call it AssertsAgent++ — that doesn’t just count assertions, but audits them:

• Flags suspicious patterns
• Shows assertion intent
• Offers insights into testing quality beyond the numbers

If that sounds like magic, you need it in your CI/CD pipeline…
Well, you know where to find us. 💬

📎 Full Working Code

You can get the full source code right here:
👉 https://github.com/nagkumar/java/tree/main/tutorials/testing/junit5/AssertsCounter/ACAgent

🩺 PS: Need Help with Legacy Code?

Old code is tricky. Assertion-less tests are just the beginning.
That’s where #CodeDoctors come in.

We specialize in:

• Diagnosing untestable code
• Curing flaky test suites
• Making legacy code maintainable again

Want your code to be robust, testable, and future-ready?

Reach out to us! http://www.shivohamai.com/services

You maintain a critical piece of legacy code. It’s a mysterious, powerful beast that runs in production, but it has one terrifying feature:
➡️ It communicates exclusively through System.out.println and System.err.println.

There are no log files, no structured events — just a firehose of strings sprayed directly to the console.

Your mission, should you choose to accept it, is to write meaningful unit tests for this code. The catch?

You are not allowed to change a single line of the original source.

How can you possibly test something that you can’t see, hear, or touch?
How do you assert that the correct "User saved successfully" message was printed, or that a specific error was sent to System.err?

Fear not!
With JUnit 5, you have several powerful techniques at your disposal. Today, we’ll unlock three of them, from the classic manual approach to the elegant, modern solution.

🔍 The Core Problem: Why Is System.out So Hard to Test?

System.out and System.err are global, static PrintStream objects.
They are a shared resource across the entire JVM.

In a test environment, this means any output from your code: — goes into the same black hole as the output from your build tool, — other tests, — and the JVM itself.

👉 You can’t easily isolate and inspect the specific strings your method printed.

Our goal?

Intercept this output before it reaches the console.

Let’s dive in 👇

✅ Method 1: The Classic Redirect (Pure JUnit 5)

This is the foundational, do-it-yourself approach — no dependencies involved.

🧠 The Concept

1. Before the test: Save the original System.out and System.err.
2. Replace them with a ByteArrayOutputStream, which acts like a memory buffer.
3. Run the test: The legacy code prints to your in-memory buffer.
4. After the test: Assert the buffer contents and restore the original streams.

🧾 Legacy Code

// src/main/java/com/example/legacy/LegacyApp.java
public class LegacyApp {
    public void run(boolean succeed) {
        if (succeed) {
            System.out.println("SUCCESS: Operation completed.");
        } else {
            System.err.println("ERROR: Operation failed.");
        }
    }
}

✅ Test Code

// src/test/java/com/example/legacy/sys/LegacyAppTest.java
import org.junit.jupiter.api.*;
import java.io.ByteArrayOutputStream;
import java.io.PrintStream;
import static org.junit.jupiter.api.Assertions.assertEquals;

class LegacyAppTest {
    private final ByteArrayOutputStream outContent = new ByteArrayOutputStream();
    private final ByteArrayOutputStream errContent = new ByteArrayOutputStream();
    private final PrintStream originalOut = System.out;
    private final PrintStream originalErr = System.err;

    @BeforeEach
    void setUpStreams() {
        System.setOut(new PrintStream(outContent));
        System.setErr(new PrintStream(errContent));
    }

    @AfterEach
    void restoreStreams() {
        System.setOut(originalOut);
        System.setErr(originalErr);
    }

    @Test
    void testSuccessOutput() {
        new LegacyApp().run(true);
        assertEquals("SUCCESS: Operation completed.\n", outContent.toString());
        assertEquals("", errContent.toString());
    }

    @Test
    void testErrorOutput() {
        new LegacyApp().run(false);
        assertEquals("ERROR: Operation failed.\n", errContent.toString());
        assertEquals("", outContent.toString());
    }
}

👍 Pros

• ✅ Zero dependencies
• ✅ Easy to understand

👎 Cons

• ❌ Boilerplate in every test class

🔁 Method 2: The Log4j Bridge

What if you could treat System.out.println like a proper logging event?

This method redirects system streams to a Log4j logger, allowing you to use logging tools to test legacy code as if it had real log messages.

🧠 The Concept

1. Create a custom PrintStream that calls logger.info() or logger.error() instead of printing.
2. Redirect System.out and System.err to it.
3. Use a Log4j test appender to capture log events and assert them.

🛠 Bridge Class

// src/main/java/com/example/legacy/log/LoggingOutputStream.java
import org.apache.logging.log4j.Logger;
import java.io.OutputStream;
import java.io.PrintStream;

public class LoggingOutputStream extends PrintStream {
    private final Logger logger;

    public LoggingOutputStream(Logger logger, OutputStream out) {
        super(out);
        this.logger = logger;
    }

    @Override
    public void println(String line) {
        logger.info(line); // or logger.error based on stream
    }
}

✅ Test Code (Using Log4j’s ListAppender)

// src/test/java/com/example/legacy/log/LegacyAppLog4jTest.java
import org.apache.logging.log4j.*;
import org.apache.logging.log4j.core.Appender;
import org.apache.logging.log4j.core.layout.PatternLayout;
import org.apache.logging.log4j.test.appender.ListAppender;
import org.junit.jupiter.api.*;

import java.io.PrintStream;

import static org.assertj.core.api.Assertions.assertThat;

class LegacyAppLog4jTest {
    private static final Logger testLogger = LogManager.getLogger(LegacyAppLog4jTest.class);
    private static ListAppender listAppender;
    private static final PrintStream originalOut = System.out;

    @BeforeAll
    static void setup() {
        listAppender = new ListAppender("List", null,
                PatternLayout.createDefaultLayout(), false, false);
        listAppender.start();

        ((org.apache.logging.log4j.core.Logger) testLogger).addAppender(listAppender);

        System.setOut(new LoggingOutputStream(testLogger, originalOut));
    }

    @AfterAll
    static void tearDown() {
        System.setOut(originalOut);
    }

    @BeforeEach
    void clearAppender() {
        listAppender.clear();
    }

    @Test
    void testSuccessIsLoggedAsInfo() {
        new LegacyApp().run(true);
        assertThat(listAppender.getMessages())
            .hasSize(1)
            .contains("SUCCESS: Operation completed.");
    }
}

👍 Pros

• ✅ Treats System.out as real log events
• ✅ Treats System.erras real log events, by using System.setErr()
• ✅ Plays well with modern log pipelines

👎 Cons

• ❌ Higher setup complexity
• ❌ Requires Log4j internals knowledge

⚡ Method 3: The Modern SLF4J Way (With System-Lambda)

This is the cleanest and most maintainable solution.

It uses the System Lambda library to intercept and return output from System.out/System.err via lambdas.

🧠 The Concept

Wrap your test code in a lambda.
The library: — redirects the stream, — runs your code, — captures the output, — restores the stream.

All in one call.

🛠 Gradle Dependency

testImplementation("com.github.stefanbirkner:system-lambda:1.2.1")

✅ Test Code

// src/test/java/com/example/legacy/lambda/LegacyAppLambdaTest.java
import com.github.stefanbirkner.systemlambda.SystemLambda;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;

class LegacyAppLambdaTest {

    @Test
    void testSuccessOutputWithLambda() throws Exception {
        String output = SystemLambda.tapSystemOut(() -> {
            new LegacyApp().run(true);
        });
        assertEquals("SUCCESS: Operation completed.\n", output);
    }

    @Test
    void testErrorOutputWithLambda() throws Exception {
        String error = SystemLambda.tapSystemErr(() -> {
            new LegacyApp().run(false);
        });
        assertEquals("ERROR: Operation failed.\n", error);
    }
}

👍 Pros

• ✅ Beautifully concise
• ✅ Zero boilerplate
• ✅ Foolproof redirection and restoration

👎 Cons

• ❌ Requires adding a lightweight library

🧠 Comparison Summary

💬 Final Thoughts

Testing legacy code doesn’t have to be a nightmare.

By intercepting the console output, you can bring even the most ancient, logging-challenged code under the safety of a modern test harness.

Don’t rewrite legacy — wrap and test it cleverly till you take control of legacy with these kind of test cases safety net.

🧪 Need Help With Legacy Code?

If your codebase talks in printlns, hides behind static methods, or screams “don’t touch me!” in every commit — you’re not alone.

Come talk to the #CodeDoctors 🧑‍⚕️💻 — specialists in testability, observability, maintainability, and any NFRs related to legacy systems.

Whether it’s: — modernizing untestable logic, — introducing clean logging patterns, — or designing safe refactors…

We help you stabilize, simplify, and scale without a risky rewrite.

👉 DM us at ShivohamAI — or leave a comment. Let’s tame your legacy beast together.

GitHub Repo CODE:
https://github.com/nagkumar/java/tree/main/tutorials/testing/junit5/logs/sys2log/sys2log

#Java #JUnit5 #Testing #SystemOut #LegacyCode #CleanCode #CodeDoctors #ShivohamAI #SoftwareCraftsmanship

Introduction

Imagine you’re testing a legacy Java application, and BAM! — the application calls System.exit(1) during a test in a test suite that have 100s of testcases.

Just like that, your entire test suite halts. No logs. No cleanup. No mercy. In Gradle, one may see build failure with misleading exception info

[Incubating] Problems report is available at: file:///junit5exit_hw/build/reports/problems/problems-report.html
FAILURE: Build failed with an exception.
* What went wrong:
Could not determine the dependencies of task ':test'.
> Could not resolve all dependencies for configuration ':testRuntimeClasspath'.
   > Failed to calculate the value of task ':compileTestJava' property 'javaCompiler'.
      > Cannot find a Java installation on your machine (Windows 11 10.0 amd64) matching: {languageVersion=24, vendor=any vendor, implementation=vendor-specific, nativeImageCapable=false}. Toolchain download repositories have not been configured.
* Try:
> Learn more about toolchain auto-detection and auto-provisioning at https://docs.gradle.org/8.14.1/userguide/toolchains.html#sec:auto_detection.
> Learn more about toolchain repositories at https://docs.gradle.org/8.14.1/userguide/toolchains.html#sub:download_repositories.
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.

Deprecated Gradle features were used in this build, making it incompatible with Gradle 9.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

For more on this, please refer to https://docs.gradle.org/8.14.1/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.
BUILD FAILED in 1s

The Gradle build logs above are unrelated to the core problem. When the main code executes System.exit(), it terminates the entire Java Virtual Machine process, which includes both the test execution environment and the Gradle build process.

Welcome to the wild world of testing legacy code that was never meant to be tested.

In this article, we’ll unravel the mystery of how System.exit(...) in main app code does not impact unit tests using tginsberg/junit5-system-exit library, also look at the evolution of solutions around these testability problems of the code under test. I shall explore how the framework works, and top it off with why your codebase might be crying out for some professional Code Doctorship from ShivohamAI.

And yes, we’ll have some AI fun along the way. 🧠🤖

The Problem: Why System.exit() is a Test Killer

When System.exit() is invoked, the JVM process terminates. This might make sense in production (e.g., to signal an unrecoverable error), but it’s disastrous during tests.

public class App {
    public static void main(String[] args) {
        if (args.length == 0) {
            System.exit(1); // 👋 Bye bye, JVM
        }
    }
}

Try testing this with JUnit 5, and you’ll watch your test runner vanish like Thanos just snapped. 🫰💀

Legacy Solutions: History of System.exit() Handling

1. Don’t Test It (aka the Ostrich Strategy 🐦🕳️)

• Pretend it doesn’t need testing.
• Hope no bugs exist in those exit paths.

Pro: Easy to be unprofessional.

Con: You have no idea what your app does when it exits. Dangerous in production!

2. Refactor Everything

• Inject a wrapper for System.exit() and test using mocks.

interface ExitHandler { void exit(int status); }

Pro: Clean, testable.

Con:

Massive refactor. Good luck doing this in legacy code. 😵

3. SecurityManager Hacks (JUnit 4 Era)

System.setSecurityManager(new NoExitSecurityManager());

Pro: It worked.

Con: Deprecated and now depricated from JDK 17+, and completely removed from JDK 24

4. Enter the Hero: junit5-system-exit

junit5-system-exit is a library that intercepts calls to System.exit() without requiring a SecurityManager and also does not require you to make any changes to legacy code. Instead, it uses bytecode instrumentation to rewrite exit behavior during tests.

How It Works (Magic Alert!) ✨

Under the hood, it works in a few clever steps:

1. Instrumentation Setup: A JUnit 5 extension is used to bootstrap a Java agent (ExitInterceptingAgent) at runtime.
2. Bytecode Rewrite: The agent finds all System.exit() calls and replaces them with a call to throw a special unchecked exception (ExitException) during the test.
3. Assertion Hooks: You can then use the injected SystemExit object to expect specific exit codes.
4. Safety Net: The JVM doesn’t really exit, but behaves like it did. No threads are killed. Test continues.

⚙️ Think of it like replacing your app’s self-destruct button with a harmless confetti cannon during tests. 🎉

This approach works reliably as long as the instrumentation is allowed access to required classes (e.g., java.lang.Runtime). That's why --add-opens flags are needed in JDK 17+.

You can view a HelloWorld working GitHub code reference here: junit5exit_hw. It demonstrates how to wire everything correctly and validate System.exit(...) behaviors cleanly.

Let’s Code: Writing a Test That Handles System.exit

Here’s a basic example:

import com.ginsberg.junit.exit.ExpectSystemExit;
import com.ginsberg.junit.exit.SystemExit;
import org.junit.jupiter.api.Test;

public class ExitAppTest {

 @Test
    @ExpectSystemExitWithStatus(42)
    void testSystemExit()
    {
         new HelloWorld().sayHelloAndExit();
    }

    @Test
    @ExpectSystemExitWithStatus(42)
    void testSystemExit2() throws InterruptedException
    {
         new Thread(() -> {
             new HelloWorld().sayHelloAndExit();
           }).start();

         Thread.sleep(1000);  // Give it some time to execute
    }
}

💡 Key Points:

• ExpectSsytemExitWithStatus argument allows you to expect and assert the exit status.

Diagrams: What Happens Behind the Scenes

Before:

App.main()
   |
System.exit(1)
   |
 JVM Dies 💀

After using junit5-system-exit:

App.main()
   |
System.exit(1)
   |
Exit call intercepted! ➡️ Exception thrown
   |
Test catches it! ✅

Pros & Cons of junit5-system-exit

✅ Pros

• ✅ No need to refactor legacy code
• ✅ No SecurityManager dependency
• ✅ Supports exit status assertions too
• ✅ Works well with JUnit5 and modern JVMs (with --add-opens)

⚠️ Cons

• ⚠️ Relies on bytecode transformation (can be brittle if JVM internals change)
• ⚠️ May not work out-of-the-box with all build tools or future JVM versions

When Things Break: Common Pitfalls

🛑 Forgot --add-opens

JVMs with strong encapsulation (JDK 17+) will refuse access unless explicitly allowed.

🛑 Conflict with Other Bytecode Libraries

junit5-system-exit uses ASM under the hood. If your codebase or plugins use a different ASM version, override like this:

dependencies {
    testImplementation("com.ginsberg:junit5-system-exit:2.0.2")
    testImplementation("org.ow2.asm:asm:9.8") // Force latest
}

Fun With AI: Meet ExitBot 🤖

“I used to crash JVMs for fun… Now I’m just a misunderstood method.”

ExitBot is our AI mascot who used to end test suites with a bang.

Now, thanks to junit5-system-exit, ExitBot's aggression is tamed:

@Test
@ExpectSystemExit
void testWithExitBot() {
    System.exit(0);
}

Real World Use Case: Legacy Financial App

A ShivohamAI client had 2500+ legacy JUnit 4 tests, more than 180+ of which invoked CLI tools with System.exit(1) for bad inputs. Migrating them was a nightmare — until we introduced junit5-system-exit.

🔧 Results:

• 96% such tests migrated to JUnit 5 in 1 week and another 1 week for testing
• Zero production changes required
• Full test coverage achieved for critical exit paths

Call to Action: Why ShivohamAI?

Legacy code is filled with dragons:

• System.exit() everywhere
• Static utilities
• Magic constants
• Old JUnit 3/4 + manual asserts
• Old JDK8 to latest JDK Migrations
• Too many manual steps to build and release
• Build taking hours
• You have too many branches to maintain

At ShivohamAI, we act as Code Doctors:

🩺 Diagnose dev & test pain points
💉 Prescribe modern tools and migration strategies
🚀 Deliver transformed test suites that work without drama

Need a second opinion on your legacy tests? Call the Code Doctors.

Conclusion: Exit without Cry🚪✅

Testing System.exit() doesn't have to be scary. With the right tools, modern JVM flags, and a bytecode touch of magic, you can regain control of your test suite.

Use junit5-system-exit to:

• Intercept exits safely
• Assert exit codes
• Avoid risky refactorings, especially when there are no tests

You can also start with the HelloWorld reference project to see everything wired and working.

And if your codebase feels like a haunted mansion of tech debt, ShivohamAI is ready with a stethoscope and a scalpel.

Expert testing practices can save teams from layoffs by addressing the legacy complexity that’s causing customer loss. 💚

For the need for speed and cheap, developers rely heavily on open-source libraries and frameworks. But every third-party dependency you include can silently introduce serious vulnerabilities into your project, as each may further depend on other open-source libraries and frameworks.

That’s where OWASP Dependency-Check comes in.

It doesn’t just list your dependencies — it checks them against the National Vulnerability Database (NVD) to find known security issues (CVEs) against the specific version of dependency used by the project/module.

🔧 What Is Dependency-Check and Why Use It?

Dependency-Check is an open-source security tool that:

• Scans your project’s dependencies (Java JARs — maven, gradle, npm packages, Python modules, etc.)
• Identifies their Common Platform Enumeration (CPE)
• Cross-reference these against the NVD to find known CVEs

✅ Why It’s Critical

• Detects vulnerabilities like Log4Shell before deployment
• Integrates into CI/CD pipelines to enforce shift-left security
• Free and open-source, supporting multiple languages and ecosystems

But there’s one issue…

Without an NVD API key, your scans are slow, rate-limited, and sometimes incomplete.

📙 What Is the NVD?

The National Vulnerability Database (NVD) is the U.S. government’s repository of standardized vulnerability data, maintained by NIST.

When a vulnerability like CVE-2021-44228 (Log4Shell) is discovered:

• It gets cataloged in the NVD
• It is assigned a severity score (CVSS), impact description, and remediation info

Dependency-Check queries this database to assess whether your dependencies are affected.

⏱️ Why It Gets Slow Without an API Key

The NVD REST API is rate-limited to prevent abuse:

Mode Rate Limit (approx.) No API Key ~1.5 requests per second With API Key 5 to 10+ requests per second

Without an API key, you hit these endpoints anonymously:

https://services.nvd.nist.gov/rest/json/cves/2.0

• You’re severely throttled
• Scans take 5x to 10x longer

⏳ Real-World Example

Java project with 120 dependencies:

Without API Key:

• ~730 CVE lookups
• ~24 minutes, includes throttling

With API Key:

• Same 730 lookups
• ~4–5 minutes

In real world these looks are much more as high as 300k

🔑 How to Get Your NVD API Key (Free!)

Getting a key is easy and free:

1. Visit: https://nvd.nist.gov/developers/request-an-api-key
2. Enter your name and email

Receive your API key instantly

Use It in Dependency-Check:

export NVD_API_KEY=your_key_here

Or in your CI/CD settings:

dependency-check --project myapp --scan ./target --nvdApiKey $NVD_API_KEY

⚖️ Is the NVD API Key Free?

Yes. 100% free.

Feature Cost NVD API Key ✅ Free OWASP Dependency-Check ✅ Free, open-source Rate limit bump ✅ Free

Provided by the U.S. government for public security awareness.

🚫 What If Your Key Gets Leaked?

❌ If a hacker gets your key:

• They can consume your rate quota
• They can’t use it to hack systems (it’s read-only)
• NIST may throttle or revoke it if abuse is detected

✅ What to Do:

• Email: nvd@nist.gov
• Request revocation and reissue
• Include your key and reason (e.g., exposed in GitHub)

⏲ Does the Key Expire?

• No fixed expiration as of now
• Rotate periodically for hygiene

💼 Can Organizations Have Multiple Keys?

Yes, but with caution:

• Multiple people can request keys (one per team/env)
• Don’t rotate keys to bypass rate limits — NIST monitors abuse

Best Practices:

• One key per environment/team
• Store in CI/CD secrets or env vars
• Monitor usage, rotate if leaked

❓ FAQ Recap

Question Answer

Is the NVD API key free? ✅ Yes
Can I use multiple keys? ✅ Yes, but don’t abuse
Can it be used to hack? ❌ No, it’s read-only public data
How do I get a new key? Request via NVD form or email
Does the key expire? ❌ Not currently

⚙️ How to Configure NVD API Key in Your Gradle Build

To make sure Dependency-Check uses your NVD API key during scans (and thus speeds up lookups), you need to pass the key to the plugin.

Step 1: Add the Dependency-Check Gradle Plugin

In your build.gradle file, include:

plugins {
    id "org.owasp.dependencycheck" version "12.1.1"  // Use latest version
}

Or if using the older buildscript style:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath "org.owasp:dependency-check-gradle:12.1.1"
    }
}

apply plugin: "org.owasp.dependencycheck"

Step 2: Set Your NVD API Key in the Gradle Configuration

There are multiple ways, but the simplest and recommended one is to set the API key as a system environment variable and then configure the plugin to pick it up.

Option A: Pass via Environment Variable

In your shell/CI environment:

export NVD_API_KEY=your_actual_api_key_here

Then in build.gradle:

dependencyCheck {
    nvd.apiKey = System.getenv('NVD_API_KEY')
    failBuildOnCVSS = 7.0  // example: fail if CVSS >= 7
    suppressionFile = 'dependency-check-suppressions.xml' // optional
    formats = ['HTML', 'XML']  // report formats
}

Option B: Directly Embed in build.gradle (not recommended for security reasons)

dependencyCheck {
    nvdApiKey = 'your_actual_api_key_here'
}

Warning: Avoid committing API keys directly into source code. Use environment variables or CI/CD secret management tools instead.

Step 3: Run Dependency-Check

Run the scan with:

./gradlew dependencyCheckAnalyze --info

This will:

• Use your NVD API key to authenticate requests,
• Speed up your CVE lookups,
• Generate reports in the configured formats.

Additional Tips

• In CI/CD pipelines, inject the API key as an environment variable securely.
• Keep your dependency-check plugin updated for best compatibility with the NVD API.
• Use failBuildOnCVSS to enforce security gates.

🔍 Final Thoughts

Dependency-Check is your early warning system for security risks hiding in your software dependencies. But to make it effective:

Use an NVD API key. It’s free, safe, and makes your scans 5–10x faster.

Set it up today and keep your software supply chain secure — without slowing down your developers.

Assistant used by the Author to write this article: #ChatGPT

Questions or tips or Blame #ChatGPT :) ?

…drop them in the comments!

In the era of CI/CD (Continuous Integration/Continuous Delivery), build scripts have become crucial components of software development. However, as projects grow in complexity, build scripts can become convoluted and burdened with technical debt. To address this issue, adopting clean code practices and refactoring techniques can greatly improve the maintainability and efficiency of Maven build scripts. This article explores how to deal with Maven scripts by promoting script and source code reuse across multiple modules (maven scripts refactoring).

Maven, a popular build automation tool, simplifies and standardizes the build process by following a convention-over-configuration approach. It promotes best practices and encourages project organization and dependency management.

A Maven build script, often referred to as a POM (Project Object Model) script, is an XML file that defines the configuration and dependencies of a Maven-based project. It serves as the backbone of the project’s build process, providing instructions for compiling source code, managing dependencies, running tests, and packaging the project for distribution.

One of the key advantages of Maven is its ability to reuse build scripts across multiple projects. This reuse reduces redundancy, improves maintainability, and helps eliminate technical debt in build scripts. Technical debt refers to the accumulated work needed to fix or improve a project’s codebase and infrastructure due to suboptimal or outdated practices.

By leveraging reusable Maven build scripts, organizations can achieve the following benefits:

1. Consistency: Reusing a standardized build script across projects ensures consistency in the build process. Developers familiar with Maven can easily understand and work on different projects that follow the same structure and conventions.
2. Simplified Dependency Management: Maven handles dependency management seamlessly. By reusing a common build script, developers can consistently specify project dependencies, ensuring that the correct versions are used across projects. This eliminates the need for manual tracking and management of dependencies, reducing the chances of version conflicts or compatibility issues.
3. Efficiency: Reusing Maven build scripts saves time and effort. Instead of starting from scratch for each project, developers can leverage preconfigured build scripts that already include commonly used plugins, build profiles, and other essential configurations. This accelerates project setup and reduces the time spent on repetitive build-related tasks.
4. Standardization and Best Practices: Maven promotes standardization and encourages the adoption of best practices. Reusing Maven build scripts ensures that projects follow consistent build processes, coding conventions, and quality assurance practices. This leads to cleaner code, easier collaboration among developers, and improved overall project quality.
5. Easy Maintenance and Updates: When a common build script is updated to incorporate new practices, security fixes, or enhancements, all projects that reuse that script can benefit immediately. It simplifies the process of adopting improvements or addressing issues across multiple projects, reducing technical debt associated with outdated or inefficient build scripts.

In Maven, there are two essential tags that enable the sharing of scripts and code across projects: <packaging> and <packaging>.

a) packaging

<packaging>: The <packaging> tag defines the type of artifact that a Maven project produces. It specifies the packaging format, such as JAR, WAR, POM, etc.

1. Preparing for Inheritance of Maven Script

The <packaging>pom</packaging> value is used for a POM project, indicating that the project is intended to inherited by other modules so that all dependencies, configurations, variables, plugins, etc need not be repeated in the child module as they are straight coming from the parent.

Also, the packaging tag value as pom does not compile the source and test code that may exist in the same module. This way any code that needs to be shared at compile time code level dependency has to be of package type pom.

2. Preparing such pom package module to share the source code

In order for source code that is present in cmn pom packaged module to be used by its children, make sure add this special script that share src & resources directories of both main and test code.

    <build>
 <plugins>
     <plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>build-helper-maven-plugin</artifactId>
  <version>3.0.0</version>
  <executions>
      <execution>
   <phase>generate-sources</phase>
   <goals>
       <goal>add-source</goal>
   </goals>
   <configuration>
       <sources>
    <source>${cmn.src}/main/java</source>
       </sources>
   </configuration>
      </execution>
      <execution>
   <id>add-resource</id>
   <phase>generate-resources</phase>
   <goals>
       <goal>add-resource</goal>
   </goals>
   <configuration>
       <resources>
    <resource>
        <directory>${cmn.src}/main/resources</directory>
    </resource>
       </resources>
   </configuration>
      </execution>
      <execution>
   <id>add-test-source</id>
   <phase>generate-test-sources</phase>
   <goals>
       <goal>add-test-source</goal>
   </goals>
   <configuration>
       <sources>
    <source>${cmn.src}/test/java</source>
       </sources>
   </configuration>
      </execution>
      <execution>
   <id>add-test-resource</id>
   <phase>generate-test-resources</phase>
   <goals>
       <goal>add-test-resource</goal>
   </goals>
   <configuration>
       <resources>
    <resource>
        <directory>${cmn.src}/test/resources</directory>
    </resource>
       </resources>
   </configuration>
      </execution>
  </executions>
     </plugin>
 </plugins>
    </build>

It configures the “build-helper-maven-plugin” plugin to handle various source and resource directories in different phases of the build process.

b) parent

<parent>: The <parent> tag specifies the parent project from which the current project should inherit configurations. It allows a project to inherit properties, dependencies, build settings, and other configurations from a common parent project. The <parent> tag establishes a hierarchical relationship between projects, enabling shared configurations and reducing redundancy.

<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
 <groupId>com.teja</groupId>
 <artifactId>cmn</artifactId>
 <version>0.0.10</version>
 <relativePath>../cmn/pom.xml</relativePath>
    </parent>
    <artifactId>dc</artifactId>
    <dependencies>
 <dependency>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-docker-compose</artifactId>
 </dependency>
    </dependencies>
</project>

The <parent> element defines the parent project from which the current project inherits its configuration.

• <groupId>: Specifies the group ID of the parent project.
• <artifactId>: Specifies the artifact ID of the parent project.
• <version>: Specifies the version of the parent project.
• <relativePath>: Specifies the relative path to the parent POM file. In this case, it points to ../cmn/pom.xml.

Verification

The best way to verify sanity of the relationship is go to child module directory and issue command mvn help:evaluate

>mvn help:evaluate

This opens up REPL where you could type the expression ${cmn.src}

Which in my case solves the parent property value to xxx\dctc\intg\cmn\pom.xml/../src

One could also look for depencides of this module if it includes parent script ones is by issue of command mvn dependency:tree

In order to see source code paths used by the child modules, run the command

mvn clean install -X > output.txt

open the output.txt to view something like this

[DEBUG] Source roots:
[DEBUG]  \dctc\intg\dc\src\main\java
[DEBUG]  \dctc\intg\cmn\pom.xml\..\src\main\java
[DEBUG]  dctc\intg\dc\target\generated-sources\annotations

Also watch for these lines, that contain parents resources directory added

 Configuring mojo execution 'org.codehaus.mojo:build-helper-maven-plugin:3.0.0:add-source:default' with basic configurator -->
[DEBUG]   (f) project = MavenProject: com.teja:dc:0.0.10 @ dctc\intg\dc\pom.xml
[DEBUG]   (f) sources = [dctc\intg\cmn\pom.xml\..\src\main\java]
[DEBUG] -- end configuration --
[INFO] Source directory: dctc\intg\cmn\pom.xml\..\src\main\java added.
[INFO] 
[INFO] --- build-helper:3.0.0:add-resource (add-resource) @ dc ---
[DEBUG] Loading mojo org.codehaus.mojo:build-helper-maven-plugin:3.0.0:add-resource from plugin realm ClassRealm[plugin>org.codehaus.mojo:build-helper-maven-plugin:3.0.0, parent: jdk.internal.loader.ClassLoaders$AppClassLoader@4e0e2f2a]
[DEBUG] Configuring mojo execution 'org.codehaus.mojo:build-helper-maven-plugin:3.0.0:add-resource:add-resource' with basic configurator -->
[DEBUG]   (f) project = MavenProject: com.teja:dc:0.0.10 @ dctc\intg\dc\pom.xml
[DEBUG]   (s) directory = dctc\intg\cmn\pom.xml/../src/main/resources
[DEBUG]   (f) resources = [Resource {targetPath: null, filtering: false, FileSet {directory: dctc\intg\cmn\pom.xml/../src/main/resources, PatternSet [includes: {}, excludes: {}]}}]
[DEBUG] -- end configuration --
[DEBUG] Added resource: dctc\intg\cmn\pom.xml/../src/main/resources
[INFO] 
[I

One other advantage of using the parent tag in Maven’s pom.xml file is that dependencies belonging to the same group as the parent do not need to provide a version number. The version number specified in the parent tag is automatically used for those dependencies.

For example, consider the following configuration:

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>my-project</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.0</version>
        <relativePath/>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-docker-compose</artifactId>
        </dependency>
    </dependencies>
</project>

In this example, the parent tag specifies the Spring Boot Starter Parent as the parent project, with a version number of 3.1.0. The <dependencies> section includes a dependency on spring-boot-docker-compose, which belongs to the same group (org.springframework.boot).

Since the parent version is defined, the version number for the spring-boot-docker-compose dependency does not need to be explicitly specified. Maven will automatically use the version defined in the parent tag (3.1.0 in this case).

This simplifies the configuration and helps ensure that all dependencies within the same group use the compatible versions defined by the parent. It also makes it easier to manage and update dependencies in the future, as you can simply update the version number in the parent tag, and all the dependencies within that group will inherit the new version.

Conclusion

By combining these two tags, Maven projects can achieve effective sharing and reuse of build script properties, configurations, and more.

• The <packaging>pom</packaging> indicates that a project is focused on managing and sharing configurations rather than producing a deployable artifact.
• The <parent> tag references the parent project that contains the shared configurations, defining the inheritance relationship and enabling the child project to inherit those configurations.

With this combination, Maven projects can effectively eliminate technical debt in build scripts by centralizing and reusing common configurations, dependencies, and build logic. Changes made in the parent project automatically propagate to the child projects, promoting consistency and reducing duplication.

About

Considering the significant opportunity loss caused by the complexities and inefficiencies in your Ant, Maven, Gradle, and Bazel scripts, it is crucial to take proactive steps to address the situation. Tejasoft, with its extensive experience of over 20 years and expertise in dealing with 2.3 billion lines of code across various technology stacks, offers an innovative solution to fix the code mess. We are the pioneers in applying a unique Code Factory work style, capable of transforming dirty tech debt-ridden code into clean, maintainable code with remarkable automation.

By engaging Tejasoft’s services, you can leverage our deep knowledge and automated code transformation capabilities to alleviate the burden of technical debt and unlock the true potential of your products in any tech stack. With a proven track record and commitment to delivering clean code outputs, TejaSoft stands as the leading Code Doctor system in the industry.

Don’t let your legacy code hold you back from realizing your business goals. Contact TejaSoft today to explore how their innovative solutions can revolutionize your development process and drive your product for scalable revenues in spite of #techdebt endless pains, stress & team execuses.

Introduction

In Gradle, the build automation tool, the Kotlin DSL (Domain-Specific Language) provides a powerful and expressive way to configure and customize build scripts. In this article, we will explore default directory pointing properties and objects in Gradle Kotlin DSL. We will learn how to set and read these properties, define custom properties, and work with different variations of source sets, such as main, java, test, resources, and Kotlin language.

Default Directory Pointing Properties: Gradle provides several default directory-pointing properties. Let’s discuss each property, its description, and how to set and read them.

• buildDir: Points to the build directory where Gradle places the compiled code, resources, and other build-related files.
• buildFile: Represents the build script file (e.g., build.gradle.kts) being executed.
• docsDir: Refers to the directory where the generated documentation is placed.
• projectDir: Points to the root directory of the project.
• reportsDir: Represents the directory where generated reports are stored.
• rootDir: Points to the root directory of the Gradle project.
• testReportDir: Refers to the directory where test reports are generated.
• testResultsDir: Represents the directory where test results are stored.
• layout.buildDirectory property represents the directory where build outputs, such as compiled classes, generated resources, and other build artifacts, are placed. The layout.buildDirectory property is useful when you need to reference or manipulate build artifacts within your build script or tasks.

You can access these properties directly within your Gradle Kotlin build script. For example:

println("buildDir: ${buildDir.absolutePath}")
println("buildFile: ${buildFile.absolutePath}")
println("projectDir: ${projectDir.absolutePath}")
println("rootDir: ${rootDir.absolutePath}")

We can also read properties that are part of project object using project.properties["propertyName"] syntax. This approach makes all plugins defined properties are accessible.

Here's an example of reading the testReportDir property from property map

println("testReportDir:" + project.properties["testReportDir"])
println("testResultsDir:" + project.properties["testResultsDir"])
println("docsDir:" + project.properties["docsDir"])
println("reportsDir:" + project.properties["reportsDir"])

To access the value of the layout.buildDirectory property in Gradle Kotlin DSL, you can use the following code

println("Build Directory: ${layout.buildDirectory.get()}")
println("Project Directory: ${project.layout.projectDirectory}")
println("ProjectDirectory: ${layout.projectDirectory}")

From the above code, we note project is the assumed parent object i.e. layout is a child property of the project object, that can be accessed as project.layout or just as layout.

We can also attach our own custom properties to projectobject this way

open class MyExtension {
    var myProperty: String = ""
}

val myExtension = extensions.create("myExtension", MyExtension::class)

configure<MyExtension> {
    myProperty = "configure"
}

myExtension.myProperty = "property"

task("myTask") {
    doLast {
         println("My Property: ${myExtension.myProperty}")
    }
}

Default Objects and Source Sets: Gradle provides default objects that allow you to work with source sets, tasks, configurations, and dependencies.

core objects in Gradle:

Project:

• Access: The Project object is automatically available in Gradle build scripts without any explicit declaration.
• Explanation: The Project object represents the entire build or project. It provides a wide range of methods and properties to configure and interact with the build environment. You can access and configure the project properties, apply plugins, define tasks, create configurations, and more using the Project object.

Plugins:

• Access: The pluginsobject is automatically available in Gradle build scripts without any explicit declaration.
• Explanation: The plugins object in Gradle provides methods to manage plugins in your build script. You can apply plugins using the plugins block or by using the apply method. The plugins object also offers functions to search for and resolve plugin dependencies, making it straightforward to incorporate third-party plugins into your build.
• Plugins in Gradle provide a powerful mechanism for extending the build configuration and adding additional functionality to your Gradle projects. A plugin is a reusable piece of build logic that encapsulates tasks, configurations, and other build-related elements.
• By applying a plugin to your Gradle project, you can easily incorporate features such as code quality checks, dependency management, test frameworks, deployment automation, and more. Plugins enable you to define custom tasks, configure default behaviors, and integrate with external tools or libraries.
• Plugins can be sourced from various locations, including the Gradle Plugin Portal, custom repositories, or locally defined scripts. They can be applied at the project level or for specific subprojects, allowing flexibility in how you structure and configure your builds.
• Plugins greatly enhance the reusability, modularity, and maintainability of your Gradle builds. They enable you to leverage existing solutions and share build configurations across projects, promoting consistency and efficiency in your development workflows.

Task:

• Access: Tasks are defined using the tasks property of the Project object, e.g., tasks.register("myTask") { ... }.
• Explanation: The Task object represents a single atomic piece of work within the build. You can define tasks to perform specific actions, such as compiling code, running tests, generating documentation, etc. Tasks can have dependencies on other tasks, and you can configure their behavior using properties and actions.

Configuration:

• Access: Configurations are defined using the configurations property of the Project object, e.g., configurations.create("myConfig") { ... }.
• Explanation: The Configuration object represents a logical grouping of dependencies. You can define configurations to specify the dependencies required for building and running the project. Configurations define the external modules or libraries that your project depends on and are used to resolve and download the required artifacts.

Dependency:

• Access: Dependencies are typically defined within configurations, e.g., dependencies { implementation "com.example:library:1.0" }.
• Explanation: The Dependency object represents a dependency on an external module or library. Dependencies are declared within configurations and specify the external artifacts required for the project. Dependencies can be declared with specific versions and can be resolved from repositories.

SourceSet:

• Access: Source sets are typically defined within the sourceSets block of the Project object, e.g., sourceSets { main { ... } }.
• Explanation: The SourceSet object represents a group of source files for a specific purpose, such as the main source code, test code, or additional source sets. Source sets allow you to organize and configure different types of source files in your project, such as Java, Kotlin, resources, etc.

gradle:

The gradle object in Gradle represents the Gradle runtime and provides access to various properties, methods, and configurations related to the current Gradle build.

Here are some common use cases and functionalities of the gradle object:

1. Accessing Gradle properties: You can access properties defined in the Gradle build script or passed via the command line using the gradle.properties file. For example, gradle.propertyName retrieves the value of the property named propertyName.
2. Configuring build behavior: The gradle object allows you to configure various aspects of the build process. For instance, you can define build-wide options such as task timeouts, parallel execution, or build caching.
3. Working with the build environment: The gradle object provides information about the build environment, including the Gradle version, the project directory, and the build directory. For example, gradle.gradleVersion retrieves the current Gradle version being used.
4. Accessing the project hierarchy: You can access the root project and subprojects within a multi-project build using the gradle.rootProject and gradle.allprojects properties, respectively. This allows you to perform operations on the entire project hierarchy.
5. Executing tasks dynamically: The gradle object provides methods to execute tasks programmatically. For example, you can use gradle.task(taskName).execute() to execute a specific task by its name.
6. Registering custom logic: You can register custom logic or actions to be executed during the build lifecycle using the gradle.buildFinished or gradle.taskGraph.whenReady properties. This allows you to add custom behavior after the build is finished or before tasks are executed.
7. Logging and reporting: The gradle object offers a logging facility through its gradle.logger property. You can log messages at different levels (e.g., info, debug, warn, error) to provide feedback and track the progress of the build.

These are just a few examples of the capabilities provided by the gradle object. It serves as a central entry point to interact with the Gradle runtime and enables you to customize the build process according to your requirements.

Let’s explore some of these objects and their usage.

Source Sets

• sourceSets.main: Represents the main source set, which includes the main Java source code, resources, and Kotlin source code.
• sourceSets.test: Represents the test source set, which includes test Java source code and resources.
• sourceSets.getByName("customSet"): Represents a custom source set named "customSet" that you can define and configure according to your project's needs.
• sourceSets.getByName("customTest"): Represents a custom source set named "customTest" for test-related code.

You can customize these source sets by adding or modifying the source directories. For example:

sourceSets {
    getByName("main") {
        java.srcDirs(
            "src/main/java",
            "src/main/otherJava"
        )
        resources.srcDirs(
            "src/main/resources",
            "src/main/otherResources"
        )
        kotlin.srcDir("src/main/kotlin")
    }
    getByName("test") {
        java.srcDir("src/test/java")
        resources.srcDir("src/test/resources")
    }
    
    create("customSet") {
        java.srcDir("src/customSet/java")
        resources.srcDir("src/customSet/resources")
    }
    
    create("customTest") {
        java.srcDir("src/customTest/java")
        resources.srcDir("src/customTest/resources")
    }
}

The way to read these directories

// Reading and printing Java source directories
println("Main Java Source Directories: ${sourceSets.main.get().java.srcDirs}")
println("Test Java Source Directories: ${sourceSets.test.get().java.srcDirs}")

// Reading and printing Kotlin source directories
println("Main Kotlin Source Directories: ${sourceSets.main.get().kotlin.srcDirs}")
println("Test Kotlin Source Directories: ${sourceSets.test.get().kotlin.srcDirs}")

// Reading and printing custom source directories
println("Custom Set Java Source Directories: ${sourceSets.getByName("customSet").java.srcDirs}")
println("Custom Set Resources Directories: ${sourceSets.getByName("customSet").resources.srcDirs}")
println("Custom Test Java Source Directories: ${sourceSets.getByName("customTest").java.srcDirs}")
println("Custom Test Resources Directories: ${sourceSets.getByName("customTest").resources.srcDirs}")

Accessing Other Core Objects: You can access other core objects like Project, Task, Configuration, Dependency, Plugin, File, Logger, ConfigurationContainer, and TaskContainer using the respective methods and properties. For example:

val project: Project = project
println("Project: $project")

val task: Task = tasks.getByName("cp")
println("Task: $task")

val configuration: Configuration = configurations.create("myConfig")
println("Configuration: $configuration")

val dependency: Dependency = dependencies.create("com.example:library:1.0")
println("Dependency: $dependency")

val sourceSet: SourceSet = sourceSets.getByName("main")
println("SourceSet: $sourceSet")

val plugin = plugins.getPlugin("java")
println("Plugin: $plugin")

val file: File = file("path/to/file.txt")
println("File: $file")

logger.info("This is an informational message.")

val configurationContainer: ConfigurationContainer = configurations
println("ConfigurationContainer: $configurationContainer")

val taskContainer: TaskContainer = tasks
println("TaskContainer: $taskContainer")

gradle

Sample usage of gradleobject

tasks.register("customTask") {
 doLast {
  // Accessing Gradle properties
  val myProperty = project.properties["myProperty"]
  println("Value of myProperty: $myProperty")

  // Working with the build environment
  val gradleVersion = gradle.gradleVersion
  val projectDir = project.projectDir
  val buildDir = project.buildDir
  println("Gradle version: $gradleVersion")
  println("Project directory: $projectDir")
  println("Build directory: $buildDir")

  // Accessing the project hierarchy
  val rootProject = project.rootProject
  val allProjects = project.allprojects
  println("Root project name: ${rootProject.name}")
  println("All project names:")
  allProjects.forEach { println(it.name) }

  // Registering custom logic
  gradle.buildFinished {
   println("Build finished!")
  }

  gradle.taskGraph.whenReady {
   println("Tasks in the task graph:")
   allTasks.forEach { println(path) }
  }

  // Logging and reporting
  logger.info("This is an informational message.")
  logger.warn("This is a warning message.")
 }
}

Printing Dependencies and Tasks

You can print the dependencies and tasks within your Gradle script using the following code snippets

tasks.register("printDependencies") {
    doLast {
        println("Dependencies:")
        configurations.forEach { configuration ->
            configuration.dependencies.forEach { dependency ->
                println("${configuration.name} -> ${dependency.name}")
            }
        }
    }
}

tasks.register("printTasks") {
    doLast {
        println("Tasks:")
        gradle.taskGraph.allTasks.forEach { task ->
            println(task.path)
        }
    }
}

There is a special propertydefaultTasks property allows you to specify a list of tasks that should be executed by default when running the build without specifying any task names.

The defaultTasks property is typically defined in the build script (e.g., build.gradle or build.gradle.kts) and accepts a list of task names as its value. For example, if you want to set task1 and task2 as the default tasks, you can do the following

defaultTasks("task1", "task2")

When you run the build without specifying any task names, Gradle will automatically execute the tasks specified in defaultTasks in the order they are defined. For example, running gradle or ./gradlew in the command line will execute task1 and task2 by default.

It’s important to note that defaultTasks does not prevent you from running other tasks explicitly by specifying their names in the command line. You can still execute other tasks alongside the default tasks.

You can also override the default tasks by providing task names explicitly in the command line. For example, running gradle task3 will execute task3 instead of the default tasks.

Defining default tasks can be useful to define a common set of tasks that should be executed when someone runs the build without specifying specific task names. It provides a convenient way to specify the entry point for your build process.

Conclusion

In this article, we explored default directory pointing properties and objects in Gradle Kotlin DSL. We learned how to set and read these properties, define custom properties, and work with different variations of source sets. With this knowledge, you can effectively configure and customize your Gradle build scripts to meet your requirements.

Note: You will have to use pluginkotlin(“jvm”) version “1.8.22”to make Kotlin part of the sourceSetsto work