Getting Started with Caja

Prerequisites

Assumes basic familiarity with Java including how to manage a CLASSPATH and how to run a java app from the command line or from within an IDE like Eclipse. If you are not familiar with java, see PATH and CLASSPATH, the command line.

Caja requires

JDK 6
The subversion version manager
The Apache Ant build system.
The JUnit testing framework. Just drop junit.jar in the $ANT_HOME/lib directory you set up for Ant.

If you intend to contribute patches to Caja (and we would love you to do that, see ContributingCode for how), you need to sign a Contributor Licence Agreement (either the individual CLA or the corporate CLA, depending on your situation). Note that patches are accepted at the discretion of the development team. Membership of the development team will be offered to those who consistently make positive contributions.

Building Caja via Ant

Once you have subversion installed, create a directory for your caja branches. Here we assume you name it caja:

mkdir caja; cd caja

Next make a directory named "svn-changes". This is necessary for certain scripts to work.

mkdir svn-changes; cd svn-changes

Then make a directory for a new branch. Here we assume you name it "pristine":

mkdir pristine; cd pristine

Repeat this step in the svn-changes directory every time you check out a new branch.

Finally, follow the instructions at http://code.google.com/p/google-caja/source/checkout to checkout the Caja source.

You should see a lot of lines like:

A  google-caja
A  google-caja/docs

ad nauseam as it pulls source files from code.google.com.

Then, from the command line:

$ cd google-caja
$ ant

If Ant is properly installed, you should see the following:

Buildfile: build.xml

dirs:
    [mkdir] Created dir: ...
...

docs:
  [javadoc] Generating javadoc
...

BUILD SUCCESSFUL
Total time: 5 seconds

You can see the set of build targets by running ant -projecthelp, and those targets can follow the ant command, so ant runtests will build and run tests, and ant clean will wipe out all generated files, so you can build from scratch.

If you look at the directory structure after building, you'll see a number of ant-* directories

ant-lib - compiled class files and resources
ant-jars - all the jars you need to run the Cajoler. You can run caja by doing java -cp "$(ls ant-jars/*.jar | tr ' ' :)" com.google.caja.plugin.PluginCompilerMain .... ant-jars/pluginc.jar contains the compiled Cajoler.
ant-reports/tests/index.html - unit test status and logs
ant-reports/coverage/index.html - emma test coverage reports. See ant emma runtests.
ant-www - demo output. See ant demos
ant-docs - javadoc (and eventually jsdoc) output.

Problems running Ant

If you see the following error when running ant, try upgrading to Ant 1.7:

google-caja/build.xml:144: java.lang.NoClassDefFoundError: org/apache/tools/ant/types/ResourceCollection
        at org.apache.tools.ant.IntrospectionHelper$Creator.create(IntrospectionHelper.java:1166)
        at org.apache.tools.ant.UnknownElement.handleChild(UnknownElement.java:549)
        at org.apache.tools.ant.UnknownElement.handleChildren(UnknownElement.java:326)
...

If you get a complaint about Java running out of heap memory, set ANT_OPTS to the additional option to be passed to your Java for increasing heap memory. For example, if you use bash and Sun's JDK, placing the following in your ~/.bashrc file increase your maximum Java heap size to 100MB:

export ANT_OPTS=-Xmx100M

Building Caja via Eclipse

Caja includes a script for creating a Eclipse project file. Eclipse relies on some files created by the ant build. Once you have checked out the caja source, run ant as follows:

$ cd google-caja
$ ant

Check that your ANT_HOME environment variable is set correctly. If it isn't, set it. For example, if you use bash and your ant is installed at /usr/share/ant, place the following in your ~/.bashrc file:

export ANT_HOME=/usr/share/ant

Now create an eclipse project:

$ ./tools/myvn eclipse

From inside eclipse, import the project from the File -> Import -> Existing Project into Workspace option. Select the Caja checkout directory as the root directory and import the project.

Run the JUnit tests to ensure everything was checked out correctly.

Code Layout

google-caja
|
+--docs : documentation files.
|
+--src : source code (java and javascript)
|  |
|  +--com
|     |
|     +--google
|        |
|        +--caja
|           |
|           +--lexer : Tokenization and escaping
|           |
|           +--parser : Parsers and tree implementations
|           |  |
|           |  +--ParseTreeNode.java : Main parse tree interface
|           |  |
|           |  +--quasiliteral : Syntactic sugar for parse tree xforms
|           |
|           +--opensocial : Dealing with Gadget specs
|           |
|           +--plugin : Transformations
|           |  |
|           |  +--PluginCompilerMain.java : main class
|           |  |
|           |  +--stages : Parse tree transforms
|           |
|           +--reporting : Error and warning messaging.
|
+--tests : test files and resources

Other Resources

http://code.google.com/p/google-caja/ : The source code repository, bug tracker, and wiki.

http://groups.google.com/group/google-caja-discuss/ : The public discussion list.

Cajadores.com periodically generates test and coverage status reports, and includes a snapshot of generated code, including the Testbed applet and other demos that can be linked to.