This information is primarily for contributors to the BIRT open‑source project and for those who want to create a custom version of BIRT, such as modifying code to make use of new plug-ins. The typical user does not need to build BIRT to extend BIRT or to write scripts for it.
After the build process completes, you can explore the BIRT source code and make changes to the code to suit your needs. Any changes made to the BIRT source are immediately implemented in BIRT Report Designer. To implement your changes in a web application, you must build and export a new web viewer.
Building the BIRT project consists of the following tasks:
Installing a working version of BIRT Report Designer
By first installing the same version of BIRT Report Designer that you want to build, you ensure that your Eclipse environment is correct and that you have all the necessary components for building BIRT.
Configuring Eclipse to compile BIRT
You may need to change the compiler settings to match those required to build BIRT. Installing the Eclipse SDK is required to use some extension points.
Downloading and extracting the correct version of the BIRT source code
Download the BIRT SDK from the Eclipse website. Builds move around as new builds are added, so use search to find the appropriate version. The downloaded version and the working version on your system must be identical.
Importing and building the BIRT projects
The act of importing the BIRT projects initiates the build process. The build process takes a few minutes and should complete with no errors.
Installing a working version of BIRT
To ensure that you have all the components that are necessary for building BIRT, first install a working version of BIRT Report Designer. Ensure that all the plug‑ins and auxiliary files BIRT requires are present and that these resources are the versions the source code requires.
The simplest and surest way to know that you have all the necessary components of a working BIRT installation is to choose the Full Eclipse Install (All-in-One) option.
After installing BIRT, launch Eclipse and open the Report Design perspective. Verify that you can build a simple report and that you can preview the report in the web viewer. Typically, this test is sufficient to guarantee that you have a valid working version of BIRT. Of course, you can run more extensive tests to confirm access to any custom items in your environment, for example, custom data sources.
Configuring Eclipse to compile BIRT
Before importing the BIRT source code into a workspace, check that the Java compiler settings on the workspace are compatible with BIRT. The 4.3.1 version of the BIRT SDK source code uses some features that are only present in JDK version 1.6 and higher. In order for BIRT to build successfully, you can now set the Eclipse compiler compliance to Java 1.7. Set this version for your Eclipse workspace by starting Eclipse and setting Eclipse preferences.
How to set Eclipse workspace compiler preferences
1 In BIRT Report Designer, choose Window➛Preferences.
2 In Preferences, expand the Java entry in the tree and select Installed JREs. In Installed JREs, select a Java 1.7 JRE, as shown in Figure 22‑1.
Figure 22‑1 Selecting a Java 1.7 JRE
You can use this screen to install additional JREs to eliminate the warnings from plug-ins that require previous Java levels. Note that BIRT 4.3.1 builds error-free using Java 1.7.
3 Select Compiler. In Compiler, as shown in Figure 22‑2, perform the following steps:
In JDK Compliance, select 1.7 in Compiler compliance level.
In Classfile Generation, select all the available options.
Figure 22‑2 Compiler preferences
Choose OK.
If a message appears asking if you want to do a full rebuild now, choose No. This message is applicable only if you changed the compiler settings and there are Java projects in the workspace.
Downloading and extracting the correct version of the BIRT SDK
Download the BIRT SDK using the same page from which you downloaded the working version of BIRT. The SDK archive is in the section labeled BIRT SDK. The archive file has a name similar to birt‑report‑framework‑sdk‑4_3_1.zip. Extract the archive into a directory.
Typically, you use a workspace for BIRT source code that is separate from workspaces used for report development. A separate workspace is not required, but keeps your report workspace less cluttered. If your workspace contains source code from a BIRT build that is not the same as the plug-ins in your Eclipse home directory, Eclipse runs BIRT using the source code in preference to the plug‑ins from the Eclipse home directory.
Importing, building, and testing the BIRT project
After downloading the BIRT SDK, import the feature files, plug-in files, and source files to your workspace. A single Eclipse import operation imports the files into a workspace and builds the projects.
How to import and build the BIRT project
Use the Java perspective to import and build the BIRT project.
1 Choose Window➛Open Perspective➛Other➛Java.
2 In the Java perspective, to import the BIRT SDK projects, choose File➛Import.
3 In Import, expand Plug-in Development. Select Plug-ins and Fragments, as shown in Figure 22‑3.
Figure 22‑3 Import showing expanded Plug-in Development node
Choose Next.
4 In Import Plug-ins and Fragments, select Directory and next to that, choose Browse.
5 Navigate to the directory into which you extracted the SDK. Select the eclipse subdirectory and then choose OK.
6 In Import As, choose Binary projects with linked content, as shown in Figure 22‑4. Then, choose Next.
To prepare for changing BIRT source, import using the Projects with source folders option. This option automatically extracts the source from the JAR file into a source folder. To reduce the number of warning messages and make the build as efficient as possible, only use this option for the plug-ins whose source you intend to modify.
Figure 22‑4 Selecting the BIRT SDK plug-in directory
7 In Selection, choose Add all to import all found plug-ins, as shown in Figure 22‑5. Then, choose Finish.
Figure 22‑5 Selecting the BIRT SDK plug-ins
Eclipse imports the SDK plug-ins into the workspace and builds all the projects in a background process that can take several minutes. Progress on the process is displayed in the lower right corner of the Eclipse window. When the build finishes, the problem area shows warnings and possibly some errors if you are building a provisional release.
How to test the BIRT project
To test the BIRT project, run the org.eclipse.birt package as an Eclipse application.
1 In Package Explorer, select the org.eclipse.birt package.
2 Choose Run➛Run Configurations.
3 In Run Configurations, select Eclipse Application, then New.
4 In Name, type EclipseApplication.
5 Choose the Arguments tab and ensure that the following values are entered:
6 Choose Run. Eclipse builds a new default workspace. On a Windows system, the name of the workspace is C:\Users\<user-name> \runtime-EclipseApplication. Eclipse opens a new instance of the Eclipse Workbench that shows the welcome page.
7 Close the welcome page.
8 Open the Report Design perspective. Choose Window ➛Open Perspective➛Report Design. If Report Design is not available, choose Other. On Open Perspective, select Report Design, then choose OK.
To test this perspective that Eclipse built from the BIRT SDK source code, create report projects and report designs.
Installing a working version of BIRT Report Designer
