Menu
Search

Introduction

NOTE: this describes the JSON version of the package file format. See also the specification based on SDLang.

Every DUB package should contain a dub.json (or dub.sdl, formerly also package.json) 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 settings and their meaning. Note that any unknown settings 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.example.com",
	"license": "GPL-2.0",
	"dependencies": {
		"vibe-d": "~>0.7.23"
	}
}

Please keep the description concise (not more than 100 characters) and avoid including unspecific information such as the fact that the package is written in D. The same goes for the package name - since all DUB packages are written in D, it's usually better to avoid mentioning D explicitly, unless the package is for example a high-level wrapper around a C/C++ library.

Contents

Global settings

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

NameTypeDescription
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
toolchainRequirements string[string] Set of version requirements for DUB, for compilers and for language frontend. See the toolchain requirements section.
homepage string URL of the project website
authors string[] List of project authors (the suggested format is either "Peter Parker" or "Peter Parker <[email protected]>")
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 format as a dub.json file - see the sub package section for more information
configurations T[] Speficies an optional list of build configurations (chosen on the command line using --config=...) - see the configurations section for more details
buildTypes T[string] Defines additional custom build types or overrides the default ones (chosen on the command line 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" section 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 the 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": "*",
		"mylib:component2": "*"
	},
	"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. To refer to sub packages within the same repository use the "*" version specifier.

It is also possible to define the sub packages within the root package file, but note that it is generally 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": "*",
		"mylib:component2": "*"
	},
	"subPackages": [
		{
			"name": "component1",
			"targetType": "library",
			"sourcePaths": ["component1/source"],
			"importPaths": ["component1/source"]
		}
	]
}

/dub.json

License specifications

The license setting 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), NCSA (University of Illinois/NCSA Open Source 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 influence the command line options passed to the compiler and linker. All settings are optional.

Platform specific settings are supported through the use of field name suffixes. Suffixes are dash separated list of operating system/architecture/compiler 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. Additionally on Windows the architectures x86_omf and x86_mscoff can be used with dmd to differentiate between 32 bit object formats used with the --arch switch. Examples:

{
	"versions": ["PrintfDebugging"],
	"dflags-dmd": ["-vtls"],
	"versions-x86_64": ["UseAmd64Impl"]
	"libs-posix": ["ssl", "crypto"],
	"sourceFiles-windows-x86_64-dmd": ["libs/windows-x86_64/mylib.lib"],
	"sourceFiles-windows-x86_omf-dmd": ["libs/windows-x86_omf/mylib.lib"],
	"sourceFiles-windows-x86_mscoff-dmd": ["libs/windows-x86_mscoff/mylib.lib"],
}
NameTypeDescription
dependencies T[string] List of project dependencies given as pairs of "<name>" : <version-spec> - see next section for what version specifications look like - this setting does not support platform suffixes
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 - this setting does not support platform suffixes
targetType string Specifies a specific target type - this setting 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 setting does not support platform suffixes
targetPath string The destination path of the output binary - this setting does not support platform suffixes
workingDirectory string A fixed working directory from which the generated executable will be run - this setting 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 setting 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"). On Posix platforms dub will try to find the correct linker flags by using pkg-config
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 setting is specified) - 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 setting can be used by dub to exclude this file in situations where a different main function is defined (e.g. for "dub test") - this setting does not support platform suffixes
copyFiles string[] A list of globs matching files or directories to be copied to targetPath. Matching directories are copied recursively, i.e. "copyFiles": ["path/to/dir"]" recursively copies dir, while "copyFiles": ["path/to/dir/*"]" only copies files within dir.
extraDependencyFiles string[] A list of globs matching files to be checked for rebuilding the dub project.
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 always executed before project generation is started
postGenerateCommands string[] A list of shell commands that is always executed after project generation is finished
preBuildCommands string[] A list of shell commands that is executed before the package is built
postBuildCommands string[] A list of shell commands that is executed after the package is built
preRunCommands string[] A list of shell commands that is executed always before the project is run
postRunCommands string[] A list of shell commands that is executed always after the project is run
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
injectSourceFiles string[] Source files that will be compiled into binaries that depend on this package. Warning: this should be under a permissive license (like Boost) or you risk infecting a users binary with an incompatible license.

Version specifications

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

Version specifiers define a range of acceptable versions. They can be specified in any of the following ways:

Numbered versions are formatted and compared according to the SemVer specification. The recommended way to specify versions is using the ~> operator as a way to balance between flexible upgrades and reducing the risk of code breakage.

Whenever you refer to (sub) packages within the same repository, use the "any version" version specifier: "*"

Target types

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

ValueDescription
"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 the "dependencies" section.
"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 for the "buildRequirements" setting:

ValueDescription
"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" setting provides a compiler agnostic way to specify common compiler options/flags. Note that many of these options are implicitly managed by the "buildRequirements" setting and most others usually only occur in "buildTypes" blocks. It supports the following values:

ValueDescriptionCorresponding 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
"coverageCTFE"Enable code coverage analysis (including code executed at compile-time via CTFE)-cov=ctfe
"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
"noBoundsCheck"Disable all bounds checking-boundscheck=off
"optimize"Enable optimizations-O
"profile"Emit profiling code-profile
"profileGC"Emit GC profiling information-profile=gc
"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
"betterC"Compile in betterC mode-betterC
"lowmem"Enable the garbage collector for the compiler(dmd/ldc), reducing the compiler memory requirements but increasing compile times.-lowmem

Environment variables

Inside of build setting values, it is possible to use variables using dollar notation. Any variable not matching a predefined name will be taken from the program environment. To denote a literal dollar sign, use $$. The predefined variables are:

VariableContent
$PACKAGE_DIR Path to the package itself
$ROOT_PACKAGE_DIR Path to the root package of the build dependency tree
$<name>_PACKAGE_DIR Path to a specific package that is part of the package's dependency graph. $<name> must be in uppercase letters without the semver string.
$DUB Path to the DUB executable

Inside of build setting values, the following variables are also supported:

VariableContent
$ARCH CPU architecture: "x86", "x86_64"
$PLATFORM Running platform: "linux", "windows", ...
$PLATFORM_POSIX Running platform: "posix", "windows", ...
$BUILD_TYPE Type of build: "debug", "release", ...

Inside of custom command directives a different set of predefined variables is available:

VariableContent
$DUB_PACKAGE Name of the package
$DUB_PACKAGE_VERSION Version of the package
$DUB_ROOT_PACKAGE Name of the root package that is being built
$DUB_ROOT_PACKAGE_TARGET_TYPE Contents of the "targetType" field of the root package as defined by the package recipe
$DUB_ROOT_PACKAGE_TARGET_PATH Contents of the "targetPath" field of the root package as defined by the package recipe
$DUB_ROOT_PACKAGE_TARGET_NAME Contents of the "targetName" field of the root package as defined by the package recipe
$DFLAGS Contents of the "dflags" field as defined by the package recipe
$LFLAGS Contents of the "lflags" field as defined by the package recipe
$VERSIONS Contents of the "versions" field as defined by the package recipe
$LIBS Contents of the "libs" field as defined by the package recipe
$SOURCE_FILES Contents of the "sourceFiles" field as defined by the package recipe
$IMPORT_PATHS Contents of the "importPaths" field as defined by the package recipe
$STRING_IMPORT_PATHS Contents of the "stringImportPaths" field as defined by the package recipe
$DC Compiler binary name (e.g. "../dmd" or "ldc2")
$DC_BASE Canonical name of the compiler (e.g. "dmd" or "ldc")
$D_FRONTEND_VER The compiler frontend version represented as a single integer, for example "2072" for DMD 2.072.2
$DUB_EXE Path to the DUB executable
$DUB_PLATFORM Name of the target platform (e.g. "windows" or "linux")
$DUB_ARCH Name of the target architecture (e.g. "x86" or "x86_64")
$DUB_TARGET_TYPE Contents of the "targetType" field as defined by the package recipe
$DUB_TARGET_PATH Contents of the "targetPath" field as defined by the package recipe
$DUB_TARGET_NAME Contents of the "targetName" field as defined by the package recipe
$DUB_WORKING_DIRECTORY Working directory in which the compiled program gets run
$DUB_MAIN_SOURCE_FILE Contents of the "mainSourceFile" field as defined by the package recipe
$DUB_CONFIG Name of the selected build configuration (e.g. "application" or "library")
$DUB_BUILD_TYPE Name of the selected build type (e.g. "debug" or "unittest")
$DUB_BUILD_MODE Name of the selected build mode (e.g. "separate" or "singleFile")
$DUB_BUILD_PATH Absolute path in which the package was compiled (defined for "postBuildCommands" only)
$DUB_COMBINED "TRUE" if the --combined flag was used, empty otherwise
$DUB_RUN "TRUE" if the "run" command was invoked, empty otherwise
$DUB_FORCE "TRUE" if the --force flag was used, empty otherwise
$DUB_RDMD "TRUE" if the --rdmd flag was used, empty otherwise
$DUB_TEMP_BUILD "TRUE" if the --temp-build flag was used, empty otherwise
$DUB_PARALLEL_BUILD "TRUE" if the --parallel flag was used, empty otherwise
$DUB_RUN_ARGS Contains the arguments passed to the built executable in shell compatible format

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" section.

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/main.d, source/<package name>/app.d, source/<package name>/main.d, src/app.d, src/main.d, src/<package name>/app.d, src/<package name>/main.d. Those files are expected to contain only the application entry point (usually main()) and are only added to the "application" configuration.

The configuration name "unittest" has a special meaning - if a configuration with this name is present, it will be used by default when executing dub test. It can be assumed to have the -unittest flag present (through the "unittest" build type). Possible use cases for custom unittest configurations overriding the default behavior of excluding the main source file or adding additional modules containing additional external tests, which don't need to be compiled in the application/library mode.

When defining a configuration's platform, any of the suffixes described in build settings may be combined to make the configuration as specific as necessary.

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" section:

{
	...
	"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" setting below).

Configuration block specific settings

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

NameTypeDescription
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>:

NameBuild options
plain[]
debug["debugMode", "debugInfo"]
release["releaseMode", "optimize", "inline"]
release-debug["releaseMode", "optimize", "inline", "debugInfo"]
release-nobounds["releaseMode", "optimize", "inline", "noBoundsCheck"]
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"]
profile-gc["profileGC", "debugInfo"]
cov["coverage", "debugInfo"]
cov-ctfe["coverageCTFE", "debugInfo"]
unittest-cov["unittests", "coverage", "debugMode", "debugInfo"]
unittest-cov-ctfe["unittests", "coverageCTFE", "debugMode", "debugInfo"]
syntax["syntaxOnly"]

The existing build types can be customized and new build types can be added using the global "buildTypes" section. Each entry in "buildTypes" can use any of the low level build settings (excluding "dependencies", "targetType", "targetName", "targetPath", "workingDirectory", "subConfigurations"). The build settings specified here will later be modified/augmented 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"]
		}
	}
}

Toolchain requirements

The package can specify version requirements for the toolchain. Each requirement is specified with the version dependency syntax. For compilers, the keyword no can be specified instead of a version requirement to disallow the use of a specific compiler for the package. The following requirements are allowed:

IdentifierDescription
"dub"DUB version requirement
"frontend"D frontend version requirement
"dmd"DMD version requirement
"ldc"LDC version requirement
"gdc"GDC version requirement

Example 1: package that needs at least dub-1.14 and uses D features introduced in frontend 2.068 and other features that will be deprecated in frontend 2.087

{
	"toolchainRequirements": {
		"dub": ">=1.14.0",
		"frontend": ">=2.068 <2.087"
	}
}

Example 2: package that needs to be compiled with LDC from version 1.11

{
	"toolchainRequirements": {
		"dmd": "no",
		"gdc": "no",
		"ldc": ">=1.11"
	}
}