blob: ab576c05e14b5a5a77ea94f86e71228318c87b77 [file] [log] [blame]
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-cpp - 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 the C binding:
* Apache APR 1.4.8
* Apache APR Util 1.5.1
* Apache APR iconv
* Cunit 2.1
* CMake >= 2.8
To compile the C++ binding:
* CMake >= 2.8.10
* Internet connection as all required dependencies are downloaded
To compile NSIS installers:
* NSIS 2.46
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.10.2/
[contents of cmake standalone 2.8.10.2 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.