First Steps

Starting a new project

To create a new project in a folder called myproject/, run:

$ dub init myproject

This begins an interactive session:

Package recipe format (sdl/json) [sdl]:
Name [myproject]:
Description [A minimal D application.]: My first project
Author name [imadev]: My Name
License [proprietary]: Boost
Copyright string [Copyright © 2022, My Name]:
Add dependency (leave empty to skip) []:
Successfully created an empty project in '/home/imadev/src/myproject'.
Package successfully created in myproject

DUB has created a "myproject" directory containing a .gitignore, a dub recipe, and a source tree containing an app.d file.

myproject/
├── source/
│   └── app.d
├── .gitignore
└── dub.json

Notice that there are two configuration file formats available. JSON is a commonly-known format, and SDL (SDLang) is a clean, minimalist format. Both offer equivalent functionality (though unlike JSON, SDLang allows comments); use whichever you prefer.

The following configuration file is generated:

dub.sdldub.json

name "myproject"
description "My first project"
authors "My Name"
copyright "Copyright © 2022, My Name"
license "Boost"

{
    "name": "myproject",
    "authors": [
        "My Name"
    ],
    "description": "My first project",
    "copyright": "Copyright © 2022, My Name",
    "license": "Boost"
}

For more information and help with configuring your builds, see the recipe documentation. DUB is smart and will provide sane defaults, but you can override almost anything.

Execute dub build to build your project, dub run to build and run it, or dub test to build and run unit tests. The last line below is the output of the default application.

dub run

    Starting Performing "debug" build using dmd for x86_64.
    Building myproject ~master: building configuration [application]
     Linking myproject
     Running myproject 
Edit source/app.d to start your project.

See the command line interface documentation, or run dub --help and dub --help for more information.

Adding a dependency

When you find a package to use from the DUB registry, add it to the dependency list in your DUB configuration file by running dub add <packageName>.

The DUB registry uses git tags to determine application versioning and DUB's dependency management is designed to work best according to SemVer rules. Please follow the rules of the SemVer specification for all packages you list on the registry. See the recipe documentation for more information on dependency version specification.

You can publish packages to the registry here.

Building a third-party project

You can easily fetch and build third-party projects published to the dub registry via the dub fetch <package name> command.

To get the package, run dub fetch <package name> to download the package and install it in your user build directory. dub run <package name> can then be used to build and execute the package. Adding the --cache=local flag to the fetch command will extract the package into a subfolder of the current working directory.

Publishing packages

To publish your own packages, just create a new package with a valid package recipe like above (see the package recipe specification) and follow the instructions on the publishing packages page.

---

Summary

These are the most commonly used commands you will use with DUB:

# builds the project in the current folder
$ dub build

# builds & runs the project in the current folder
$ dub run
# or shorthand equivalent:
$ dub

# asks to download "someapp" from the registry and runs it
$ dub run someapp

---

Last update: November 23, 2023
Created: September 1, 2023