root/branches/tango/docs/README.technical

This document intends to explain how DSSS works on a low level, its theory of
operation, and how it is implemented. It is assumed that the reader is
experienced with the D language, build tools such as bud and rebuild, and DSSS.

DSSS' function is simple in principle, but rather complex in practice.
Essentially, the goal of DSSS is to minimize the amount of information the user
needs to provide to compile and use D software. Some of the ways it
accomplishes this is with transparent dependency management, library handling
and consistent installation. This documentation will divide the process into
three section: Building, installing, and the 'net' feature.


Building
--------

There are three classes of builds: binaries, libraries, and non-compilation
sections. Since the non-compilations sections (sourcelibrary and extra
sections) are not built, they are not discussed here.

In either binaries or libraries, the list of files to be passed into the build
tool is generated:
1) If the section name is a file name, that file is the only element.
2) If the section name is a directory name, all files in that directory or any
   of its subdirectories which are:
   * Not covered by a more specific directory-named section and
   * Not in the 'exclude' variable for the section.

The target file name (when not specified) is generated. The exact semantics
behind this generation is discussed in the next section.

If a library is being built, .di (D Interface) files are generated from every
file which is to be built into the library. These .di files should be generated
by the compiler, but due to compiler limitations, they are generated by
duplicating the .d files. The .di files then have pragmas added such that they
are associated with the proper libraries, such as:
version (build) {
    pragma(link, "SDG-foolib");
}


    Target Name Generation
    ----------------------

With binaries, the generated name is simply the section name without the .d
extension, and with a .exe extension on Windows. Libraries have a more complex
naming scheme.

Library naming is based around the standard library naming convention of the
host operating system, so on Posix systems libraries are named lib<something>.a
or lib<something>.so.<soversion>, and on Windows they are named
<something>.lib. The middle part (<something>) contains a "host specifier" and
the name of the package that the library contains. The host specifier is a
character sequence which encodes the type of the library and the required host
compiler. The specifier is in the form:
[S]D{D,G}

The 'S' specifies a static library, it is elided for shared libraries. The
first 'D' specifies that the library is in D. The second D or G specifies that
the library requires DMD or GDC, respectively.

After the host specifier is a hyphen, then the package specifier. The package
specifier is simply the D package that the library contains, with dots replaced
with hyphens.

This library target name generation is beneficial because it creates no
conflicts, and makes the contents of the libraries immediately obvious.


Installing
----------

DSSS installation simply involves going through each section and copying the
produced binaries to the appropriate paths. .di files are copied into the
import path, .lib or .a files are copied into the lib path, and binary programs
are copied into the binary path. These paths, by default are:
Import path:    <DSSS' prefix>/include/d
Lib path:       <DSSS' prefix>/lib
Bin path:       <DSSS' prefix>/bin

DSSS keeps track of everything it intalls for a given software package in the file:
<DSSS' prefix>/share/dsss/manifest/<package name>.manifest
so that it can be uninstalled in the future.

The lib and import paths are also added to the build program's command line at
build time, such that a tool being built with DSSS can use previously-installed
libraries.

There is also an 'install' pseudocommand, to be used in a preinstall or
postinstall setting, which will install any file to any path, adding it to the
manifest file.


The 'net' Feature
-----------------

`dsss net` is one of DSSS' most alluring features. It allows the user to
easily install D software packages, and also resolve depenencies.

The mechanism behind the 'net' feature is quite simple. There is a central
'sources' repository which DSSS uses. The list of source repositories is stored
in the file
<DSSS' prefix>/etc/dsss/list.list

When a source list repository is selected, DSSS downloads three files from it:
source.list, pkgs.list and mirrors.list. The function of the files are as
follows:

source.list
    Associates software package names with upstream repositories, in svn or
    .tar.gz format, as well as associating necessary patch files with packages.
    This file is maintained manually.

pkgs.list
    Associates packages with the latest version numbers, and lists static
    dependencies of modules upon packages, and packages on other packages. This
    file includes the list of modules provided by any package, e.g.:
    wx/Button.d 0.10 wxd
    This file is generated. See below.

mirrors.list
    Simply lists mirrors, alternative locations to download software packages
    from. This file is maintained manually.

When the command `dsss net install <package>` is given, DSSS looks in
source.list to find the upstream repository of the package to install from. It
then downloads the package, applies any patches necessary, traces dependencies
(explained below), then simply runs `dsss build` and `dsss install`.

Dependencies are also traced by the `dsss net` feature, through `dsss net
install` or `dsss net deps`. The process of seeking dependencies is simple:

1) Every source file in the current package is parsed for imports.
2) Imports which correspond to modules which are not installed are looked up in
   pkgs.list, and associated with software package names.
3) Those packages which were found in step 2 are installed via `dsss net
   install`.


    pkgs.list
    ---------

The pkgs.list file is generated by an aptly named program, pkgslist.d. This
program is available in DSSS' subversion repository. Its function is:

1) Download all software installable via DSSS (this tool also generates DSSS'
   mirrors).
2) For each software package downloaded, using the same algorithm as sss.build,
   find all of the D files (not library files or binary programs) the package
   would install.
3) In the pkgs.list file, associate the D files found in step 2 with the
   appropriate software packages.