iText library developer guide

Where to start if you need to develop on the iText library itself.

First, you’ll have to check out the source code from subversion. The svn root holds a couple of things so for itext itself do

svn co https://itext.svn.sourceforge.net/svnroot/itext/trunk/itext itext

this will checkout the itext core trunk. If you’d like geospatial and richmedia packages you also need to checkout xtra trunk

svn co https://itext.svn.sourceforge.net/svnroot/itext/trunk/xtra xtra

Now you have the sources and you’re ready to build the project. As build tool we use Maven (3.x). You’re not obligated to use Maven, you can perfectly setup the project in your IDE without it, but it will require more work. Most major IDEs have Maven support so importing the project as a Maven Project in your IDE is the easiest way.

If you want to build with the command line do mvn install. Both itext and xtra have a parent pom that’s called itext-parent, this pom holds some profiles and the java compiler version. If you want to build the sources and javadoc jar too, you need to use the profile ‘all’. ( mvn install -P all). Normally there is no need to checkout the source of the itext-parent project, it is in Maven Central. If however you’d like to build it yourself, you can get the pom from subversion

svn co https://itext.svn.sourceforge.net/svnroot/itext/itext-parent/trunk itext-parent

For building itext asian and hyph jars, there are poms in trunk/itext you should build them commandline with e.g. mvn clean install -f itext-hyph-xml.pom

The global subversion structure (thanks to Kevin for adding this)

/book – contains information related to iText In Action and the examples in that book.
/branches
/tags
/trunk   – these 3 are the standard SVN structure related to the main iText library.  Note that the main library itself has two main sections:
     /itext  – the main library
     /xtra – extra extension libraries that aren’t part of the main library (e.g. geospatial and richmedia packages)
/examples – contains the old examples dating back to itext 2.1.7.  This folder does not have the traditional branchs|tags|trunk structure – it is never branched
/itext-parent – container for a top-level POM used for the maven build process.  You should almost never have to check out or use this folder
/tutorial – contains examples for things not in the iText in Action Book (e.g. the XMLWorker )  This folder does not have the traditional branchs|tags|trunk structure – it is never branched.

 

Coding guidelines

I’m not aware of any rules for coding in the itext project, but here are some of my coding guidelines:

  • Any method you create should have descriptive Javadoc on what it does.
  • When you encounter a method that does not have Javadoc, please add it.
  • You should provide a unit test that verifies that the code you’ve written works correctly, this allows other committers to easily detect the introduction of a bug by there changes.
  • Each commit should have a descriptive comment on what change is done.
  • Rather commit many times then one commit with a lot of changes. (this also makes it easier to comment)
  • Rather provide accessors to class variables then to make them public/protected.
  • Don’t be afraid to write small in-line code comments ( // )  in complex methods.
  • When a method gets really complex, perhaps it’s an indication that too much is going on in that method. Consider splitting up that method in multiple methods/classes that each have it’s own responsibility, if possible.
  • Implement to an interface, not an implementation!
  • All non java files should go in the resources directory src/main/resources or for test resources in src/test/resources. Java files go into src/main/java or src/test/java.
  • Don’t forget to add the AGPL header to new source files.
  • Don’t be afraid to ask questions/advice on itext-developers mailinglist.
  • There are more but the above is enough to begin with.

(Update) Other points:

  • do not let your IDE autoformat a whole file on save, do not manually format the whole file! Only format the lines you worked on. Makes it easier to track changes in the svn commit mail.

But I don’t have commit rights! You can create a patch and submit that. It will be reviewed and if approved added to the source. Perhaps after that you’ll get commit rights if you sign the CLA (Committers License Agreement).

Leave a Reply