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.a or lib.so., and on Windows they are named .lib. The middle part () 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: /include/d Lib path: /lib Bin path: /bin DSSS keeps track of everything it intalls for a given software package in the file: /share/dsss/manifest/.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 /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 ` 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.