← Back

Package Development Guide

This document describes how to create and maintain package scripts for the toolarium common-build package installation system.

Overview

The package system allows cb --install <package> [version] to download, extract, and register developer tools. Each package is defined by a pair of scripts:

bin/packages/<package-name>/<package-name>.sh    (Linux/macOS)
bin/packages/<package-name>/<package-name>.bat   (Windows)

The package script's sole job is to set environment variables that tell the main cb installer what to download, where to extract, and how to register the tool. The script does not download or extract anything itself.

Installation Flow

When a user runs cb --install maven 3.9.14 --default, the following steps happen:

1. Version resolution — If no version is given, cb looks up the default in conf/tool-version-default.properties (or the custom config's version).
2. Package script execution — cb sources bin/packages/maven/maven.sh (or .bat), passing the version as $1. The script sets CB_PACKAGE_* variables.
3. URL construction — If CB_PACKAGE_DOWNLOAD_URL is not set, cb constructs it from CB_PACKAGE_BASE_URL + CB_PACKAGE_DOWNLOAD_NAME.
4. Download — The archive is downloaded to $CB_DEVTOOLS/.repository/ (skipped if already cached).
5. Extraction — The archive is extracted into $CB_DEVTOOLS/. The top-level directory is auto-detected from the archive, or forced via CB_PACKAGE_DEST_VERSION_NAME.
6. Post-install commands — CB_PACKAGE_BUILD_CMD and CB_PACKAGE_PERMISSION_CMD run inside the extracted directory.
7. Junction/symlink creation — If --default is given (or this is the first install), a symlink is created: $CB_HOME/current/<package> → $CB_DEVTOOLS/<extracted-dir>.
8. Version tracking — The version is recorded in conf/tool-version-installed.properties.

Environment Variables Set by Package Scripts

These variables are the contract between a package script and the cb installer.

Mandatory

URL (one of these must be set)

Optional

Environment Variables Available to Package Scripts

These variables are set by cb before calling the package script. Package scripts can read them to make platform-specific decisions.

Platform and Architecture

Directories

Flags

Writing a Package Script

Minimal example (shell)

#!/bin/bash
# bin/packages/mytool/mytool.sh

# Default version (can be overridden via CB_MYTOOL_VERSION env var)
[ -z "$CB_MYTOOL_VERSION" ] && CB_MYTOOL_VERSION="1.2.3"

# Accept version from command line, fall back to default
CB_PACKAGE_VERSION="$1"
[ -z "$CB_PACKAGE_VERSION" ] && CB_PACKAGE_VERSION="$CB_MYTOOL_VERSION"

# Set download coordinates
CB_PACKAGE_BASE_URL="https://releases.example.com/mytool/${CB_PACKAGE_VERSION}"
CB_PACKAGE_DOWNLOAD_NAME="mytool-${CB_PACKAGE_VERSION}.tar.gz"
CB_PACKAGE_VERSION_NAME="mytool-${CB_PACKAGE_VERSION}"

export CB_PACKAGE_VERSION CB_PACKAGE_BASE_URL CB_PACKAGE_DOWNLOAD_NAME CB_PACKAGE_VERSION_NAME

Minimal example (batch)

@ECHO OFF
:: bin\packages\mytool\mytool.bat

if not defined CB_MYTOOL_VERSION set "CB_MYTOOL_VERSION=1.2.3"

set "CB_PACKAGE_VERSION=%1"
if .%CB_PACKAGE_VERSION%==. set "CB_PACKAGE_VERSION=%CB_MYTOOL_VERSION%"

set "CB_PACKAGE_BASE_URL=https://releases.example.com/mytool/%CB_PACKAGE_VERSION%"
set "CB_PACKAGE_DOWNLOAD_NAME=mytool-%CB_PACKAGE_VERSION%.zip"
set "CB_PACKAGE_VERSION_NAME=mytool-%CB_PACKAGE_VERSION%"

With already-exist check (recommended)

#!/bin/bash
[ -z "$CB_MYTOOL_VERSION" ] && CB_MYTOOL_VERSION="1.2.3"
CB_PACKAGE_VERSION="$1"
[ -z "$CB_PACKAGE_VERSION" ] && CB_PACKAGE_VERSION="$CB_MYTOOL_VERSION"

CB_PACKAGE_BASE_URL="https://releases.example.com/mytool/${CB_PACKAGE_VERSION}"
CB_PACKAGE_DOWNLOAD_NAME="mytool-${CB_PACKAGE_VERSION}.tar.gz"
CB_PACKAGE_VERSION_NAME="mytool-${CB_PACKAGE_VERSION}"

# Prevent redundant extraction when already installed
CB_PACKAGE_DIRECTORY_NAME="$CB_DEVTOOLS/mytool-${CB_PACKAGE_VERSION}"
[ "$CB_INSTALL_OVERWRITE_DIST" = "false" ] && [ -d "$CB_PACKAGE_DIRECTORY_NAME" ] && CB_PACKAGE_ALREADY_EXIST=true

export CB_PACKAGE_VERSION CB_PACKAGE_BASE_URL CB_PACKAGE_DOWNLOAD_NAME CB_PACKAGE_VERSION_NAME
export CB_PACKAGE_DIRECTORY_NAME CB_PACKAGE_ALREADY_EXIST

Platform-specific downloads

#!/bin/bash
CB_PACKAGE_VERSION="$1"
[ -z "$CB_PACKAGE_VERSION" ] && CB_PACKAGE_VERSION="2.0.0"

case "$CB_OS" in
  linux)  CB_PACKAGE_DOWNLOAD_NAME="mytool-${CB_PACKAGE_VERSION}-linux-x${CB_PROCESSOR_ARCHITECTURE_NUMBER}.tar.gz" ;;
  mac)    CB_PACKAGE_DOWNLOAD_NAME="mytool-${CB_PACKAGE_VERSION}-macos-x${CB_PROCESSOR_ARCHITECTURE_NUMBER}.tar.gz" ;;
  cygwin) CB_PACKAGE_DOWNLOAD_NAME="mytool-${CB_PACKAGE_VERSION}-windows-x${CB_PROCESSOR_ARCHITECTURE_NUMBER}.zip" ;;
  *)      CB_PACKAGE_DOWNLOAD_NAME="mytool-${CB_PACKAGE_VERSION}-linux-x${CB_PROCESSOR_ARCHITECTURE_NUMBER}.tar.gz" ;;
esac

CB_PACKAGE_DOWNLOAD_URL="https://github.com/example/mytool/releases/download/v${CB_PACKAGE_VERSION}/${CB_PACKAGE_DOWNLOAD_NAME}"
CB_PACKAGE_VERSION_NAME="mytool-${CB_PACKAGE_VERSION}"
CB_PACKAGE_DEST_VERSION_NAME="mytool-${CB_PACKAGE_VERSION}"

export CB_PACKAGE_VERSION CB_PACKAGE_DOWNLOAD_URL CB_PACKAGE_DOWNLOAD_NAME
export CB_PACKAGE_VERSION_NAME CB_PACKAGE_DEST_VERSION_NAME

With post-install build command

#!/bin/bash
# When the archive has a nested directory structure that needs flattening
CB_PACKAGE_VERSION="$1"
[ -z "$CB_PACKAGE_VERSION" ] && CB_PACKAGE_VERSION="21.0.2"

CB_PACKAGE_DOWNLOAD_URL="https://github.com/graalvm/graalvm-ce-builds/releases/download/jdk-${CB_PACKAGE_VERSION}/graalvm-community-jdk-${CB_PACKAGE_VERSION}_linux-x64_bin.tar.gz"
CB_PACKAGE_DOWNLOAD_NAME="graalvm-community-jdk-${CB_PACKAGE_VERSION}_linux-x64_bin.tar.gz"
CB_PACKAGE_VERSION_NAME="graalvm-${CB_PACKAGE_VERSION}"
CB_PACKAGE_DEST_VERSION_NAME="graalvm-${CB_PACKAGE_VERSION}"

# Flatten nested directory after extraction
CB_PACKAGE_BUILD_CMD="mv graalvm-community-*/* . 2>/dev/null; rmdir graalvm-community-* 2>/dev/null"

export CB_PACKAGE_VERSION CB_PACKAGE_DOWNLOAD_URL CB_PACKAGE_DOWNLOAD_NAME
export CB_PACKAGE_VERSION_NAME CB_PACKAGE_DEST_VERSION_NAME CB_PACKAGE_BUILD_CMD

Supported Archive Formats

Adding a Tool to PATH

After installing a package, it must be added to PATH in two separate code paths in cb/cb.bat:

1. --setenv (function setCBEnv() / label :SET_ENV) — Sets environment variables for interactive shell use.
2. Build execution (function commonBuild() / label :COMMON_BUILD) — Adds tools to PATH for build-time use. This path does NOT go through setCBEnv.

Custom Package Hooks

If a custom settings script (CB_CUSTOM_SETTING_SCRIPT) is configured, cb calls it at these points during installation:

Version Configuration

Default versions for all tools are defined in conf/tool-version-default.properties:

maven = 3.9.14
gradle = 8.14
node = 22.16.0
java = 21

Installed versions are tracked in conf/tool-version-installed.properties (auto-maintained by cb).

Each package script should also define a fallback default version constant (e.g., CB_MAVEN_VERSION=3.9.14) used when no version is specified and the properties file is unavailable.

Platform Compatibility

Global Configuration Variables

These environment variables can be set by the user or in CI to customize common-build behavior globally. They affect installation, connectivity, and directory layout.

Directory Layout

Network and Connectivity

Custom Configuration

Installer Behavior

System Dependencies

The following tools must be present on the system. cb-install verifies these at installation time:

Checklist for New Packages

1. Create bin/packages/<name>/<name>.sh and .bat
2. Set CB_PACKAGE_DOWNLOAD_NAME (mandatory)
3. Set CB_PACKAGE_BASE_URL or CB_PACKAGE_DOWNLOAD_URL
4. Set CB_PACKAGE_VERSION_NAME for clean directory naming
5. Add the CB_PACKAGE_ALREADY_EXIST check
6. Handle platform differences using CB_OS / CB_MACHINE / CB_PROCESSOR_ARCHITECTURE_NUMBER
7. Add a default version to conf/tool-version-default.properties
8. If the tool needs PATH access: add it to both setCBEnv() and commonBuild() in cb/cb.bat
9. Shell scripts: export all CB_PACKAGE_* variables
10. Test with cb --install <name> --default and verify current/<name> symlink is created

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

← Back