								-*-outline-*-

* Introduction

This file is intended to be a helping hand to all people who intend to
hack on the Sizzle interpreter and the supporting tools.  If you want
to stick your fingers into the code, read this file carefully.

When reading the following, always apply some _common sense_.  The
rules I wrote down do not require bondage and discipline for their own
sake, but they are here because I think they make sense.

If you have questions about this file, do not hesitate to contact me
at <mgrabmue@cs.tu-berlin.de>.

Happy hacking,
  'mgrabmue (2000-08-17)


* Development requirements

The source distribution only requires a Unix with a working ANSI C
compiler or a Windows box with either the Cygwin or MingW32 tools if
you only want to build the interpreter library and the standalone
interpreter.

For hacking on the source code, you will need the following additional
packages (the following descriptions are taken from the Guile
distribution and adjusted as needed):

Autoconf 2.13: A system for automatically generating `configure'
	scripts from templates which list the non-portable features a
	program would like to use.  Available in
	"ftp://ftp.gnu.org/pub/gnu/autoconf".

Automake 1.4: A system for automatically generating Makefiles that
	conform to the (rather Byzantine) GNU coding standards.  The
	nice thing is that it takes care of hairy targets like 'make
	dist' and 'make distclean', and automatically generates
	Makefile dependencies.  Automake is available in
	"ftp://ftp.gnu.org/pub/gnu/automake".

libtool 1.3.4: A system for managing the zillion hairy options needed
	on various systems to produce shared libraries.  Available in
	"ftp://ftp.gnu.org/pub/gnu/libtool"


* CVS access

Sizzle is availabe via anonymous CVS to the public.

If you have write access to the repository, make sure that the source
tree is always compilable and as stable as possible.  Also do not
check in automatically generated files into the repository, with two
exceptions: the files require special tools, or the files require an
already installed working copy of the Sizzle interpreter.  These files
should only be built on demand.

Instructions for anonymous CVS:

- Log in as user `anoncvs' with the password `anoncvs':
  ...
  cvs -d :pserver:anoncvs@lkcc.pinuts.de:/home/cvs/cvsroot login
  Password: anoncvs
  ...

- Check out the module `sizzle':
  ...
  cvs -d :pserver:anoncvs@lkcc.pinuts.de:/home/cvs/cvsroot co sizzle
  ...

- Update your source tree whenever you feel like it:
  ...
  cd sizzle
  cvs update
  ...

Whenever you check out the source or update your repository, execute
the script autogen.sh, which will re-create some automatically
generated files.

* Guidelines

** Coding styleguide

Consistency is important!

The Sizzle project is free software and sympathizes with the GNU
project.  Thus all Sizzle code must conform to the GNU coding style
guides as close as possible.  I will only accept patches which are
formatted in GNU style.  Emacs will help you to accomplish that.

Please use small functions.  Function call overhead is not that bad
and does not justify huge functions.  If it is, use inline functions
instead or (shudder) preprocessor macros.  Functions should not be
much larger than 60 lines or so.  An exception are functions like
zzz_evaluate(), which is required to be large, and which is written
with extreme care.

Please format your code that it does not exceed 76 characters per
line.

Add comments to all functions and variables, telling their
functionality and how to use them.  At least all exported functions
and variables.

Please follow the naming conventions in the code.  All non-static
variables and functions must have a `zzz_' prefix.  Export as few
symbols as possible to keep the API simple and clean and to avoid name
clashes.

When making changes, also add an entry to the ChangeLog file.  Emacs
will help you with that too: C-x 4 a will open the ChangeLog file and
start a new entry for your change.  In the ChangeLog file, write down
what was changed, not _why_.  If it is not obvious why you changed a
bit of code, add a comment to the code explaining the reason.

Whenever you make changes which may affect the normal user, add an
entry to the NEWS file also.

** Documentation

Documentation is important!

Always keep this in mind.  Although the current manuals are not yet as
good as I would like them to be, you should always try to be better
than me and follow these directions:

- When you add a primitive, make sure that you supply a documentation
  string and an appropriate entry in the reference manual.

- When you add a source file which contains documentation strings, add
  them to the variable DOCSTRING_CANDIDATES in the file
  data/Makefile.am, so that the docstrings will make it into the
  docstrings.txt file.

- If you find an error or unclear formulation in the documentation,
  please report it as a bug, because wrong documentation is as bad as
  no documentation.

** Portability

Portability is important!

Sizzle should run under as many platforms as possible.  When you add
non-portable functionality, make sure that the configure script tests
for availability and that the non-portable code is left out if
necessary.

When changing the code, try to not to break Sizzle on other platforms.

Things to keep in mind:

- Make sure that the libsizzle can be built as a DLL under Win32.
  This means that you have exported variables in the header files with
  special keywords.  Refer to existing headers for how to do this.

- When developing under GNU/Linux, keep in mind that a lot of the
  functionality provided in the glibc is not provided on other
  platforms, or may require linking with special libraries.  Add tests
  to the configure code if in doubt.

** Compatibility

Compatibility is also important!

Do not introduce new patterns of use if they exists already.  Whenever
you implement new primitives, have a look at existing Scheme
implementations, mainly Guile.  Also refer to R5RS and the SRFIs.  It
is likely that someone has already defined syntax and semantic for
your problem, and it nice for users if you do not create Yet Another
Solution (TM) for a common problem.


** Internationalization and Localization

Use the gettext() or _() function for all constant strings.  Do not
forget to add new files which include translatable strings in the file
po/POTFILES.in.  Try to keep the PO files up to date.  If you do not
speak the languages, contact me and I will take care for it.

Do not hesitate to create new PO files if you are a native speaker of
any language which is not already supported.


** Code requirements

Safety comes before speed!

If you want to add a feature, implement it as robust as possible, even
if that means that the code runs a bit slower than it could be.
Sizzle does not try to compete with high-speed optimized compiler
output, it is merely meant to be a robust and stable embedding
language.

Try not to ignore the results of functions which might signal error
conditions.  In evaluation functions and primitives, make sure to
propagate errors and exeptions up to the caller (I know that currently
this is not the present state, but please try to be better than me).

Be careful about buffer overruns.

Never, never use functions like strcpy, strcat etc., except you are
_really_ sure that you know everything about the data involved.  Use
functions like strncpy or memcpy.  If you find that that is not
possible, change your code.  If it should be complicated, do the work
anyway, or forget about the change.

If you include experimental code into the distribution, please disable
it by default with preprocessor macros and conditional compilation, so
that everyone who is interested in your changes can turn it on by
defining a variable, but all others are not affected in their normal
use.

** Test suite

Add as many (sensible) tests as possible to the test suite.  If you
create new test files, please follow the existing examples.  The aim
is to have test files which test specific features (list procedures,
string procedures etc.), test files which represent real programs by
testing a variety of different functions and syntactic constructs, and
some test files which stress-test the interpreter by dealing with
large data structures and complicated computations.

But keep in mind that a test suite is no replacement for thought-out
and reviewed code.  There can never be enough tests for all possible
(and impossible) conditions, so please be careful when writing code.

