www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Newly rewritten developer docs for DSSS

reply Gregor Richards <Richards codu.org> writes:
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
Aug 09 2007
next sibling parent reply Bill Baxter <dnewsgroup billbaxter.com> writes:
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?
Aug 09 2007
next sibling parent reply Gregor Richards <Richards codu.org> writes:
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?
 


These are all excellent questions which are indeed not answered in the 
doc. I will update the doc to answer them all after I get home from work 
(in about eight hours).

Thanks for the feedback.

  - Gregor Richards
Aug 09 2007
parent Bill Baxter <dnewsgroup billbaxter.com> writes:
Gregor Richards wrote:

 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.






....

 
 These are all excellent questions which are indeed not answered in the 
 doc. I will update the doc to answer them all after I get home from work 
 (in about eight hours).
 
 Thanks for the feedback.
 
  - Gregor Richards


Great.  Thanks a lot for taking another run at the dsss documentation.

I think another thing that would be useful would be a dsss-by-example 
page that didn't include all the distractors (i.e. the bits about how to 
do X with something besides dsss), and which went a little further to 
cover a few more scenarios.  The ideal to me would be that when starting 
a new project I could just browse through snippets of existing dsss 
scripts and grab the one that applies to my project, change the names, 
and be done.

--bb
Aug 09 2007
prev sibling parent reply Gregor Richards <Richards codu.org> writes:
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
Aug 09 2007
parent reply Bill Baxter <dnewsgroup billbaxter.com> writes:
Gregor Richards wrote:

 Bill Baxter wrote:



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


...[good additions cut]...


  > 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?


Well, it still basically says "'set' sets a setting", which is defining 
a word by using the word.  It doesn't clarify what you mean by a 
'setting'.  That should be explained.  Also, it might help if you 
explained in the 'set' section more clearly what problem 'set' is 
designed to solve.

And as for the 'on-the-fly' part, which you changed to "while DSSS is 
actually running" -- are there other commands that do something when 
DSSS is not running!?

--bb
Aug 09 2007
parent reply Gregor Richards <Richards codu.org> writes:
Bill Baxter wrote:

 Gregor Richards wrote:

 Bill Baxter wrote:


 

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


 
 ...[good additions cut]...
 

  > 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?


 
 Well, it still basically says "'set' sets a setting", which is defining 
 a word by using the word.  It doesn't clarify what you mean by a 
 'setting'.  That should be explained.  Also, it might help if you 
 explained in the 'set' section more clearly what problem 'set' is 
 designed to solve.


I honestly haven't a clue how to make this more clear. I'm not saying 
that it's at all clear, just that I don't know how to improve it. What 
exactly a setting is is described in an above section, so repeating it 
there wouldn't be helpful. If you can suggest a wording, that would help.


 
 And as for the 'on-the-fly' part, which you changed to "while DSSS is 
 actually running" -- are there other commands that do something when 
 DSSS is not running!?


No, but there's no other way to set a setting while DSSS is running.


 
 --bb


  - Gregor Richards
Aug 10 2007
parent Bill Baxter <dnewsgroup billbaxter.com> writes:
Gregor Richards wrote:

 Bill Baxter wrote:

 Gregor Richards wrote:

 Bill Baxter wrote:



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


 ...[good additions cut]...


  > 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?


 Well, it still basically says "'set' sets a setting", which is 
 defining a word by using the word.  It doesn't clarify what you mean 
 by a 'setting'.  That should be explained.  Also, it might help if you 
 explained in the 'set' section more clearly what problem 'set' is 
 designed to solve.


 
 I honestly haven't a clue how to make this more clear. I'm not saying 
 that it's at all clear, just that I don't know how to improve it. What 
 exactly a setting is is described in an above section, so repeating it 
 there wouldn't be helpful. If you can suggest a wording, that would help.


I see what you mean.  Yes the description in the =SETTINGS= section is 
good.  Maybe the best thing would be to stick in a (See Section 
=SETTINGS=) after saying that set sets a setting.



 And as for the 'on-the-fly' part, which you changed to "while DSSS is 
 actually running" -- are there other commands that do something when 
 DSSS is not running!?


 
 No, but there's no other way to set a setting while DSSS is running.


I don't get what the difference is between saying
   a = Hello
and
   set a Hello

They both seem to set a value while DSSS is running to me.  The main 
difference seems to be that 'set' can apply to a different section than 
the one it appears in.


One more question:  Is there some way to set up dsss.conf to build 
recursively?  For instance in the directory top/ there's a dsss.conf 
file that invokes top/sub/dsss.conf.  Will a sticking in a [sub] section 
do that?

--bb
Aug 12 2007
prev sibling parent reply Olli Aalto <oaalto gmail.com> writes:
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.
 


It would be nice to be able to build and install a project in one go.
For example:
dsss build install
or just
dsss install
(which would do a build if the target is older than its sources).

Also how do I mark a section in dsss.conf to be non-installable?
For example I have a test/demo application for a library which I don't 
want to go to dsss/bin.

O.
Aug 09 2007
parent reply Gregor Richards <Richards codu.org> writes:
Olli Aalto 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.


 
 It would be nice to be able to build and install a project in one go.
 For example:
 dsss build install
 or just
 dsss install
 (which would do a build if the target is older than its sources).
 
 Also how do I mark a section in dsss.conf to be non-installable?
 For example I have a test/demo application for a library which I don't 
 want to go to dsss/bin.
 
 O.


Unfortunately, these are both lacks in DSSS, not lacks in its 
documentation :)

The current way to make a section non-installable is to simply make it 
non-default. This is a fairly new feature so it didn't yet make it into 
the documentation. Note to self: Add it to the documentation :P

That being said, there should be a better way.

I've made some tickets:
http://www.dsource.org/projects/dsss/ticket/105
http://www.dsource.org/projects/dsss/ticket/106

  - Gregor Richards
Aug 09 2007
next sibling parent reply BCS <ao pathlink.com> writes:
Reply to Gregor,


 Olli Aalto 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_engi
 neers and yell at me. All responses welcome.
 


 It would be nice to be able to build and install a project in one go.
 For example:
 dsss build install
 or just
 dsss install
 (which would do a build if the target is older than its sources).
 Also how do I mark a section in dsss.conf to be non-installable?
 For example I have a test/demo application for a library which I
 don't
 want to go to dsss/bin.
 O.
 


 Unfortunately, these are both lacks in DSSS, not lacks in its
 documentation :)
 
 The current way to make a section non-installable is to simply make it
 non-default. This is a fairly new feature so it didn't yet make it
 into the documentation. Note to self: Add it to the documentation :P
 
 That being said, there should be a better way.
 
 I've made some tickets:
 http://www.dsource.org/projects/dsss/ticket/105
 http://www.dsource.org/projects/dsss/ticket/106
 - Gregor Richards
 


What is your thoughts on the idea of using miniD as a scripting language 
inside DSSS?

This would go a long ways towards adding the kinds of things I want DSSS 
to do.
Aug 09 2007
parent reply Gregor Richards <Richards codu.org> writes:
BCS wrote:

 Reply to Gregor,
 

 Olli Aalto 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_engi
 neers and yell at me. All responses welcome.


 It would be nice to be able to build and install a project in one go.
 For example:
 dsss build install
 or just
 dsss install
 (which would do a build if the target is older than its sources).
 Also how do I mark a section in dsss.conf to be non-installable?
 For example I have a test/demo application for a library which I
 don't
 want to go to dsss/bin.
 O.


 Unfortunately, these are both lacks in DSSS, not lacks in its
 documentation :)

 The current way to make a section non-installable is to simply make it
 non-default. This is a fairly new feature so it didn't yet make it
 into the documentation. Note to self: Add it to the documentation :P

 That being said, there should be a better way.

 I've made some tickets:
 http://www.dsource.org/projects/dsss/ticket/105
 http://www.dsource.org/projects/dsss/ticket/106
 - Gregor Richards


 
 What is your thoughts on the idea of using miniD as a scripting language 
 inside DSSS?
 
 This would go a long ways towards adding the kinds of things I want DSSS 
 to do.
 
 


I am very strongly considering it. In fact, I have a ticket on it.

The only problem I see is that it would create a big Phobos-Tango 
schism. Basically, I'd like to maintain both a Phobos and a Tango 
branch, but if I do that, only the Tango branch will have scripting 
support. I'd hate for a build to not work because somebody has the 
Phobos version of DSSS installed ...

My current consideration is to maintain the library portion in two 
branches, so that people making .d files importing DSSS can use either, 
but make the binary only compilable with Tango. Since I'll be 
distributing binaries, this may or may not be a problem.

Anyway, none of this is going to happen before the conference. I need 
things to calm down :)

  - Gregor Richards
Aug 09 2007
parent BCS <ao pathlink.com> writes:
Reply to Gregor,


 I am very strongly considering it. In fact, I have a ticket on it.
 
 The only problem I see is that it would create a big Phobos-Tango
 schism. Basically, I'd like to maintain both a Phobos and a Tango
 branch, but if I do that, only the Tango branch will have scripting
 support. I'd hate for a build to not work because somebody has the
 Phobos version of DSSS installed ...
 
 My current consideration is to maintain the library portion in two
 branches, so that people making .d files importing DSSS can use
 either, but make the binary only compilable with Tango. Since I'll be
 distributing binaries, this may or may not be a problem.
 
 Anyway, none of this is going to happen before the conference. I need
 things to calm down :)
 


cool, Thanks.


 - Gregor Richards
Aug 09 2007
prev sibling parent Olli Aalto <oaalto gmail.com> writes:
Gregor Richards wrote:

 Olli Aalto 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.


 It would be nice to be able to build and install a project in one go.
 For example:
 dsss build install
 or just
 dsss install
 (which would do a build if the target is older than its sources).

 Also how do I mark a section in dsss.conf to be non-installable?
 For example I have a test/demo application for a library which I don't 
 want to go to dsss/bin.

 O.


 
 Unfortunately, these are both lacks in DSSS, not lacks in its 
 documentation :)
 
 The current way to make a section non-installable is to simply make it 
 non-default. This is a fairly new feature so it didn't yet make it into 
 the documentation. Note to self: Add it to the documentation :P
 
 That being said, there should be a better way.
 
 I've made some tickets:
 http://www.dsource.org/projects/dsss/ticket/105
 http://www.dsource.org/projects/dsss/ticket/106
 


Thanks for clearing this up. Both are not very critical, more of a 
convenience type things.

O.
Aug 09 2007