<?xml version="1.0" encoding="UTF-8"?>
<chapter id="building">
  <title>Building</title>

  <section id="prerequisites">
    <title>Prerequisites</title>
    
    <section id="jdk">
      <title>Java Development Kit (JDK)</title>
      <para>You must have the following JDK installed in order to build the project:</para>

      <itemizedlist spacing="compact">
         <listitem>
            <para>Sun JDK 1.7.x</para>
         </listitem>
         <listitem>
            <para>OpenJDK 1.7.x</para>
         </listitem>
         <listitem>
            <para>Sun JDK 1.8.x</para>
         </listitem>
         <listitem>
            <para>OpenJDK 1.8.x</para>
         </listitem>
      </itemizedlist>

      <para>Remember to ensure that "javac" and "java" are in your path (or symlinked).</para>

      <programlisting>
JAVA_HOME=/location/to/javahome
export JAVA_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
      </programlisting>

    </section>

    <section id="ant">
      <title>Apache Ant</title>
      <para>You must have Apache Ant 1.9.4+ installed on your system.</para>
      <para>Remember to ensure that "ant" are in your path (or symlinked).</para>

      <programlisting>
ANT_HOME=/location/to/anthome
export ANT_HOME

PATH=$ANT_HOME/bin:$PATH
export PATH
      </programlisting>

      <para>You may need to set the memory settings for the Apache Ant process like</para>

      <programlisting>
ANT_OPTS="$ANT_OPTS -Xms128m -Xmx512m -XX:MaxPermSize=256m"
export ANT_OPTS
      </programlisting>
    </section>

    <section id="ivy">
      <title>Apache Ivy</title>
      <para>The IronJacamar project uses Apache Ivy for dependency management.</para>

      <para>Apache Ivy is automatically downloaded and included in the development
        environment, so no additional setup is required.</para>

    </section>

    <section id="git">
      <title>Git</title>
      <para>You must have Git installed on your system.</para>
      <para>Remember to ensure that "git" are in your path (or symlinked).</para>
    </section>
 
  </section>

  <section id="obtainingthesource">
    <title>Obtaining the source code</title>

    <section id="forking">
      <title>Forking the repository</title>
      <para>
        The IronJacamar repository is located at:
      </para>

      <programlisting>
https://github.com/ironjacamar/ironjacamar
      </programlisting>
      
      <para>
        Press the "Fork" button in order to fork the repository to your own GitHub account.
      </para>

      <para>
        Clone your repository to your machine using
      </para>

      <programlisting>
git clone git@github.com:&lt;your_account&gt;/ironjacamar.git
      </programlisting>

      <para>
        Next add the upstream repository as a remote location:
      </para>

      <programlisting>
cd ironjacamar
git remote add upstream git@github.com:ironjacamar/ironjacamar.git
      </programlisting>

    </section>

    <section id="gitbranches">
      <title>Git branches</title>
      <para>We have the following branches for the project:</para>
      <itemizedlist>
         <listitem>
            <para>master</para>
            <para>The head of development targeting the next upcoming release.</para>
         </listitem>
         <listitem>
            <para>1.0</para>
            <para>The development targeting the IronJacamar 1.0 releases.</para>
         </listitem>
         <listitem>
            <para>1.1</para>
            <para>The development targeting the IronJacamar 1.1 releases.</para>
         </listitem>
         <listitem>
            <para>1.2</para>
            <para>The development targeting the IronJacamar 1.2 releases.</para>
         </listitem>
      </itemizedlist>
    </section>

  </section>

  <section id="compiling">
    <title>Compiling the source code</title>
    <para>In order to build the IronJacamar project you execute:</para>
    <programlisting>
ant &lt;target&gt;
    </programlisting>
    <para>where target is one of</para>
    <itemizedlist>
      <listitem>
        <para>jars</para>
        <para>Builds the JAR archives in the distribution.</para>
      </listitem>
      <listitem>
        <para>test</para>
        <para>Builds the JAR archives in the distribution and runs all the test cases.</para>
      </listitem>
      <listitem>
        <para>module-test</para>
        <para>Builds the JAR archives in the distribution and runs all the test cases for the specified
        module (<code>-Dmodule=&lt;modulename&gt;</code>).</para>
      </listitem>
      <listitem>
        <para>one-test</para>
        <para>Builds the JAR archives in the distribution and runs the specified test case
        (<code>-Dmodule=&lt;modulename&gt; -Dtest=&lt;classname&gt;</code>).</para>
      </listitem>
      <listitem>
        <para>docs</para>
        <para>Builds the API documentation for the project.</para>
      </listitem>
      <listitem>
        <para>aggregated-javadocs</para>
        <para>Builds the Aggregated API documentation for the project.</para>
      </listitem>
      <listitem>
        <para>aggregated-javadocs-api-spi</para>
        <para>Builds the Aggregated API documentation for API/SPI of the project.</para>
      </listitem>
      <listitem>
        <para>sjc</para>
        <para>Builds the standalone environment using IronJacamar/SJC.</para>
      </listitem>
      <listitem>
        <para>release</para>
        <para>Builds a release of the project.</para>
      </listitem>
      <listitem>
        <para>clean</para>
        <para>Cleans the project of temporary files.</para>
      </listitem>
      <listitem>
        <para>clean-cache</para>
        <para>Cleans the Apache Ivy repository.</para>
      </listitem>
    </itemizedlist>
    <para>See the full list of targets in the main build.xml file.</para>

    <para>An example to get the IronJacamar/SJC built and running:</para>
    <programlisting>
ant clean sjc
cd target/sjc/bin
./run.sh
    </programlisting>

  </section>

  <section id="creating_a_patch">
    <title>Creating a patch</title>

    <para>
      Our user guide explains in the "I would like to implement a feature" section how to get 
      started on a writing a new feature or submitting a patch to the project. 
    </para>

    <para>
      You should develop your feature on a Git branch using
    </para>

    <programlisting>
git checkout -b &lt;feature_name&gt;
    </programlisting>

    <para>
      Once you are done you will need to rebase your work with the latest master
    </para>

    <programlisting>
git fetch upstream
git rebase -i upstream/master
    </programlisting>

    <para>
      You will need to resolve any conflicts of course. Note, that all pull requests
      must be rebased against upstream master in order to get merged.
    </para>

    <para>
      Then push the feature to your repository
    </para>

    <programlisting>
git push origin &lt;feature_name&gt;
    </programlisting>

    <para>
      Go to your account on GitHub.com and submit a pull request via the "Pull request" button
    </para>

    <programlisting>
https://www.github.com/&lt;your_account&gt;/ironjacamar
    </programlisting>

    <para>
      Remember to select the correct branch, fill in the subject with a short description
      of the feature, and fill in the description with the full description of the feature.
    </para>

    <para>
      If your feature / bug-fix applies to multiple branches you will need to submit
      multiple pull requests - one pull request per branch.
    </para>

  </section>

</chapter>
