Apache™ FOP Development: Developer Tools
This page documents items that may be helpful to other developers, especially to those who are new to Apache™ FOP. Exhaustive treatment of these topics is better suited to other fora, but the information presented here is intended to deal with FOP-specific issues related to these tools, especially "gotchas", and to help developers get jump-started.
Developer Checklist
Here is a (probably not comprehensive) list of tools you will need to be a successful FOP developer:
-
A java IDE (see IDE).
-
A Git client (see Git).
-
Maven (see Building FOP).
-
checkstyle (see Checkstyle on the conventions page).
-
JUnit (see Basic Testing).
General Developer Information
See the Apache Contributors Tech Guide for useful information and links for Apache developers, including help with tools and procedures.
Git
General
Visit Apache XML Graphics Code Repositories for useful information.
You will need a Git client to be able to gain access to the FOP repository. For general Git information, visit Git Home. A comprehensive list of clients for all operating systems and many IDEs can be found at the Git Links page. For Microsoft Windows we recommend TortoiseGit. The command-line client that comes with Git is also very easy to use.
Step-by-step instruction for downloading FOP using the Git command-line client
On the command-line (Windows or Unix), simply run:
git clone https://github.com/apache/xmlgraphics-fop.git
This will download the FOP main into the directory "xmlgraphics-fop".
Step-by-step instructions for downloading FOP using TortoiseGit (on Windows)
-
Create a new, empty directory in a place of your choice.
-
Right-click the new directory and select "Git Clone..." from the context menu.
-
Enter
https://github.com/apache/xmlgraphics-fop.gitas the URL of the repository. -
Click "OK" and the download should begin.
Creating Patches
-
cdto a directory that contains all of the changes that you wish to include in the patch. To comprehend the entire distribution,cdto the top directory where you checked out the sources. -
Run:
git pullto make sure the diff is created against the latest sources. -
Run:
git diff >mypatch.diffThis will write the patch to the file "mypatch.diff".
-
If you are running TortoiseGit, you can select "Create Patch..." in the TortoiseGit context menu.
Documentation
-
[online resource] The Git Home Page.
-
[electronic manual] Version Control with Git (official Git manual). Note that this manual applies to the command-line version of Git.
-
[online resource] Comprehensive list of links to documentation and Git clients and plugins.
Integrated Development Environments (IDEs)
An IDE is not required, but will generally be found to be helpful, especially for serious debugging and refactoring.
Borland's JBuilder 7/8 does not support Ant builds unless you have the Enterprise Edition (which is quite expensive). This causes problems with any code that is generated by the Ant build. First, you must run the Ant build before you can use the IDE. Second, when you are editing in the IDE, you must be editing the generated files, which means that you must make any changes to the source files in another editor. This is less serious for development on the main, but in the maintenance branch, all source files were "generated".
Sun ONE Studio Four does support Ant, but seems to use a built-in version, and as of this writing chokes on the FOP build file, saying that it is not valid. There is awkward because there is no official DTD for Ant, and it may be merely an Ant version issue.
Additional notes on setting up FOP within an IDE (ex. Eclipse) in the Wiki.