Bug 63381 - Suggested change to "How to build" instructions
Summary: Suggested change to "How to build" instructions
Status: NEW
Alias: None
Product: POI
Classification: Unclassified
Component: SS Common (show other bugs)
Version: 4.0.x-dev
Hardware: PC
: P2 enhancement (vote)
Target Milestone: ---
Assignee: POI Developers List
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2019-04-24 03:22 UTC by David Gauntt
Modified: 2019-05-05 21:11 UTC (History)
0 users



Attachments
Suggested text for the "Working with Eclipse" section of "How to build" page (1.60 KB, text/plain)
2019-05-05 21:11 UTC, David Gauntt
Details

Note You need to log in before you can comment on or make changes to this bug.
Description David Gauntt 2019-04-24 03:22:17 UTC
After downloading the POI git mirror into Eclipse, I struggled for a couple of weeks with building the project.  Now having done this successfully, I have some suggested additions to the "Working with Eclipse" section of https://poi.apache.org/devel/index.html ("Apache POI - How to Build").

The current text reads as

"Apache POI includes a pre-defined Eclipse project file which can be used to quickly get set up in the Eclipse IDE.

In order to get started, first build Apache POI using Ant as described above to get all required 3rd party libraries downloaded.

Then import the project in Eclipse via File->Import->Existing Projects into Workspace.

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."

I suggest that this be changed to the following:

"Apache POI includes a pre-defined Eclipse project file which can be used to quickly get set up in the Eclipse IDE.

First make sure that the location of javac.exe is in your shell's path.

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

Right-click on "build.xml", and select "Run As / Ant Build...".  The "Edit Configuration" dialog should appear.  In the "Targets" tab, select the "Compile" target and click on "Run".

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."

This text could be refined by more detailed instructions on creating a SVN or Git repository.
Comment 1 David Gauntt 2019-05-05 21:11:48 UTC
Created attachment 36570 [details]
Suggested text for the "Working with Eclipse" section of "How to build" page

After spending a few (!) weeks getting my first successful build of POI, I think that I can make suggestions useful for those like me with experience with Eclipse but not experience with Ant; these suggestions are in the attached file.

The Ugly Details

The ultimate reason for my struggles is that when I tried to run Ant from within Eclipse instead of the command line, any Java code run by Ant would run with a working directory of "C:/Windows/System32" instead of the directory containing build.xml. This strikes me as an OS-specific Eclipse bug.  It happened running Eclipse 2019-03 in Windows 10, but not Eclipse 2019-03 in Mac OS X 11.6.

In Windows 10, when I ran the "assemble" target, its dependency "test-ooxml" would fail while running "TestPOIXMLDocument"

I was able to partially compensate for this changing the value of tempdir from a relative to an absolute path by replacing
    <property name="tempdir" value="build/tmp"/>
with
    <property name="tempdir" value="<absolute path of folder containing build.xml>/build/tmp"/>

With this change "TestPOIXMLDocument" would succeed, but the later test "AddImageBenchmark" would fail. It may be possible to solve this by changing more path parameters in build.xml from relative to absolute, but for the time being it seems to me that the simplest workaround is to recommend running Ant from the command prompt.