Newly rewritten developer docs for DSSS

[Gregor Richards]

Bill Baxter wrote:
> Gregor Richards wrote:
>> Because DSSS' README.software_engineers was pretty bad, I've 
>> completely rewritten it from the ground up. It's not yet finished, but 
>> it's definitely ready to receive some intensive feedback.
>>
>> So please, read
>> http://svn.dsource.org/projects/dsss/trunk/docs/README.software_engineers
>> and yell at me. All responses welcome.
>>
>>  - Gregor Richards
> 
> Here are some questions I have about writing a dsss.conf file, but which 
> I couldn't easily find the answer to in the new doc:
> 
> - How do I add to the library path?
> - How do I add to the include path?
> - How do I specify that I want to link to a particular pre-existing library
>   > in a platform independent way?
>   > for a dsss'ed lib?
>   > for a non-dsss'ed lib?
> - Can I use environment variables in specifying an include or library 
> search path? (it says you can use them in hook commands, but doesn't 
> mention about elsewhere).
> - Are slashes in dsss.conf platform agnostic? (i.e. '/' works everywhere)?
> - after you use the 'cd' command do you need to 'cd' back?
> - How do I enable my project for dsss net installation?
> - How do I get dsss to run unit tests on all or some of my modules?
> - How do I build documentation using dsss?
> - What are the different values for 'type'?
>   (The different possible settings for 'type' now seem to be spread all 
> over the place.  It would be good to give a consolidated list before 
> going into the details of the individual types.)
> 
> And one comment:
> - "The 'set' command sets a setting" -- this not a very helpful 
> description.
> It's not clear why you need 'set'.  It says it's for doing things 
> 'on-the-fly'.  But what does that mean?  Is
>    prebuild = echo "Hi"
> not on-the-fly?
> 

*whew*!

OK, I think that I covered these fairly effectively. When I first wrote 
this doc, I had immediate peer review, but these additions did not, so 
rewording suggestions are welcome.

 > - How do I add to the library path?
 > - How do I add to the include path?
 > - How do I specify that I want to link to a particular pre-existing 
library
 >   > in a platform independent way?
 >   > for a dsss'ed lib?
 >   > for a non-dsss'ed lib?

These should be covered in the new "dependencies" section:
-----------------------------------------------------------------
== DEPENDENCIES ==

The primary reason that DSSS exists is to make handling dependencies 
easier. To
this end, is is never necessary to explicitly specify a dependency upon a
library which is itself set up to use DSSS. Because DSSS traces D 
imports and
keeps an Internet-accessible repository of package information, 
installing the
dependencies which are supported by DSSS is as easy as typing:
$ dsss net deps

However, dependencies on non-DSSS D libraries or C libraries can be more
complicated.

= INCLUDE PATHS =

It is possible to specify include paths in the 'buildflags' settings. Import
paths are specified with the -I flag:
buildflags=-I../prerequisite/import

= PREREQUISITE LIBRARIES =

Library search paths are specified with the -S flag:
buildflags=-S../prerequisite/lib

Libraries can be explicitly linked in with the -ll flag. -ll works 
similarly to
-l in most compilers. On POSIX and similar platforms, a flag such as
-ll<library>
will link in a library named
lib<library>.a (or lib<library>.so)

On Windows (except GDC), the same flag will link a library named
<library>.lib

Libraries linked in with the -ll flag are searched for in the search paths
specified by the -S flag.

The -ll flag is only useful for explicitly linking libraries into 
binaries. If
your library depends on a non-DSSS library, you must list that 
dependency in a
.d file which is part of your library. This is done with the 'link' pragma,
which must always be specified within version(build):
version (build) {
     pragma(link, "example");
}

The above example will cause any binary linked against your library to link
against the library named libexample.a (or example.lib on Windows).
-----------------------------------------------------------------


 > - Can I use environment variables in specifying an include or library
 > search path? (it says you can use them in hook commands, but doesn't
 > mention about elsewhere).

I've moved the description of environment variables to make it obvious 
that they will work in any setting.


 > - Are slashes in dsss.conf platform agnostic? (i.e. '/' works 
everywhere)?

I added a notice in the "basics" section to explain that '/' should be 
used everywhere.


 > - after you use the 'cd' command do you need to 'cd' back?

Added: It is unnecessary to return to the original directory after 
'cd'ing. The directory will be restored after the hook commands have 
finished.


 > - How do I enable my project for dsss net installation?

I haven't added this yet, but I added a note to myself to add this.

For your information, register at dsss.codu.org and then ask me to give 
you permissions to add your package to the source list.


 > - How do I get dsss to run unit tests on all or some of my modules?
 > - How do I build documentation using dsss?

Added an "advanced features" section.


 > - What are the different values for 'type'?
 >   (The different possible settings for 'type' now seem to be spread all
 > over the place.  It would be good to give a consolidated list before
 > going into the details of the individual types.)

You're absolutely right, this was a bit messy. I've made a subsection 
with this information.


 >
 > And one comment:
 > - "The 'set' command sets a setting" -- this not a very helpful
 > description.
 > It's not clear why you need 'set'.  It says it's for doing things
 > 'on-the-fly'.  But what does that mean?  Is
 >    prebuild = echo "Hi"
 > not on-the-fly?

I changed the wording:

"The 'set' command sets a dsss.conf file setting while DSSS is actually 
running."

Better?


Thanks for your feedback, I think these changes have substantially 
improved the document.

  - Gregor Richards