Introduction

DUB is a build tool for D projects with support for automatically retrieving dependencies and integrating them in the build process. The design emphasis is on maximum simplicity for simple projects, while providing the opportunity to customize things when needed.

An important property of the build description for each project is that it only contains the minimally needed information to describe how a package is built, skipping things such as build type (debug, release, unittest etc.). What is specified can be done so in a mostly platform and compiler agnostic way using abstract fields (e.g. import paths or used libraries) and by having DUB automatically translate common DMD command line flags to GCC or LDC flags.

This kind of representation has several important advantages. It allows DUB to generate VisualD and Mono-D project files, makes most packages automatically usable with any supported compiler and finally means that all packages support the same build types and platforms. Also, by using DUB itself as a library, external build tools can access the package description to provide further functionality without requiring the packages to add explicit support to their build script.

Finally, in many cases there is no explicit configuration needed at all, by relying on some conventions:

Installation

Simply download the pre-compiled package for your platform. On Windows, the installer will perform all the necessary setup. On other systems, the only thing that you may want to do, other than extracting the archive, is to place the dub executable somewhere in your PATH so that you can call it from anywhere.

If a binary is not available for your platform, simply clone or download the dub repository and run the contained ./build.sh. You need to have DMD and libcurl development files installed (Only DMD on Windows).

Building foreign projects

Building existing projects is as simple as getting the package and running either dub run (or short dub) to build and run or dub build from the package's root directory to build it. DUB will automatically download all needed dependencies and issue the build command. See the command line documentation for information on how to customize the build process.

To get the package, either use git clone with the projects git URL, or type dub fetch <package name> to have the package downloaded and installed in a package repository in your user folder. dub run <package name> can then be used to build and execute the package. dub fetch --local <package name> can be used instead to extract the package into a sub folder of the current working directory.

Creating an own project

The easiest way is to type dub init <package name> on the command line to have DUB create an application skeleton for you. It will create the following directory structure:

Folder Description
<package_name>/ The root folder of the new project
    source/ The root folder for the project's source code
        app.d Suggested source file for the application entry point - this will automatically excluded if the project is used as a library
        <package_name>/ The suggested root package under which the project's source code will be stored
    public/ A folder for putting public files that are used at run time (mostly meant for web service projects)
    views/ May contain string import files, such as HTML or UI templates
    dub.sdl or dub.json Contains the package description of the project

Note that this directory structure is just a suggestion for a standard way of laying out things. Any of these folders can be removed or named differently, as long as the package description is adjusted accordingly. See the package format specification page for a full reference of the possibilities.

It is recommended to version your code using GIT tags of the form v1.0.0, where the "1.0.0" can be any valid SemVer version number. Please try to follow the rules of the SemVer specification as close as possible (regarding breaking changes and added features). This has a fundamental effect on the vitality of the overall package ecosystem, so it's worth putting some care into this.

The version numbers can then be used to refer to specific commits/revisions of your package. See the package version section of the package description format page for more information. If you need to use a version control system other than GIT, please open a ticket or add a comment if an equivalent ticket already exists.

After you have your new package in place, you can publish it here.

Single-file packages

For small applications or scripts, DUB supports a special mode where the whole package is contained in a single .d file (it must have that extension). The contents that would otherwise go into the package recipe file (dub.sdl/dub.json) are embedded in a /+ … +/ comment within the file itself:

#!/usr/bin/env dub
/+ dub.sdl:
	name "hello"
+/
void main() {
	import std.stdio : writeln;
	writeln("Hello, World!");
}

This can now be executed with dub run --single hello.d (append -- <app arguments> to pass arguments to the generated executable), or using the short syntax dub hello.d <app arguments>. The latter also enables execution as a script using just ./hello.d with the optional shebang line at the top of the example (needs chmod +x hello.d first). Single-file packages cannot be used to create library packages.

Using dependencies that are not on the public registry

cases where certain dependencies are not available in the package registry, for example because they are in closed source repositories, or because they are modified forks of the official packages, there are several possibilities to choose from:
dub add-path
Adds a local search directory. All direct sub directories will be searched for packages and those are preferred over packages downloaded from the registry.
dub add-local
Similar to the above, but only adds a single package directory.
dub add-override
Can be used to override a certain version or version range of a package with another version, branch or path. This can be used to change dependencies system wide without modifying the description or selection files of a package.
Path based dependencies
Dependencies in the package description can use a path instead of a version. This can be used together with Git sub-modules or -trees, or with an otherwise known directory layout to use arbitrarily defined versions of a dependency. Note that this should only be used for non-public packages.
Path based selections
The dub.selections.json file can be used to specify arbitrary versions, branches, or paths, even if they contradict with the dependency specification of the packages involved (DUB will output a warning message in that case).

Command line interface

See the command line interface documentation for an overview of DUB's CLI. You can also view the available command line options by running dub --help or dub <command> --help.