The Teiid Designer project is a set of Eclipse-based features and plugins. Therefore, Teiid Designer runs within the Eclipse runtime platform. Teiid Designer can also be developed using the Eclipse IDE. This document describes how to setup an Eclipse IDE for Teiid Designer development, maintainence, and testing. First we'll go over how to get a copy of the latest source code, which includes code from both the Teiid Designer project and the JBoss Tools project; then we'll show you how to configure your Eclipse IDE and how to perform a local maven build; and lastly, how to test Teiid Designer by running it within your IDE.
Not only will you need the Teiid Designer source code, you will also need the JBoss Tools' build project and one of JBoss Tools' SWTBot projects. Both Teiid Designer and JBoss Tools currently use Subversion (SVN) for source code management.
Follow these steps to obtain a local copy of the latest (trunk) Teiid Designer source code for the first time:
- Create a directory where you want to put the latest Teiid Designer code. For example, mkdir ~/projects/teiid-designer/trunk.
- At a command-line prompt, change directory to the trunk directory. For example, cd ~/projects/teiid-designer/trunk.
- Issue one of these commands to download the latest Teiid Designer source code:
Follow these steps to obtain a local copy of the latest (trunk) JBoss Tools' build project for the first time:
- Create a directory where you want to put the JBoss Tools' build project. For example, mkdir ~/projects/jbosstools/trunk/build.
- At a command-line prompt, change directory to the build directory. For example, cd ~/projects/jbosstools/trunk/build.
- Issue one of these commands to download the supporting code within the JBoss Tools build project:
- For committer trunk (login required); svn co https://svn.jboss.org/repos/jbosstools/trunk/build . (space dot at the end), or
- For anonymous trunk: svn co http://anonsvn.jboss.org/repos/jbosstools/trunk/build . (space dot at the end).
Follow these steps to obtain a local copy of the latest (trunk) JBoss Tools' SWTBot project required by Teiid Designer:
- The project is located in the tests/plugins/org.jboss.tools.ui.bot.ext directory under trunk. Create a directory where you want to put the one SWTBot project. For instance, mkdir ~/projects/jbosstools/trunk/tests/plugins/org.jboss.tools.ui.bot.ext.
- At a command-line prompt, change directory to that directory created in the previous step. For example, cd ~/projects/jbosstools/trunk/tests/plugins/org.jboss.tools.ui.bot.ext.
- Issue one of the following commands to download the required SWTBot project:
- For committer trunk (login required); svn co https://svn.jboss.org/repos/jbosstools/trunk/tests/plugins/org.jboss.tools.ui.bot.ext . (space dot at the end), or
- For anonymous trunk: svn co http://anonsvn.jboss.org/repos/jbosstools/trunk/tests/plugins/org.jboss.tools.ui.bot.ext . (space dot at the end).
When you need to work with source code branches, just follow the steps above but replace trunk with the specific branch you will be working with.
If you need to install Eclipse to use as your IDE you can download it here: Eclipse Downloads. Make sure you download a version that includes the PDE (Plugin Development Environment) feature.
After starting up the Eclipse IDE for the first time there a few things you need to do:
- make sure the correct JRE is installed,
- install Teiid Designer preferences,
- install SVN and create SVN repositories,
- install target platform, and
- import Teiid Designer projects.
In Eclipse preferences, make sure that:
- the installed JRE should is set to 1.6 (Preferences -> Java -> Installed JREs), and
- the Java compiler compliance level is set to 1.6 (Preferences -> Java -> Compiler -> Compiler compliance level).
If you don't have JRE 1.6 you can download one here: Java SE Downloads.
Make sure you have checked-out the Teiid Designer source code.
The Teiid Designer Eclipse IDE preferences are stored in the eclipse-preferences.epf file found in the trunk directory we checked out from SVN (see Check It Out). Import this file using File -> Import... -> General -> Preferences. These preferences help ensure we maintain better coding standards and minimize the differences between changes made by committers and previous code versions.
Teiid Designer uses Subversion (SVN) as its source code management system. In order to work with SVN from within the IDE you must install the SVN plugins and create the SVN source code repositories. Here are the steps:
- Install the SVN plugins by running Help -> Install New Software.
- Select http://download.eclipse.org/releases/indigo in the Work with: drop-down. Replace indigo with the release name of the Eclipse installation being used
- Under Collaboration select Subversive SVN Team Provider and Subversive JDT Ignore Extensions.
- Click Next -> Next, accept licensing terms, and click Finish to finish the Install wizard.
- When prompted, restart your Eclipse IDE.
- When Eclipse restarts you might be asked to select an SVNKit. Select the latest, compatible one for the target platform and complete the wizard.
- In Eclipse, open the SVN repositories view by running Window -> Show View -> Other -> SVN -> SVN Repositories. You will need to create 2 repositories using this view.
- Create a new repository for the Teiid Designer source code by using one of these URLs:
- Create new repository for the JBoss Tools project using one of these URLs:
The Eclipse Target Platform is used to compile and test the Teiid Designer plug-ins against. The target platform consists of the Eclipse runtime binaries for your operating system, any additional Eclipse features, and any required 3rd-party features and plug-ins. In the case of Teiid Designer, these additional Eclipse features are required: the Eclipse Modeling Framework (EMF), Unified Modeling Language 2.0 (UML2), Eclipse Graphical Editing Framework (GEF), Eclipse Data Tools Project (DTP), and the Eclipse Web Tools Platform (WTP).
One way to create the target platform is to define it manually. Manually creating the target platform requires you to install another Eclipse and install, in that new install, all the required features and plugins needed mentioned above. An alternative to manually creating the target platform is to use a target definition file. Eclipse documentation states that "A target definition file specifies all aspects of a target - including its location, constituent plug-ins and environment." JBoss Tools, the parent project of Teiid Designer, contains several target platform definition files that it uses to perform the various builds of products and releases. These JBoss Tools target definitions already have the correct version of the Eclipse runtime and all the required additional features and plug-ins to match the release or product that Teiid Designer is being developed for.
Make sure you have obtained a local copy of the JBoss Tools build project.
JBoss Tools target definition files are found in the JBoss Tools source code repository. Using one of these target definition files as your Teiid Designer target platform ensures the target platform you are developing and testing against, agrees with the target platform JBoss Tools is going to use. To use a JBoss Tools target platform definition file, follow these steps:
- In your Eclipse IDE, import the JBoss Tools jboss-trunk-build project into your workspace by selecting File -> Import... -> Existing projects into workspace.
- Select the root directory where you put the build project. For example, ~/projects/jbosstools/trunk/build.
- Select to import jboss-trunk-build project and click Finish to complete the Import Projects wizard. The target definitions files are located under the target-platform directory.
- In Preferences -> Plug-in Development -> Target Platform select/check the appropriate target platform. The unified.target file is a good one to use.
- With the unified.target target platform selected, hit the Reload... This will start downloading all the Eclipse features and plugins required.
To create a target platform manually, use the following steps:
- Download and install the Eclipse IDE for Java EE Developers in the directory of your choosing. For instance, mkdir ~/target-platforms/eclipse3.7.2. Yes this is a different installation of Eclipse than the one installed earlier for your IDE.
- Run this new installation of Eclipse and select Help -> Install New Software.
- Select http://download.eclipse.org/releases/indigo. Replace indigo with the release name of the target platform Eclipse runtime in the Work with: drop-down.
- Under Database Development select both "Extender SDK's."
- Under Modeling select the following:
a) EMF - Eclipse Modeling Framework SDK
b) Graphical Editing Framework GEF SDK
c) UML2 Extender SDK
d) XSD - XML Schema Definition SDK
- Under Web, XML, Java EE and OSGi Development select the following:
a) Eclipse Jave Web Developer Tools
c) JST Server UI
d) WST Server Adapters
- Click Next -> Next, accept the licensing terms, and click Next -> Finish to complete the Install wizard.
- When prompted, restart Eclipse so that all these new plugins will be installed.
- Now, exit this version of Eclipse.
- Back in your Eclipse IDE, select Preferences -> Plug-in Development -> Target Platform and click Add... to create a new target definition.
- Choose Nothing: Start with an empty target definition in the New Target Definition wizard and click Next >.
- On the Locations tab, click Add..., select Directory, then Next >, and browse to the directory of where you installed the target platform Eclipse in the first step. If you selected the correct directory (where the command to run Eclipse is located), then all this target platform's contents will load and show.
- Click Finish and select/check this new target platform as the active/default target platform.
Make sure you have setup your SVN repositories in your IDE before importing the Teiid Designer and JBoss Tools projects.
Once you've checked out the source code, you are ready to import projects. Follow these steps to get the Teiid Designer and supporting JBoss Tools projects into your Eclipse workspace:
- Run File -> Import... -> Existing projects into workspace.
- Select the root directory where you have put the Teiid Designer projects. For example, ~/projects/teiid-designer/trunk.
- The Projects list should be filled up. Deselect any projects that are found in the deprecated directory and press Finish to get all of the projects into your Eclipse workspace. Currently these are the deprecated projects: org.teiid.designer.rose, org.teiid.designer.rose.ui, org.teiid.designer.vdb.edit, and org.teiid.designer.vdb.edit.test.
- Click Finish to complete the Import Projects wizard.
- Run the wizard again the time for the JBoss Tools SWTBot project: File -> Import... -> Existing into workspace.
- Select the root directory where you have put the JBoss Tools SWTBot project. For example, ~/projects/jbosstools/trunk/tests/plugins/org.jboss.tools.ui.bot.ext.
- Select to import the org.jboss.tools.ui.bot.ext project in the Projects list and Finish the Import Projects wizard.
- Perform a full/clean build of all projects.
If you ever update source code the command-line SVN you will need to refresh your Eclipse workspace.
Must have Maven 3 installed.
Prior to checking-in changes to the Teiid Designer software repository, you should perform a local build. Performng a local build, which uses the same build scripts the JBoss Tools nightly builds use, is the best way to prevent build issues. Here are the steps to do a local build:
- In a terminal window (command-line):
- change directory to your JBoss Tools build directory. For example, cd ~/projects/jbosstools/trunk/build.
- make sure you have the latest souce code by running: svn update.
- change directory to your JBoss Tools SWTBot project directory. For example, cd ~/projects/jbosstools/trunk/tests/plugins/org.jboss.tools.ui.bot.ext.
- make sure you have the latest source code by running: svn update.
- change directory to your Teiid Designer source code root directory. For example, cd ~/projects/teiid-designer/trunk.
- make sure you have the latest source code from running: svn update.
- In the Teiid Designer tests directory, edit the pom.xml file. For example, ~/projects/teiid-designer/trunk/tests/pom.xml. Comment out the Teiid Designer SWTBot test plugins. This edit is necessary because the SWTBot tests currently fail when building locally.
- In terminal window (command-line):
change directory to your Teiid Designer source code root directory. For example, cd ~/projects/teiid-designer/trunk.
- Run this command: mvn install -P jbosstools-nightly-staging-composite,jbosstools-nightly-staging-composite-soa-tooling,unified.target. If necessary, fix any errors found and rerun.
If you don't want to run tests you can add the following option to the above mvn command: -Dmaven.test.skip=true. However, tests should always be run prior to checking-in code.
Remember NOT to check-in the tests/pom.xml file that was changed above.
Under Run -> Run Configurations ..., you will find predefined launch configurations for the different platforms (Mac, Linux, and Windows). Select the appropriate launcher and Run. Once Eclipse starts, there will be a Designer perspective available to open.