Installing BIRT

Installing BIRT

• Introduction
• Report Designer Full Eclipse Install
• Designer Install
• GEF
• EMF
• BIRT
• Optional Eclipse Link File
• iText
• prototype.js
• JDBC Drivers
• Updating a BIRT Installation
• Deploying to J2EE Server
• Installing BIRT Language Packs on Windows
• Common Problems

Introduction

Below are complete instructions for installing BIRT. If you are already familiar with Eclipse plugins, you might want to follow the abbreviated requirements and instructions on the download page. Otherwise, follow along below for detailed steps for installing BIRT.

The instructions here are for the Release 2.1/2.0.2 (and later) builds.

Java

You'll need a Java runntime environment (JRE) The version you choose will depend on the version of Eclipse you are running. See below.

Eclipse

BIRT is currently tested with the following configurations:

• BIRT 2.0.2
• Eclipse 3.1
• GEF 3.1.
• EMF 2.1.
• JRE 1.4.2/JRE 1.5.

And

• BIRT 2.1/2.1.1
• Eclipse 3.2.
• GEF 3.2.
• EMF 2.2.
• JRE 1.4.2/JRE 1.5.

Report Designer Full Eclipse Install

BIRT now supplies a download that incudes Eclipse, GEF, EMF and BIRT. Use this download if you do not already have Eclipse installed. You will still need iText.jar and prototype.js (this file is no longer needed with 2.1 or later builds), which are described below.

Designer Install

Use these instructions if you have Eclipse installed or do not desire to use the Report Designer Full Eclipse Install.
Download and install the Eclipse Platform 3.1/3.2 Release

(Note: Eclipse, EMF, GEF and BIRT are all available from the Eclipse download page.)

Eclipse comes as a zip file or tar file. On Windows, unzip the install file into your "C:/Program Files" directory. This will create a subdirectory called eclipse.

To make it easier to start Eclipse on Windows, create a shortcut to Eclipse on your desktop:

• From the desktop, right click, choose New→Shortcut.
• For location, enter "C:/Program Files/eclipse/eclipse.exe" (without quotes.)
• Click Next.
• Enter “Eclipse” for the shortcut name.

GEF

GEF, the Graphic Editor Framework, is an Eclipse plugin used by the BIRT UI. Download the GEF 3.1/3.2 Release, GEF Runtime.

GEF comes as a zip file. Unzip GEF into directory that contains Eclipse. If you installed Eclipse into the standard location on Windows, then unzip GEF into "C:/Program Files".

EMF

The BIRT charting feature uses EMF, the Eclipse Modeling Framework. Download the EMF & SDO RT version 2.1/2.2. Look in the Latest Releases sections of the download page.

EMF also comes as a zip file. Unzip EMF into directory that contains Eclipse. This is the same directory you used for GEF.

BIRT

Download Release 2.1.0 (or later). Download only the BIRT designer framework for now: "birt-report-framework-2_1_0.zip".

BIRT is also a zip file. Unzip BIRT into the directory that contains Eclipse.

Optional Eclipse Link File

If you currently have an Eclipse install with GEF and EMF, you can download the BIRT framework and unzip the contents to any directory.

• After doing this, create a links directory in your installed Eclipse location (ie C:/eclipse3.1/eclipse/links).
• Within this directory create a file with a unique name like birt.2.0.link.
• Open the file you just created and enter path=drive:/pathtobirt (ie path=c:/birt2.1)
• You will still need iText and prototype.js files. See next section.

iText

• iText 1.3.

The iText APIs are discussed at iText Homepage
BIRT 2.0.2
The itext-1.3.jar file needs to be copied to the plugins/org.eclipse.birt.report.engine.emitter.pdf_version/lib directory.
BIRT 2.1.0 (or later)
The itext-1.3.jar file needs to be copied to the plugins/com.lowagie.itext_*/lib directory.

Birt 2.1.1 or Later Note:

• To Support Asian fonts in PDF, download the following jar and place it in the plugins/com.lowagie.itext_*/lib directory.
• iTextAsian.jar.

 

 

prototype.js

This step is only required if installing BIRT 2.0.2 or earlier.
Download prototype.js v1.4.0 from dev.conio.net. Copy it into the plugins/org.eclipse.birt.report.viewer_version/birt/ajax/lib directory.

 

JDBC Drivers

You will likely want to use your own JDBC driver with BIRT. Use the data source editor’s JDBC driver management wizard. To start the wizard, open a BIRT report design, go to the Data Explorer view, right click on “Data Sources” and select “New Data Source”. Choose “JDBC Data Source” and click “Next”. In the next dialog, choose “Manage Drivers…” to bring up the “Manage JDBC Drivers” dialog.

In the “JAR Files” tab, click on “Add…” to add the JAR file required by your JDBC driver. Then go to the “Driver” tab to confirm that the list of drivers includes the new drivers added. You may also want to assign a display name and URL template for the new drivers in this tab.

Updating a BIRT Installation

If you have a version of BIRT installed, and want to install a newer version, do the following:

• Close Eclipse.
• Locate your Eclipse plugins directory. If you installed on Windows in the default location, this is "C:/program files/eclipse/plugins".
• Delete all directories that start with "org.eclipse.birt".
• Download and install BIRT as described in the BIRT section above.
• Restart Eclipse with the -clean option: eclipse -clean

Deploying to J2EE Server

Please see Setting up the BIRT Viewer

Birt 2.0.2 Runtime Note:

• If you are installing the BIRT 2.0.2 Runtime (J2EE Application Server Deployment), The iText and prototype files will need to be copied to the birt-runtime/Web Viewer Example directory structure.
• Copy itext-1.3.jar to /Web Viewer Example/plugins/org.eclipse.birt.report.engine.emitter.pdf/lib.
• Copy prototype.js v1.4.0 to /Web Viewer Example/ajax/lib.

Birt 2.1 Runtime Note:

• If you are installing the BIRT 2.1 Runtime (J2EE Application Server Deployment), The iText file will need to be copied to the birt-runtime/WebViewerExample directory structure.
• Copy itext-1.3.jar to /WebViewerExample/WEB-INF/platform/plugins/com.lowagie.itext/lib.

Birt 2.1.1 Runtime Note:

• If you are installing the BIRT 2.1.1. or Later Runtime (J2EE Application Server Deployment),
• Copy itext-1.3.jar to /WebViewerExample/WEB-INF/platform/plugins/com.lowagie.itext/lib.
• Copy iTextAsian.jar to /WebViewerExample/WEB-INF/platform/plugins/com.lowagie.itext/lib.

Installing BIRT Language Packs on Windows

 

1. Download the Language Pack for the desired product and extract into your eclipse install.
2. Open the Regional and Language Options in the Control Panel and switch to the advanced tab.
3. Select the group 1 language you desire from the drop-down combo box.
4. Save changes and restart the system.
5. Launch Eclipse and select Window->Preferences->Report Design->Preview. Select the desired language from the drop-down combo box.
6. Restart Eclipse.

 

Common Problems

Some problems are due to cached information within Eclipse. Eclipse caches information about plugins for faster startup. Adding BIRT as we did above may result in stale cached information. Symptoms of this problem include:

• The BIRT perspective does not appear in Eclipse.
• You receive "An error occurred" dialogs when opening reports or using the BIRT UI.

Cleaning Cached Plugin Information

The solution is to clean up the cached information. The recommended practice is to start Eclipse with the -clean option:

eclipse -clean

Cleaning the Cache on Windows

If you are on Windows, and are not familiar with how to invoke Eclipse from the command line, do the following:

• Choose Start→All Programs→Accessories→Command Prompt
• Move to the directory where you installed eclipse. If you installed Eclipse in the standard location, enter:

   

  cd "/Program Files/eclipse"
  

• Run Eclipse with the -clean option:

  eclipse -clean
  

• Eclipse will restart. Again check for the BIRT perspective.