1DUB(1) The D Language Foundation DUB(1)
2
6 dub - Package and build management system for D
7
9 dub [--version] [COMMAND] [OPTIONS...] [-- [APPLICATION ARGUMENTS...]]
10
12 Manages the DUB project in the current directory. DUB can serve as a
13 build system and a package manager, automatically keeping track of
14 project's dependencies - both downloading them and linking them into
15 the application.
16
18 init Initializes an empty package of the specified type in the given
19 directory. By default, the current working directory is used.
20 Custom templates can be defined by packages by providing a sub-
22 package called "init-exec". No default source files are added in
23 this case. The "init-exec" subpackage is compiled and executed
24 inside the destination folder after the base project directory
25 has been created. Free arguments "dub init -t custom -- free
26 args" are passed into the "init-exec" subpackage as app argu‐
27 ments.
28 run Builds and runs a package (uses the main package in the current
30 working directory by default)
31 build Builds a package (uses the main package in the current working
33 directory by default)
34 test Builds the package and executes all contained unit tests.
36 If no explicit configuration is given, an existing "unittest"
38 configuration will be preferred for testing. If none exists, the
39 first library type configuration will be used, and if that
40 doesn't exist either, the first executable configuration is cho‐
41 sen.
42 When a custom main file (--main-file) is specified, only library
44 configurations can be used. Otherwise, depending on the type of
45 the selected configuration, either an existing main file will be
46 used (and needs to be properly adjusted to just run the unit
47 tests for 'version(unittest)'), or DUB will generate one for li‐
48 brary type configurations.
49 Finally, if the package contains a dependency to the "tested"
51 package, the automatically generated main file will use it to
52 run the unit tests.
53 lint Builds the package and executes D-Scanner linter tests.
55 generate
57 Generates project files using one of the supported generators:
58 visuald - VisualD project files sublimetext - SublimeText
60 project file cmake - CMake build scripts build - Builds the
61 package directly
62 An optional package name can be given to generate a different
64 package than the root/CWD package.
65 describe
67 Prints a JSON build description for the root package an all of
68 their dependencies in a format similar to a JSON package de‐
69 scription file. This is useful mostly for IDEs.
70 All usual options that are also used for build/run/generate ap‐
72 ply.
73 When --data=VALUE is supplied, specific build settings for a
75 project will be printed instead (by default, formatted for the
76 current compiler).
77 The --data=VALUE option can be specified multiple times to re‐
79 trieve several pieces of information at once. A comma-separated
80 list is also acceptable (ex: --data=dflags,libs). The data will
81 be output in the same order requested on the command line.
82 The accepted values for --data=VALUE are:
84 main-source-file, dflags, lflags, libs, linker-files, source-
86 files, versions, debug-versions, import-paths, string-import-
87 paths, import-files, options
88 The following are also accepted by --data if --data-list is
90 used:
91 target-type, target-path, target-name, working-directory, copy-
93 files, string-import-files, pre-generate-commands, post-gener‐
94 ate-commands, pre-build-commands, post-build-commands, pre-run-
95 commands, post-run-commands, requirements
96 clean This command removes any cached build files of the given pack‐
98 age(s). The final target file, as well as any copyFiles are cur‐
99 rently not removed. Without arguments, the package in the cur‐
100 rent working directory will be cleaned.
101 dustmite
103 This command uses the Dustmite utility to isolate the cause of
104 build errors in a DUB project.
105 It will create a copy of all involved packages and run dustmite
107 on this copy, leaving a reduced test case.
108 Determining the desired error condition is done by checking the
110 compiler/linker status code, as well as their output (stdout and
111 stderr combined). If --program-status or --program-regex is
112 given and the generated binary is an executable, it will be exe‐
113 cuted and its output will also be incorporated into the final
114 decision.
115 fetch Note: Use "dub add <dependency>" if you just want to use a cer‐
117 tain package as a dependency, you don't have to explicitly fetch
118 packages.
119 Explicit retrieval/removal of packages is only needed when you
121 want to put packages in a place where several applications can
122 share them. If you just have a dependency to add, use the `add`
123 command. Dub will do the rest for you.
124 Without specified options, placement/removal will default to a
126 user wide shared location.
127 Complete applications can be retrieved and run easily by e.g. $
129 dub fetch vibelog --cache=local $ dub run vibelog --cache=local
130 This will grab all needed dependencies and compile and run the
132 application.
133 add Adds <packages> as dependencies.
135 Running "dub add <package>" is the same as adding <package> to
137 the "dependencies" section in dub.json/dub.sdl. If no version
138 is specified for one of the packages, dub will query the reg‐
139 istry for the latest version.
140 remove Removes a package that is cached on the local system.
142 upgrade
144 Upgrades all dependencies of the package by querying the package
145 registry(ies) for new versions.
146 This will update the versions stored in the selections file
148 (dub.selections.json) accordingly.
149 If one or more package names are specified, only those dependen‐
151 cies will be upgraded. Otherwise all direct and indirect depen‐
152 dencies of the root package will get upgraded.
153 add-path
155 Adds a default package search path. All direct sub folders of
156 this path will be searched for package descriptions and will be
157 made available as packages. Using this command has the equiva‐
158 lent effect as calling 'dub add-local' on each of the sub fold‐
159 ers manually.
160 Any packages registered using add-path will be preferred over
162 packages downloaded from the package registry when searching for
163 dependencies during a build operation.
164 The version of the packages will be determined by one of the
166 following:
167 - For GIT working copies, the last tag (git describe) is used
168 to determine the version
169 - If the package contains a "version" field in the package de‐
170 scription, this is used
171 - If neither of those apply, "~master" is assumed
172 remove-path
174 Removes a package search path previously added with add-path.
175 add-local
177 Adds a local package directory to be used during dependency res‐
178 olution. This command is useful for registering local packages,
179 such as GIT working copies, that are either not available in the
180 package registry, or are supposed to be overwritten.
181 The version of the package is either determined automatically
183 (see the "add-path" command, or can be explicitly overwritten by
184 passing a version on the command line.
185 See 'dub add-path -h' for a way to register multiple local pack‐
187 ages at once.
188 remove-local
190 Removes a local package directory
191 list Prints a list of all or selected local packages. This includes
193 all cached packages (user or system wide), all packages in the
194 package search paths ("dub add-path") and all manually regis‐
195 tered packages ("dub add-local"). If a package (and optionally a
196 version spec) is specified, only matching packages are shown.
197 search Search all specified providers for matching packages.
199 add-override
201 This command is deprecated. Use path based dependency, custom
202 cache path, or edit `dub.selections.json` to achieve the same
203 results.
204 remove-override
206 This command is deprecated. Use path based dependency, custom
207 cache path, or edit `dub.selections.json` to achieve the same
208 results.
209 list-overrides
211 This command is deprecated. Use path based dependency, custom
212 cache path, or edit `dub.selections.json` to achieve the same
213 results.
214 clean-caches
216 This command removes any cached metadata like the list of avail‐
217 able packages and their latest version.
218 convert
220 This command will convert between JSON and SDLang formatted
221 package recipe files.
222 Warning: Beware that any formatting and comments within the
224 package recipe will get lost in the conversion process.
225
227 -h, --help
228 Display general or command specific help
229 --root=VALUE
231 Path to operate in instead of the current working dir
232 --registry=VALUE
234 Search the given registry URL first when resolving dependencies.
235 Can be specified multiple times. Available registry types:
236 DUB: URL to DUB registry (default)
237 Maven: URL to Maven repository + group id containing dub packages
238 as artifacts. E.g. mvn+http://localhost:8040/maven/libs-re‐
239 lease/dubpackages
240 --skip-registry=VALUE
242 Sets a mode for skipping the search on certain package registry
243 types:
244 none: Search all configured or default registries (default)
245 standard: Don't search the main registry (e.g.
246 https://code.dlang.org/)
247 configured: Skip all default and user configured registries
248 all: Only search registries specified with --registry
249 --annotate
251 Do not perform any action, just print what would be done
252 --bare
254 Read only packages contained in the current directory
255 -v, --verbose
257 Print diagnostic output
258 --vverbose
260 Print debug output
261 -q, --quiet
263 Only print warnings and errors
264 --verror
266 Only print errors
267 --vquiet
269 Print no messages
270 --color=VALUE
272 Configure colored output. Accepted values:
273 automatic: Colored output on console/terminal,
274 unless NO_COLOR is set and non-empty (default)
275 on: Force colors enabled
276 off: Force colors disabled
277 --cache=VALUE
279 Puts any fetched packages in the specified location [local|sys‐
280 tem|user].
281
283 dub.sdl, dub.json
284
286 Copyright (c) 1999-2023 by The D Language Foundation
287
289 http://code.dlang.org/docs/commandline
290 ⟨http://code.dlang.org/docs/commandline⟩
291
293 dmd(1), rdmd(1), dub-init(1), dub-run(1), dub-build(1), dub-test(1),
294 dub-lint(1), dub-generate(1), dub-describe(1), dub-clean(1), dub-dust‐
295 mite(1), dub-fetch(1), dub-add(1), dub-remove(1), dub-upgrade(1), dub-
296 add-path(1), dub-remove-path(1), dub-add-local(1), dub-remove-local(1),
297 dub-list(1), dub-search(1), dub-add-override(1), dub-remove-over‐
298 ride(1), dub-list-overrides(1), dub-clean-caches(1), dub-convert(1)
299The D Language Foundation 2023-03-23 DUB(1)