1DUB(1)                     The D Language Foundation                    DUB(1)
2
3
4

NAME

6       dub - Package and build management system for D
7

SYNOPSIS

9       dub [--version] [COMMAND] [OPTIONS...] -- [APPLICATION ARGUMENTS...]
10

DESCRIPTION

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

COMMANDS

18       init   Initializes an empty package of the specified type in the  given
19              directory.  By default, the current working directory is used.
20
21              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" sub-package 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" sub-package as  app  argu‐
27              ments.
28
29       run    Builds  and runs a package (uses the main package in the current
30              working directory by default)
31
32       build  Builds a package (uses the main package in the  current  working
33              directory by default)
34
35       test   Builds the package and executes all contained unit tests.
36
37              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
43              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
50              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
54       lint   Builds the package and executes D-Scanner linter tests.
55
56       generate
57              Generates project files using one of the supported generators:
58
59              visuald  -  VisualD  project  files  sublimetext  -  SublimeText
60              project  file  cmake  -  CMake  build scripts build - Builds the
61              package directly
62
63              An optional package name can be given to  generate  a  different
64              package than the root/CWD package.
65
66       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
71              All  usual options that are also used for build/run/generate ap‐
72              ply.
73
74              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
78              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
83              The accepted values for --data=VALUE are:
84
85              main-source-file,  dflags,  lflags,  libs, linker-files, source-
86              files, versions,  debug-versions,  import-paths,  string-import-
87              paths, import-files, options
88
89              The  following  are  also  accepted  by --data if --data-list is
90              used:
91
92              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
97       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
102       dustmite
103              This command uses the Dustmite utility to isolate the  cause  of
104              build errors in a DUB project.
105
106              It  will create a copy of all involved packages and run dustmite
107              on this copy, leaving a reduced test case.
108
109              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
116       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
120              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
125              Without specified options, placement/removal will default  to  a
126              user wide shared location.
127
128              Complete applications can be retrieved and run easily by e.g.  $
129              dub fetch vibelog --cache=local $ dub run vibelog --cache=local
130
131              This will grab all needed dependencies and compile and  run  the
132              application.
133
134       add    Adds <packages> as dependencies.
135
136              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
141       remove Removes a package that is cached on the local system.
142
143       upgrade
144              Upgrades all dependencies of the package by querying the package
145              registry(ies) for new versions.
146
147              This  will  update  the  versions  stored in the selections file
148              (dub.selections.json) accordingly.
149
150              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
154       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
161              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
165              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
173       remove-path
174              Removes a package search path previously added with add-path.
175
176       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
182              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
186              See 'dub add-path -h' for a way to register multiple local pack‐
187              ages at once.
188
189       remove-local
190              Removes a local package directory
191
192       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
198       search Search all specified providers for matching packages.
199
200       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
205       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
210       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
215       clean-caches
216              This command removes any cached metadata like the list of avail‐
217              able packages and their latest version.
218
219       convert
220              This command will convert  between  JSON  and  SDLang  formatted
221              package recipe files.
222
223              Warning:  Beware  that  any  formatting  and comments within the
224              package recipe will get lost in the conversion process.
225

COMMON OPTIONS

227       -h, --help
228           Display general or command specific help
229
230       --root=VALUE
231           Path to operate in instead of the current working dir
232
233       --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
241       --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
250       --annotate
251           Do not perform any action, just print what would be done
252
253       --bare
254           Read only packages contained in the current directory
255
256       -v, --verbose
257           Print diagnostic output
258
259       --vverbose
260           Print debug output
261
262       -q, --quiet
263           Only print warnings and errors
264
265       --verror
266           Only print errors
267
268       --vquiet
269           Print no messages
270
271       --color=VALUE
272           Configure colored output. Accepted values:
273                  auto: Colored output on console/terminal,
274                        unless NO_COLOR is set and non-empty (default)
275                always: Force colors enabled
276                 never: Force colors disabled
277
278       --cache=VALUE
279           Puts  any  fetched  packages  in the specified location [local|sys‐
280           tem|user].
281

FILES

283       dub.sdl, dub.json
284

AUTHOR

286       Copyright (c) 1999-2023 by The D Language Foundation
287

ONLINE DOCUMENTATION

289       http://code.dlang.org/docs/commandline ⟨⟩
290

SEE ALSO

292       dmd(1), rdmd(1), dub-init(1),  dub-run(1),  dub-build(1),  dub-test(1),
293       dub-lint(1),  dub-generate(1), dub-describe(1), dub-clean(1), dub-dust‐
294       mite(1), dub-fetch(1), dub-add(1), dub-remove(1), dub-upgrade(1),  dub-
295       add-path(1), dub-remove-path(1), dub-add-local(1), dub-remove-local(1),
296       dub-list(1),   dub-search(1),   dub-add-override(1),   dub-remove-over‐
297       ride(1), dub-list-overrides(1), dub-clean-caches(1), dub-convert(1)
298
299
300
301The D Language Foundation         2023-07-24                            DUB(1)
Impressum