/*
 * Licensed to the Apache Software Foundation (ASF) under one   *
 * or more contributor license agreements.  See the NOTICE file *
 * distributed with this work for additional information        *
 * regarding copyright ownership.  The ASF licenses this file   *
 * to you under the Apache License, Version 2.0 (the            *
 * "License"); you may not use this file except in compliance   *
 * with the License.  You may obtain a copy of the License at   *
 *                                                              *
 *   http://www.apache.org/licenses/LICENSE-2.0                 *
 *                                                              *
 * Unless required by applicable law or agreed to in writing,   *
 * software distributed under the License is distributed on an  *
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
 * KIND, either express or implied.  See the License for the    *
 * specific language governing permissions and limitations      *
 * under the License.                                           *
*/
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
      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
   

  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.7+
 * JavaCC 4.0
 * Junit 4.3.1
 * Velocity 1.5

To compile the C# bindings and examples:

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

 * NSIS 2.23

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

The primary development environments for the Etch committers are Win32 and
*nix (Mac OS X). As such we have attempted to make the build process platform
neutral. In addition, Etch builds are done daily on our internal Bamboo server
here at Cisco on the win32 platform. This means that we tend to have a bias
towards a working Win32 build. To further complicate matters, we have much
development-environment divergence in our committer base, some of us being very
shell-centric (dixson) while others of us being firmly rooted in Eclipse (sccomer).
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.7 or later). 

2. Put /path/to/apache-ant-1.7/bin in your PATH.

3. If you have Mono, make certain MONO_HOME is set correctly. If you have .NET
   framework, make certain msbuild.exe is in your PATH.

4. If building C#, make certain NUNIT_HOME is set correctly.

5. If building on Win32 and you want to build the NSIS installers, set
   NSIS_HOME to /path/to/nsis/2.23.

6. [IMPORTANT] Update 'build.dependencies' with the correct paths to the jar's
   this project depends upon:

  * javacc.home=/path/to/javacc-4.0      
        ('${javacc.home}/bin/lib/javacc.jar' should exist)
        
  * junit.lib=/path/to/junit-4.3.1
        ('${junit.lib}/junit-4.3.1.jar' should exist)
        
  * velocity.lib=/path/to/velocity-1.5            
        ('${velocity.lib}/velocity-dep-1.5.jar' should exist)

  --OPTIONAL--        
  * ant-dotnet.lib=/path/to/apache-ant-dotnet-1.0 

(dixson) This is a hack until I get autoconf working. Just not there yet :-(


7. At the shell prompt type:

 > ant release

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 4.0
 ant 1.7.0
 junit 4.3.1
 velocity 1.5

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.5/
 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.5\velocity-dep-1.5.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-dep-1.5.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.

 Select Run / External Tools / Compile Router 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.

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, perf or chat.