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
  • How to contribute code

    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
  • Requirements

    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.

    Submitting Contributed Code

    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).

    Naming Conventions

    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 files in contrib

    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.

    The files in the template contribution

    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.