Apache Software Foundation > Apache POI
 

Apache POI - How To Build

JDK Version

POI 4.0 and later require JDK version 1.8 or later.

POI 3.11 and later 3.x versions require JDK version 1.6 or later.

POI 3.5 to 3.10 required the JDK version 1.5 or later. Versions prior to 3.5 required JDK 1.4+.

Install Apache Forrest

The POI build system requires Apache Forrest to build the documentation.

Specifically, the build has been tested to work with Forrest 0.9. When building with Forrest, it is recommended to use Java 8.

Remember to set the FORREST_HOME environment variable.

Building Targets with Gradle

The main Apache POI build was traditionally done with Apache Ant. In 2021, we moved to using Gradle. After checking out the POI code, you will find gradlew and gradlew.bat. These command files are used for running Gradle on Linux/Mac and Windows respectively. Gradlew checks if you the right version of Gradle installed and will install it if you don't.

The main targets of interest to our users are:

Gradle Target Description
clean Erase all build work products (ie. everything in the build directory
test Run all unit tests from main, ooxml and scratchpad
jar Produce jar files
jenkins Runs the tests which Jenkins, our Continuous Integration system, does. This includes the unit tests and various code quality checks. Also, packages up the jars and build distributions.

To run the tests from just one test class, use a command like:

./gradlew poi-ooxml:test --tests *TestXSSFBugs

gradlew poi-ooxml:test --tests *TestXSSFBugs

The example command runs tests in the poi-ooxml sub-project that match the name '*TestXSSFBugs'. The '*' wildcard is useful to avoid typing the full Java package name.

Working with Eclipse

Apache POI no longer includes a pre-defined Eclipse project file. When importing the POI project, your IDE should recognise that there is Gradle support and offer to do the build using that.

First make sure that Java is set up properly and that you can execute the 'javac' executable in your shell.

Next, open Eclipse and create either a local SVN repository, or a copy of the Git repository, and import the project into Eclipse.

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.

Working with IntelliJ Idea

Import the Gradle project into your IDE. Execute a build to get all the dependencies and generated code in place.

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.

Setting environment variables

by Glen Stampoultzis, Tetsuya Kitahata, David Fisher