Building BIRT


This document describes how to get the BIRT source from CVS and build it under Eclipse. If you simply want to use BIRT, it is easier to simply download an existing build.

Building BIRT 2.1.1 is described below.
For the latest instructions, see the BIRT Wiki.


Download the BIRT all in one designer. It is listed under "Report Designer Full Eclipse Install" on the download page. It is possible to build BIRT with an existing Eclipse install, but this method is the quickest, as all the required files, with the exception of iText.jar and iTextAsian.jar are present.

Configuring Eclipse

The BIRT source code uses some features that are only present in JDK 1.4.2 or later. In order for it to successfully build you need to set your compiler compliance to 1.4. Make sure this is not set to 5.0. You can set this for the entire workbench as follows:

  • From the menu, choose Window->Preferences.

  • In the tree, expand Java and choose Compiler.

  • On Compiler compliance level, select 1.4.

  • Unselect Use default compliance settings.

  • On Generated .class files compatibility, select 1.4.

  • On Source compatibility, select 1.4.

    The following illustration shows these settings.

  • Choose OK.

Understanding the CVS Structure

The BIRT modules are available in CVS in the source folder under /home/birt. BIRT has over 150 modules, some of these are described below.

Project Folder Contents
org.eclipse.birt.chart.device.extension Extension classes for the device renderer framework for charts
org.eclipse.birt.chart.engine Chart model and factory classes
org.eclipse.birt.chart.engine.extension Extension classes for the model renderer framework for charts
org.eclipse.birt.chart.reportitem Classes for the chart module to interact with the BIRT designer and runtime engine
org.eclipse.birt.chart.shared Classes shared between different components of the chart module
org.eclipse.birt.chart.ui Chart builder UI classes
org.eclipse.birt.chart.ui.extension Extensions for the chart builder UI
org.eclipse.birt.chart.device.extension Chart engine extension plugin containing device renderers implementations (Swing, SWT, PNG, GIF, JPG, BMP)
org.eclipse.birt.chart.device.svg Chart engine extension plugin containing SVG device renderer's implementation
org.eclipse.birt.converters Contains converters that can convert reports from other formats to the BIRT report format
org.eclipse.birt.core Provides the framework for loading the plugins at run-time and contains other classes that can be used by any other module Provides the data engine implementation and the ODA factory implementation. It also contains classes for applying transformations on the data. ODA public interface: the classes and interfaces used to create data extensions. Adapter for Data Tools project The ODA driver for accessing flat file data sources The user interface for the ODA flat file driver The ODA driver for accessing JDBC data sources The user interface for the ODA JDBC driver The ODA driver for accessing the sample Derby data base The user interface for the ODA sample database driver The ODA driver for accessing XML data sources The user interface for the ODA XML driver Used for creating launch configuration when debugging reports that contain Java events The core classes of the BIRT report designer, including classes that interact with the BIRT model, and localization and other utility classes The classes used for library manipulation Handles browsing and exploring library contents The BIRT report designer The BIRT RCP report designer The BIRT reporting engine that generates the report from a report design The emitter for generating report output using FO The emitter that generates report output in HTML The emitter that generates report output in PDF The BIRT report model The BIRT report viewer (BIRT web app)
org.eclipse.birt-feature The BIRT feature

Checking out Code from CVS

Configure the Repository Under Eclipse

  • To open the CVS Repository Exploring perspective, choose Window -> Open Perspective -> Other. In Select Perspective, select CVS Repository Exploring and choose OK.

  • Right-click on the CVS repositories window. From the context menu, choose New -> Repository Location.

  • On Add CVS Repository, set the following values:
    Repository path/cvsroot/birt
    Connection typepserver
    Use Default PortSelected

  • Choose Finish

A new node appears in the CVS Repositories window.

Check Out Code for the First Time

  • Expand the new node in the repositories tree.

  • Select Versions

  • Select source

  • Open the source BIRT_2_1_1_Release_20060927 node

  • Select all the nodes under this node, with the exception of the these projects:

  • On CVS Repositories, right-click and choose Check Out from the context menu.

    This will get the BIRT projects from CVS and load them into your Eclipse workspace folder. This will take some time. Once finished, change to the Java perspective.

Import Additional Files

Import iText 1.3 and iTextAsian into the com.lowagie.itext/lib directory.

If your Eclipse environment is not setup to build automatically, build the source now. This designer should build correctly. If you wish to build the Web Viewer proceed to the next section. Do this if you wish to make changes to the deployable Web Viewer Example.

Preparing the Viewer

The viewer project contains an ant build script that builds the Web Viewer. When executed it will create a birt_web directory in the root of the viewer project. This directory can then be exported and deployed in a similar fasion to the Web Viewer example in the Report Engine download. To use this script, perform the following steps.

  • Copy the following plugins from the all in one download to the source directory of the workspace you are currently using to build BIRT.


    When copying these plugins rename them to the following:


    eg. If you have checked the projects out to c:/work/birt2.1.1/source and your all in one distribution is located under c:/birt2.1.1, copy the three plugins from c:/birt2.1.1/eclipse/plugins to c:/work/birt2.1.1/source and rename them as stated above.

  • In Package Explorer, expand the project.

  • Right-click the BuildWebViewer.xml file. From the context menu, choose Run -> Ant Build....

  • In the BuildViewer.xml, select the Properties tab. Unselect Use global properties specified in the Ant runtime preferences as shown in the following illustration. Add the eclipse.home property and set it to your all in one Eclipse install directory.

  • Choose Run. The ant build of the Web Viewer runs in the console. This will create the birt_web directory within the project that contains the Web Viewer. Refresh the viewer project and the birt_web directory will be displayed.

Running BIRT

Start BIRT by running it as an Eclipse Application. This can be done as follows:

  • Select Run... from the Run menu on the menu bar

  • Select Eclipse Applicaiton from the list on the left and click on the New button as shown in the following illustration:

  • Click the Run button to launch the Eclipse Application. In the new Eclipse application start a new BIRT project and build reports as usual. You should be able to step through and debug the BIRT code.

Instructions for Running JUnit Tests

  • Open debug perspective

  • click on Run --> Run --> Double click on JUnit Plug-in Test , this will create a new configuration. In the window, you can select among different options.

    To run all tests in a selected project, click on the option 'Run all tests in selected project,package or source folder'. On the right side, select the package to run tests for by clicking on Search and selecting a required source folder.

    In this example, we will run tests in project. So lets name this configuration as ReportEngineTests in the 'Name:' box on the top of the configuration window. And then click 'Apply' to save the changes.

    To run the test, in the ReportEngineTests window, click on 'Run'. This will run all tests in

    If you want to see the progress of the tests, look at the JUnit window.

    The results for birt2_1_1_Release_20060927 should be 613 tests ran, with 2 failures and no errors.