Boss
Boss is an open source dependency manager inspired by npm for projects developed in Delphi and Lazarus.
🚀 Getting started
We have a Getting Started article to help you get started with Boss.
📦 Installation
Download setup
Just type boss in the terminal
(Optional) Install a Boss Delphi IDE complement
Or you can use the following the steps below:
Download the latest version of the Boss
Extract the files to a folder
Add the folder to the system path
Run the command boss in the terminal
📚 Available Commands
> Init
Initialize a new project and create a boss.json file. Add -q or --quiet to skip interactive prompts and use default values.
> Install
Install one or more dependencies with real-time progress tracking:
Progress Tracking: Boss displays progress for each dependency being installed:
The dependency name is case insensitive. For example, boss install horse is the same as boss install HORSE.
You can also specify the compiler version and platform:
Aliases: i, add
> Uninstall
Remove a dependency from the project:
Aliases: remove, rm, r, un, unlink
> Update
Update all installed dependencies to their latest compatible versions:
Aliases: up
> Upgrade
Upgrade the Boss CLI to the latest version. Add --dev to upgrade to the latest pre-release:
> Dependencies
List all project dependencies in a tree format. Add -v to show version information:
Aliases: dep, ls, list, ll, la, dependency
> Run
Execute a custom script defined in your boss.json file. Scripts are defined in the scripts section:
> Login
Register credentials for a repository. Useful for private repositories:
Aliases: adduser, add-user
> Logout
Remove saved credentials for a repository:
> Version
Show the Boss CLI version:
Aliases: v
Global Flags
> Global (-g)
Use global environment for installation. Packages installed globally are available system-wide:
> Debug (-d)
Enable debug mode to see detailed output:
> Help (-h)
Show help for any command:
Configuration
> Cache
Manage the Boss cache. Remove all cached modules to free up disk space:
Aliases: purge, clean
> Delphi Version
You can configure which Delphi version BOSS should use for compilation. This is useful when you have multiple Delphi versions installed.
List available versions
Lists all detected Delphi installations (32-bit and 64-bit) with their indexes.
Select a version
Selects a specific Delphi version to use globally. You can use the index from the list command, the version number, or the version with architecture.
Example:
> Git Client
You can configure which Git client BOSS should use.
embedded: Uses the built-in go-git client (default).
native: Uses the system's installed git client (git.exe).
Using native is recommended on Windows if you need support for core.autocrlf (automatic line ending conversion).
Shallow Clone
You can enable shallow cloning to significantly speed up dependency downloads. Shallow clones only fetch the latest commit without the full git history, reducing download size dramatically (e.g., from 127 MB to <1 MB for large repositories).
Note: Shallow clone is disabled by default to maintain compatibility. When enabled, you won't have access to the full git history of dependencies.
You can also temporarily enable shallow clone using an environment variable:
> Project Toolchain
You can also specify the required compiler version and platform in your project's boss.json file. This ensures that everyone working on the project uses the correct toolchain.
Add a toolchain section to your boss.json:
Supported fields in toolchain:
compiler: The compiler version (e.g., "37.0").
platform: The target platform ("Win32" or "Win64").
path: Explicit path to the compiler (optional).
strict: If true, fails if the exact version is not found (optional).
Samples
Using semantic versioning to specify update types your package can accept
You can specify which update types your package can accept from dependencies in your package's boss.json file.
For example, to specify acceptable version ranges up to 1.0.4, use the following syntax:
Patch releases: 1.0 or 1.0.x or ~1.0.4
Minor releases: 1 or 1.x or ^1.0.4
Major releases: * or x
boss.json File Format
The boss.json file is the manifest for your Delphi/Lazarus project. It contains metadata, dependencies, build configuration, and custom scripts.
Complete Structure
Here's a comprehensive example showing all available fields:
Field Descriptions
Core Fields
name (required): Package name. Must be unique if publishing.
"name": "my-awesome-library"
name (required): Package name. Must be unique if publishing.
description (optional): A brief description of your project.
"description": "REST API framework for Delphi"
description (optional): A brief description of your project.
version (required): Package version following semantic versioning.
"version": "1.2.3"
version (required): Package version following semantic versioning.
homepage (optional): Project website or repository URL.
"homepage": "https://github.com/myuser/my-project"
homepage (optional): Project website or repository URL.
Source Configuration
mainsrc (optional): Main source directory path.
"mainsrc": "src/"
mainsrc (optional): Main source directory path.
browsingpath (optional): Additional paths for IDE browsing (semicolon-separated).
"browsingpath": "src/;src/controllers/;src/models/"
browsingpath (optional): Additional paths for IDE browsing (semicolon-separated).
Build Configuration
projects (optional): List of Delphi project files (.dproj) to compile.
"projects": [
"MyProject.dproj",
"MyLibrary.dproj"
]
Note: If not specified, Boss won't compile the package but will still manage dependencies.
projects (optional): List of Delphi project files (.dproj) to compile.
Note: If not specified, Boss won't compile the package but will still manage dependencies.
Dependencies
dependencies (optional): Map of package dependencies with version constraints.
"dependencies": {
"github.com/HashLoad/horse": "^3.0.0",
"dataset-serialize": "~2.1.0",
"jhonson": "*"
}
Supported version formats:
Exact version: "1.0.0"
Caret (minor updates): "^1.0.0" (allows 1.x.x, but not 2.x.x)
Tilde (patch updates): "~1.0.0" (allows 1.0.x, but not 1.1.x)
Wildcard (any): "*" or "x"
Range: ">=1.0.0 <2.0.0"
dependencies (optional): Map of package dependencies with version constraints.
Supported version formats:
Exact version: "1.0.0"
Caret (minor updates): "^1.0.0" (allows 1.x.x, but not 2.x.x)
Tilde (patch updates): "~1.0.0" (allows 1.0.x, but not 1.1.x)
Wildcard (any): "*" or "x"
Range: ">=1.0.0 <2.0.0"
Custom Scripts
scripts (optional): Custom commands you can run with boss run <script-name>.
"scripts": {
"build": "msbuild MyProject.dproj /p:Config=Release",
"test": "dunitx-console.exe MyProject.exe",
"clean": "del /s .dcu .exe",
"deploy": "xcopy /s /y bin\\*.exe deploy\\"
}
Execute with:
boss run build
boss run test
scripts (optional): Custom commands you can run with boss run <script-name>.
Execute with:
Engine Requirements
engines (optional): Specify minimum compiler/platform requirements.
"engines": {
"compiler": ">=35.0",
"platforms": ["Win32", "Win64", "Linux64"]
}
compiler: Minimum compiler version
platforms: Supported target platforms
engines (optional): Specify minimum compiler/platform requirements.
compiler: Minimum compiler version
platforms: Supported target platforms
Toolchain Configuration
toolchain (optional): Specify the exact toolchain to use for this project.
"toolchain": {
"compiler": "37.0",
"platform": "Win64",
"path": "C:\\Program Files\\Embarcadero\\Studio\\37.0",
"strict": true
}
compiler: Required compiler version
platform: Target platform ("Win32", "Win64", "Linux64", etc.)
path: Explicit path to the compiler (optional)
strict: If true, fails if the exact version is not found (default: false)
toolchain (optional): Specify the exact toolchain to use for this project.
compiler: Required compiler version
platform: Target platform ("Win32", "Win64", "Linux64", etc.)
path: Explicit path to the compiler (optional)
strict: If true, fails if the exact version is not found (default: false)
Minimal boss.json
The minimal valid boss.json file:
Creating a new boss.json
Use boss init to create a new boss.json interactively:
Or use quiet mode for defaults:
Example: Library Package
Example: Application Package
💻 Code Contributors
