<?xml version="1.0" encoding="UTF-8"?>
<!--
   ====================================================================
   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.
   ====================================================================
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "document-v20.dtd">

<document>
    <header>
        <title>Apache POI - How To Build</title>
        <authors>
            <person email="user@poi.apache.org" name="Glen Stampoultzis" id="GS"/>
            <person email="tetsuya@apache.org" name="Tetsuya Kitahata" id="TK"/>
            <person email="dfisher@jmlafferty.com" name="David Fisher" id="DF"/>
        </authors>
    </header>
    <body>
        <section>
          <title>JDK Version</title>
          <p>
            POI 4.0 and later require JDK version 1.8 or later.
          </p>
          <p>
            POI 3.11 and later 3.x versions require JDK version 1.6 or later.
          </p>
          <p>
            POI 3.5 to 3.10 required the JDK version 1.5 or later.
            Versions prior to 3.5 required JDK 1.4+.
          </p>
        </section>
        <section>
            <title>Install Apache Ant</title>
            <p>
                The POI build system requires <a href="https://ant.apache.org/">Apache Ant</a>
                version 1.8 - 1.9.x for Java 1.6 and higher. Newer versions (1.10.x) require Java 8 or higher.
            </p>
            <p>
                Specifically the build has been tested to work with Ant version
                1.9.9 and 1.10.1.
            </p>
            <p>
                Remember to set the ANT_HOME environment variable and add 
                ANT_HOME/bin to your shell's PATH.
            </p>
        </section>
        <section>
            <title>Install Apache Forrest</title>
            <p>
                The POI build system requires 
                <a href="https://forrest.apache.org/">Apache Forrest</a> 
                to build the documentation.
            </p>
            <p>
                Specifically the build has been tested to work with Forrest 0.90.
            </p>
	    <p>
	        Remember to set the FORREST_HOME environment variable.
            </p>
        </section>
        <section>
            <title>Building Targets with Ant</title>
            <p>
                The main targets of interest to our users are:
            </p>
            <table>
                <tr>
                    <th>Ant Target</th>
                    <th>Description</th>
                </tr>
                <tr>
                    <td>clean</td>
                    <td>Erase all build work products (ie. everything in the
                        build directory</td>
                </tr>
                <tr>
                    <td>compile</td>
                    <td>Compiles all files from main, ooxml and scratchpad</td>
                </tr>
                <tr>
                    <td>test</td>
                    <td>Run all unit tests from main, ooxml and scratchpad</td>
                </tr>
                <tr>
                    <td>jar</td>
                    <td>Produce jar files</td>
                </tr>
                <tr>
                    <td>assemble</td>
                    <td>Produce .zip and tar.gz distribution packages</td>
                </tr>
                <tr>
                    <td>docs</td>
                    <td>Generate all documentation (Requires Apache Forrest)</td>
                </tr>
                <tr>
                    <td>jenkins</td>
                    <td>Runs the tests which Jenkins, our Continuous Integration system, does. This includes the unit tests and various code quality checks.</td>
                </tr>
            </table>
        </section>
        <section>
            <title>Working with Eclipse</title>
            <p>
            	Apache POI includes a pre-defined Eclipse project file which can be 
            	used to quickly get set up in the Eclipse IDE. 
            </p>
            <p>
            	In order to get started, first build Apache POI using Ant as described above
            	to get all required 3rd party libraries downloaded. 
            </p>
            <p>
            	Then import the project in Eclipse via File->Import->Existing Projects into Workspace.
            </p>
            <p>
            	Note: when executing junit tests from within Eclipse, you might need to set the system 
            	property "POI.testdata.path" to the actual location of the 'test-data' directory to make 
            	the test framework find the required test-files. A simple value of 'test-data' usually works. 
            </p>
        </section>
        <section>
            <title>Working with IntelliJ Idea</title>
            <p>
                We currently do not offer project files for IntelliJ and unfortunately it
                cannot import the project from the Ant build files.
            </p>
            <p>
                In order to get started, first build Apache POI using Ant as described above
                to get all required 3rd party libraries downloaded.
            </p>
            <p>
                Then import the main folder into a new project and then define all the source folders under src
                accordingly. Also add all libraries from the lib, compile-lib and ooxml-lib folders.
            </p>
            <p>
                Note: when executing junit tests from within IntelliJ, you might need to set the system
                property "POI.testdata.path" to the actual location of the 'test-data' directory to make
                the test framework find the required test-files. A simple value of 'test-data' usually works.
            </p>
        </section>
        <section>
            <title>Using Maven</title>
            <p>Building Apache POI using Maven is not currently officially
             supported, and we strongly suggest continuing to use the official
             Ant build.</p>
            <p>However, including Apache POI within your own Maven project
             is fully supported, and widely used. Please see the
             <a href="site:components">Components Page</a>
             for details of the Maven artifacts available.</p>
        </section>
        <section>
            <title>Setting environment variables</title>
            <p>Linux:
              <a href="https://help.ubuntu.com/community/EnvironmentVariables">help.ubuntu.com</a>,
              <a href="http://unix.stackexchange.com/questions/117467/how-to-permanently-set-environmental-variables">unix.stackexchange.com</a>
            </p>
            <p>Windows:
              <a href="https://en.wikipedia.org/wiki/Environment_variable#DOS.2C_OS.2F2_and_Windows">en.wikipedia.org</a>
            </p>
        </section>
    </body>
  <footer>
    <legal>
      Copyright (c) @year@ The Apache Software Foundation. All rights reserved.
      <br />
      Apache POI, POI, Apache, the Apache feather logo, and the Apache 
      POI project logo are trademarks of The Apache Software Foundation.
    </legal>
  </footer>
</document>


