View mode: basic / threaded / horizontal-split · Log in · Help
August 09, 2007
Newly rewritten developer docs for DSSS
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
August 09, 2007
Re: Newly rewritten developer docs for DSSS
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?
August 09, 2007
Re: Newly rewritten developer docs for DSSS
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.
August 09, 2007
Re: Newly rewritten developer docs for DSSS
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
August 09, 2007
Re: Newly rewritten developer docs for DSSS
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
August 09, 2007
[little ot]Re: Newly rewritten developer docs for DSSS
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.
August 09, 2007
Re: [little ot]Re: Newly rewritten developer docs for DSSS
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
August 09, 2007
Re: [little ot]Re: Newly rewritten developer docs for DSSS
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
>
August 09, 2007
Re: Newly rewritten developer docs for DSSS
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
August 10, 2007
Re: Newly rewritten developer docs for DSSS
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
« First   ‹ Prev
1 2
Top | Discussion index | About this forum | D home