# Getting Started

The following steps give you an introduction how to configure, build and work with the Apache Etch sources. At the the moment we support Windows and Linux builds. 

1. [Preconditions](#Preconditions)
2. [Get the source code](#getSourceCode)
3. [Build sources](#buildSources)

After your build of Apache Etch was successful, you will be able to run the examples in the example directory. 

### Preconditions {#Preconditions}
The tools and libraries mentioned in the following listing must be available on your development machine in order to be able to work with Etch. 
It is a good practice to set up a folder containing the external dependencies of all the bindings you would like to build. This folder will be called <strong>ETCH_EXTERNAL_DEPENDS</strong> later on. 

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

* Win32: [https://builds.apache.org/job/etch-trunk-windows-x86/ws/externals/](https://builds.apache.org/job/etch-trunk-windows-x86/ws/externals/)
* Linux: [https://builds.apache.org/job/etch-trunk-linux-x86/ws/externals/](https://builds.apache.org/job/etch-trunk-linux-x86/ws/externals/)

<table style="width:99%;">
  <thead>
    <tr>
	<th>Component</th>
	<th>Prerequisites and dependencies</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="vertical-align:middle; width:200px">Etch compiler/code generator <br/><b>[mandatory for each binding]</b></td>
      <td>  
        <ul>
	  <li>Java JDK version 1.5_011 or higher</li>
  	  <li>Apache Ant 1.8.2 or higher</li>
	  <li>JavaCC 5.0</li>
	  <li>JUnit 4.3.1</li>
	  <li> Velocity 1.7</li>
	</ul>
      </td>
    </tr>
    <tr>
      <td>
	Binding Java
      </td>
      <td>
        no additional dependencies
      </td>
    </tr>
    <tr>
      <td>Binding C#</td>
      <td>
        <ul>
	  <li>Apache Ant DotNet 1.1</li>
	  <li>.NET Framework 4.0 (Visual Studio 2008 or higher)</li>
	  <li>(Mono 1.9 support is experimental)</li>
	  <li>NUnit 2.5.10.11092</li>
	</ul>
      </td>
    </tr>
    <tr>
      <td>Binding C</td>
      <td>
	<ul>
	  <li>Apache APR 1.4.5</li>
	  <li>Apache APR Util 1.3.12</li>
	  <li>Apache APR iconv 1.2.1</li>
	  <li>Cunit 2.1</li>
	  <li>Apache Ant CMake 1.0 (cmakeant.jar)</li>
	</ul>
      </td>
    </tr>
  </tbody>
</table>


After the download of all the dependencies mentioned above you should now have the following structure (if you want to compile and build for all language bindings):

    :::text
    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-dep-1.7.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]

### Get the source code {#getSourceCode}
You can checkout the source tree by using the following SVN command:

    :::text
    svn co http://svn.apache.org/repos/asf/etch/trunk/

If you prefer to use Git you can use git-svn:

    :::text
    git svn clone http://svn.apache.org/repos/asf/etch/trunk/

### Build sources {#buildSources}
As soon as all the required dependencies and the source is available on your machine, you are able to build Etch.

*Note for Linux 64-bit users:* <br/>
In order to perform the 32-bit build of the C and C++ bindings make sure that you have installed the 32-bit support libraries. On Ubuntu you need the following packages:

    :::text
    ia32-libs
    libc6.dev.i386
    g++-multilib
    gcc-multilib


##### Ant Build

1. Open the `scripts/antSetup.bat` (Windows) or `scripts/antSetup.sh` (Linux) with your favourite text editor
   
2. Check if every environment variable set by the script points to the right location

3. Run the antSetup script to prepare your build environment

    Win32:

        :::text
        `scripts/antSetup.bat`

    Linux:

        :::text
        `source scripts/antSetup.sh`

4. Check the correctness of the paths to the jar archives Etch depends on in the `build.dependencies` file inside the root folder.

5. Start build by executeing `ant debug` at the shell prompt