Skip to main content
Jump to: navigation, search

Difference between revisions of "BIRT/FAQ/Birt Project"

< BIRT‎ | FAQ
(Using Project Sets: Step By Step)
(Using Project Sets: Step By Step)
Line 56: Line 56:
 
==== Using Project Sets: Step By Step ====
 
==== Using Project Sets: Step By Step ====
 
# From the Java Perspective, select File => Import
 
# From the Java Perspective, select File => Import
# Select Team => Project Set [[Image:ImportTeamProjectSet.zip|right|thumb|50px]]
+
# Select Team => Project Set [[Image:ImportTeamProjectSet.png|right|thumb|50px]]
  
 
=== Q: How do I build BIRT? ===
 
=== Q: How do I build BIRT? ===

Revision as of 08:33, 1 November 2008

< To: BIRT/FAQ

Release Schedule

Q: What is the BIRT release schedule?

The latest BIRT release schedule can be found on the BIRT Project Development Plan pages.

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
    ImportTeamProjectSet.png

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.

We are in the process of creating Team Project Sets that will simplify the process of getting the BIRT source from CVS. If you are interested in using Team Project Sets with BIRT 2.3.0 or 2.3.1, I have created a HowTo on the BirtWorld Blog. I have links to Team Project Set Files on a Subversion server at PSF Files.

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.

BIRTViewerBuildimg1.PNG

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

BIRTViewerBuildimg2.PNG

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.

BIRTViewerBuildimg3.PNG

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.

BIRTViewerBuildimg4.PNG

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

Contribution

Q: How can I contribute to the BIRT Project?

BIRT is an open source project and seeks contributions in many areas:

  • Answer questions in the newsgroup. – As BIRT grows, new people will come to BIRT and ask questions that more experienced users have already answered. A great way to "give back" to the BIRT community is to answer such questions.
  • Try out new builds & features and report suggestions & problems. – BIRT uses an incremental development process: "release early and often." If you're adventerous, try out new builds & features and let us know about bugs, or ways to improve the product.
  • Platform, driver, app server and other integration issues. – The team tests BIRT on a set of plaforms identified in the Project Plan. If you work on a different platform, please try BIRT and report any problems that you find. File bugs using Bugzilla. Please be as specific as possible, since the development team does not have access to your platform.
  • Examples. – Examples help users quickly see what BIRT can do, show how to accomplish tasks, and help the development team visualize how BIRT is used in practice. You can contribute a static example (HTML output of a report), a report design, a code example and more. Please let us know on the newsgroup that you've got an example and we'll work with you to get it onto the web site.
  • Articles. – Articles can include how-to, tutorials, case studies, or brief notes about how to solve a particular problem, integrate with a particular bit of sofware and so on. Please let us know via the newsgroup and we'll work with you to get it onto the web site.
  • Bug fixes. – If you discover a problem or enhancement, and have the time & skills to track down the problem and find a fix; you can submit the fix to the development team as a Bugzilla entry.

Q: How can I help develop BIRT by contributing code?

Interested in joining the BIRT project as a code contributor? Maybe you found a bug and made a patch to the source code to address this, or perhaps you would like to make significant contribution in a specific area.

Eclipse has an extensive process for code contributions and you can find more information on this topic on the How to Contribute to the BIRT Project page.

In brief, you have to earn the right to be Committer. This is done by submitting code patches, bug fixes, etc. or by making a significant contribution in some other way.

Q: Which codeline do I check out from CVS to create my patch?

Instructions about which codeline to use, and contributing to already released versions of BIRT are available on the Which Codeline page.

Futures

Q: How do I find out what the BIRT Project Team is working on next?

The development team publishes Development Plans for all upcoming releases to keep the community informed and provide a mechanism for feedback.

In addition, the Eclipse Bugzilla system is used to track all projects, big and small, that are being worked on for the BIRT project. You can query the Bugzilla system to find out what is assigned to any particular BIRT release.

Q: What other projects might fit within the BIRT project?

The BIRT Project has chosen to focus on reporting for the initial releases. Other possible projects could expand BIRT into many of the dimensions of Business Intelligence:

  • Data Modeling tools for defining schemas, meta data.
  • ETL (Extract, Transform, Load) tools for creating and maintaining the data warehouse.
  • APIs and Frameworks to build business-user query tools for with flexible ad hoc access to data.
  • Analysis tools that enable power-users to slice-and-dice the same data.

Q: How does the BIRT project relate to TPTP, Data Tools, etc.

Eclipse is an active, growing community with new top-level projects being created at a lively pace. The BIRT PMC has an active dialog with these other projects to understand where BIRT can leverage existing or proposed functionality. With a community as dynamic as Eclipse, we adjust our plans to incorporate new functionality as the community evolves.

Back to the top