written by Karl Trygve Kalleberg
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
1.1 What is SDS ?
As the project web page at http://sds.yi.org
"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
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.
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
- 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
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
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
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
- A C/C++ compiler. We use gcc-2.95.x.
Anything close be safe. If you have a commercial compiler, your milage may
- 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
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
- 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.
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.
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