FOPIDESetupGuide - Xmlgraphics-fop Wiki

IDE Setup Guide

This page tells you how to setup FOP for development in an IDE.

Eclipse (3.x)

For the following to work you'll need the Subclipse plug-in which you can get through the following update site: http://subclipse.tigris.org/update

Importing an existing FOP checkout into Eclipse

Simply import the root directory of the FOP checkout (Choose "Existing Project into Workspace")
After that choose "Share Project..." from the "Team" menu item in the context menu of the project.
Choose "SVN" as repository type.
Eclipse will recognize that you've checked out FOP using SVN and will now simply let you verify the connection.
That's it.

Checking out inside Eclipse

Setup SVN Repository location

Open the "SVN Repository Exploring" Perspective
Create a new "Repository Location" (via context menu)

Anonymous access

Url: http://svn.apache.org/repos/asf/xmlgraphics/fop
User: leavy empty
Password: leave empty

new-svn-repo

Committer access

Url: https://svn.apache.org/repos/asf/xmlgraphics/fop
User: <uid>
Password: <pwd>

Work on the Trunk

Download the project files

Expand the newly created repository location and right-click on "trunk" and select "Check Out As...".

svn-checkout-as

Make sure you DON'T choose "Check out as Project" or you'll not get the whole Java-related support!
Choose "Java Project" on the next screen and run through the rest of the wizard.
This will finally download the sources.

Setup source directories and libraries

In order to enjoy the automatic compilation feature of Eclipse, you have to define source directories and add libraries in the project preferences ("source" and "libraries" tabs). Because FOP uses Java code generated from XML in the src/codegen directory, you'll still have to run the "codegen" target in the buildfile. The generated code is written to the build/gensrc directory. See notes below on adding source directories before you do this. Here is how you do it:

Open the Java Build Path of the Project

in the "source tab", remove all the existings "source folders on build path"
set the "default output folder":
- click on "Browse..." and "create" the folder "build" (under your project root)
- "create" the folder "eclipse" under "build"
- when you come back to the "Java Build Path" dialog, you should have something like "/<your project name>/build/eclipse" in the "default output folder"

Add the following directories as source directories:

build/gensrc
- Add this before running the codegen target outside Eclipse. When adding, you will have the opportunity to create a new directory. Create this directory. After running codegen, Refresh the directory in the Navigator view.
src/java
src/java-1.3 or src/java-1.4 depending on your JRE release
test/java (available soon)
optional: examples/mathml/src
optional: examples/plan/src
optional: examples/embedding/java

Libraries:

Add all libraries in the "lib" directory in the "libraries" tab of the project's Java Build Path section.
Download and add JIMI, JAI, JEuclid and JUnit jars as external libraries or, alternatively, set an exclude path for the files which depend on Jimi, JAI, JEuclid and, for JDK 1.3, on JCE (TODO: add list).
If you install JAI into a JRE, e.g. 1.4.1, and then set that JRE as the default for Eclipse, you don't have to add JAI as an external library.
JCE and crypto service providers have to be installed in the JRE in order to work anyway, so you don't have to add them either.

Note: If you haven't followed the above instructions, it might happen that eclipe will not set the project as a Java Project. You might want to try this hack:

Shut down eclipse, and open the ".properties" file of the project in an editor.
Update the followings tags. That's how eclipse understands that it is a java project.

        <buildSpec>
                <buildCommand>
                        <name>org.eclipse.jdt.core.javabuilder</name>
                        <arguments>
                        </arguments>
                </buildCommand>
        </buildSpec>
        <natures>
                <nature>org.eclipse.jdt.core.javanature</nature>
        </natures>

When you restart eclipse, your project should be checked with a "J" (Java project)

Work on the Maintenance Branch

Due to the current directory layout, setting FOP in Eclipse is a headache, you'll have to use exclude paths because src/org and src/java-1.4/org overlap.

Download the project files

Open the "SVN Repository Exploring" Perspective
Create the repository location for FOP as shown above
Expand the new repository location: You see trunk, branches and tags
Expand "branches" and select "fop-0_20_2-maintain" for the "Check out as..." context menu entry, similar to the instructions for trunk shown above.
The rest is the same as above.

Setup source directories and libraries

See the setup in the "Work on the Trunk" section, however, you have to carefully set exclusion masks for

one of the src/java-1.3 or src/java-1.4 directory
all the directories in build/gensrc which contain copy-filtered source files which are already in the main source tree

You have to run an external Ant with both the targets of gensrc and prepare-compile, and clean out some of the superfluous generated files which Eclipse marks as conflicting.

General setup

Preferences

The following setup is required for smooth work on the project, both for committers and users providing patches. Choose Windows->Preferences.

Java -> Code Generation, "Code and Comments" tab
- Code -> New Java Files: Press Edit and Copy&Paste from an source file the comment with the license. Look for dollar signs in the RCS "$Id: $" tag: replace them with two dollar signs, also kill the content behind the "Id:".
- Comments -> Types: Press Edit, kill the old content and add a line with "$(todo) add Javadoc". Add an appropriate "@autor" tag if you wish. Further ideas about customizations are welcome.
Java -> Code Generation, "Names" tab: no prefixes or suffixes.
Java -> Code Formatter, "Style" tab: you must uncheck the third option ("Insert tabs for indentation, not spaces"), we dont accept tabs in our Java source files. Also, the number of spaces representing an indentation level is 4. Uncheck the "Compact assignment" and "insert space after a cast" options too.
Java -> Code Formatter, "New Lines" tab: uncheck the first, second and forth options ("Insert a blank line before an opening brace": we don't want this, "Insert new lines in control statements": we don't want this either, "Insert new line between 'else if': not our style). It is recommended to leave the third option ("Clear all blank lines") unchecked.
Java -> Appearance -> Members sort order: this is only relevant if you intent to use the "Sort Members" functionality. We use the default order (Types, Static initializers, Static Fields, Static Methods, Initializers, Fields, Constructors, Methods)
Java -> Organize Imports: We use the default order (java, javax, org, com). Inquiries for additions are welcome.
Java -> Task tags: we use a TODO with normal priority (default), also a @todo with normal priority and occasionally a FIXME with a high priority (you have to add both if you want to see them in the task list).

Ant support

Seems to be working now.

Checkstyle support

Download the Eclipse Checkstyle plug-in .

After installing the plug-in go to the Preferences dialog and to the Checkstyle section. Import the checkstyle config file from FOP's root directory. Adjust the path of the checkstyle.header.file entry.

Tip: Set a file filter (".*/gensrc/.*") in the Checkstyle section of the project's Properties page. This avoids a lot of unavoidable style violations due to code generation.

PMD support

PMD is similar to CheckStyle. It allows more powerful rules but configuring them is more difficult. It also comes with a nifty copy'n'paste detector.

Get the PMD plugin from http://pmd.sf.net
Unpack the binary into your Eclipse plugin directory, as usual.
Select your preferred rules in the preference window.
Enable PMD checking for the project in the project properties.

JBuilder

Details of JBuilder setup to come.

Checkstyle setup (for JBuilder)

Download jbCheckstyle, an Open Tool for JBuilder that provides integration of JBuilder and Checkstyle, from: http://jbcheckstyle.sourceforge.net/jbcheckstyle. After unzipping the contents, the README.html file contains complete instructions for installation and configuration.

Be sure to adjust the path of the checkstyle.header.file entry, and use forward slashes for directory delimiters (even if you are running on a Windows platform). Failure to correctly configure this will cause jbCheckstyle to not provide any output.

NetBeans (4.1)

Work on the Trunk

NetBeans 4.1 or later is recommended as this is the first NetBeans version supporting multiple source root directories. This allows to work with the unchanged FOP directory layout.

For the following to work you'll need the Subversion profile installed in NetBeans which you can get through the following update site: http://vcsgeneric.netbeans.org/profiles/index.html.

Download the project files

Checkout the trunk from Subversion into an empty directory from now on referred to as $FOP_HOME. Download / install any additional libraries like JAI and/or Jimi. The simplest way is to put them into the $FOP_HOME/lib directory. One can also create a build-local.properties file in $FOP_HOME, define the property <property name="optional.lib.dir" value="<path to optional lib directory>"/> in that file, and put the non FOP supplied libraries in that directory. Now do a command line build of FOP using ant.

Setup the project in NetBeans

To import this into NetBeans following these steps:

Create a new Project (File / New Project) of type 'Java Project with Existing Sources'.

netbeans_step_1

Give it a suitable Project Name, e.g. 'Fop' and Project Folder e.g. '$FOP_HOME/netbeans_projects/fop'.

netbeans_step_2

Add the following directories as the directories for 'Existing Sources':
- $FOP_HOME/src/java
- $FOP_HOME/src/java-1.4
- $FOP_HOME/build/gensrc

netbeans_step_3

Right click the project in the Projects window and open the project properties. Add all the jar files in $FOP_HOME/lib as well as those added above, e.g. JAI, Jimi, ...

netbeans_step_4

Connect the project to Subversion

Open the Versioning Manager (Versioning / Versioning Manager) and click on Add.

Enter $FOP_HOME as the 'Working Directory'
Enter ' http://svn.apache.org/repos/asf/xmlgraphics/fop/trunk' as 'Repository URL'
Leave everything else blank (for non committers) and click 'Finish'

netbeans_step_5

In the Project window right click the nodes for '$FOP_HOME/src/java' and $FOP_HOME/src/java-1.4'
For each node select 'SVN Local' and then 'Refresh recursively'

Checkstyle support

Download and install the NetBeans 4.0 Checkstyle plug-in. Under Tools/Options/Building/Checkstyle Settings set the Checkstyle Properties file location to the checkstyle.xml that comes with the SVN checkout of FOP.