Introduction

Every DUB package should contain a dub.json (was package.json in earlier versions) file in its root folder. This file contains meta-information about the project and its dependencies. This information is used for building the project and for deploying it using the registry. The following sections give an overview of the recognized fields and their meaning. Note that any unknown fields are ignored for backwards compatibility reasons.

A typical example of a simple application that requires no platform specific setup:

{
	"name": "myproject",
	"description": "A little web service of mine.",
	"authors": ["Peter Parker"],
	"homepage": "http://myproject.com",
	"license": "GPL-2.0",
	"dependencies": {
		"vibe-d": ">=0.7.11"
	}
}

Contents

Global fields

In addition to the fields listed here, all build settings fields are allowed at the global scope.

Name Type Description
name [required] string Name of the package, used to uniquely identify the package. Must be comprised of only lower case ASCII alpha-numeric characters, "-" or "_".
description [required for publishing] string Brief description of the package
homepage string URL of the project website
authors string[] List of project authors
copyright string Copyright declaration string
license [required for publishing] string License(s) under which the project can be used - see the license specification section for possible values
subPackages T[] Defines an array of sub-packages defined in the same directory as the root project, where each entry is either a path of a sub folder or an object of the same formatas a dub.json file - see the sub package section for more information
configurations T[] Speficies an optional list of build configurations (specified using "--config=...") - see the configurations section for more details
buildTypes T[string] Defines additional custom build types or overrides the default ones (specified using "--build=...") - see the build types section for an example
-ddoxFilterArgs string[] Specifies a list of command line flags usable for controlling filter behavior for --build=ddox [experimental]

Sub packages

A package may contain an arbitrary number of additional publicly visible packages. These packages can be defined in the "subPackages" field of the main dub.json file. They can be referenced by concatenating their name with the name of the main package using a colon as a delimiter (i.e. "main-package-name:sub-package-name").

The typical use for this feature is to split up a library into a number of parts without breaking it up into different code repositories:

{
	"name": "mylib",
	"targetType": "none",
	"dependencies": {
		"mylib:component1": "~master",
		"mylib:component2": "~master"
	},
	"subPackages": [
		"./component1/",
		"./component2/"
	]
}

/dub.json

{
	"name": "component1",
	"targetType": "library"
}

/component1/dub.json

The sub directories /component1 and /component2 then contain normal packages and can be referred to as "mylib:component1" and "mylib:component2" from outside projects.

It is also possible to define the sub packages in the root package file, but note that it's discouraged to put the source code of multiple sub packages into the same source folder. Doing so can lead to hidden dependencies to sub packages that haven't been explicitly stated in the "dependencies" section. These hidden dependencies can then result in build errors in conjunction with certain build modes or dependency trees that may be hard to understand.

{
	"name": "mylib",
	"targetType": "none",
	"dependencies": {
		"mylib:component1": "~master",
		"mylib:component2": "~master"
	},
	"subPackages": [
		{
			"name": "component1",
			"targetType": "library",
			"sourcePaths": ["component1/source"],
			"importPaths": ["component1/source"]
		}
	]
}

/dub.json

License specifications

The license field should only contain one of the standard license identifiers if possible. At a later point in time, DUB may use this information to validate proper licensing in dependency hierarchies and output warnings when licenses don't match up. Multiple licenses can be separated using the term "or" and for versioned licenses, the postfix "or later" is allowed to also include any later version of the same license.

The standard license identifiers are: public domain, AFL-3.0 (Academic Free License 3.0), AGPL-3.0 (Affero GNU Public License 3.0), Apache-2.0, APSL-2.0 (Apple Public Source License), Artistic-2.0, BSL-1.0 (Boost Software License), BSD 2-clause, BSD 3-clause, EPL-1.0 (Eclipse Public License), GPL-2.0, GPL-3.0, ISC, LGPL-2.1, LGPL-3.0, MIT, MPL-2.0 (Mozilla Public License 2.0), MS-PL (Microsoft Public License), MS-RL (Microsoft Reciprocal License), OpenSSL (OpenSSL License), SSLeay (SSLeay License), Zlib (zlib/libpng License)

Any other value is considered to be a proprietary license, which is assumed to be incompatible with any other license. If you think there is a license that should be included in this list, please file a quick bug report. Please also note that pure D bindings of C/C++ libraries should specify the same license as the original library, although a stricter but compatible license can be used, too.

Some example license specifications:

"GPL-3.0"
"GPL-2.0 or later"
"GPL-2.0 or later or proprietary"
"GPL-2.0 or LGPL-3.0"
"LGPL-2.1 or proprietary"

Build settings

Build settings fields influence the command line options passed to the compiler and linker. All fields are optional.

Platform specific settings are supported through the use of field name suffixes. Suffixes are dash separated platform identifiers, as defined in the D language reference, but converted to lower case. The order of these suffixes is os-architecture-compiler, where any of these parts can be left off. Examples:

{
	"versions": ["PrintfDebugging"],
	"dflags-dmd": ["-vtls"],
	"versions-x86_64": ["UseAmd64Impl"]
	"libs-posix": ["ssl", "crypto"],
	"sourceFiles-windows-x86_64-dmd": ["lib/win32/mylib.lib"],
}

Inside of build setting values, it is possible to use variables using dollar notation. $PACKAGE_DIR contains the path to the package itself and all other variables are taken from the program environment.

Name Type Description
dependencies T[string] List of project dependencies given as pairs of "<name>" : <version-spec> - see next section for how version specifications look like
systemDependencies string A textual description of the required system dependencies (external C libraries) required by the package. This will be visible on the registry and will be displayed in case of linker errors.
targetType string Specifies a specific target type - this field does not support platform suffixes
targetName string Sets the base name of the output file; type and platform specific pre- and suffixes are added automatically - this field does not support platform suffixes
targetPath string The destination path of the output binary - this field does not support platform suffixes
workingDirectory string A fixed working directory from which the generated executable will be run - this field does not support platform suffixes
subConfigurations string[string] Locks the dependencies to specific configurations; a map from package name to configuration name, see also the configurations section - this field does not support platform suffixes
buildRequirements string[] List of required settings for the build process. See the build requirements section for details.
buildOptions string[] List of build option identifiers (corresponding to compiler flags) - see the build options section for details.
libs string[] A list of external library names - depending on the compiler, these will be converted to the proper linker flag (e.g. "ssl" might get translated to "-L-lssl")
sourceFiles string[] Additional files passed to the compiler - can be useful to add certain configuration dependent source files that are not contained in the general source folder
sourcePaths string[] Allows to customize the path where to look for source files (any folder "source" or "src" is automatically used as a source path if no sourcePaths field is given) - note that you usually also need to define "importPaths" as "sourcePaths" don't influence those
excludedSourceFiles string[] Files that should be removed for the set of already added source files (takes precedence over "sourceFiles" and "sourcePaths") - Glob matching can be used to pattern match multiple files at once
mainSourceFile string Determines the file that contains the main() function. This field can be used by dub to exclude this file in situations where a different main function is defined (e.g. for "dub test") - this field does not support platform suffixes
copyFiles string[] Files that are copied to the applications directory - typically these are DLLs on Windows
versions string[] A list of D versions to be defined during compilation
debugVersions string[] A list of D debug identifiers to be defined during compilation
importPaths string[] Additional import paths to search for D modules (the source/ folder is used by default as a source folder, if it exists)
stringImportPaths string[] Additional import paths to search for string imports/views (the views/ folder is used by default as a string import folder, if it exists)
preGenerateCommands string[] A list of shell commands that is executed before project generation is started
postGenerateCommands string[] A list of shell commands that is executed after project generation is finished
preBuildCommands string[] A list of shell commands that is executed always before the project is built
postBuildCommands string[] A list of shell commands that is executed always after the project is built
dflags string[] Additional flags passed to the D compiler - note that these flags are usually specific to the compiler in use, but a set of flags is automatically translated from DMD to the selected compiler
lflags string[] Additional flags passed to the linker - note that these flags are usually specific to the linker in use

Version specifications

A version specification can either be a simple declaration or a more complex variant, alowing more control.

Target types

The following values are recognized for the "targetType" field:

Value Description
"autodetect" Automatically detects the target type. This is the default global value and causes dub to try and generate "application" and "library" configurations. Use of other values limits the auto-generated configurations to either of the two. This value is not allowed inside of a configuration block.
"none" Does not generate an output file. This is useful for packages that are supposed to drag in other packages using its "dependencies" field.
"executable" Generates an executable binary
"library" Specifies that the package is to be used as a library, without limiting the actual type of library. This should be the default for most libraries.
"sourceLibrary" This target type does not generate a binary, but rather forces dub to add all source files directly to the same compiler invocation as the dependent project.
"staticLibrary" Forces output as a static library container.
"dynamicLibrary" Forces output as a dynamic/shared library.

Build requirements

The following values are recognized as array items in the "buildRequirements" field:

Value Description
"allowWarnings" Warnings do not abort compilation
"silenceWarnings" Don't show warnings
"disallowDeprecations" Using deprecated features aborts compilation
"silenceDeprecations" Don't show deprecation warnings
"disallowInlining" Avoid function inlining, even in release builds
"disallowOptimization" Avoid optimizations, even in release builds
"requireBoundsCheck" Always perform bounds checks
"requireContracts" Leave assertions and contracts enabled in release builds
"relaxProperties" Do not enforce strict property handling (removes the -property switch) [deprecated, recent versions of DUB never issue -property]
"noDefaultFlags" Does not emit build type specific flags (e.g. -debug, -cov or -unittest). Note that this flag should never be used for released packages and is indended purely as a development/debugging tool. Using "-build=plain" may also be a more appropriate alternative.

Build options

The "buildOptions" field provides a compiler agnostic way to specify common compiler options/flags. Note that many of these options are implicitly managed by the "buildRequirements" field and most others usually only occur in "buildTypes" blocks. It supports the following values:

Value Description Corresponding DMD flag
"debugMode" Compile in debug mode (enables contracts) -debug
"releaseMode" Compile in release mode (disables assertions and bounds checks) -release
"coverage" Enable code coverage analysis -cov
"debugInfo" Enable symbolic debug information -g
"debugInfoC" Enable symbolic debug information in C compatible form -gc
"alwaysStackFrame" Always generate a stack frame -gs
"stackStomping" Perform stack stomping -gx
"inline" Perform function inlining -inline
"noBoundsChecks" Disable all bounds checking -noboundscheck
"optimize" Enable optimizations -O
"profile" Emit profiling code -profile
"unittests" Compile unit tests -unittest
"verbose" Verbose compiler output -v
"ignoreUnknownPragmas" Ignores unknown pragmas during compilation -ignore
"syntaxOnly" Don't generate object files -o-
"warnings" Enable warnings, enabled by default (use "buildRequirements" to control this setting) -wi
"warningsAsErrors" Treat warnings as errors (use "buildRequirements" to control this setting) -w
"ignoreDeprecations" Do not warn about using deprecated features (use "buildRequirements" to control this setting) -d
"deprecationWarnings" Warn about using deprecated features, enabled by default (use "buildRequirements" to control this setting) -dw
"deprecationErrors" Stop compilation upon usage of deprecated features (use "buildRequirements" to control this setting) -de
"property" Enforce property syntax - deprecated -property

Configurations

In addition to platform specific build settings, it is possible to define build configurations. Build configurations add or override build settings to the global ones. To choose a configuration, use dub --config=<name>. By default, the first configuration that matches the target type and build platform is selected automatically. The configurations are defined by adding a "configurations" field.

If no configurations are specified, dub automatically tries to detect the two default configurations "application" and "library". The "application" configuration is only added if at least one of the following files is found: source/app.d, source/<package name>.d, src/app.d, src/<package name>.d. Those files are expected to contain only the application entry point (usually main()) and are only added to the "application" configuration.

The following example defines "metro-app" and "desktop-app" configurations that are only available on Windows and a "glut-app" configuration that is available on all platforms.

{
	...
	"name": "somepackage"
	"configurations": [
		{
			"name": "metro-app",
			"targetType": "executable",
			"platforms": ["windows"],
			"versions": ["MetroApp"],
			"libs": ["d3d11"]
		},
		{
			"name": "desktop-app",
			"targetType": "executable",
			"platforms": ["windows"],
			"versions": ["DesktopApp"],
			"libs": ["d3d9"]
		},
		{
			"name": "glut-app",
			"targetType": "executable",
			"versions": ["GlutApp"]
		}
	]
}

You can choose a specific configuration for certain dependencies by using the "subConfigurations" field:

{
	...
	"dependencies": {
		"somepackage": ">=1.0.0"
	},
	"subConfigurations": {
		"somepackage": "glut-app"
	}
}

If no configuration is specified for a package, the first one that matches the current platform is chosen (see the "platforms" field below).

Configuration block specific fields

In addition to the usual build settings, the following fields are recognized inside of a configuration block:

Name Type Description
name [required] string Name of the configuration
platforms string[] A list of platform suffixes (as used for the build settings) to limit on which platforms the configuration applies

Build types

By default, a set of predefined build types is already provided by DUB and can be specified using dub build --build=<name>:

Name Build options
plain []
debug ["debugMode", "debugInfo"]
release ["releaseMode", "optimize", "inline"]
unittest ["unittests", "debugMode", "debugInfo"]
docs ["syntaxOnly"], plus "dflags": ["-c", "-Dddocs"]
ddox ["syntaxOnly"], plus "dflags": ["-c", "-Df__dummy.html", "-Xfdocs.json"]
profile ["profile", "optimize", "inline", "debugInfo"]
cov ["coverage", "debugInfo"]
unittest-cov ["unittests", "coverage", "debugMode", "debugInfo"]

The existing build types can be customized and new build types can be added using the global "buildTypes" field. Each entry in "buildTypes" can use any of the low level build settings fields (excluding "dependencies", "targetType", "targetName", "targetPath", "workingDirectory", "subConfigurations"). The build settings specified here will later be modified by the package/configuration specific settings.

An example that overrides the "debug" build type and defines a new "debug-profile" type:

{
	"name": "my-package",
	"buildTypes": {
		"debug": {
			"buildOptions": ["debugMode", "debugInfo", "optimize"]
		},
		"debug-profile": {
			"buildOptions": ["debugMode", "debugInfo", "profile"]
		}
	}
}