Bug 16425 – DUB "Getting Started" is seriously wanting

As reported by Andrei on the n.g.: So I've set out to set up a dub package for https://github.com/dlang/phobos/pull/4613 from a position of total ignorance. Naturally I went with http://code.dlang.org/getting_started and found it wanting. * It gives instructions on how to install dub, but does not mention "sudo apt-get install dub" which I tried randomly and just worked. Well that should be mentioned. * I'd expect and hope a "getting started" doc to take me from nothing to "I got a hello world package going", then point me to advanced option. Instead, http://code.dlang.org/getting_started gives a flat overview of everything dub can do, from the simplest (single-file packages) to the rather esoteric (foreign projects, advanced dependencies). Then it gives me links to things like "package format specification", completely leaving me in the dark as to what in the world I need to do from where I am to where I want to be (have a library packaged). * In an extra twinge of irony, the link to the package format specification goes to http://code.dlang.org/package-format?lang=json, i.e. the JSON format. Which is of course not what "dub init" (which I duly ran because it was on the getting started page) generated. It was no source of confusion to me because I had the context, but it may for others. * So I look at the SDL spec and even after I'm done I have no idea where to specify "I have a package called checkedint, and the only file for it is ./checkedint/checkedint.d". I do know what I'd need to do if I had subpackages though. * At this point I've read two full pages of documentation and I have no idea how to (a) define my package for one library with one file in it, and (b) build it. Literally: no idea. * So I assume on a hunch that since the package name is "checkedint" and there is a homonym directory, there might be some nice automatic setting to pick that up. So I go to dub's Command Line documentation. * I see the default is "run" so I go to the initial dir where I ran "dub init checkedint" and issue "dub". No go. I figure I need to go inside the checkedint dir (nice error msg). OK, that builds a library. Nice. * Next thing I want is to unittest the thing. Searching the cmdline docs, first hit suggests "dub --build=unittest" is the way to go. It does build, but doesn't run the unittests. Fortunately I keep on searching and find that "dub test" does what I want. So here we are. Hope this helps building a simpler, clear tutorial. The "Getting Started" document is really "Documentation Root".

@WalterBright the issue tracker for DUB is at https://github.com/dlang/dub/issues Btw the DUB issue tracker is already overloaded with _a lot_ of issues, because we have a serious lack of manpower (atm Sönke is the only maintainer & he has a lot of other projects (our flagship web framework vibe.d, the proposed std.data.json, ddox, the dub registry server, ... and his full-time job). Hence I believe that this issue will only rest here without anyone working on it and moved it over the the DUB issue tracker: https://github.com/dlang/dub/issues/914