Boss is a dependency manager for Delphi and Lazarus projects, providing automated package installation, version resolution, and build orchestration. This document introduces the system's purpose, key features, and high-level architecture.
For installation and initial setup procedures, see Installation and Setup. For detailed CLI command usage, see CLI Commands Reference. For internal architecture details, see Core Architecture.
Sources: README.md1-25 app.go1-15
Boss is an open-source dependency manager inspired by npm, designed specifically for Delphi and Lazarus development. It automates the management of project dependencies by fetching packages from Git repositories, resolving semantic version constraints, updating Delphi project files, and orchestrating builds with proper dependency ordering.
The system addresses the challenge of managing third-party libraries in Pascal-based IDEs, where manual library path configuration and DCP (Delphi Compiled Package) management are traditionally error-prone and time-consuming.
Key Problem Solved: Eliminates manual dependency management by automating package installation, version resolution, and Delphi project configuration through a declarative manifest (boss.json) and deterministic lock file (boss.lock).
Sources: README.md17-25 README.md337-377
^), tilde (~), and wildcard (*) constraints for flexible version matchingboss.lock for reproducible builds across environmentsboss update~/.boss/cache/ with separate Git metadata and working treesBOSS_GIT_SHALLOW environment variable.dproj and .lpi files to include dependency source pathsrequires clauses./modules/ for project-specific dependencies~/.boss/dependencies/ via -g flag for shared packagesSources: README.md40-182 README.md327-336 internal/core/domain/dependency.go27-147
Boss Architecture - Code Entity Mapping
The system follows a clean architecture pattern with clear separation of concerns across four layers. The CLI Layer implements Cobra commands that delegate to the Service Layer for business logic. The Domain Layer contains pure business entities (Package, PackageLock, Dependency) with no external dependencies. The Infrastructure Layer provides adapters for Git operations, Windows Registry access, and filesystem operations.
Sources: app.go1-15 internal/core/domain/dependency.go1-148
Boss Domain Model - Entity Relationships
| Entity | Location | Primary Responsibility |
|---|---|---|
Package | internal/core/domain/package.go | Represents the boss.json manifest with declared dependencies and build configuration |
PackageLock | internal/core/domain/package_lock.go | Represents the boss.lock file tracking exact installed versions and artifacts |
Dependency | internal/core/domain/dependency.go28-32 | Encapsulates a single dependency with repository URL, version constraint, and authentication mode |
Installed | internal/core/domain/package_lock.go | Records the resolved version and compiled artifacts for an installed dependency |
The Dependency type provides critical operations at internal/core/domain/dependency.go34-147:
HashName() internal/core/domain/dependency.go35-42: Generates MD5 hash for cache directory namingGetURL() internal/core/domain/dependency.go66-82: Resolves HTTPS or SSH URL based on authentication configurationParseDependency() internal/core/domain/dependency.go85-104: Parses repository string and version constraint into structured objectNeedsVersionUpdate() internal/core/domain/dependency.go135-147: Performs semantic version comparison to determine update necessitySources: internal/core/domain/dependency.go1-148
Boss uses a three-tier configuration system with increasing specificity:
Configuration System - Code Mapping
| Scope | Location | Managed By | Purpose |
|---|---|---|---|
| Environment Variables | Shell environment | User/CI system | Override paths and feature flags (e.g., BOSS_HOME, BOSS_GIT_SHALLOW) |
| Global Configuration | ~/.boss/config.json | boss config commands | User-wide settings (Git mode, Delphi version, authentication) |
| Project Manifest | ./boss.json | boss init, manual editing | Project dependencies, toolchain requirements, build scripts |
| Lock File | ./boss.lock | boss install, boss update | Exact resolved versions for reproducible builds |
The env package provides path resolution at multiple levels:
GetBossHome() pkg/env/env_test.go66-86: Returns ~/.boss/ or BOSS_HOME environment variableGetCacheDir() pkg/env/env_test.go88-95: Returns ~/.boss/cache/ for Git repository storageGetModulesDir() pkg/env/env_test.go106-113: Returns ./modules/ or ~/.boss/dependencies/ based on global flagGetCurrentDir() pkg/env/env_test.go115-141: Returns current directory or global directory based on env.GetGlobal()Sources: pkg/env/env_test.go1-248 README.md183-294
.dproj compilation.dproj and .lpi file modification for library paths and DCP injectionSources: README.md1-25
my-project/
├── boss.json # Project manifest
├── boss.lock # Resolved versions
├── modules/ # Downloaded dependencies
│ ├── horse/
│ │ ├── .git # Gitdir pointer to ~/.boss/cache/
│ │ └── src/ # Working tree
│ └── jhonson/
└── MyProject.dproj # Modified with library paths
-g flag)~/.boss/
├── config.json # Global configuration
├── cache/ # Shared Git repositories
│ ├── a3f2b9.../ # Hashed repository name
│ │ └── .git/ # Git metadata
│ └── 8c4e1d.../
├── dependencies/ # Global modules
│ ├── {DelphiHash}/ # Per-Delphi-version isolation
│ │ ├── horse/
│ │ └── jhonson/
│ └── env/ # Build artifacts
│ ├── bpl/ # Compiled packages
│ ├── dcp/ # Package definitions
│ └── dcu/ # Compiled units
└── bin/ # Global executables
The cache structure uses separate Git directories (.git/ metadata in cache, working trees in modules) to enable multiple projects to share the same repositories while maintaining independent working copies at different versions.
Sources: README.md183-294 internal/adapters/secondary/git/git_embedded.go98-112
The application entry point is minimal, delegating immediately to the Cobra command framework:
main() [app.go:11-15]
└─> cmd.Execute() [cmd package]
├─> Parse CLI flags (--global, --debug, --compiler, --platform)
├─> Route to subcommand (init, install, uninstall, config, etc.)
└─> Execute command handler
├─> Load configuration (env.GlobalConfiguration)
├─> Initialize services (installer, compiler, git adapter)
└─> Perform operation with progress tracking
All commands follow the pattern: parse arguments → load configuration → initialize services → execute business logic → handle errors. The msg package provides structured logging with debug, info, warning, and error levels.
Sources: app.go1-15
Refresh this wiki