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.