https://issues.dlang.org/show_bug.cgi?id=16425

          Issue ID: 16425
           Summary: DUB "Getting Started" is seriously wanting
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: normal
          Priority: P1
         Component: dlang.org
          Assignee: nobody@puremagic.com
          Reporter: bugzilla@digitalmars.com

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

--