BIRT/FAQ/Building BIRT 2.2 and 2.3

< To: BIRT/FAQ

Project Source

Q: Where can I find the BIRT project source?

BIRT source is in the Eclipse CVS system. Full information for obtaining and building the source is available on the BIRT Build page.

Q: I'm behind a firewall and cannot access CVS. Is there another way to access the source?

Eclipse provides an HTML interface into CVS. Be sure to select the BIRT Project to see the BIRT sources.

Q: How do I build BIRT using the PSF File?

There are almost 300 individual source projects that are combined into the BIRT and Data Tools project. Rather than force you to pull each of these files from their respect repositories, the BIRT team provides Team Project Sets which bundle the projects into appropriate and useful collections of projects.

Builds Available

Each tagged build (Milestones and Releases) has a team project published through the download page. In addition, there is a Team Project Set for the Head release available Media:birt_psf_head.zip.

Available Project Sets

BIRT has twelve different team project sets that cover the functional pieces of BIRT (Engine, UI, Model,etc.) In order to pull a team project set, you use one of the project set files (PSF). If you would like to pull all of the BIRT and Data Tools projects, use the all_files.psf.

File	Description
all_files.psf	All of the source projects for BIRT (more than 200 projects)
birt_chart.psf	Charting projects for BIRT
birt_crosstab.psf	Crosstab components
birt_data.psf	Aggregation and ODA projects
birt_doc.psf	All of the BIRT Documentation
birt_engine.psf	The BIRT Report Engine source
birt_features.psf	The features projects for BIRT
birt_gui.psf	BIRT Graphic UI projects including preview, editors, and sample reports
birt_i18n.psf	All of the i18n language bundles for BIRT
birt_model.psf	The BIRT Report Object Model and related projects
birt_test.psf	All of the test code for BIRT
dtp_i18n.psf	The Data Tools i18n language bundles
orbit_bundles.psf	The orbit projects that BIRT uses. Currently does not work correctly.

Using Project Sets: Step By Step

1. From the Java Perspective, select File => Import
2. Select Team => Project Set
3. Navigate to the PSF file that you want to use
4. You should probably select Run the Import in the background or plan on going for a long cup of coffee

If you have issues, please file a bugzilla entry.

Q: How do I build BIRT?

Complete instructions are available on the Build page.

For building BIRT 2.1.3 or 2.2, those instructions are out of date (2.1.1). The following instruction will (hopefully) be migrated there at some point, after being tested for correctness and modified as needed.

Building BIRT 2.1.3 (pre-release) under Windows.

1/ Install the BIRT report designer all-in-one.
a/ Download BIRT Designer Full Eclipse Install (birt-report-designer-all-in-one-2.1.3-S20070705.zip) from http://europa-mirror1.eclipse.org/birt/downloads/build.php?build=S-R1-2.1.3-S20070705-200707051847.
b/ Open it with your favorite ZIP utility.
c/ Extract all files (with paths preserved) to a base directory (I used c:\birtdev213). This should create a single eclipse subdirectory (c:\birtdev213\eclipse) containing all the needed files.
d/ Create a shortcut to c:\birtdev213\eclipse\eclipse.exe.

2/ Initial configuration.
a/ Start the eclipse program.
b/ Append "\birtdev213" to the workspace path to keep it separate from your other workspaces.
c/ Select the checkbox "Use this as the default..." then press OK.
d/ Click on the workbench icon.
e/ Select Windows|Preferences from the menu.
f/ Under Java|Compiler, set the Compiler Compliance Level to 1.4, deselect Use default compliance settings, then set generated class compatibility and source compatibility to 1.4.
g/ Under Java|InstalledJREs, add a Java 1.4 compiler (I used Suns latest Java 1.4.2, setting the JRE name to jre1.4.2 and the JRE home directory to C:\Program Files\Java\jre1.4.2_14, its default install location).
h/ Make this the default for new projects by selecting its checkbox under Java|InstalledJREs.
i/ Let the workspace do its full rebuild (of zero projects, relatively fast :-).

3/ Attach to the CVS repository.
a/ Use Window|OpenPerspective|Other to list the available perspectives.
b/ Select CVS Repository Exploring and click on OK.
c/ Right-click in the CVS Repositories pane and select New|RepositoryLocation.
d/ Enter dev.eclipse.org for the Host, /cvsroot/birt for the Repository Path and anonymous for the User. Click on Finish button.

4/ Check out and build source.
a/ Under CVS Repositories, expand :pserver:anonymous@dev.eclipse.org:/cvsroot/birt, then expand Versions, then source.
b/ Expand sourceBIRT_2_1_3_RC_20070606 (the S20070705 stable builfd doesn't seem to be labelled in CVS yet).
c/ Select ALL projects by clicking on com.lowagie.itext, scrolling down and shift-clicking on org.w3c.sac.feature.
d/ Deselect (using control-click) org.eclipse.birt.build, all projects beginning with org.eclipse.birt.report.tests (that one plus .chart, .engine, .engine.emitter.html, .model and .viewer) and org.eclipse.birt.tests.data.
e/ Right-click on one of the selected projects and choose Check Out option.
f/ It should start checking out 139 folders. Click the Run in Background button and switch back to the Java perspective (menu item Window|ClosePerspective).
g/ At the bottom of the window, you should see the text "Checking out 139 folders from CVS (0%)". You can click on the "conveyer belt" icon to the right of this to open the Progress tab for more detail. In either case, go grab a coffee. This will take some time.
h/ Auto build will then start, this will also take some time and you'll see a lot of activity in the Progress tab if you opened it.

5/ After all the projects have been built, you'll end up with no errors and 2,209 warnings (see the Problems tab in the lower pane).

Building BIRT 2.2 under Windows.

1/ Install the BIRT report designer all-in-one.
a/ Download BIRT Designer Full Eclipse Install (birt-report-designer-all-in-one-2_2_0.zip) from http://europa-mirror1.eclipse.org/birt/downloads/build.php?build=R-R1-2_2_0-200706261010.
b/ Open it with your favorite ZIP utility.
c/ Extract all files (with paths preserved) to a base directory (I used c:\birtdev22). This should create a single eclipse subdirectory (c:\birtdev22\eclipse) containing all the needed files.
d/ Create a shortcut to c:\birtdev22\eclipse\eclipse.exe.

2/ Initial configuration.
a/ Start the eclipse program.
b/ Append "\birtdev22" to the workspace path to keep it separate from your other workspaces.
c/ Select the checkbox "Use this as the default..." then press OK.
d/ Click on the workbench icon.
e/ Select Windows|Preferences from the menu.
f/ Under Java|Compiler, set the Compiler Compliance Level to 5.0.
g/ Under Java|InstalledJREs, add a Java 5 compiler (I used Suns latest Java 5, setting the JRE name to jre1.5.0 and the JRE home directory to C:\Program Files\Java\jre1.5.0_11, its default install location).
h/ Make this the default for new projects by selecting its checkbox under Java|InstalledJREs.
i/ Let the workspace do its full rebuild (of zero projects, relatively fast :-).

3/ Attach to the CVS repository.
a/ Use Window|OpenPerspective|Other to list the available perspectives.
b/ Select CVS Repository Exploring and click on OK.
c/ Right-click in the CVS Repositories pane and select New|RepositoryLocation.
d/ Enter dev.eclipse.org for the Host, /cvsroot/birt for the Repository Path and anonymous for the User. Click on Finish button.

4/ Check out and build source.
a/ Under CVS Repositories, expand :pserver:anonymous@dev.eclipse.org:/cvsroot/birt, then expand Versions, then source.
b/ Expand sourceBIRT_2_2_0_Release_20070625.
c/ Select ALL projects by clicking on com.lowagie.itext, scrolling down and shift-clicking on org.w3c.sac.feature.
d/ Deselect (using control-click) org.eclipse.birt.build, org.eclipse.birt.data.oda.adapter.dtp and all projects beginning with org.eclipse.birt.report.tests (that one plus .chart, .engine, .engine.emitter.html, .model and .viewer).
e/ Right-click on one of the selected projects and choose Check Out option.
f/ It should start checking out 140 folders. Click the Run in Background button and switch back to the Java perspective (menu item Window|ClosePerspective).
g/ At the bottom of the window, you should see the text "Checking out 140 folders from CVS (0%)". You can click on the "conveyer belt" icon to the right of this to open the Progress tab for more detail.
h/ Auto build will then start, this will also take some time and you'll see a lot of activity in the Progress tab if you opened it.

5/ After all the projects have been built, you'll end up with no errors and 25,800 warnings (see the Problems tab in the lower pane).

Q: How do I build the 2.2 BIRT Viewer?

1. Install BIRT prerequisite in Eclipse home. (You can use the allinone download to get all prerequisites.)
2. Download or import BIRT source code in workspace.
3. Change viewer code.
4. Right click on the MANIFEST.MF of org.eclipse.birt.report.viewer. Select “PDE tools”-> “Create Ant Build File.

5. The PDE build will generate the build.xml under the root folder of org.eclipse.birt.report.viewer.

6. Right click on the build.xml. Select “Run As” -> “Ant Build” to start the compile process. It will generate the servlet jars during the process.

7. When the build process is finished, viewservlets.jar can be found under birt/WEB-INF/lib/ folder. This jar is used with the Viewer when it is deployed as a J2EE application. Replace this jar in your existing deployment. The viewer.jar can be found under root folder. This jar is used when the Web Viewer is used in plugin format.

Q: How do I export the 2.2/2.3 BIRT web viewer?

1. Downloaded and installed the birt-report-designer-all-in-one.
2. Configure the cvs repository and checked out the project BIRT_2_2_2_Release 20080227 (Excluding org.eclipse.birt.build and all *.test, *.tests, *.releng.*, *.doc.isv, *.cshelp and org.eclipse.birt.report.engine.emitter.Prototype_excel).
3. Created build file from MANIFEST.MF in the org.eclpse.birt.report.viewer project - Run build.xml as ant file. - You will get viewservlets.jar under org.eclipse.birt.report.viewer/birt/WEB-INF/lib/

4. Create api jars for web viewer. - Create build.xml for below BIRT plugins from MANIFEST.MF files by PDE tools:

* org.eclipse.birt.core
* org.eclipse.birt.data
* org.eclipse.birt.report.model
* org.eclipse.birt.report.model.adapter.oda
* org.eclipse.birt.report.engine
* org.eclipse.birt.report.data.adapter

- Run the auto-generated build.xml files of above plugins in workspace seperately. Api jars (coreapi.jar, dteapi.jar, modelapi.jar, modelodaapi.jar,odadesignapi.jar,engineapi.jar,scriptapi.jar,dataadapterapi.jar) will be generated automatically under those plugins.

5. Run ant file WebViewerPackager.xml (target = Jar)under org.eclipse.birt.report.viewer and set the vairable: -Declipse.home=<YOUR ALL-IN-ONE INSTALL DIR> -Dintegrate.dir=<YOUR ALL-IN-ONE INSTALL DIR>

6. Run "Export" target of WebViewerPackager.xml and set the variable export.dir=<output dir of web viewer>.

7. Before deploy your web viewer to app server, rename the web_deploy.xml to web.xml (overwrite the original one).

Q: How do I export the 2.3.1 BIRT web viewer?

1. Download and install the Birt 2.3.1 All-In-One file birt-report-designer-all-in-one-2_3_1.zip.
2. Download the Birt 2.3.1 Runtime file birt-runtime-2_3_1.zip.
3. Run Eclipse. Ensure that the default JRE is for Java 1.5 and that the compiler complience is set to 1.5
4. Configure the CVS repository :pserver:anonymous@dev.eclipse.org:/cvsroot/birt
5. Under the Head/source folder select all the packages except for;

   org.eclipse.birt.build

   *.test,

   *.tests.*,

   *.testhelper

   *.releng.*,

   *.doc.isv,

   *.cshelp.

6. Right-Click and selcet Check-Out-As. Refresh the tags and select the BIRT_2_3_1_Release_200809221151 version.
7. For the following projects,
   1. Create a build.xml file from the META-INF/MANIFEST.MF file using the Right-Click/PDE Tools/Create Ant Build File option.
   2. Run the ant build.xml file by using the Right-Click/Run-As/Ant Build option and generate the corresponding jar files.
   • org.eclipse.birt.report.viewer

     birt.temp.folder/birt/WEB-INF/lib/viewservlets.jar.bin

   • org.eclipse.birt.core

     coreapi.jar

   • org.eclipse.birt.data

     dteapi.jar

   • org.eclipse.birt.data.aggregation

     dataaggregationapi.jar

   • org.eclipse.birt.report.model

     modelapi.jar

   • org.eclipse.birt.report.model.adapter.oda

     modelodaapi.jar

     odadesignapi.jar

   • org.eclipse.birt.report.engine

     engineapi.jar

     scriptapi.jar

   • org.eclipse.birt.report.engine.dataextraction

     dataextraction.jar

   • org.eclipse.birt.report.data.adapter

     dataadapterapi.jar

   • org.eclipse.birt.report.item.crosstab.core

     crosstabcoreapi.jar

8. Create <Eclipse-Birt-Project-Home>\extras directory (WebViewerPackager.xml will fail without this directory)
9. Modify WebViewerPackager.xml and comment-out lines 608-612. The java command here is not necessary and will throw errors.
10. Run ant file WebViewerPackager.xml to build the web viewer with the following command;

    ant Jar -Declipse.home=<BIRT-ALL-IN-ONE-INSTALL-DIR> -Dintegrate.dir=<BIRT-ALL-IN-ONE-INSTALL-DIR>
    

    -Dorg.apache.axis=1.4.0.v200807230600 -Djavax.xml.rpc=1.1.0.v200806030420
    

    -Djavax.xml.soap=1.2.0.v200806030421 -Dorg.apache.commons.discovery=0.2.0.v200806030120
    

    -f WebViewerPackager.xml

11. Copy the file commons-logging-api-1.1.jar into the <Eclipse-Birt-Project-Home>\org.eclipse.birt.report.viewer\birt_web\WEB-INF\lib directory (needed for running under apache 6)
12. Copy the file org.eclipse.birt.api_1.0.0.jar from the \birt-runtime-2_3_1\WebViewerExample\WEB-INF\platform\plugins directory to <Eclipse-Birt-Project-Home>\org.eclipse.birt.report.viewer\birt_web\WEB-INF\platform\plugins directory
13. Your can either drop the <Eclipse-Birt-Project-Home>\org.eclipse.birt.report.viewer\birt_web\ directory into your application server's applications directory or Run the "Export" target of WebViewerPackager.xml and set the variable export.dir=<output dir of web viewer>.

Q: How can I generate org.eclipes.birt.api.jar for ReportEngine?

The framework fragment org.eclipse.birt.api is used to import the BIRT API jars into the OSGi framework, so the ReportEngine can be embedded into other framework (such as main app or J2EE).

The org.eclipse.birt.api bundle only contains a manifest file which exports all the packages defined in the BIRT API jars (include coreapi.jar, modelapi.jar, chartapi.jar etc). It locates under WEB-INF/platform/plugins folder.

You can get a tool from org.eclipse.birt.build/org.eclipse.birt.build.ExportManifestUtils which can be used to export the packages from the jars. Below are suggested steps:

1. Check out org.eclipse.birt.build project (:pserver:anonymous@dev.eclipse.org:/cvsroot/birt,,source/org.eclipse.birt.build)

2. Run ExportManifestUtils.java as "Java Application". (There might be compile errors which is caused by missning dom4j library. Please see the readme.txt for resolve the error. Those errors won't affect the generating of birt.api jar )

3. In configuration dialog of "Java Application", set lib folder as the parameter. For example: "C:\Documents and Settings\Farrah\Desktop\WebViewerExample\WEB-INF\lib"

4. Press "Run". All packages of jars under lib will be output in the Console view.

5. Create the MAINFIEST.MF file that export all the packages got by step (4) and create the org.eclipse.birt.api jar that only contain this MANIFEST.MF

6. Copy org.eclipse.birt.api bundle to WEB-INF/platform/plugins folder.

Q: How can I check out BIRT source code according to certain map files?

This is only supported in BIRT 2.2 and above. You need to know the exact version of map file(org.eclipse.birt.releng) before you perform the steps.

An easier way is to use the org.eclipse.releng.tools plug-in (at the end of the platform download page for each build):

- Install org.eclipse.releng.tools into your Eclipse
- Check out the map project: org.eclipse.birt.releng with the tag you like
- Select the cvs project(s) you're interested in
- Choose context menu > Replace With > Released

This should fetch each project's tag from the map files and check out the correct version.

Q: How do I run BIRT JUnit Tests?

Please follow instructions on Build-Junit page.

Q: How do I use BIRT Test Package to setup test framework?

The BIRT Test Package contains all the test plugins and the required resources. Integrating with Eclipse test framework, it’s easy to run the Junit test cases in batch. In this section, we will give out the instructions about usage of birt-test-suite package and how to run the automated JUnit test plugin.

Prerequisites

Before running the JUnit test, users need to download 3 packages:

1. birt-report-designer-all-in-one-<package.version>.zip or birt-report-designer-all-in-one-<package.version>-linux-gtk.tar.gz (http://download.eclipse.org/birt/downloads)

2. birt-test-suite-<package.version>.zip ( http://download.eclipse.org/birt/downloads)

3. eclipse-test-framework-I20070625-1500.zip (http://www.eclipse.org/downloads/download.php?file=/eclipse/downloads/drops/R-3.3-200706251500/eclipse-test-framework-3.3.zip )

Note:

1.Only BIRT 2.2.0 or above support the automated JUnit test.

2.Suggest to download BIRT2.2.1 test framework which contains the newest BIRT bootstrap script (BirtRunner.sh and BirtRunner.bat).

Setup Steps

1. Make sure JDK1.5 or above version is installed in the test environment. JAVA_HOME is pointing to the correct directory and $JAVA_HOME/bin has been added to system classpath.

2. Make sure ant is installed in the test environment. ANT_HOME is pointing to the correct directory and $ANT_HOME/bin has been added to system classpath

3. Unzip birt-report-all-in-one-<package.version>.zip

4. Unzip birt-test-suite-<package.version>.zip into the same folder as birt-report-all-in-one package

5. Unzip eclipse-test-framework-<package.version>.zip into the same folder as above.

6. If any duplicated plugins, please choose overwrite

Run Tests

Run All Tests on Windows

The top level ant script for start the whole JUnit tests is BirtRunner.xml, which can be found under the root folder of birt-test-suite.zip package. Please see the <target> “Start” in BirtRunner.xml to find out which tests will be called by bootstrap script.

Set three variables correctly in ant property file BirtRunner.properties:

1. test.home=<test directory, birt-test-suite.zip is unzipped to this folder>

2. jvm.15.home=< where the jvm 1.5 installed>

3. os=windows

4. test-output-dir=<test report output directory>

The bootstrap script for Windows OS is BirtRunner.bat. Double-click the BirtRunner.bat. Double-click the BirtRunner.bat to start the tests.

Run All Tests on Linux

The bootstrap script for Linux is BirtRunner.sh. Double-click the BirtRunner.sh,

Set three variables correctly in ant property file BirtRunner.properties:

1. test.home=<test directory, birt-test-suite.zip is unzipped to this folder>

2. jvm.15.home=< where the jvm 1.5 installed>

3. os=linux

4. test-output-dir=<test report output directory>

Start the test by command:

>./BirtRunner.sh start

Check Test Results

The output result files are in xml format. They can be found in folder ${test-output-dir}.

Run Single Test Plugin

If you like to run certain test plugin instead of all test plugins, follow below steps:

1. Switch to command mode(Windows)

2. Enter into the test plugin directory. (e.g. D:\tmp\eclipse\plugins\org.eclipse.birt.report.engine.tests_2.2.1.v20070821-0630 )

3. Start the JUnit test by command:

Windows

ant -f test.xml -Dos=windows -Declipse-home=<main test directory> -Dtest-output=<output file path> -Djvm=<JVM path> -Dvmargs=<vm args>

Linux

ant -f test.xml -Dos=linux -Declipse-home=<main test directory> -Dtest-output=<output file path> -Djvm=<JVM path> -Dvmargs=<vm args>

The output xml file can be found at the ${test-output}.

Generate HTML Test Reports

The xml test reports can be transformed to html reports by JUNIT.XSL, which locates in org.eclipse.birt.tests plugin.

Note:

Before transforming, all xml reports need to add root node <testsuites>. The original root node is <testsuite>.

Following steps are transforming to HTML reports by ant script.

1. Modify all xml reports’ root node to <testsuites> manually.

2. Set variable test-output-html-dir to the html result folder you want.

3. Enter to ${test.home} directory

4. Run ant command: ant -f BirtRunner.xml -propertyfile BirtRunner.properties genHtml

After the execution, the html reports can be found under folder ${ test-output-html-dir }

Update Test Plugins

If BIRT plugins/test plugins were changed and users like to rerun the automated tests with changed plugin, they can export changed BIRT plugins/test plugins by PDE and updated to the test environment.

Please follow below steps:

1. Make sure the source code pass compilation in Eclipse workbench

2. Right click the BIRT plugin/test plugin that need to be export.

3. Choose “Export…”->“Plug-in Development”->“Deployable plug-ins and fragments”, press “Next”

4. Set the “Destination” with the directory you like to export to.

5. Switch to “Options” tab, uncheck the option “Package plug-ins” as individual JAR archives” for test plugins

6. Click “Finish”.

7. The exported binary test plugins can be found in destination folder after execution. Update the export plugins to your own test environment and rerun the tests.