Build Instructions for Apache Etch
==================================

Contents
--------
  Source tree
  Dependencies
  Setup Development Environment
  Building from ANT
  Building from Eclipse
  

Source tree
-----------

This is the source tree for Etch. It is organized as follows:

   build.xml         - top-level ant build script
   build.dependecies - locations for jars this compile depends on
   etch.properties   - static build properties 
   
   compiler/      - core compiler
   build-support/ - common ant scripts shared by all modules
   plugins/       - extensions that embed the compiler, e.g. ant, maven, etc.
   scripts/       - common scripts for eclipse
   util/          - shared java classes
   tests/         - functional tests
   examples/      - Etch application examples
      helloworld/ - classic example
      chat/       - simple IM application
      distmap/    - example implementation of a distributed map in etch
      perf/       - etch client/server performance test
      example/    - minimal example
   installers/    - project for NSIS installer and tar.gz, .zip archives
       
   binding-xml    - xml binding
   binding-java   - java-language binding
   binding-csharp - C#-language binding
   binding-c      - C-language binding
   binding-go     - Google Go language binding   

  About the Structure of Etch bindings
  ------------------------------------

Each binding is factored into its own structure into the build tree. The intent
is to provide an easy pattern for potential binding authors to emulate.
Essentially each binding has two components:

   - compiler/
   - runtime/
   
The 'compiler' is always implemented in Java and is coded to implement a
backend interface for the target of choice.

The 'runtime' is coded in the target language. The most useful language
bindings implement identical functionality as the Java and C# bindings.
Non-languages bindings (like binding-xml) may not have a runtime component
at all.

Dependencies
------------

To build the compiler core and the Java and XML bindings and Java-based examples,
you need the following:

 * Java JDK 1.5_011 or later
 * Apache Ant 1.8.2
 * JavaCC 5.0
 * Junit 4.3.1
 * Velocity 1.7

To compile the C# bindings and examples:

 * Apache Ant DotNet 1.0
 * .NET Framework 4.0 (Visual Studio 2005 and upper)
 ** (Mono 1.9 support is experimental)
 * NUnit 2.5.9.10348
 
To compile NSIS installers:

 * NSIS 2.46

To compile the C binding:

 * Apache APR 1.4.5
 * Apache APR Util 1.3.12
 * Apache APR iconv
 * Cunit 2.1
 * Apache Ant CMake 1.0 (cmakeant.jar)

Setting up your ETCH_EXTERNAL_DEPENDS folder:
---------------------------------------------

Set up a folder containing all external dependencies of the Etch build (all languages).
This folder will be called ETCH_EXTERNAL_DEPENDS later on.

To ease the download of the APR dependencies, we have created scripts/apr-install.sh
and scripts/apr-install.bat for linux and windows. Those scripts provide you a complete
APR installation folder for the directory structure below. See also binding-c/runtime/c/README.txt
for more details on this.

You can use the workspace contents of our continous integration server as a reference 
for you machine, 

- e.g. for Win32:
  https://builds.apache.org/job/etch-trunk-windows-x86/ws/externals/
- e.g. for Linux x86:
  https://builds.apache.org/job/etch-trunk-linux-x86/ws/externals/

You should have the following structure, if you want to compile and build for all language bindings
(newer version could, but do not have to, work):

  ETCH_EXTERNAL_DEPENDS/
    javacc/
        5.0/
          javacc.jar
    junit /
        4.3.1/
          junit-4.3.1.jar
    nunit/
        2.5.10.11092/
          [contents of nunit 2.5.10.11092 release tgz/zip]               
    velocity/
        1.7/
          velocity-1.7-dep.jar
    apache-ant/
        1.8.2/
          [contents of apache ant 1.8.2 release tgz/zip]
    apache-ant-cmake/
        1.0/
          cmakeant.jar
    apache-ant-dotnet/
        1.1/
          [contents of apache ant dotnet 1.1 release tgz/zip]
    apr/
        1.4.5/
          [apr binary installation, see above]
    cmake/
        2.8.6/
          [contents of cmake standalone 2.8.6 release tgz/zip]    
    cunit/
        2.1/
          [built cunit version, 
           on linux: you can skip this and use system libraries on your machine, e.g. apt-get install libcunit1 libcunit1-dev
           on win32: see binding-c/runtime/c/README.txt for instructions on building cunit on Win32]
    nsis/ (WINDOWS ONLY)
        2.46/
          [skip if you want no installer built, else: contents of nsis 2.46 standalone zip/tgz]

Setup development environment
-----------------------------

The primary development environments for the Etch committers are Win32 and
*nix (Linux, Mac OS X). As such we have attempted to make the build process platform
neutral. 

The build is running continously for Windows and Linux on our build server at Apache:
https://builds.apache.org/view/A-F/view/Etch/

To further complicate matters, we have much development-environment divergence in 
our committer base, some of us being very shell-centric while others of us 
being firmly rooted in Eclipse. So the compromise has been to attempt to structure 
the build such it can be friendly and productive to both groups and keep the 
sectarian violence to a minimum. :-)

1. Install JDK. Make certain that you set your JAVA_HOME environment variable
   to point to the correct location.
   
Building from ANT
-----------------

1. Install Apache ANT (version 1.8.2 or later). 

2. on Win32: 
      set ETCH_EXTERNAL_DEPENDS=<YOUR_EXTERNAL_DEPENDS_FOLDER>
      Execute scripts/antSetup.bat 
   on Linux: 
      export ETCH_EXTERNAL_DEPENDS=<YOUR_EXTERNAL_DEPENDS_FOLDER>

3. Check 'build.dependencies' with the correct paths to the jar's this project depends upon.

4. At the shell prompt type:

 > ant Debug

This will build all compilers and all the bindings for which you have setup
dependencies. It will also build and run all unit/functional tests and build
all the examples in examples/.

Once complete, the dist tree can be found in 'target/Installers/dist'. Copy
this directory manually to the desired install location.

Building from Eclipse
---------------------

After you checkout the project in eclipse, you will likely be told that there are
build path problems. There are three dependent projects you need to get going with
etch for eclipse, and one plugin:

 javacc 5.0
 ant 1.8.2
 junit 4.3.1
 velocity 1.7

JavaCC is an eclipse plugin, get it from here:

 http://eclipse-javacc.sourceforge.net/

On that page are directions to install the plugin from within eclipse. The other two
you download:

 http://sourceforge.net/projects/junit/
 http://velocity.apache.org/engine/releases/velocity-1.7/
 http://archive.apache.org/dist/ant/binaries/

NOTE: junit-4.3.1 is a hard dependency. Later versions of ant, JavaCC and Velocity may
work, but later versions of JUnit will not (true as of etch-1.0.2).

Once downloaded, you will need to create an environment variable (for example):

 ETCH_DEPENDENT_JARS=C:\workspace-etch\tools\velocity\1.7\velocity-1.7-dep.jar

These are the extra jar files required to actually run the compiler. You will need
to restart eclipse if it is running. Once eclipse is started, you will need to 
configure the Etch project:

 Right click on the etch project, and select Build Path / Configure Build Path
 
 Select the Libraries tab on the right.
 
 If ETCH_DEPENDENT_JARS is here, delete it.

 Select Add Library... on the right.

 Select User Library and click Next.

 Select User Libraries...

 Select New...

 Enter the name ETCH_DEPENDENT_JARS and click Ok.

 With ETCH_DEPENDENT_JARS selected, click Add JARs...

 Navigate to junit-4.3.1.jar and select it.

 With ETCH_DEPENDENT_JARS selected, click Add JARs... again...

 Navigate to velocity-1.7-dep.jar and select it.

 Navigate to ant.jar and select it.

 Click Ok.

 Click Finish.

 Click Ok.

Eclipse should rebuild the project. There may still be errors, that's ok:

 Open Window / Preferences / Java / Compiler / Building.

 Expand Build path problems.

 Set Incomplete build path to be a warning.
 
 Set Circular dependencies to be an error.

 Set Incompatible required binaries to warning.

 Click Ok.

Make sure JavaCC compiled EtchGrammar.jj. There should be a JavaCC console
view open. If not, open it (Window / Show View / Other... / JavaCC console /
JavaCC console).

If JavaCC console is empty, Select Project / Clean... and clean all projects.
A few JavaCC messages should appear. It is ok if JavaCC warns about creating
a directory.

Now that the compiler is built, you will still have errors for etch build
products which are missing. you will need to recompile all the etch files.
You can do this by:

 Select the etch project.

 Select Run / External Tools / Compile Java Etch Files.

(You may want to configure the external tools first. Select Run / External
Tools / Organize Favorites... Click Add... Select All. Ok. Ok.)

You should see a nice output in the Console reporting successful compilation
of a bunch of etch files. Eclipse should then rebuilt the project.

(alternative: do ant debug in examples directory)

Finally, you can check things out by running the unit tests.

 Right click on the etch project, select Run as... / Junit test.

You'll get some output on the console window, including scary looking stack
traces. That's ok. JUnit runner should tell you that 1197 tests passed, 22
ignored, with 0 errors and 0 failures. This takes 66 seconds for me (sccomer).

You're done, start exploring. Check out examples: helloworld, perf or chat.