If you're new to SDS and think you can skip to 'Installation' and live happy as a clam ever after, you're sadly mistaken. SDS is complex. Difficult. Beastly. Horrendous. Or somewhere in between.

If that didn't scare you off, you probably have what it takes not only to see the installation through, but learning how to (ab)use SDS in your daily affairs. You will have to read this entire HOWTO, though, that's all I'm trying to say.

1. Introduction

1.1 What is SDS ?

As the project web page at http://sds.yi.org says:

"The Software Development Foundation (SDS) is an open architecture
designed for developing tools for software development. Based on
XML, the SDS makes it easy for most languages and other systems to
incorporate its tools.

One of the most important principles of SDS is to make development tools
easily available for new languages and is therefore an important tool for
people interested in making new languages.

The core of SDS is the Code Structure Format (CSF) which collects most
interesting information about source code which can be easily utilised by
tools. Included is also a documentation application SDOC which allows
CSF-files to be streamlined for documentation."

What this means is that SDS is a framework for language tools which do

Source level documentation, like Javadoc
Cross referencing, like lxr
Code metrics
Source navigation, like Cygnus' Source Navigator
More

Included in the standard distribution are tools for:

Converting C/C++ code into a CSF database
Converting Java code into a CSF database
Converting Lisp code into a CSF database
Generating source level documentation from a CSF database
A CSF linker for merging CSF databases

A CSF database should best be thought of as an object file, from C/C++ terminology. Once the above core tools have stabilised, we envision a few new tools and fixes:

CSF database based on SQL
Cross indexing
Emacs bindings (this has already been done, but is not up to date)
#include graphs/package dependency graphs

1.2 Who should use SDS ?

In an ideal world, the answer is: "everybody who wants to". But in this world, the target user group is limited to experienced programmers. Installing and using SDS can be a difficult process, one which we are working on improving, but not at the cost of functionality.

In particular, the target audience for the current incarnations of SDS is developers who wish to contribute with suggestions, bugs-fixes, documentation, ideas and of course code.

2. Overview

What we refer to as 'SDS' in this documentation is actually just a collection of command line tools. If you treat SDS as a large-scale compiler, the front-end would consist of:

cxx2csf - the C/C++ front end which converts C/C++ code into the a CSF file
java2csf - the Java front end which converts Java code into a CSF file
lisp2csf - the Lisp front end which converts Lisp code into a CSF file

The CSF files should be though of as ASTs (Abstract Syntax Trees). They can be linked, pruned, rewritten. This is the job of the CSF linker, imaginatively called csf2csf.

Once you have a CSF file, you can send it to the back-end, which is currently represented only by:

csf2sdoc - The documentation system which produces HTML documentation from your sources

As time goes by, we expect to have

csf2xr - A cross referencing tool
csf2emacs - An emacs (or general editor) binding
csf2metric - A code metric tool, once we figure out what's worth measuring..

It is important to know that SDS isn't an 'all-in-one' package that has no hope of accomodating change and growth. The entire idea behind SDS was to allow it to be extended fairly easily, using any language. As proof of concept, different parts of the system has been written in different languages. Each front-end is currently written in its respective language.

If you find any part of the system slow or unfit, you should be able to easily drop in a replacement. Say you dislike the current Java front-end, there should be little work involved to replace it, if you have another Java front-end handy.

3. Installation

Here there be dragons. Beware!

Installing SDS in its fullest of blooms can be a headache. We acknowledge that fact. You have been warned.

3.1 Necessary tools

First off, you will need the following:

A Lisp system. CMUCL and ACL will work best. CLISP will also work. You can get CMUCL with your Debian and CLISP at ftp://ftp.ii.uib.no/pub/stig/SDS/developer/
A C/C++ compiler. We use gcc-2.95.x. Anything close be safe. If you have a commercial compiler, your milage may vary.
A JDK. We use IBM's JDK 1.1.8.
Python. We use version 1.5.x
A normal, healthy Unix or GNU/Linux environment with a good compliment of GNU tools.

The installation script will of course look to see that everything is Jim Dandy.

3.2 Compiling the beast

After untarring to a suitable place with some free space (compiled source tree takes around 40MB), you should decide what to include in your compilation and where to put it.

If you run Solaris/Sparc, use option --disable-shared. If you're paranoid, this options is also for you.
If you use CLISP instead of CMUCL, use option --with-clisp
If you have Harlequin LispWorks instead of CMUCL, use option --with-lispworks
If you have ACL and want to use it instead of CMUCL, use option --with-allegro
If you use jikes, or if javac isn't in your path, use --with-javac=(your javac)
Add --enable-cplusplus to have the C/C++ front-end compiled and installed.
Add --enable-javapart to have the Java front-end compiled and installed
If the default installation dir, /usr/local isn't good enough for your, use option --prefix=(your nice spot)

Once you have composed your configure line, run it. Then run make install. If things go awry, send us a bug report.

4. Usage

Is ill-advised.

A simple test-case is however provided here. I assume that you have installed SDS in /FOO/ and all paths in the example will reflect that. It is also assumed you wish to use the server and have installed a proper $HOME/.sds/prefs.xml file based on e.g tests/glob-prefs.xml in the dist.

Have two xterm-windows ready, one for the server and one for all other work. In the server-xterm you start the SDS-server.

    /FOO/bin/start-sds-server.sh

In the src/clisp/examples/ directory there is a file generate-doc.sh which shows how I generate docs for SDS. The accompanying file sds-prefs.xml might be useful as well. Any use of this generator will be noisy at this stage though. Use the file as a template and tailour it to your needs.

5. Bug reports

If you find any show-stoppers or have anything else regarding SDS you want to complain about, you can send your gripe to Stig E. Sandø or Karl Trygve Kalleberg

If you want to help out, you can join the sds-devel mailing list.

Bugs in this documentation should be sent to Karl Trygve Kalleberg