Building Projects in Eclipse
Eclipse supports several different types of projects, but Pentaho only uses the simple and Java project types. Simple projects have the most basic Eclipse project configuration and capabilities, which encompasses little more than file browsing. Java projects contain source code that needs compiling, and configuration files such as the .classpath file which references all the java libraries required by the project. The assembly is an example of a simple Eclipse project that contains no Java sources. The rest of the platform projects are Java projects.
To complete the example development setup for debugging that follows, you must clone the following projects:
Checking Out: Get the Latest Code
Pentaho is in the process of transitioning from Subversion to Git as our source code repository. While most projects are still in Subversion, more will be migrated to Git hosted on GitHub.com in priority based on level of active development. Some unmaintained projects will most likely remain in Subversion, though you will not be working with them anyway.
Cloning Github Repositories
- Switch to the Git Repository perspective
- Select the "Clone an Existing Repository" option
- Enter the HTTP URI for your GitHub Fork, e.g https://github.com/joe-user/pentaho-platform.git
- Enter your username and password then select "Next"
- In the branch selection screen, select "master" or whichever branches you're developing against and select "Next"
- Select the location to store the repository clone on disk.
- In the "Projects" section select the "Import all existing projects" option and "Finish" the dialog.
If your cloned project does not show up in the "Java" perspective, right-click the repository in Repository Explorer and select the "Import Projects..." option. Follow the options for a "General Project".
Checking Out Subversion Stored Projects
The recommended structure for the projects you are pulling from Subversion is to check them out as sibling directories. This structure acommodates the Eclipse project paradigm well, since each Pentaho project owns a .classpath and .project file for Eclipse (with very few exceptions).
- Change your Eclipse perspective to the SVN Repository Exploring perspective.
- If you haven't already done so, you will need to set up a connection to the Pentaho Subversion repository, which houses the Pentaho source code.
- Expand the repository connection, and navigate to the project you want to retrieve.
- You want to checkout the project at the parent directory that contains the .project file. Under most circumstances, this is the trunk directory. However, there are exceptions. For example, the platform projects all live under the same parent trunk directory, so you want to check each of those projects out at the trunk/<project name> level.
- Right click on the directory you wish to perform a check out on.
- From the popup menu, select Checkout...
- The Checkout from SVN Wizard will load. Follow the instructions in the wizard to checkout the project to your workspace.
- When prompted for an Eclipse project name, use the same name the project had in Subversion.
- Repeat these steps for each project listed above.
NOTE: You don't have to check out the projects individually, you can select all projects under trunk and do a full checkout of everything at one time.
Compile Errors on Checkout
Since the projects are using IVY as a dependency manager, the initial compile will most likely fail due to missing library files (jar files). As long as your Eclipse environment is set to "Build Automatically", ivyDE will immediately begin to download any missing jar files which may take a few minute. After ivyDE is finished resolving dependencies the compile errors should go away. If there are still build problems, you most likely do not have the required projects checked out.
Getting the Dependencies
As each project is checked out and built, the ivyDE Eclipse plugin will automatically resolve that project's dependencies and reference them in an Eclipse classpath container called ivy.xml.
IVY dependency resolution
ivyDE does not resolve dependencies the same way that
ant resolve would. If you expand the ivy.xml classpath container in your project you will notice that the jar files it references live in <home>/.ivy2/cache and not a lib dir in your project. If you are developing outside of Eclipse and just want to build with Ant, you would run ant resolve, which does populate a lib dir in your project.
ivyDE will keep your project's dependencies in sync with your Eclipse environment, just right click on the ivy.xml classpath container (in the Eclipse Package Explorer view) and select Resolve to update your dependencies when needed. For more information on using ivyDE, see Developing with ivyDE.
Compiling the Code
If your Build Automatically setting is active, you will notice that the project is compiled immediately after checking out all of the required projects. The project may compile with warnings, but will not complete if there are compilation errors. This task could take several minutes, depending on the speed of your computer.
Set the codegen to your platform for the pentaho-open-admin-console project. Right click the project in package explorer and select properties. Select Java Build Path in the left pane and then select Libraries. Select ivy.xml and press Edit.... Check source and codegen-XXX where XXX is win, linux or mac.
If the projects do not compile automatically after you checkout all of the required projects, select the specific projects you want to compile from the view on the left, then click on Build Project in the Project menu. Sometimes selecting Project/Clean... and then Clean all projects will set things straight.
Using Eclipse without IvyDE
You can generate an Eclipse .classpath file using ant by using "ant resolve" and then "ant create-dot-classpath".
For the Pentaho platform sub-projects you should start by "core". Make sure to export the dependencies in the project. In Eclipse, create dependencies to "core", "api" and then build up that way towards the other sub-projects until all dependencies are resolved.
In Case of Problems
If you experience errors, take the necessary steps to resolve them before moving forward. The typical reasons for compilation errors when setting up the project for the first time are the module structure not following the recommended hierarchy, and a third-party library is missing from the Eclipse classpath (by way of the ivy.xml container).
If you're still having trouble, submit the compilation error that Eclipse is reporting to the Pentaho BI forum.