common-build

The common-build project simplifies the development environment setup across Linux, MacOS and Windows. It acts as a transparent wrapper for common build tools such as Gradle, Maven or Ant, and manages the installation of developer tools like Java, Node, Python, Trivy and many more. All software is installed into a local "devtools" directory, and all settings can be overridden via environment variables.

Key features:

• Tool management — Install, update and switch between versions of developer tools with a single command (cb --install). Use cb --setenv to add all managed tools to your PATH.
• Build execution — Run project builds transparently through Gradle, Maven or Ant without manual setup.
• Project wizard — Scaffold new projects interactively with cb --new, supporting multiple project types (Java, Node/React/Vue/Nuxt, Kubernetes, OpenAPI, and more).
• Organization Config — Centralize tool versions, project templates, naming conventions and lifecycle hooks in a Git repository for consistent corporate-wide developer environments.
• Package development — Add new tool packages to common-build with a simple script convention, supporting cross-platform downloads, version management, and post-install hooks.
• Automated testing — Cross-platform test suite with sandbox isolation, gated build verification, and nightly CI coverage for all project types.
• Self-update — Keep common-build itself up to date with cb --install cb.

Installing common-build

Using script to install the latest release

Linux / MacOS

Install the latest cli to $HOME/devtools:

curl -fsSL https://raw.githubusercontent.com/toolarium/common-build/master/bin/cb-install | /bin/bash

Alternatively, download cb-install manually and run it with /bin/bash cb-install.

Tested on debian, ubuntu, centos, fedora and macOS.

Windows

Install the latest cli to c:\devtools and add this directory to the User PATH environment variable:

powershell -Command "iwr https://raw.githubusercontent.com/toolarium/common-build/master/bin/cb-install.bat -OutFile ${env:TEMP}/cb-install.bat" & %TEMP%\cb-install.bat

Alternatively, download cb-install.bat manually and run it.

The common-build also supports cygwin — use the Linux installation for that. Currently only Windows 10 is properly tested.

Usage

cb [OPTION] [build-arguments...]

When called without options (or with build arguments only), cb sets up the required tools and executes the project build (Gradle, Maven, or Ant) found in the current directory.

Options

Supported Packages

The following packages can be installed via cb --install <package>:

Windows-only packages: git, npp (Notepad++), multicommander, winmerge, wt (Windows Terminal), scoop, rangerdesktop.

Utility Scripts

In addition to the main cb command, common-build ships with a set of standalone helper scripts in bin/. Each one has cross-platform counterparts (shell script and .bat) and supports -h / --help.

Examples

Run a build:

cb

Run a build with a specific Java version:

cb --java 17

Install a package:

cb --install gradle

Install a specific version and set it as default:

cb --install gradle 8.12 --default

Set up environment (recommended — add all managed tools to PATH):

:: Windows:
cb --setenv

# Linux/Mac:
. cb --setenv
# or
source cb --setenv

# Nushell (save output to a file, then source it):
cb --setenv --nushell | save -f ~/.config/nushell/cb-tools.nu
source ~/.config/nushell/cb-tools.nu

This makes tools like java, gradle, maven, node, python, git, trivy, ant, etc. directly available on the command line.

List available packages:

cb --packages

Create a new project:

cb --new

Update common-build itself to the latest version:

cb --install cb

Environment Variables

Tool Version Defaults

The file conf/tool-version-default.properties defines the default version for every managed tool. When you run cb --install <package> without specifying a version, the version from this file is used. It is a simple key = value format:

java = 21
gradle = 8.13
node = 24.14.1

You can override a tool version per-run (e.g. cb --java 17) or install a specific version and mark it as the new default with cb --install gradle 8.12 --default. Installed versions are tracked in conf/tool-version-installed.properties.

Product Types

A product type is an organizational grouping that pre-fills wizard defaults when creating new projects. Products are defined in conf/product-types.properties (see conf/product-types-sample.properties for a template).

Each product maps a name to a set of key:value pairs separated by |:

My product = projectComponentId:myc|projectGroupId:myg|projectRootPackageName:myc.rootpackage.name

When a user selects a product during cb --new, the configured values are automatically applied as defaults for the project wizard fields (component ID, group ID, root package name, etc.). This avoids repetitive input when creating multiple projects under the same product umbrella.

Product types are optional. If no product-types.properties file exists, the wizard skips the product selection step.

Project Types

A project type is a template that defines what kind of project to scaffold and which wizard fields to prompt. Project types are defined in conf/project-types.properties.

Each entry maps a type ID to a description and a list of configuration sections:

java-application = Simple java application|projectName|projectRootPackageName|projectGroupId|projectComponentId|projectDescription
vuejs = Vue|projectName=-ui|projectComponentId|projectDescription|install=node|initAction=npx --yes @vue/cli create --default @@projectName@@ >@@logFile@@

Available project types include: java-application, java-library, config, script, openapi, quarkus, vuejs, nuxtjs, react, kubernetes-product, documentation, container, and organization-config.

For full details on how project types work and how to configure them, see the Project Wizard documentation.

Per-Project Java Version

Place a .java-version file in your project root containing just the major version number:

17

When cb runs in that directory, it automatically switches to the specified Java version. This is useful for teams working on projects with different Java requirements — each project controls its own version without affecting others.

How It Works

When you run cb in a project directory, the following happens:

cb [build-arguments...]
 │
 ├─ 1. Load configuration
 │     Read tool-version-default.properties, custom config, .java-version
 │
 ├─ 2. Set up tools
 │     Resolve and add Java, Gradle/Maven/Ant, and other tools to PATH
 │
 ├─ 3. Run lifecycle hooks
 │     Call custom hook script (if configured): verify-configuration, build-start
 │
 ├─ 4. Execute build
 │     Detect build system (build.gradle → Gradle, pom.xml → Maven, build.xml → Ant)
 │     Run the build with all arguments forwarded
 │
 └─ 5. Post-build
       Call build-end hook (if configured)

For cb --setenv, only steps 1-2 are executed to set up tools in the current shell. For cb --install <package>, the tool is downloaded, extracted and linked into the current/ directory. For cb --new, the project wizard is started instead.

Sample Output of cb --version

================================================================================
toolarium common build 1.0.14

.: Installed tool versions:
    - ant: 1.10.15
    - gradle: 8.13
    - java: 21
    - maven: 3.9.14
    - node: 24.14.1
    - python: 3.13.12
    - trivy: 0.69.3
================================================================================

Special Files

Customization

Custom Hook Script

Set CB_CUSTOM_SETTING to point to a shell script that will be called at various lifecycle hooks: start, build-start, build-end, install-start, install-end, cleanup-start, cleanup-end, setenv-start, setenv-end, error-end, and more. See the sample scripts for complete templates:

• cb-custom-sample.sh / cb-custom-sample.bat — fully commented samples with all hooks active
• cb-custom.sh / cb-custom.bat — minimal templates ready to copy and customize

Custom Config Project

For organization-wide customization, create a Custom Config Home project (cb --new, select the organization-config template). Publish it as a git repository and set CB_CUSTOM_CONFIG to the git URL. Common-build checks for updates daily and applies the configuration automatically.

Alternatively, add the git URL to the file $HOME/.common-build/conf/.cb-custom-config.

For full details on setting up an organization config with custom tool versions, project types, product types, lifecycle hooks, and concrete examples, see the Organization Config documentation.

Nushell Support

Common-build supports Nushell as a first-class shell. The --nushell flag causes cb --setenv to output Nushell-compatible environment variable assignments instead of modifying the current process environment.

Manual usage

# Print Nushell env commands to stdout
cb --setenv --nushell

# Save and source in one step
cb --setenv --nushell | save -f ~/.config/nushell/cb-tools.nu
source ~/.config/nushell/cb-tools.nu

Automatic setup via installer

When cb-install (or cb-install.bat) detects that Nushell is installed, it automatically:

1. Creates ~/.config/nushell/cb-setenv.nu with CB_HOME and PATH configuration.
2. Adds a source line to ~/.config/nushell/env.nu so the configuration is loaded on every Nushell startup.

On subsequent updates (cb --install cb), the cb-setenv.nu file is regenerated with the updated CB_HOME path.

GNU General Public License v3.0 — see LICENSE for details. | GitHub