I used dub for the first time, here are a few notes

[Andrei Alexandrescu via Digitalmars-d]

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".



Thanks,

Andrei