Back to FOPProjectPages.

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

http://people.apache.org/~jeremias/eclipse-setup/new-svn-repo.png

Committer access

Work on the Trunk

Download the project files

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

http://people.apache.org/~jeremias/eclipse-setup/svn-checkout-as.png

  • 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/codegen/java
  • src/codegen/unicode/java
  • test/java
  • 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

Net{{`Beans 4.1 or later is recommended as this is the first Net}}`Beans 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'.

http://people.apache.org/~manuel/fop/images/netbeans_step_1.gif

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

http://people.apache.org/~manuel/fop/images/netbeans_step_2.gif

  • Add the following directories as the directories for 'Existing Sources':
    • $FOP_HOME/src/java
    • $FOP_HOME/src/codegen/java
    • $FOP_HOME/src/codegen/unicode/java
    • $FOP_HOME/build/gensrc

http://people.apache.org/~manuel/fop/images/netbeans_step_3.gif

  • 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, ...

http://people.apache.org/~manuel/fop/images/netbeans_step_4.gif

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'

http://people.apache.org/~manuel/fop/images/netbeans_step_5.gif

  • In the Project window right click the nodes for '$FOP_HOME/src/java' and the other source directories.
  • 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.

Setup for NetBeans (6.5)

Netbeans 6.5 or later has built in support for SVN (Subversion). SVN allows you to work on the latest trunk version of Apache's FOP. See http://subversion.tigris.org/ for more information on SVN.

This tutorial assumes you are familiar with Netbeans, Apache's Ant and SVN. In order to set up the FOP in Netbeans 6.5, you will need the following installed:

Check out the trunk

  • Start Netbeans 6.5
  • Click 'Versioning', 'Checkout'

http://www.aviationcontentmanagement.com/images/netbeans/checkout.png

http://www.aviationcontentmanagement.com/images/netbeans/checkout2.png

  • Click 'Next'
  • In the local Folder textbox, choose a location where you want the trunk version to be downloaded to. You will need to remember this location for when you create your Netbeans project.

http://www.aviationcontentmanagement.com/images/netbeans/checkout3.png

  • The check out process may take several minutes. After checking out the trunk, you will need to do an Ant build.

Run an Ant build

  • Do an Ant build of the trunk that you downloaded.

http://www.aviationcontentmanagement.com/images/netbeans/ant1.png

http://www.aviationcontentmanagement.com/images/netbeans/ant2.png

Creating the Project

  • In Netbeans, click 'New Project'
  • The New Project dialog box opens.
  • In the Catagories, choose 'Java" and then choose "Java Project with Existing Sources' from the projects window.
  • Click 'Next'

http://www.aviationcontentmanagement.com/images/netbeans/step1.png

  • The 'Java Project with Existing Sources' dialog will open.
  • In the Project Name textbox, give your project a name (e.g. Fop).
  • Choose your Project Folder.
  • Click 'Next'

http://www.aviationcontentmanagement.com/images/netbeans/step2.png

  • Now you will need to add your Existing Sources.
  • Click the 'Add Folder'

http://www.aviationcontentmanagement.com/images/netbeans/step3.png

  • Navigate to where you downloaded the trunk to. (e.g. c:\foptrunk2)
  • Add the Folders: ( this assumes your downloaded version of Fop Trunk is c:\foptrunk2
  • c:\foptrunk2\src\java
  • c:\foptrunk2\build\gensrc

http://www.aviationcontentmanagement.com/images/netbeans/step4.png

  • Click 'Next'
  • The next step is the Includes and Excludes dialog.
  • Give Netbeans a few minutes to load all the included files.
  • Click 'Finished'

http://www.aviationcontentmanagement.com/images/netbeans/step5.png

  • Now, netbeans will create the project. When Netbeans finishes, you will notice a number of resources missing:

http://www.aviationcontentmanagement.com/images/netbeans/step6.png

http://www.aviationcontentmanagement.com/images/netbeans/step7.png

  • You will need to a number of dependencies for your project.

http://www.aviationcontentmanagement.com/images/netbeans/step8.png

  • Jai (by default (windows) located in 'C:\jai-1_1_2_01\lib')
  • jai_codec.jar
  • jai_core.jar
  • mlibwrapper_jai.jar
  • Saxon

http://www.aviationcontentmanagement.com/images/netbeans/saxon.png

  • FOP
  • avalon-framework-4.2.0.jar
  • batik-all-1.7.jar
  • commons-io-1.3.1.jar
  • commons-logging-1.0.4.jar
  • saxon9-dom.jar
  • serializer-2.7.0.jar
  • servlet-2.2.jar
  • xalan-2.7.0.jar
  • xercesImpl-2.7.1.jar
  • xml-apis-1.3.04.jar
  • xml-apis-ext-1.3.04.jar
  • xmlgraphics-commons-1.4svn.jar
  • Ant
  • ant.jar (located in the ant director e.g. c:\ant\lib)

http://www.aviationcontentmanagement.com/images/netbeans/step8a.png

http://www.aviationcontentmanagement.com/images/netbeans/step8b.png

http://www.aviationcontentmanagement.com/images/netbeans/step9.png

  • Netbeans will take a few minutes to import the resources.
  • If all goes well, you will see:

http://www.aviationcontentmanagement.com/images/netbeans/finished.png

  • That's it! Good Luck.
  • No labels