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 

   > 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 

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.
 

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.

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.

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.

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