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

On 8/23/16 1:46 PM, Andrei Alexandrescu wrote:

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

json has returned as the default format. Your distribution probably installed an older dub that used sdl as the default format.

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

Typically, the source goes in source. So you want source/checkedint/checkedint.d (or source/checkedint.d).

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

$ dub init
$ rm source/app.d # this is a library
$ vi source/checkedint.d # or mkdir source/checkedint; vi source/checkedint/checkedint.d
...
$ dub build
Performing "debug" build using dmd for x86_64.
checkedint ~master: building configuration "library"...
Target is a library. Skipping execution.
$ ls -l
total 40
-rw-r--r--+ 1 steves  staff   112 Aug 23 13:55 dub.sdl
-rw-r--r--+ 1 steves  staff    39 Aug 23 13:56 dub.selections.json
-rw-r--r--+ 2 steves  staff  9548 Aug 23 13:56 libcheckedint.a
drwxr-xr-x+ 3 steves  staff   102 Aug 23 13:56 source

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

dub test

is what I usually do.

-Steve

On Tuesday, 23 August 2016 at 17:46:18 UTC, Andrei Alexandrescu wrote:

> So here we are. Hope this helps building a simpler, clear tutorial. The "Getting Started" document is really "Documentation Root".
>
>
>
> Thanks,
>
> Andrei

This is a point I've made on a number of occasions. Dub is largely useless to me, because even if I can figure it out, there is no way I can tell others that they should use it.

Thankfully Mike Parker said (must have been a few weeks ago) that he has started a project to document it. When that is released I will seriously consider using Dub.

On Tuesday, 23 August 2016 at 17:58:31 UTC, Steven Schveighoffer wrote:
> On 8/23/16 1:46 PM, Andrei Alexandrescu wrote:
>> * 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.
>
> json has returned as the default format. Your distribution probably installed an older dub that used sdl as the default format.

Yea, unfortunately the version of dub packaged with Ubuntu 16.04 does default to using SDL, and that version is going to be around for a long while (5 years' support and all that).

In principle it might be worth seeing if it's possible to upgrade the packaged version.

On Tuesday, 23 August 2016 at 18:05:32 UTC, bachmeier wrote:
> On Tuesday, 23 August 2016 at 17:46:18 UTC, Andrei Alexandrescu wrote:
>
>> So here we are. Hope this helps building a simpler, clear tutorial. The "Getting Started" document is really "Documentation Root".
>>
>>
>>
>> Thanks,
>>
>> Andrei
>
> This is a point I've made on a number of occasions. Dub is largely useless to me, because even if I can figure it out, there is no way I can tell others that they should use it.
>
> Thankfully Mike Parker said (must have been a few weeks ago) that he has started a project to document it. When that is released I will seriously consider using Dub.

We are still searching for someone to do one or two DUB gems on the DLang Tour:

https://github.com/dlang-tour/english/issues/8

On Tuesday, 23 August 2016 at 18:05:32 UTC, bachmeier wrote:
> On Tuesday, 23 August 2016 at 17:46:18 UTC, Andrei Alexandrescu wrote:
>
>
> This is a point I've made on a number of occasions. Dub is largely useless to me, because even if I can figure it out, there is no way I can tell others that they should use it.
>
> Thankfully Mike Parker said (must have been a few weeks ago) that he has started a project to document it. When that is released I will seriously consider using Dub.

I've been using dub for years now. It helps me a lot, but the documentation could be better, I agree. It would be nice to have a UI for people who don't want to bother with cli switches and config files, that would be a first step towards IDE functionality. I think with dub having reached 1.0 status, we should think about a UI and IDE integration (chances are that somebody has already embarked on this).

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

On Tuesday, 23 August 2016 at 17:46:18 UTC, Andrei Alexandrescu wrote:
>  [ rant ]
>
> Thanks,
>
> Andrei

I usually use Cargo when I need such a tool.  The only problem with Cargo is that its support for D is rather poor, so I'm being forced to use Rust.  It really sucks.  Any chance we could have Cargo support D?

On Wed, 24 Aug 2016 09:27:43 +0000, Chris wrote:

> On Tuesday, 23 August 2016 at 18:05:32 UTC, bachmeier wrote:
>> On Tuesday, 23 August 2016 at 17:46:18 UTC, Andrei Alexandrescu wrote:
>>
>>
>> This is a point I've made on a number of occasions. Dub is largely useless to me, because even if I can figure it out, there is no way I can tell others that they should use it.
>>
>> Thankfully Mike Parker said (must have been a few weeks ago) that he has started a project to document it. When that is released I will seriously consider using Dub.
> 
> I've been using dub for years now. It helps me a lot, but the documentation could be better, I agree. It would be nice to have a UI for people who don't want to bother with cli switches and config files

Probably the easiest way to do that is to start up a web server and use HTML for the GUI.

It should be pretty straightforward, especially for the simpler functionality. Add dependencies, change project details, build and test, maybe run dscanner too, probably run your project.

I'll look into it.

On Wednesday, 24 August 2016 at 09:27:43 UTC, Chris wrote:
>
> I've been using dub for years now. It helps me a lot, but the documentation could be better, I agree. It would be nice to have a UI for people who don't want to bother with cli switches and config files, that would be a first step towards IDE functionality. I think with dub having reached 1.0 status, we should think about a UI and IDE integration (chances are that somebody has already embarked on this).

If you look here
https://wiki.dlang.org/IDEs
many of the projects indicate some kind of dub support.