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 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 To compile the C binding: * Apache APR 1.3.12 * 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://hudson.apache.org/hudson/view/etch/job/etch-trunk-windows-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/ 4.0/ javacc.jar junit / 4.3.1/ junit-4.3.1.jar nunit/ 2.4.7/ [contents of nunit 2.4.7 release tgz/zip] velocity/ 1.5/ velocity-dep-1.5.jar apache-ant/ 1.7.0/ [contents of apache ant 1.7 release tgz/zip] apache-ant-cmake/ 1.0/ cmakeant.jar apache-ant-dotnet/ 1.0/ [contents of apache ant dotnet 1.0 release tgz/zip] apr/ 1.3.2/ [apr binary installation, see above] cmake/ 2.8.2/ [contents of cmake standalone 2.8.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.23/ [skip if you want no installer built, else: contents of nsis 2.23 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 contiously for Windows and Linux on our build server at Apache: https://hudson.apache.org/hudson/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.7 or later). 2. on Win32: set ETCH_EXTERNAL_DEPENDS= Execute scripts/antSetup.bat on Linux: export ETCH_EXTERNAL_DEPENDS= 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 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. (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.