Configuring jb

Imports
Properties
Publishing to a Maven Repository
Configuration Reference

Introduction

For a directory to contain a jb project, a YAML or JSON file called jbuild.yaml or jbuild.json must exist in it.

This file defines the configuration for the project.

The jb configuration model is defined in this file. A JSON Schema can be generated from the model (TODO).

The minimal configuration file looks like this:

YAML

module: my-module

JSON

{
    "module": "my-module"
}

To display the full configuration model of a jb project, run the show task.

Example:

######################## Full jb configuration ########################

### For more information, visit https://github.com/renatoathaydes/jb

# Maven artifact groupId
group: "com.athaydes"
# Module name (Maven artifactId)
module: "example"
# Human readable name of this project
name: null
# Maven version
version: "0.0.0"
# Description for this project
description: null
# URL of this project
url: null
# Licenses this project uses
licenses: []
# Developers who have contributed to this project
developers: []
# Source control management
scm: null
# List of source directories
source-dirs: ["src"]
# List of resource directories (assets)
resource-dirs: ["resources"]
# Output directory (class files)
output-dir: null
# Output jar (may be used instead of output-dir)
output-jar: "build/example.jar"
# Java Main class name
main-class: "com.athaydes.example.Main"
# Manifest file to include in the jar
manifest: null
# Java Compiler arguments
javac-args: []
# Java Compiler environment variables
javac-env: {}
# Java Runtime arguments
run-java-args: []
# Java Runtime environment variables
run-java-env: {}
# Java Test run arguments
test-java-args: []
# Java Test environment variables
test-java-env: {}
# Maven repositories (URLs or directories)
repositories: []
# Maven dependencies
dependencies: {}
# Dependency exclusions (regular expressions)
dependency-exclusion-patterns: []
# Annotation processor Maven dependencies
processor-dependencies: {}
# Annotation processor dependency exclusions (regular expressions)
processor-dependency-exclusion-patterns: []
# Compile-time libs output dir
compile-libs-dir: "build/compile-libs"
# Runtime libs output dir
runtime-libs-dir: "build/runtime-libs"
# Test reports output dir
test-reports-dir: "build/test-reports"
# jb extension project path (for custom tasks)
extension-project: null

The Configuration Reference section below explains in more detail what each of these fields mean and how to use them.

Properties

The properties value is a Map which can be used for declaring properties.

Example:

properties:
    versions:
        jbuild: 0.10.1
        java: 11
        junit: 5.9.1
        assertj: 3.23.1

Properties can be used anywhere in a config file using double-curly-braces to refer to them.

Example:

javac-args: [ "--release={{versions.java}}" ]

dependencies:
  "org.junit.jupiter:junit-jupiter-api:{{versions.junit}}":
  "org.junit.jupiter:junit-jupiter-params:{{versions.junit}}":
  "org.assertj:assertj-core:{{versions.assertj}}":

Imports

The imports value is a list of other YAML or JSON files to be imported into the current one.

When a config file is imported, it gets merged with it, and jb sees only the result of that merge.

Example:

imports:
    - "../../build_properties.yaml"

A common usage of imports is to allow declaring all dependencies versions used across various sub-projects in a single place.

Check the JBuild Tests config for a real example.

Publishing to a Maven Repository

To be able to publish to a Maven Repository, the following fields must be configured properly:

group
module
name
version
description
developers
scm
licenses
url

Once all of the above fields have proper values, you can publish with jb publish :-m (Sonatype Maven Central) or jb publish :-n (Sonatype Legacy Repository, use this if your domain was registered before the transition to the newer repo).

Running jb publish without any argument publishes to Maven Local at ~/.m2/repository.

Any other argument is treated as a destination directory or a http(s) URL.

Configuration Reference

group

A project group ID. This is normally used to group associated projects together and for the published artifact metadata.

Refer to the Maven Documentation for the expected conventions regarding Maven repositories metadata.

Example: com.athaydes.jbuild.

module

The artifact ID. This is the main identifier of a published artifact.

Example: jbuild.

name

Human-readable name of the project.

Example: JBuild.

version

The version of this artifact. It is advisable that Semantic Versioning should be used.

As a project evolves, new versions of it may be published on a repository and then used by other projects as dependencies.

Example: 1.2.3

description

A brief description of what the artifact does.

Example: Java CLI and Library for building and analysing Java projects..

url

Project URL. Normally the Documentation Website.

Example: https://renatoathaydes.github.io/dartle-website/

licenses

List of licenses this artifact is published under. Each string in the list must be a license identifier from SPDX.

The allowed license identifiers are updated from the SPDX API on every release.

Example: ["Apache-2.0", "CC0-1.0"]

developers

List of Developer objects including the main developers working on the project.

Only used by jb to include it in generated Maven POMs.

Example:

developers:
    - name: Joe Doe
      email: joe.doe@example.org
      organization: ACME Co.
      organization-url: https://example.org

scm

Source Control Management specification.

Only used by jb to include it in generated Maven POMs.

Example:

scm:
    connection: https://github.com/renatoathaydes/jb.git
    developer-connection: https://github.com/renatoathaydes/jb.git
    url: https://github.com/renatoathaydes/jb

source-dirs

The directories where source files can be found.

Defaults to ["src"].

Example:

source-dirs: ["src/main/java", "src/test/java"]

resource-dirs

The directories where files that should be included in the jar, but are not source files, can be found.

Defaults to [resources].

Example:

resourde-dirs: ["src/main/resources"]

output-dir

The directory where the build output (usually the compiled class files) should be written to.

This option is mutually exclusive with output-jar. If this option is used, no jar will be produced.

Example:

output-dir: build

output-jar

The path to the jar to be produced by the build.

This option is mutually exclusive with output-dir. If this option is used, class files will be first written to a temporary directory, and then archived in the jar.

Example:

output-jar: build/lib.jar

main-class

The name of the main class in this project.

The main class is the class that can be run with the java command. jb will include Main-Class in the generated MANIFEST.MF file, which means that the produced jar will be runnable, for example with this command:

java -cp "build/runtime-libs/*" -jar build/lib.jar

Example:

main-class: org.example.Main

manifest

The location of a MANIFEST text file to be passed to the jar command when creating a jar. The file may contain any directives allowed by the Java Manifest Format.

Example:

manifest: meta/manifest.txt

javac-args

Java compiler arguments.

jb passes various arguments to javac based on the configuration of the project. However, you may want to pass further arguments as necessary.

To see which options jb is already including, run jb compile -l debug.

Example:

javac-args: ["--release=11"]

javac-env

Deprecated.

run-java-args

Java runtime arguments.

Used by the run task only.

Example:

run-java-args: ["-Xmx128m"]

run-java-env

Deprecated.

test-java-args

Arguments to be passed to the java command when executing tests with the test task.

Example:

test-java-args
  - "-Dtests.repo.dir=resources/jbuild/commands/repo"

test-java-env

Deprecated.

repositories

The repositories to use when resolving dependencies.

By default, Maven Central and Maven Local (~/.mvn/repository) are used.

Example:

repositories:
    - https://maven.repository.redhat.com/ga/
    - https://repo1.maven.org/maven2/

dependencies

The artifact dependencies of the project.

Dependencies use the notation <group>:<module>:<version> and may have the following attributes:

transitive: true or false - whether to include transitive dependencies or only the single artifact.
scope: one of:
- all - the default, include dependency both at compile time and at runtime.
- compile-only - only include the dependency when compiling.
- runtime-only - only include the dependency at runtime.
path: path to a local jar or another jb project. This is recommended only for local development.

Example:

dependencies:
    org.slf4j:slf4j-api:2.0.16:
    com.google.guava:guava:33.4.0-jre:
        transitive: false
        scope: all

dependency-exclusion-patterns

Regular expressions for excluding specific transitive dependencies from the classpath.

The patterns should match against dependencies specifications, not file names.

Example:

dependency-exclusion-patterns:
    - com.google.errorprone.*

processor-dependencies

Dependencies for Java annotation processors.

Example:

processor-dependencies:
    com.google.errorprone:error_prone_core:2.16:

processor-dependency-exclusion-patterns

Similar to dependency-exclusion-patterns above, but for annotation processor dependencies.

compile-libs-dir

The directory to use for compile-time dependencies.

Defaults to build/compile-libs.

Example: target/libs.

runtime-libs-dir

The directory to use for compile-time dependencies.

Defaults to build/runtime-libs.

Example: target/runtime.

test-reports-dir

The directory to use for testing framework’s reports.

Defaults to build/test-reports.

Example: target/test-reports.

extension-project

The path to a jar containing a jb extension, or to a local directory containing a jb project which is a jb extension.

See Extending jb.

WARNING: this may be changed to become an array in the future.

Example: jb-extensions/my-extension.

Configuring jb

Table of Contents

Introduction

YAML

JSON

Properties

Imports

Publishing to a Maven Repository

Configuration Reference