Installing Cernunnos

Cernunnos is simple to install, especially for developers who are already familiar with setting up tools like Ant or Maven.

Binary Distributions

You can obtain a binary distribution of Cernunnos from the Downloads Page. Choose .zip (for Windows) or .tar.gz (for *-nix operating systems).

STEP ONE: Unpack Cernunnos

Extract all files in the distribution to a location on your file system. A root directory is included, so if you extract to C:\mystuff, the files will be in a directory like C:\mystuff\cernunnos-cmd-tool-1.0.0.

STEP TWO: Configure Cernunnos

You need to create a CRN_HOME environment variable that points to the root directory of the Cernunnos distribution, and you need to add the bin/ directory (within that root directory) to your path.

On Windows, you can edit your Environment Variables (recommended) or enter the following commands at the DOS prompt:

set CRN_HOME=[directory where Cernunnos resides]
set PATH=%PATH%;%CRN_HOME%\bin

On Ubuntu, you can edit your default environment in /etc/environment. Here I've installed Cernunnos at /usr/local/cernunnos

PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11:/usr/games:/usr/local/maven/maven-2.0.7/bin:/usr/local/cernunnos/bin"
CRN_HOME=/usr/local/cernunnos

That's all there is -- Cernunnos is ready to go!

Building the Cernunnos Manual

The first thing you will likely want to do is build the manual for Cernunnos. It contains a comprehensive reference for the built-in Task and Phrase implementations, as well as a good overview of core concepts.

On Windows

From within the CRN_HOME directory, use the following command to invoke the grammardoc.crn script.

crn grammardoc.crn

On Linux

Under Ubuntu and other Linux flavors, this is

crn.sh grammardoc.crn

Note that you'll need to chmod crn.sh to executability.

awp@unilaptop:/usr/local/cernunnos$ crn.sh grammardoc.crn
bash: /usr/local/cernunnos/bin/crn.sh: Permission denied
awp@unilaptop:/usr/local/cernunnos$ chmod ugo+x ./bin/crn.sh
awp@unilaptop:/usr/local/cernunnos$ crn.sh grammardoc.crn
... (Cernunnos will now run normally) ...

Regardless of Windows or Linux, the upshot is...

If your installation was successful, a docs/grammardoc/ directory should appear within Cernunnos. Open the index.html file to see the features supported by Cernunnos out-of-the-box.

Congratulations! You have installed Cernunnos successfully.

Building Cernunnos from Source

STEP ZERO: Prerequisites

Cernunnos is a Java application and requires JDK 5 or later.

You will also need the following software to build Cernunnos.

• Subversion -- Used to obtain Cernunnos from the Google Code repository.
• Maven -- Used to build Cernunnos from source & fetch its dependencies.

STEP ONE: Download Cernunnos Source

Use Subversion to checkout Cernunnos source code from the Google Code repository. The simplest statement (from the command prompt) that will do this is:

svn co http://cernunnos.googlecode.com/svn/trunk/

This command will create a subdirectory called "trunk" under the current directory and download the Cernunnos project within it.

STEP TWO: Compile Cernunnos

Navigate your command prompt so that you are within the directory that contains Cernunnos ("trunk" using the command above). Use Maven to build Cernunnos with the following command:

mvn package

STEP THREE: Setup Cernunnos

Maven will build Cernunnos to the cernunnos-cmd-tool/target/ directory. You will need to choose either the .zip or .tar.gz, then follow the instructions for binary distributions above.

Appendix: The grammardoc.crn Script

Let's take a closer look at the script that generates the Cernunnos Grammar Reference (used in 'Building the Grammar Reference' above). It illustrates how Cernunnos is powerful, flexible, and succinct.

<serialize-grammar>

    <file-iterator dir="media/grammardoc" excludes="**/*.xsl">
        <copy-file to-dir="docs/grammardoc"/>
    </file-iterator>

    <xslt stylesheet="media/grammardoc/table-of-contents.xsl" to-file="docs/grammardoc/table-of-contents.html"/>
    
    <node-iterator xpath="entry">
        <xslt stylesheet="media/grammardoc/entry.xsl" to-file="docs/grammardoc/entries/${valueOf(name)}.html"/>
    </node-iterator>

</serialize-grammar>

Now here's a step-by-step explaination of what this script is doing:

Step One: Create an XML Representation of the Grammar

When Cernunnos starts up, it loads a 'Grammar': a collection of the features that are available in Cernunnos and the names that invoke them. There is a 'default' or 'root' Grammar, but additional, custom Grammars may be layered over the basic Grammar as needed.

The <serialize-grammar> element invokes a Task that represents all the current Grammar information as XML and makes that data available to subtasks. All the child elements of <serialize-grammar> are subtasks of this Task implementation.

Step Two: Copy non-XSL Resources to the Destination Directory

The <file-iterator> element invokes a Task that recursively iterates over the contents of the media/grammardoc/ directory, excluding all files with the '.xsl' extension.

The <copy-file> element invokes a Task that copies each of these files to the docs/grammardoc/ directory, preserving folder information relative to media/grammardoc/.

Step Three: Transform the Table of Contents

The first <xslt> element invokes a Task that transforms the XML representation of the Grammar (created by <serialize-grammar>) against the stylesheet at media/grammardoc/table-of-contents.xsl. This task writes the result of the trasformation to docs/grammardoc/table-of-contents.html.

Step Four: Transform Each of the Grammar Entries

The <node-iterator> element invokes a Task that evaluates an XPath expression ('entry') against the XML Representation of the Grammar (created by <serialize-grammar>) to create a node list. This task then invokes all of its subtasks once for each node in the node list, making the current node available to subtasks in the process.

The second <xslt> element -- a subtask of <node-iterator> -- invokes a Task that transforms the current node against the stylesheet at media/grammardoc/entry.xsl. This task writes the output of the transformation to docs/grammardoc/entries/entry-name.html.