How I install my development environment for iText (Eclipse)
On the previous page, I explained which products and tools I usually install when I buy myself a new PC, and how I get the most recent iText version from Subversion (SVN). On this page, I'll explain how I create an Eclipse Workspace, and projects called 'main' and 'test'.
Creating a Workspace in Eclipse
Upon opening Eclipse, you have to choose a workspace. Let's fill in the path you have just created for the itext-core c:/itext-core (see SVN):

Eclipse didn't know about this workspace yet, so it will show you a welcome page:

You've probably seen this welcome page many times before, so you can close it, and this is what you'll see:

The work-space is empty for now, but let's add a new project:

More specifically, let's add a new Java project:

First we have to give the project a name. Let's call it main, so that the path to the project will be c:/itext-core/main/.

Don't ask Eclipse to build the project from existing code and don't worry if you can't change the JRE to 1.4 (in my case 1.6 is installed but I don't want to use it for iText), just click next and see what happens. Note that you may have to wait for a while, before you see the next screen:

Eclipse has done a great job trying to set the source path, the jars,... and other properties (that's why it took some time). There's very little work left for us; note that I've only changed the default output folder to main/build/bin
If you don't change this, the code will be compiled to class files in the directory main/bin. This isn't really a problem. If you prefer it that way, you can leave the path as-is. Personally, I prefer my class files under the build directory. My ANT files will add plenty of other directories to the build directory; it will use these directories to write temporary files that have to be jarred of zipped. The tutorial, including all the PDFs that are generated from the tutorial examples, will also be written to one of build's subdirectories.
As a rule, I never add files or directories manually to the build directory (or its subdirectories). That way, I can safely throw away the build directory without losing any important code or files. This allows me to start (almost) from scratch if something went wrong. Everything in my build directory can be generated either automagically by Eclipse or using an ANT script.
Now is the time to start worrying about using the right JRE. Switch to the tab Libraries; and you'll see that Eclipse has added all the jars it found in the lib directory (which is nice).

As you can see, the Java 6 runtime environment is used. We don't want that (see requirements). You can create an iText.jar using Java 6 if that's what you want, but if you have users that aren't ready to make the switch the Java6 yet (many developers out there are still using the JDK 1.4), you will get a lot of complaints. Trust me: one gets really tired hearing the question 'can you compile me a jar for the JDK 1.3 please?' over and over again. People don't always appreciate getting the answer: DO IT YOURSELF!
Select JRE System Library [jre_1.6.0_01] or whichever jre other than 1.4 is mentioned and use the Remove button to delete the reference to Java 6. Once this is done, try adding the JRE 1.4. We choose Add Library and select JRE System Library:

The default JRE System library in my current Eclipse installation, is jre1.6.0_01:

Clicking on Installed JREs, you see it's even the only JRE on my system according to Eclipse.

That's not entirely correct: I have a 1.4.2 JRE in my program files directory. Let's add it:

The only thing that remains to do, is to check the correct JRE:

And select it as alternative JRE:

This looks more like it:

If all goes well --that is: if the version in SVN isn't broken--, everything compiles. Note that there will always be some warnings, but most of them can safely be ignored).

The next step, is something personal, feel free to follow this advise or not. I usually create a second project in the itext-core workspace: c:/itext-core/test/
I use this project to create small standalone test programs, for instance to test if some bug reported on the mailing list is indeed a bug, or just some example of bad use of iText.

Check the properties of this project, and check if the JRE 1.4 is used. Do the same for the jars: iText only needs the BouncyCastle jars; but the examples also need JFreeReport, iTextAsian, and so forth. I usually don't care much about the location of the class files, but you should make sure the main project is defined as a required project on the build path.

If you look at the directory c:/itext-core now, you can see that Eclipse created a directory called .metadata; don't change it; Eclipse needs it to store metadata about the workspace.
You still have the main directory, you shouldn't touch its contents if you're not working on iText. But as you created a new project called test, a new directory test was created next to the main directory. This is the directory where you can put all your experimental code when you're working with iText (note the important difference).

You can organize the contents of the test directory any way you wish, but the main directory is organized like this:

The bin directory was added by Eclipse when compiling the source code the first time. However, when we told iText we wanted the bin directory to move to the build/bin directory, bin was emptied and we can safely delete it.
The .classpath and .project file are Eclipse specific files, don't change them or you risk corrupting your Eclipse project main in your itext-core workspace.
I have write access to SVN, so I will be committing code to SVN on a regular basis. As I already explained, other iText developers use other IDEs, so it's important that I don't upload files that are specific for my environment to SVN. That's why I usually tell SVN to ignore the build directory, and the two project files:

There's one final setting I often forget, but that is useful to avoid confusion when you're exploring your directories, more specifically the build/bin directory. Eclipse copies all the files that can't be compiled to build/bin; including all the .svn directories and SVN related files. This can give you the impression that the stuff generated in the build/bin directory is (or should be) in SVN too. You want to avoid this, and you can, by changing the Output folder property of your projects:

Add *.svn to your filtered resources (*.launch is added by Eclipse by default).
Now I am ready to build the jar and make a release. That's done with ANT. You'll find more info on the build.xml file on the next page.
SourceForge.net Logo
iText, the #1 Java-PDF library
Amazon books: amazon.co.uk-link