root/branches/bud/docs/README.software_engineers

DSSS is a tool to:

* Build D software.
* Install D software.
* Configure D software dependencies and libraries.
* Maintain a repository of DSSS-compatible D sources to be easily installable
  via the Internet.

To the average software engineer, the most important part is dsss.conf, the
file added to your source code to configure how DSSS will compile it.

dsss.conf is a plain-text file, with a similar syntax to Windows INI files. It
can have any number of sections, each of which is headed with the name in
brackets, like so:
[foo/bar.d]

Each section is named by a source file or directory. In general, sections named
for source files will generate binaries, and sections named for directories
will generate libraries, which are set up through DSSS to be equivalent to D
packages.

In each section, there can be any number of settings. Each setting is a
keyword, possibly followed by = or += and a value. For example, the "target"
setting sets the name of the output binary or library in a given section:
target=foobar
(In general, the target setting will be automatically set to something
sensible)

Furthermore, any amount of content in dsss.conf can be set up as version-
specific, with a version keyword similar to the version keyword in D. For
example, to make sure that a certain binary is only produced on Windows:
version (Windows) {
 [foo/windows.d]
 target=foo_for_windows
}

The version statement in dsss.conf has a fairly strict syntax: the { must be on
the same line as the statement, and the version being tested must be in
parenthesis. Unlike D, DSSS' version statement supports the ! (not) operator:
version (!Windows) {
 [foo/nowindows.d]
 target=foo_for_notwindows
}

The version statement also supports an 'else' clause:
version (Windows) {
 [foo/windows.d]
 target=foo_for_windows
} else {
 [foo/notwindows.d]
 target=foo_for_notwindows
}


There are quite a few other settings supported, such as:

* exclude
  * Exclude a list of .d files from being included in a library:
    exclude=foo.d bar.d

* prebuild, preinstall, preclean, postbuild, postinstall, postclean
  * Commands to be run before/after building/installing/cleaning. Can be any
    number of ;-separated commands, and supports some special command types:
    * .d files. If a .d file is specified as a command, it will be compiled and
      run.
      * Notably, D files can always use DSSS' headers. That is, the package
        'sss'.

    * install: DSSS has an internal 'install' command, which takes the
      following syntax:
      * install <file> <target directory>

    * eval: Run a command (.d file or otherwise), and execute its result
      * For example, the command could print "install chosen/file/to/install
        $INCLUDE_PREFIX"

    * set: Set a setting in DSSS' environment. The syntax is as follows:
      * set <section>.<setting> <value>
      * You may use * to apply a setting to all sections, or simply exclude the
        section (but still include the .) to set a global setting.

    * add: Like set, but adds to a setting.

  * In any command, you can use environment variables with a '$', such as
    $PREFIX. The following environment variables are provided by DSSS:
    * $DSSS : The dsss binary, if you need to call DSSS recursively. Better
      than counting on it being on the PATH.

    * $PREFIX : The prefix to which the software is being installed.

    * $BIN_PREFIX : The prefix to which binaries are being installed.

    * $LIB_PREFIX : The prefix to which libraries are being installed.

    * $INCLUDE_PREFIX : The prefix to which generated .di interface files are
      being installed.
      * This is the /base/ prefix, so for example the module foo.bar will be
        installed to $INCLUDE_PREFIX/foo/bar.di
      * This directory can also be used for .d files.

    * $ETC_PREFIX : The prefix to which configuration files are being
      installed.

* buildflags
  * Flags that will be added to the output to build/bud when building this
    section.


Furthermore, there is a global section for settings which are not specific to
any binary or library. You can add settings to this section simply by adding
them before any section declarations, or by making an empty section declaration
like so:
[]
global_setting=0

The important global settings are 'name' (which will otherwise be gleaned from
the directory name) and 'version' (which will otherwise be set to 'latest').


It is possible to add a setting to all sections with the special [*] section.


You can make 'special' build steps, which do not correspond to source files, by
naming them prefixed with a +. For example:
[+genSource]
prebuild = gensource.d


You can also recurse into subdirectories, by specifying the subdirectory as a
section and setting the type to "subdir":
[subtool]
type = subdir