Developer Hints

This file contains some helpful recipes and other tips for people working with the source code.

Creating Javadocs for ANTLR

Here's how I create javadocs for ANTLR on my cygwin installation.

[cclifton@MOJOE antlr !53]$ cd /usr/local/antlr

[cclifton@MOJOE antlr !53]$ CLASSPATH="."

[cclifton@MOJOE antlr !54]$ javadoc -private -d javadocs -link file:c:/cygwin/usr/local/jdkdocs/jdk1.4/docs/api -use -subpackages antlr

Decorator Recipe

- Converting to decorator pattern

  * For a concrete decorator with a concrete superclass the subclass
    should inherit the delegee field and any methods that reference
    the field but should initialize the delegee to the appropriate
    subtype of the field's type.

  * Decorating recipe:

    - write test cases

    - make interfaces

      * cvs add

      * add to Makefile

      * change original class to implement interface
    
    - Change references

      * make tags for both packages

      * visit-tags-table for both packages

      * tags-query-replace J~ J~Type (be careful not to replace instantiations)

    - make Jml~ class

      * cvs add

      * add to Makefile

      * change package declaration

      * import mjc.*

      * implement interface

      * add constructor

      * add private fields

      * add accessors

      * delegate (watch for void and remove parameter types)

Integrating external changes into CVS

This recipe explains how to integrate changes submitted by those who do not have direct CVS access to the repository.

Assumptions

Recipe

  1. Create a directory and move the tar-ball into it
  2. Checkout a copy of the code matching the snapshot from which the changes were derived by executing the following substituting the correct date and time: cvs -z3 -d:ext:multijava.cvs.sourceforge.net:/cvsroot/multijava checkout -D YYYY/MM/DD HH:MM MultiJava
  3. Test the tar-ball by executing tar -tzvf filename.tar.gz
  4. Change to the directory of your checked-out code to which the directory structure in the tar-ball corresponds.
  5. Untar the tar-ball, overwriting the changed files and adding the new files, by executing tar -xzvf filename.tar.gz
  6. Execute cvs -n update -A to verify that the changes can be integrated with the current repository. The -A option removes the sticky tags that would otherwise cause synchronization based the old date specified when checking out the code.
  7. Read the results of the previous step to make sure no merge conflicts were reported. If any were reported make sure they can easily be resolved (see cvs info for more details). In particular watch out for changes in line endings between Unix and Windows that cause entire files to mismatch.
  8. Execute cvs update -A to synchronize changes from the repository with your working code.
  9. Set the environment variables CLASSROOT, JCLASSROOT, and CLASSPATH to reference your working directory. An easy way to do this is to change to the MultiJava directory and source (i.e., execute . scriptfile) the shell script given below.
  10. Change to the directory containing the Make.Defs file and execute make rebuild-all.
  11. If the previous step succeeds, then delete the files that are to be removed with this set of changes. Use cvs rm to remove them from the repository as well.
  12. Again, change to the directory containing the Make.Defs file and execute make rebuild-all.
  13. Execute make runtests 2>&1 | tee results.out to run the regression test suite.
  14. If the regression tests are as expected then delete results.out.
  15. Change to the MultiJava directory and commit the changes.
  16. Treat yourself to a snack. Dried apricots are a healthy alternative.

Helper Script

Here is a shell script that is useful in following the recipe above.

#!/bin/bash -x

# source this file in the directory which is the root of the MultiJava
# source-code and it will set the pertinent environment variables

export CLASSROOT=`cygpath -u -a .`
export JCLASSROOT=`cygpath -w -a . | sed 's/\\\\/\\\\\\\\/g'`
export CLASSPATH="`cygpath -w -a .`;${CLASSPATH}"