Am 17.10.2013 13:54, schrieb Joseph Rushton Wakeling:

Hello all,

I just downloaded and built DUB from source today -- first time using it, so this is going to be one of those "Aaargh, WTF, I can't work out how to use this program, you're all stupid" kind of posts. Except that I'm not going to call anyone stupid because that would be neither true nor nice.

Anyway, I found myself a little disconcerted by how dub works, so I thought I'd give a little write-up of my experience as a first-time user, both in the hope of advice and also that it might be useful for future development.

First up -- I was aware that dub essentially handles source dependencies, which are placed (if locally installed) in the ~/.dub/packages directory. So it was rather a surprise, when I tried

 dub install vibe-d

that instead source was just downloaded to ~/vibe-d-0.7.17 and not placed there. And -- having typed an "install" command -- it was still more disconcerting that "dub list-installed" listed nothing.

This is a bug. It should indeed go to to ~/.dub/packages and also be
available afterwards (dub list-installed). Implying "dub add" when doing
"dub install xxx --local" (which is what seems to happen now) sounds
also like a good idea.

But in general the idea is that "dub install" is usually not needed
explicitly. Dependencies are automatically installed and built.

If I'm not mistaken, the following paragraphs reflect consequences of
this same misunderstanding/bug.

A bit of reading, and I gathered that I was supposed to go into the vibe-d-0.7.17 directory and just type "dub", which downloaded the dependencies and placed them where I'd expected, in ~/.dub/packages -- but still didn't install vibe.d, even in source form. OK, this is comprehensible -- the idea is clearly that if you've downloaded source for a particular package or library, no matter how you've obtained it, dub will make sure you have dependencies in place ready for you to build.

A bit more reading, and I discovered I was supposed to type "dub build" to build vibe.d itself -- and that there are nice options to allow me to specify a compiler and a build mode. Good -- but what this outputs is a library file in the root of the vibe-d-0.7.17 directory, and there's no obvious way to install it short of manually placing it where I'd like it to go. In addition, because it doesn't output to a specified build dir, this could create problems if many libraries/executables were being built -- there's no "dub clean" command to remove built files, so short of unpleasant stuff like git reset, it's finnicky to manually remove built files.

"dub clean" to remove build output files sounds like a good addition.

In short, this initial experience with dub makes me feel that it's a basically sound and on-the-right-track piece of software which could maybe do with a rethink for the names of certain commands (e.g. what's currently done by "install" is ... not an install, I would say) and could do with some better docs to describe some of the bread-and-butter activities. For example, it would help a lot to have a detailed tutorial on code.dlang.org about installing a package and dependencies using dub.

I agree. Better documentation on code.dlang.org is on the agenda, but
there are just so many other things to do, that without some external
help it is currently difficult to get all that done in a reasonable
amount of time.

On that note, what are the preferred methods for contributing to dub documentation? I'm happy to write some stuff up once I know what I'm doing. :-)

That would definitely be great. The documentation is currently written
in the form of diet templates on GitHub, so pull requests are the
most direct way for contribution.

https://github.com/rejectedsoftware/dub-registry/blob/master/views/usage.dt