{"id":36604962,"url":"https://github.com/toolarium/common-build","last_synced_at":"2026-04-18T16:01:45.331Z","repository":{"id":62198475,"uuid":"274414850","full_name":"toolarium/common-build","owner":"toolarium","description":"The common-build project has the goal to simplify the development environment setup. It works for the main environment such as Linux, Windows and Mac. It can be used as a \"transparent\" wrapper of the most common build tools such as Gradle, Maven or Ant.","archived":false,"fork":false,"pushed_at":"2026-04-06T15:25:52.000Z","size":888,"stargazers_count":13,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-06T15:27:06.352Z","etag":null,"topics":["ant","build","common","gradle","java","linux","mac","maven","windows","wrapper"],"latest_commit_sha":null,"homepage":"https://toolarium.github.io/common-build/","language":"Batchfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toolarium.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-06-23T13:36:26.000Z","updated_at":"2026-04-06T15:26:02.000Z","dependencies_parsed_at":"2024-01-08T20:48:14.300Z","dependency_job_id":"abf220c7-f0c9-4211-8d7a-0dc56e8d1bfc","html_url":"https://github.com/toolarium/common-build","commit_stats":null,"previous_names":[],"tags_count":104,"template":false,"template_full_name":null,"purl":"pkg:github/toolarium/common-build","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolarium%2Fcommon-build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolarium%2Fcommon-build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolarium%2Fcommon-build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolarium%2Fcommon-build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toolarium","download_url":"https://codeload.github.com/toolarium/common-build/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolarium%2Fcommon-build/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31974954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ant","build","common","gradle","java","linux","mac","maven","windows","wrapper"],"created_at":"2026-01-12T08:43:57.200Z","updated_at":"2026-04-18T16:01:45.320Z","avatar_url":"https://github.com/toolarium.png","language":"Batchfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# common-build\n[![License](https://img.shields.io/github/license/toolarium/common-build)](https://opensource.org/licenses/GPL-3.0)\n[![CI](https://github.com/toolarium/common-build/actions/workflows/cb-test.yml/badge.svg)](https://github.com/toolarium/common-build/actions/workflows/cb-test.yml)\n[![Release](https://img.shields.io/github/v/release/toolarium/common-build)](https://github.com/toolarium/common-build/releases/latest)\n[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-blue)]()\n\n\u003cimg align=\"right\" height=\"110\" src=\"docs/logo/common-build-icon.png\"\u003e\n\nThe common-build project simplifies the development environment setup across Linux, MacOS and Windows.\nIt 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.\nNo administrator or root privileges are required.\n\nKey features:\n\n- **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.\n- **Build execution** — Run project builds transparently through Gradle, Maven or Ant without manual setup.\n- **[Project wizard](docs/project-wizard.md)** — Scaffold new projects interactively with `cb --new`, supporting multiple project types (Java, Node/React/Vue/Nuxt, Kubernetes, OpenAPI, and more).\n- **[Organization Config](docs/organization-config.md)** — Centralize tool versions, project templates, naming conventions and lifecycle hooks in a Git repository for consistent corporate-wide developer environments.\n- **[Package development](docs/package-development.html)** — Add new tool packages to common-build with a simple script convention, supporting cross-platform downloads, version management, and post-install hooks.\n- **Self-update** — Keep common-build itself up to date with `cb --install cb`.\n- **[Automated testing](docs/testing.md)** — Cross-platform test suite with sandbox isolation, gated build verification, and nightly CI coverage for all project types.\n\n\u003e Works hand in hand with its sister project [**common-gradle-build**](https://github.com/toolarium/common-gradle-build). For Gradle-based projects, common-gradle-build provides the build framework while common-build manages the developer toolchain and project scaffolding.\n\n\n## Installing common-build\n\n### Using script to install the latest release\n\n**Linux / MacOS**\n\nInstall the latest cli to `$HOME/devtools`:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/toolarium/common-build/master/bin/cb-install | /bin/bash\n```\n\nAlternatively, download [`cb-install`](https://raw.githubusercontent.com/toolarium/common-build/master/bin/cb-install) manually and run it with `/bin/bash cb-install`.\n\nTested on debian, ubuntu, centos, fedora and macOS.\n\n**Windows**\n\nInstall the latest cli to `c:\\devtools` and add this directory to the User PATH environment variable:\n\n```powershell\npowershell -Command \"iwr https://raw.githubusercontent.com/toolarium/common-build/master/bin/cb-install.bat -OutFile ${env:TEMP}/cb-install.bat\" \u0026 %TEMP%\\cb-install.bat\n```\n\nAlternatively, download [`cb-install.bat`](https://raw.githubusercontent.com/toolarium/common-build/master/bin/cb-install.bat) manually and run it.\n\nThe common-build also supports cygwin — use the Linux installation for that.\nCurrently only Windows 10 is properly tested.\n\n\n## Usage\n\n```\ncb [OPTION] [build-arguments...]\n```\n\nWhen 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.\n\n\n## Options\n\n| Option | Description |\n|---|---|\n| `-h`, `--help` | Show the help message. |\n| `-v`, `--version` | Print version information and installed tool versions. |\n| `--new` | Create a new project via an interactive [project wizard](docs/project-wizard.md). Settings can be prefilled, e.g. `--new 1 my-project my.root.pkg my my`. |\n| `--java [version]` | Override the Java version for this run, e.g. `--java 17`. |\n| `--install [pkg] [version]` | Install a software package. Uses the default version from `tool-version-default.properties` unless a version is specified. Add `-d` or `--default` to mark the installed version as the default. See [Package Development](docs/package-development.html) for creating custom packages. |\n| `--packages` | List all supported packages. |\n| `--setenv` | Set all internal environment variables (adds installed tools to `PATH`). This is the recommended way to make all managed tools available on the command line. It adds tools like git, node, java, maven, gradle, python, trivy, ant and others to the current `PATH`. For GraalVM, only `GRAALVM_HOME` is set (not added to `PATH`). On Windows, if Visual Studio Build Tools are installed, the VC environment is initialized automatically via `vcvars64.bat`. |\n| `--nushell` | When used with `--setenv`, output [Nushell](https://www.nushell.sh/)-compatible syntax (`$env.VAR = '...'`) instead of modifying the current shell. See [Nushell support](#nushell-support) below. |\n| `--update` | Update the custom config. Can be combined with `--force`. |\n| `-exp`, `--explore` | Open the file explorer at the current path. |\n| `--silent` | Suppress console output from common-build. |\n| `--force` | Force a fresh installation (re-download and re-extract). |\n| `--offline` | Use offline mode (normally auto-detected). |\n| `--verbose` | Enable verbose output. |\n| `--default` | Mark an installed package version as the default. |\n\n\n## Supported Packages\n\nThe following packages can be installed via `cb --install \u003cpackage\u003e`:\n\n| Package | Default Version | Description |\n|---|---|---|\n| [ant](https://ant.apache.org/) | 1.10.15 | Apache Ant build tool |\n| [btrace](https://github.com/btraceio/btrace) | 2.2.6 | BTrace dynamic tracing tool |\n| [docker](https://www.docker.com/) | | Docker |\n| [eclipse](https://www.eclipse.org/) | 2026-03 | Eclipse IDE (JEE package) |\n| [flutter](https://flutter.dev/) | 3.41.5 | Flutter SDK |\n| [gaiden](https://github.com/kobo/gaiden) | 1.3 | Gaiden documentation tool |\n| [gradle](https://gradle.org/) | 8.13 | Gradle build tool |\n| [groovy](https://groovy-lang.org/) | 4.0.31 | Apache Groovy |\n| [insomnia](https://insomnia.rest/) | | Insomnia API client |\n| [intellij](https://www.jetbrains.com/idea/) | 2025.2.6.1 | IntelliJ IDEA |\n| [graalvm](https://www.graalvm.org/) | 21.0.2 | GraalVM Community Edition |\n| [java](https://adoptium.net/) | 21 | Java JDK |\n| [jmeter](https://jmeter.apache.org/) | 5.6.3 | Apache JMeter |\n| [maven](https://maven.apache.org/) | 3.9.14 | Apache Maven |\n| [micronaut](https://micronaut.io/) | 4.10.18 | Micronaut framework CLI |\n| [mucommander](https://www.mucommander.com/) | 1.6.0-1 | muCommander file manager |\n| [node](https://nodejs.org/) | 24.14.1 | Node.js |\n| [postman](https://www.postman.com/) | | Postman API client |\n| [python](https://www.python.org/) | 3.13.12 | Python |\n| [rust](https://www.rust-lang.org/) | | Rust toolchain |\n| [sbt](https://www.scala-sbt.org/) | 1.12.8 | Scala Build Tool |\n| [squirrel](https://squirrel-sql.sourceforge.io/) | 5.1.0 | SQuirreL SQL Client |\n| [trivy](https://trivy.dev/) | 0.69.3 | Trivy security scanner |\n| [visualvm](https://visualvm.github.io/) | 2.2.1 | VisualVM profiler |\n| [vscode](https://code.visualstudio.com/) | 1.113.0 | Visual Studio Code |\n\nWindows-only packages: [`git`](https://git-scm.com/), [`npp`](https://notepad-plus-plus.org/) (Notepad++), [`multicommander`](https://multicommander.com/), [`winmerge`](https://winmerge.org/), [`wt`](https://github.com/microsoft/terminal) (Windows Terminal), [`scoop`](https://scoop.sh/), [`rangerdesktop`](https://rancherdesktop.io/).\n\n\n## Utility Scripts\n\nIn 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`.\n\n| Script | Description |\n|---|---|\n| `cb-clean-files` | Delete regular files older than N days from a single directory (top-level, non-recursive). Supports glob pattern filter, `--dry-run` and `--silent` modes. Rejects dangerous target paths (`/`, `$HOME`, `/usr`, `/etc`, ...). |\n| `cb-cleanup` | Cleanup common-build artifacts (caches, temp directories, stale downloads). Calls `cleanup-start` / `cleanup-end` lifecycle hooks if a custom hook script is configured. |\n| `cb-dockterm` | Open an interactive terminal inside a running Docker container. Types are defined in `conf/dockterm-types.properties` (key = type name, value = Docker image). Default types: alpine, arch, debian, fedora, kali, ubuntu. Add custom entries to use private or corporate images. |\n| `cb-filetail` | Follow/tail a file (like `tail -f`) with optional `grep` filtering — cross-platform, works on Windows too. |\n| `cb-meminfo` | Print memory usage information for the current host. |\n| `cb-open-ports` | List all open TCP/UDP ports on the host. Accepts optional filter arguments (e.g. `cb-open-ports 8080 443`). |\n| `cb-shortcut` | Create Windows desktop shortcuts (Windows-only). |\n| `cb-version-filter` | Filter a list of semver version numbers by major-version thresholds and previous-major patch thresholds. Accepts input via stdin, file, or `--path`. Useful for pruning old release versions. Example: `echo 2.2.1 2.1.0 1.3.4 1.2.0 \\| cb-version-filter --majorThreshold 2 --previousMajorPatchThreshold 2` |\n\n\n## Examples\n\nRun a build:\n```bash\ncb\n```\n\nRun a build with a specific Java version:\n```bash\ncb --java 17\n```\n\nInstall a package:\n```bash\ncb --install gradle\n```\n\nInstall a specific version and set it as default:\n```bash\ncb --install gradle 8.12 --default\n```\n\nSet up environment (recommended — add all managed tools to PATH):\n```batch\n:: Windows:\ncb --setenv\n```\n```bash\n# Linux/Mac:\n. cb --setenv\n# or\nsource cb --setenv\n```\n```nu\n# Nushell (save output to a file, then source it):\ncb --setenv --nushell | save -f ~/.config/nushell/cb-tools.nu\nsource ~/.config/nushell/cb-tools.nu\n```\n\nThis makes tools like java, gradle, maven, node, python, git, trivy, ant, etc. directly available on the command line. GraalVM is not added to `PATH` but `GRAALVM_HOME` is set.\n\nList available packages:\n```bash\ncb --packages\n```\n\nCreate a new project:\n```bash\ncb --new\n```\n\nUpdate common-build itself to the latest version:\n```bash\ncb --install cb\n```\n\n\n## Environment Variables\n\n| Variable | Description | Default |\n|---|---|---|\n| `CB_DEVTOOLS` | Root directory for all dev tools. | `$HOME/devtools` (Linux/macOS), `c:\\devtools` (Windows) |\n| `CB_DEVTOOLS_NAME` | Name of the devtools directory (without path). | `devtools` |\n| `CB_DEVTOOLS_DRIVE` | (Windows only) Drive letter where devtools are installed. | `c:` |\n| `CB_HOME` | Common-build installation directory. | `$CB_DEVTOOLS/toolarium-common-build-v\u003cversion\u003e` |\n| `CB_TEMP` | Temporary directory for work files, download caches, and lock files. | `$TMPDIR/cb-$USER` (Unix), `%TEMP%\\cb` (Windows) |\n| `CB_CUSTOM_CONFIG` | Git URL to a custom config project for full customization. | |\n| `CB_CUSTOM_SETTING` | Path to a custom hook script called during all operations. See [`docs/sample/`](docs/sample/) for templates. | |\n| `CB_PACKAGE_URL` | URL to a directory of additional package zip files. | |\n| `CB_PACKAGE_USER` | Username for accessing `CB_PACKAGE_URL`. | |\n| `CB_PACKAGE_PASSWORD` | Password for `CB_PACKAGE_URL`. Set to `ask` for interactive prompt. | |\n| `CB_ONLINE_ADDRESS` | IP address or hostname for the internet connectivity check. Override for corporate proxies. | `8.8.8.8` |\n| `CB_ONLINE_ADDRESS_PORT` | Port for the connectivity check. | `53` |\n| `CB_ONLINE_TIMEOUT` | Timeout in seconds for the connectivity check. | `2` |\n| `CB_INSTALL_ONLY_STABLE` | Set to `false` to allow pre-release/draft versions during `cb-install`. | `true` |\n\n\n## Tool Version Defaults\n\nThe file `conf/tool-version-default.properties` defines the default version for every managed tool. When you run `cb --install \u003cpackage\u003e` without specifying a version, the version from this file is used. It is a simple `key = value` format:\n\n```properties\njava = 21\ngraalvm = 21.0.2\ngradle = 8.13\nnode = 24.14.1\n```\n\nYou 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`.\n\n\n## Product Types\n\nA **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).\n\nEach product maps a name to a set of key:value pairs separated by `|`:\n\n```properties\nMy product = projectComponentId:myc|projectGroupId:myg|projectRootPackageName:myc.rootpackage.name\n```\n\nWhen 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.\n\nProduct types are optional. If no `product-types.properties` file exists, the wizard skips the product selection step.\n\n\n## Project Types\n\nA **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`.\n\nEach entry maps a type ID to a description and a list of configuration sections:\n\n```properties\njava-application = Simple java application|projectName|projectRootPackageName|projectGroupId|projectComponentId|projectDescription\nvuejs = Vue|projectName=-ui|projectComponentId|projectDescription|install=node|initAction=npx --yes @vue/cli create --default @@projectName@@ \u003e@@logFile@@\n```\n\nAvailable project types include: `java-application`, `java-library`, `config`, `script`, `openapi`, `quarkus`, `vuejs`, `nuxtjs`, `react`, `kubernetes-product`, `documentation`, `container`, and `organization-config`.\n\nFor full details on how project types work and how to configure them, see the [Project Wizard documentation](docs/project-wizard.md).\n\n\n## Per-Project Java Version\n\nPlace a `.java-version` file in your project root containing just the major version number:\n\n```\n17\n```\n\nWhen `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.\n\n\n## How It Works\n\nWhen you run `cb` in a project directory, the following happens:\n\n```\ncb [build-arguments...]\n │\n ├─ 1. Load configuration\n │     Read tool-version-default.properties, custom config, .java-version\n │\n ├─ 2. Set up tools\n │     Resolve and add Java, Gradle/Maven/Ant, and other tools to PATH\n │\n ├─ 3. Run lifecycle hooks\n │     Call custom hook script (if configured): verify-configuration, build-start\n │\n ├─ 4. Execute build\n │     Detect build system (build.gradle → Gradle, pom.xml → Maven, build.xml → Ant)\n │     Run the build with all arguments forwarded\n │\n └─ 5. Post-build\n       Call build-end hook (if configured)\n```\n\nFor `cb --setenv`, only steps 1-2 are executed to set up tools in the current shell.\nFor `cb --install \u003cpackage\u003e`, the tool is downloaded, extracted and linked into the `current/` directory.\nFor `cb --new`, the [project wizard](docs/project-wizard.md) is started instead.\n\n\n## Sample Output of `cb --version`\n\n```\n================================================================================\ntoolarium common build 1.0.14\n\n.: Installed tool versions:\n    - ant: 1.10.15\n    - gradle: 8.13\n    - java: 21\n    - maven: 3.9.14\n    - node: 24.14.1\n    - python: 3.13.12\n    - trivy: 0.69.3\n================================================================================\n```\n\n\n## Special Files\n\n| File | Description |\n|---|---|\n| `.java-version` | Place in a project root to pin a specific Java version (e.g. `17`). |\n| `conf/tool-version-default.properties` | Default versions for all tools. |\n| `conf/tool-version-installed.properties` | Tracks currently installed tool versions. |\n| `conf/project-types.properties` | Project type definitions for `cb --new`. |\n| `conf/product-types.properties` | Product type definitions (optional). |\n| `conf/dockterm-types.properties` | Docker container types for `cb-dockterm`. Key = type name, value = Docker image. |\n\n\n## Customization\n\n### Custom Hook Script\n\nSet `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](docs/sample/) for complete templates:\n\n- [`cb-custom-sample.sh`](docs/sample/cb-custom-sample.sh) / [`cb-custom-sample.bat`](docs/sample/cb-custom-sample.bat) — fully commented samples with all hooks active\n- [`cb-custom.sh`](docs/sample/cb-custom.sh) / [`cb-custom.bat`](docs/sample/cb-custom.bat) — minimal templates ready to copy and customize\n\n### Custom Config Project\n\nFor 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.\n\nAlternatively, add the git URL to the file `$HOME/.common-build/conf/.cb-custom-config`.\n\nFor 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](docs/organization-config.md).\n\n\n## Nushell Support\n\nCommon-build supports [Nushell](https://www.nushell.sh/) 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.\n\n**Manual usage:**\n\n```nu\n# Print Nushell env commands to stdout\ncb --setenv --nushell\n\n# Save and source in one step\ncb --setenv --nushell | save -f ~/.config/nushell/cb-tools.nu\nsource ~/.config/nushell/cb-tools.nu\n```\n\n**Automatic setup via installer:**\n\nWhen `cb-install` (or `cb-install.bat`) detects that Nushell is installed, it automatically:\n1. Creates `~/.config/nushell/cb-setenv.nu` with `CB_HOME` and `PATH` configuration.\n2. Adds a `source` line to `~/.config/nushell/env.nu` so the configuration is loaded on every Nushell startup.\n\nOn subsequent updates (`cb --install cb`), the `cb-setenv.nu` file is regenerated with the updated `CB_HOME` path.\n\n\n## Versioning and compatibility\n\nThis project follows [Semantic Versioning](https://semver.org/):\n\n- **Patch** releases (e.g. 1.0.1 → 1.0.2) are fully backward compatible — bug fixes only.\n- **Minor** releases (e.g. 1.0.x → 1.1.0) add new features while remaining backward compatible — all existing scripts, environment variables, and configurations continue to work.\n- **Major** releases (e.g. 1.x → 2.0.0) may introduce breaking changes.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed compatibility guidelines.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolarium%2Fcommon-build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoolarium%2Fcommon-build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolarium%2Fcommon-build/lists"}