DUB Package Management

Analogy categoryAnalogies

What DUB Does for a D Project

DUB is D's de-facto build tool and package manager, analogous to Cargo for Rust or npm for Node: a dub.json or dub.sdl manifest at the project root declares the package name, dependencies with semver ranges, and build configurations, and running 'dub build' or 'dub run' fetches missing dependencies from the DUB registry at code.dlang.org, resolves version conflicts, and invokes the compiler -- dmd, ldc2, or gdc -- with the right flags automatically.

🏏

Cricket analogy: A franchise's team manager doesn't personally negotiate every player's central contract -- the board office handles registrations and paperwork so the manager just fields the XI; DUB plays that board-office role, resolving dependency versions so you just run 'dub build'.

The dub.json / dub.sdl Manifest

The manifest -- dub.json (plain JSON) or dub.sdl (a terser SDLang-based syntax) -- declares the package name, targetType (executable, library, sourceLibrary, or dynamicLibrary), and a dependencies object mapping package names to version specifiers such as '~>2.0.1' to accept compatible patch and minor updates or '==1.0.0' to pin exactly; DUB also supports named configurations and subPackages so a single repository can produce multiple build targets, and buildTypes like debug, release, and unittest select different compiler flag sets without editing the manifest.

🏏

Cricket analogy: A player's central contract specifies exact clauses -- match fees, IPL release windows, retainer tier -- in one document the board references; a dub.json manifest is that same single contract, spelling out dependency version clauses like '~>2.0.1' that DUB references on every build.

json

{
  "name": "myapp",
  "description": "A sample D application",
  "authors": ["Jane Doe"],
  "targetType": "executable",
  "dependencies": {
    "vibe-d": "~>0.9.6",
    "mir-algorithm": "~>3.10.0"
  },
  "configurations": [
    { "name": "default", "targetType": "executable" }
  ]
}

Resolving Dependencies and the Registry

When you run 'dub build', DUB resolves the full dependency graph against the version ranges in dub.json and writes the exact versions it picked into dub.selections.json, a lockfile that should be committed so teammates and CI get byte-identical dependency versions; running 'dub upgrade' recomputes that resolution against the newest versions satisfying your ranges, while packages themselves are fetched from and published to the public registry at code.dlang.org, or a private registry configured in ~/.dub/settings.json.

🏏

Cricket analogy: The DRS system locks in the exact ball-tracking data used for a review so both teams see the identical evidence; dub.selections.json locks in the exact dependency versions DUB resolved, so every teammate builds against identical evidence.

Run 'dub upgrade' to recompute dub.selections.json against the newest versions allowed by your dub.json ranges, and 'dub add <package>' to add a new dependency and fetch it in one step without hand-editing the manifest.

Publishing and Running Tasks with DUB

Beyond building, 'dub test' compiles and runs the project's unittest blocks, optionally with 'dub test -b unittest-cov' for coverage reports, and 'dub run' builds and immediately executes the resulting binary, which is handy for quick scripts; publishing a package is as simple as pushing a semver git tag such as v1.2.0 to a public repository and registering it once at code.dlang.org, after which DUB automatically picks up new tagged releases for anyone depending on that package.

🏏

Cricket analogy: A domestic player getting picked for the national squad just needs a strong Ranji Trophy season on record -- the selectors watch the stats feed automatically; publishing a DUB package is that same automatic pickup, where DUB watches your repo's git tags and lists new releases without manual submission.

DUB resolves version ranges using semantic versioning, but a badly tagged release -- pushing breaking changes under a patch version like 1.2.4 instead of bumping to 2.0.0 -- will silently break every downstream project using a '~>1.2.0' range on their next 'dub upgrade'. Always follow semver strictly when tagging a published package, and pin exact versions with '==' in production projects if you can't fully trust upstream discipline.

DUB is D's standard build tool and package manager, driven by a dub.json or dub.sdl manifest.
Version specifiers like '~>1.2.0' for compatible updates or '==1.0.0' for an exact pin control which dependency versions are allowed.
dub.selections.json is the resolved lockfile -- commit it so builds are reproducible across machines and CI.
targetType, configurations, and subPackages let one manifest produce multiple build outputs from one repository.
'dub test', 'dub run', and 'dub upgrade' cover testing, quick execution, and re-resolving dependencies respectively.
Publishing to code.dlang.org is as simple as pushing a semver-tagged git release to a public repository.
Sloppy semver tagging upstream can silently break downstream builds using range-based version specifiers.