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, maintenance, and testing.
Starting with the Teiid Designer 8.0 release, we have moved to the source code to a git repository. In this article, we'll first go over how to get a copy of the latest source code from git. Next, we'll show you how to configure your Eclipse IDE and how to perform a local maven build. Finallly, we'll show you how to run the Teiid Designer tests.
To build Teiid Designer, you will need maven. If you don't have maven installed on your system already, you can download here.
NOTE: Currently we require maven 3.0.x for the Teiid Designer build. Verify by typing $mvn -version at a command prompt.
The required jboss profiles are included in the provided settings.xml file. Please edit your local maven installation configuration settings.xml to include these profiles. Your installation configuration can be found at <my_maven_install>/conf/settings.xml.
The official code repository for Teiid Designer is now located here on github.
- First, install git on your local system. If you are new to git, please refer to these instructions.
- Follow our Get the Code section on github, which shows you how to create your own fork of the github repository and clone the fork to your file system.
- You are now ready to set up your Eclipse environment.
If you need to install Eclipse, you can download it here: Eclipse Downloads. Download the 'Eclipse Standard' version, or any version that includes the PDE (Plugin Development Environment) feature. We will assume that you are downloading Eclipse version 4.3 (Kepler) or higher.
Once you have downloaded, go ahead and launch Eclipse. Now, there are a few things you need to do:
- Make sure the correct JRE is installed,
- Import Teiid Designer preferences,
- Install EGit plugins and connect to git repository,
- Install Target Platform and set API Baseline, and
- Import the Teiid Designer projects.
In Eclipse preferences, make sure that:
- the installed JRE 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 1.6 JRE, 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 your local git repository at <INSTALL_LOC>/teiid-designer/scripts/eclipse.
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 git as its source code management system. In order to work with git from within the IDE we recommend installing the EGit plugin , then setup the git repository in your eclipse dev environment. Here are the steps:
- Install the EGit plugins by running Help -> Install New Software.
- Select Kepler - http://download.eclipse.org/releases/kepler in the Work with: drop-down. Replace kepler if you are using a different Eclipse installation.
- Under Collaboration, select Eclipse EGit.
- Click Next -> Next, accept licensing terms, and click Finish to finish the Install wizard.
- When prompted, restart your Eclipse IDE.
- In Eclipse, open the Git Repositories view by running Window -> Show View -> Other -> Git -> Git Repositories.
- On the Git Repositories view, click the link: Add an existing local Git repository (you already have a local git repo)
- In the dialog, browse to your git repo on your local file system: <INSTALL_LOC>/teiid-designer
- Click Finish to complete the wizard.
The Eclipse Target Platform is used to compile and test the Teiid Designer plug-ins. 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).
We have included a version controlled Eclipse target file and the ability to generate the Designer target platform, as described below:
- The Target Platform target file is located in the local git repo at <INSTALL_LOC>/teiid-designer/target-platform/teiid-designer.target.
- It is possible to regenerate this file by executing the build.sh (or build.bat) script located in the same directory.
- Now, in your Eclipse IDE, open the target definition file using File -> Open File...
- Use File -> Open File... then navigate to the target definition file at <INSTALL_LOC>/teiid-designer/target-platform/teiid-designer.target . Click OK to accept.
- Eclipse will start resolving and downloading all of the required dependencies (this may take several minutes).
- Finally, set the Target Platform in your Eclipse preferences: Go to Preferences -> Plug-in Development -> Target Platform , then select/check the teiid-designer target platform.
You will need to define a Plug-in Development 'API Baseline' in Eclipse.
- In your Eclipse preferences, go to Preferences -> Plug-in Development -> API Baselines . On the API Baselines page, click the Add Baseline... button.
- On the New API Baseline dialog, enter a name for your baseline - eg Eclipse42.
- The baseline location may already be pre-filled with the location of your Eclipse installation. If not, browse to an installed eclipse42 location on your file system.
- Click the Reset button, which will load the plugins/bundles.
- Finally, click Finish. Make sure the baseline you just created is set as the default
Make sure you have setup your Git repository in your IDE before importing the Teiid Designer projects.
Follow these steps to get the Teiid Designer plugins into your Eclipse workspace:
- In Eclipse, open the Git Repositories view by selecting Window -> Show View -> Other -> Git -> Git Repositories.
- In the Git Repositories View, expand the teiid-designer repository tree and select the Working Directory node. Then Rt-Click >> Import Projects... This starts the Import Projects Wizard.
- In the Import Projects from Git Repository dialog, select Import existing projects. Expand the Working Directory folder, then select the plugins folder. Click Next.
- On the next wizard page, make sure all plugins are selected. Click Finish.
- All Teiid Designer projects are now imported into your Eclipse environment. Perform a full/clean build of all projects.
- The teiid runtime client projects, org.teiid.7.7.x and org.teiid.8.2.x, will initially contain errors concerning their lack of libraries. These libraries are installed through maven using a builder configured on the eclipse projects. This should succeed but may fail if the target platform has not been installed to your local maven repository. Should this be the case, navigate to the target-platform directory and run mvn install. Then try cleaning and building the teiid projects. If the builders succeed then a set of jars will be loaded into the lib directory of each project.
NOTE: I still had Eclipse errors, so I had to run mvn verify to actually build the teiid jars and download all of the jboss jars in the lib directory
- Extra steps if needed: (thanks Paul R.)
Turn off automatic building
Clean then build the teiid plugins
Refresh the teiid plugins
Refresh the lib directories
Turn on automatic building so the rest of the plugins compile correctly
Visually the teiid projects will:
1. Have a red exclamation mark decoration
2. Have a red cross
3. Have no decoration (all is well!)
You must have maven 3.0.x installed. See the Install maven section.
Prior to checking-in changes to the Teiid Designer software repository, you should perform a local build. A build script is contained in the git repository.
To run a build of your local git repo:
- In a terminal window (command-line), change directory to your Teiid Designer source code root directory. For example, cd <INSTALL_LOC>/teiid-designer
- execute the build script: ./build.sh (or build.bat on Windows). If necessary, fix any errors found and re-run.
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.
Under Run -> Run Configurations ..., you will find pre-defined launch configurations for the different platforms (Mac, Linux, and Windows). Select the appropriate launcher and Run. Once Eclipse starts, open the Designer perspective.