Examples of dub use needed

[jmh530 via Digitalmars-d]

On Wednesday, 22 June 2016 at 15:48:03 UTC, Mike Parker wrote:
>
> What needs to be improved?

I will say that it looks a lot better now than it used to, even 
though I'm not sure if the content has changed as much.

It's not entirely clear why to use SDLang over JSON. It should be 
more clearly labeled which is preferred.



In the JSON description, I'm not a fan of the Build Options text. 
I would change it to this:

Build settings influence the command line options passed to the 
compiler and linker. All settings are optional. Examples:

{
	"versions": ["PrintfDebugging", "UseAmd64Impl"],
	"dflags": ["-vtls"],
	"sourceFiles": ["lib/mylib.lib"],
}

In addition, it is possible to implement platform specific 
settings using field name suffixes. Field name suffixes are dash 
separated platform identifiers, as defined in the D language 
reference, but converted to lower case. The order of these 
suffixes is os-architecture-compiler, where any of these parts 
can be left off. For instance, "sourceFiles-windows-x86_64-dmd" 
would pass "sourceFiles" only to the DMD compiler on Windows with 
an x86_64 bit architecture. This can be helpful when a project 
requires libraries specific to a particular OS and hardware 
architecture. Other examples:

{
	"versions": ["PrintfDebugging"],
	"dflags-dmd": ["-vtls"],
	"versions-x86_64": ["UseAmd64Impl"]
	"libs-posix": ["ssl", "crypto"],
	"sourceFiles-windows-x86_64-dmd": ["lib/win32/mylib.lib"],
}
____________________
In the Configuration section:
It says "A list of platform suffixes (as used for the build 
settings) to limit on which platforms the configuration applies." 
Platform suffixes is not clear enough. Above they are referred to 
as field name suffixes. I would re-write this as "A list of field 
name suffixes (as described above and used for the build 
settings) to limit on which platforms the configuration applies. 
For instance, setting "platforms": ["windows-x86_64-dmd"] would 
mean the configuration would only apply when compiling only with 
the DMD compiler on Windows with an x86_64 bit architecture."

Also, it says "When defining a configuration's platform, any of 
the suffixes described in build settings may be combined to make 
the configuration as specific as necessary." to which I would 
append:

For instance, in the following configuration
{
	"name": "desktop-app",
	"targetType": "executable",
	"platforms": ["windows"],
	"versions": ["DesktopApp"],
	"libs-x86_64-dmd": ["d3d9"]
},
"libs" is customized for compiling with DMD on the x86_64 
architecture.  Further, since "platforms" is set to Windows, it 
applies "libs" (and "versions" and "windows" does not need to be 
specified.