How to Build BIRT from CVS

Introduction

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.

Requirements

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:
  1. From the menu, choose Window->Preferences.
  2. In the tree, expand Java and choose Compiler.
  3. On Compiler compliance level, select 1.4.
  4. Unselect Use default compliance settings.
  5. On Generated .class files compatibility, select 1.4.
  6. On Source compatibility, select 1.4.

    The following illustration shows these settings.



  7. 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
org.eclipse.birt.data Provides the data engine implementation and the ODA factory implementation. It also contains classes for applying transformations on the data.
org.eclipse.birt.data.oda ODA public interface: the classes and interfaces used to create data extensions.
org.eclipse.birt.data.oda.adapter.dtp Adapter for Data Tools project
org.eclipse.birt.report.data.oda.flatfile The ODA driver for accessing flat file data sources
org.eclipse.birt.report.data.oda.flatfile.ui The user interface for the ODA flat file driver
org.eclipse.birt.data.oda.jdbc The ODA driver for accessing JDBC data sources
org.eclipse.birt.data.oda.jdbc.ui The user interface for the ODA JDBC driver
org.eclipse.birt.report.data.oda.sampledb The ODA driver for accessing the sample Derby data base
org.eclipse.birt.report.data.oda.sampledb.ui The user interface for the ODA sample database driver
org.eclipse.birt.data.oda.xml The ODA driver for accessing XML data sources
org.eclipse.birt.data.oda.xml.ui The user interface for the ODA XML driver
org.eclipse.birt.report.debug.ui Used for creating launch configuration when debugging reports that contain Java events
org.eclipse.birt.report.designer.core The core classes of the BIRT report designer, including classes that interact with the BIRT model, and localization and other utility classes
org.eclipse.birt.report.designer.lib The classes used for library manipulation
org.eclipse.birt.report.designer.lib.explorer Handles browsing and exploring library contents
org.eclipse.birt.report.designer.ui The BIRT report designer
org.eclipse.birt.report.designer.ui.rcp The BIRT RCP report designer
org.eclipse.birt.report.engine The BIRT reporting engine that generates the report from a report design
org.eclipse.birt.report.engine.emitter.fo The emitter for generating report output using FO
org.eclipse.birt.report.engine.emitter.html The emitter that generates report output in HTML
org.eclipse.birt.report.engine.emitter.pdf The emitter that generates report output in PDF
org.eclipse.birt.report.model The BIRT report model
org.eclipse.birt.report.viewer The BIRT report viewer (BIRT web app)
org.eclipse.birt-feature The BIRT feature

Checking out Code from CVS

Configure the Repository under Eclipse

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



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



  3. On Add CVS Repository, set the following values:

    Host dev.eclipse.org
    Repository path /cvsroot/birt
    User anonymous
    Connection type pserver
    Use Default Port Selected



  4. Choose Finish.
A new node appears in the CVS Repositories window.

Check Out Code for the First Time

  1. Expand the new node in the repositories tree.
  2. Select Versions
  3. Select source
  4. Open the source BIRT_2_1_1_Release_20060927 node



  5. Select all the nodes under this node, with the exception of the these projects:
    org.eclipse.birt.report.data.oda.flatfile
    org.eclipse.birt.report.data.oda.flatfile.nl
    org.eclipse.birt.report.data.oda.flatfile.ui
    org.eclipse.birt.report.data.oda.flatfile.ui.nl
    org.eclipse.birt.report.tests.engine
    org.eclipse.birt.report.tests.model
    org.eclipse.birt.report.tests.viewer
    org.eclipse.birt.test.performance
    org.eclipse.birt.tests.core
    org.eclipse.birt.tests.data

  6. 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.
  1. Copy the following plugins from the all in one download to the source directory of the workspace you are currently using to build BIRT.
    org.apache.batik.pdf_1.6.0.v20060623-1511
    org.apache.batik_1.6.0.v20060623-1511
    org.apache.xerces_2.8.0.v20060815-0630

    When copying these plugins rename them to the following:
    org.apache.batik.pdf
    org.apache.batik
    org.apache.xerces

    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.

  2. In Package Explorer, expand the org.eclipse.birt.report.viewer project.

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



  4. In the org.eclipse.birt.report.viewer 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:
  1. Select Run... from the Run menu on the menu bar

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



  3. 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

  1. Open debug perspective
  2. 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 org.eclipse.birt.report.engine 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 org.eclipse.birt.report.engine.



    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.