As a demonstration of how to use libraries from the DUB registry as project dependencies, we're going to develop a short little program called colors. It takes any command line-arguments you feed it and displays it to the console with random foreground and background colors and in a random style. To do this, it uses a library developed by Pedro Tacla Yamada, called colorize, as a dependency.

On the main page of the DUB repository, linked above, you can find a link to the registry page for the colorize library. Following that will bring up the project information page, as shown here:

The top section of the page displays information mostly taken from the library's package configuration file. The link to GitHub was provided when the project was registered. Following that is an example of how to include the library as a dependency in your project. Finally, the last part of the page is the README file from the project's GitHub repository.

Version numbers in DUB packages follow the Semantic Version (or SemVer) format (see http://semver.org/). The basic format is MajorVersion.MinorVersion.PatchLevel. Additional information can be tagged on to the end, for example 1.1.0+2.068 might indicate version 1.1.0 of a library, which required version 2.068 of DMD. When adding dependencies to the DUB project configuration, a version number must be specified. There is more than one way to do it, each having different meanings.

>=1.0.5 means any version greater than or equal to version 1.0.5, while <1.1.0 means any version less than version 1.1.0, and >=1.0.5 <1.1.0 constrains the version to the anything greater than or equal to 1.0.5 and less than 1.1.0. The latter form has a shortcut in the form of ~>1.0.5, which is the recommended format for most projects. See the section titled Version specifications at http://code.dlang.org/package-format?lang=sdl#version-specs for more details.

For our little example project, the first thing to do is to create a dub.sdl file in $LEARNINGD/Chapter08/colors. It looks like this:

name colors
description "Print randomly colored text to stdout."
copyright "Copyright © 2015, Mike Parker"
authors "Mike Parker"
dependency "colorize" version="~>1.0.5"

Next, create a source subdirectory in the same location. There, create a file app.d. At the top of the file, we need two imports.

import colorize;

The enumerations fg and bg in the colorize module represent foreground and background colors, respectively. mode represents different text styles. There is an overload of std.random.uniform which takes an enumeration as a template argument and returns a random member from the enum. We can use that to randomly select colors and modes in the function coloredPrint.

void coloredPrint(string msg) {
    import std.random : uniform;
    auto fore = uniform!fg;
    auto back = uniform!bg;
    auto style = uniform!mode;
    cwriteln(msg.color(fore, back, style));
}

The function cwriteln is part of colorize. It takes the place of writeln. Finally, a main function which ties it all together.

void main(string[] args) {
    import std.stdio : writeln, readln;
    writeln("Enter some text to colorize:");
    auto input = readln();
    coloredPrint(input);
}

The output of one run looked like this for me:

That's all there is to it. No matter how complex the library, if it's in the DUB registry, DUB will manage everything for you with one simple addition to the project configuration.

To create a library for the DUB registry, there's a major point to keep in mind for the project configuration: do not provide an app.d in the project's source directory unless you explicitly add the line "targetType": "library" to the project configuration. If no target type is specified, DUB will compile an executable when it encounters an app.d in the source directory. If there is no app.d, it will generate a library instead. Let's try it.

First, let's create a dub.sdl in the directory $LEARNINGD/Chapter08/mylib, which has the following content:

name "mylib"
description "An example DUB-enabled library."
copyright "Copyright © 2015, Mike Parker"
authors "Mike Parker"
dependency "colorize" version="~>1.0.5"

Now, let's create a file in the source subdirectory called mylib.d. It has a single function:

module mylib;
void sayIt() {
    import std.stdio : writeln;
    writeln("I don't care what you say anymore, this is my lib.");
    writeln("Go ahead with your own lib. Leave me alone!");
}

Now, we can execute dub in the project directory, with or without the build command, and we'll see a shiny new library in the lib subdirectory. If you were really going to register the new library with the DUB registry, you would first need to create a project either at GitHub or BitBucket (which are the only two supported providers at the time of writing), push everything in the project directory to the remote repository, and then tag a new release.

Once the repository is set up, you would head over to http://code.dlang.org/ and register a new account if you don't have one already. After registering and logging in, you would then go to the My packages link in the menu bar (http://code.dlang.org/my_packages). At the top of that page is a button labelled Register new package.

Clicking on that button leads to a page that has a choice box and two text fields.

At the time of writing, the choice box offers two options: GitHub and BitBucket. After making the appropriate selection, you would fill in the first field with your GitHub or BitBucket account name, the second with the name of the repository, and finally click on the Register package button. After that, the newly registered library would show up at the top of the registry's main page on its next update (and updates happen fairly frequently).

Once a package is registered, new tagged releases in the git repository will automatically be picked up by the registry. This may take some time though, as not all packages are checked for updates at one time. To help speed things along, you can log in, go to My packages, click on the link for the updated library, and then click on Trigger manual update. If that button is greyed out and you are not able to click on it, it means that the package is already scheduled for an update.

It's inevitable that the interface will be updated at some point, making these instructions obsolete, but the basic functionality should remain consistent.

At the time of writing, in mid-October of 2015, there are nearly 600 packages in the DUB registry and it's growing every week. The majority of the packages are libraries that scratch one itch or another. To more efficiently browse the registry and find the libraries you need, there is a mechanism that package maintainers can use to categorize their projects.

At the top of the main registry page is a choice box labeled Select category. There are two options, Development library and Stand-alone applications. Select the former. This will display a new choice box that allows you to select a category. Some of these may open up a third choice box to select a sub-category.

Categories can be added for your own DUB packages by logging in, clicking on My packages in the menu bar, and selecting the project you want to categorize. There, on the project page, you will find choice boxes allowing you to associate up to four categories with the package.