How to Contribute Software for Inclusion in Dervish
These are the guidelines for submitting code that you feel should some
day be part of Dervish. We expect that similar procedures will one day be
instituted for other products, such as photo.
How to contribute code
The files in contrib
The files in the template contribution
Before donating code, you must ensure that it meets certain criteria, and that
it is suitably packaged.
Requirements
Submitting Contributed Code
Naming Conventions
Coding Standards
The section on the template directory describes
which files we expect you to provide, and what they should be named.
Your code must compile with no warnings using the project-approved
picky compiler flags (and the -filter option to sdssmake). We would
prefer you to have compiled it on more than one target machine, or
with more than one compiler, but this is not manditory. If warnings
later show up on other machines you will be required to fix them.
Once your code is cleaned up you should put together a test suite. You
probably wrote a good deal of code to test things while you were developing
your contribution, so instead of throwing all that work away here's
your chance to preserve it for posterity. Convert each of your test
cases into a TCL verb, and put all of the resulting TCL into a file
called something like template_test.tcl in the test directory. If you
have tests that can only be called from C, please write an extra TCL
primitive to call them. As described in the section on
test files, this TCL script should return silently
if no tests fail, and return an error if any do.
Finally, write some documentation and put it in the www directory. We'd
prefer it in html, but a straight ascii file is acceptable too.
Once you have read (or skimmed) this document and believe that your
code is ready for distribution, and have checked that you can build
the dervish using it, and that it passes all tests, you are ready to
submit it. This simply involves checking it in using rcvs in the
usual manner and sending mail to a responsible person (currently
rhl@astro.princeton.edu, but this will change -- in fact it will
become automatic at some point).
Bacause your code is a candidate for inclusion in dervish, all external
names should follow the usual
dervish naming conventions;
if you have forgotten the details, the highlights are:
all public external names begin sh
all private external names begin p_sh
names look like [p_]shFooDestroyWithPrejudice
no names with file scope may follow dervish conventions
Coding Standards
Bacause your code is a candidate for inclusion in dervish, it should
follow the usual
dervish coding conventions;
if your memory is a little rusty, these are basically:
Follow the Indian Hills Style Guide
Format your code as in Kernighan & Ritchie (but with a 2, 3, or 4
space indent).
Declare all external variables and prototype all external functions
in header files.
All files should start with a short description of the functionality
that the file provides.
Each non-trivial function should have a few
line description of what it does.
Non-trivial variables should have a
comment on the line that they are declared on to say what they do.
If it isn't obvious what a block of code does a comment is appropriate,
as are comments between logical parts of a function.
Comments that merely
describe what the code says should be omitted (e.g. `i++; /* increment i */').
The following files are always present in a contrib directory:
- Makefile
- Make the libraries and run the tests
- run_tests.tcl
- A script to run all of the test scripts in the test directory.
- tclContribVerbs.c
- The file that makes contributed words available to dervish. When you
add your package to contrib, you should add one function to this file
that declares all of your TCL words.
- tclContribDummy.c
- A dummy version of tclContribVerbs.c that makes none of the contrib
code available. It's invoked with the -nocontrib flag to sdssmake.
- test/Makefile
- A Makefile with just clean and install targets. Not very exciting.
- www/contrib.html
- This document.
In addition, the following are produced by running sdssmake:
- libcontrib.a
- The library containing all of the contributed code
- libcontrib_dummy.a
- The dummy library with no real code (used by sdssmake -nocontrib)
- tclIndex
- An index of TCL procedures. This is used to load TCL when referenced,
rather than always loading all of the contributed TCl verbs.
If I have donated a package called template, the following files should be
present:
- tclTemplate.c
- C-code to define all of your TCL primitives. This file has only one
external function to define all of the verbs; you must ensure that this
function is called by tclContribVerbs.c.
- template.c
- Any C that your application requires.
- template.h
- An include file to define all of the external symbols that your
application uses.
- template.tcl
- Any TCL that you need. Most applications probably define a small number
of C primitives and a relatively large amount of TCl.
- test/test_template.tcl
- This is the test file for your application.
It must produce no output if no errors are detected, and
return an error (with a helpful message) if any test fails. You should
try to write tests that test as much of your package as possible, and to
test both expected failures as well as anticipated successes.
- www/template.html
- The documentation that you deem necessary to use your package. It should
describe both the C and the TCL interfaces.