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.
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.
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.
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. :-)
Thanks & best wishes,