Pentaho Platform 7.0

Owned by Former user (Deleted)
Last updated: Feb 23, 2017 by Former user (Deleted)Version comment

This document describes the steps for setting up the development environment, getting the Pentaho Platform code from GitHub and the tools required to build the platform code. It also outlines the process of building, deploying and debugging the local instance of Pentaho BA server on your machine.

Setting Environment

Following are the list of tools required to build the Pentaho Platform code on your machine 

  • Java Development Kit 8 (JDK 8)
  • Java IDE (Eclipse or IntelliJ)
  • EGit Eclipse plugin (Eclipse only)
  • IvyDE Eclipse Plugin (Eclipse only)
  • GitHub account

The Java Development Kit (JDK)

The Pentaho Platform 7.0 is built and tested using JDK 8. If it is not already installed, please download it here: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

Git and GitHub

At Pentaho, we use Git for version control and store our repositories on GitHub. The Pentaho Platform code is stored in a GitHub repository at https://github.com/pentaho/pentaho-platform. These instructions will help you clone the pentaho-platform GitHub repository to get ready for development if you are unfamiliar on how to do so.

  • Login to your GitHub account at https://github.com. If you do not have a GitHub account, you can create one from the home page.
  • Navigate to the Pentaho Platform GitHub repository at https://github.com/pentaho/pentaho-platform.
  • Select Fork in the upper right area of the page. Select your username from the dialogue window that opens in order to fork the pentaho-platform repository under your account.
  • Download and install a preferred Git client if you do not have one already. These instructions will focus on using Git Bash (command line), but alternative software packages are available, such as SourceTree.
  • Open Git Bash and navigate to a folder on your computer that you wish to clone the pentaho-platform repository to.
  • Run git init to initialize an empty Git repository in your project folder.
  • Run _git clone https://github.com/{username}/pentaho-platform.git_ where {username} is your GitHub account name where you forked the pentaho-platform repository to.

Apache Ant

Apache Ant is a Java library and command line tool primarily used for the building of Java Applications. At Pentaho, we use Ant to build many of our projects. If you would like to learn how to install Ant and it to build the Pentaho Platform, please follow these instructions.

Install

  • Navigate to the Apache Ant Project website and download the latest binary: http://ant.apache.org/bindownload.cgi (file: 
  • Extract the downloaded archive file to an easily accessible folder on your computer.
  • Right click on My Computer and select Properties > Advanced system settings.
  • Select Environmental Variables.
  • Note: If you haven’t, you must add a JAVA_HOME system variable and set it to the path of your JDK installation. If JAVA_HOME is set, you can skip this step.
    • Under System Variables, select New.
    • In the Variable Name field, enter JAVA_HOME.
    • In the Variable Value field, enter in the path of your JDK installation or select the Browse Directory button to select the folder of your JDK installation.
  • Add Ant to your PATH system variable (for Windows 10).
    • Under System Variables, select New.
    • In the Variable name field, enter ANT_HOME.
    • In the Variable Value field, enter in the path of your Ant installation or click the Browse Directory button to select the folder of your Ant installation.
    • Under System Variables, select Path and then Edit.
    • In the dialogue that appears, select New and enter in %ANT_HOME%\bin
    • Select OK to save all changes.
  • (Optional) Open a new Command Prompt window and enter in “ant -version” to verify your installation.

Maven

Maven is a software project management and comprehension tool also used in the building of Java applications. At Pentaho, we currently use both Ant and Maven for our project builds. The installation process for Maven is very similar to the Ant process, as described below.

Install

  • Navigate to the Apache Maven Project website and download the latest binary file: https://maven.apache.org/download.cgi
  • Extract the downloaded archive file to an easily accessible folder on your computer.
  • Right click on My Computer and select Properties > Advanced system settings.
  • Select Environmental Variables.
  • Add Maven to your PATH system variable (for Windows 10).
    • Under System Variables, select Path and then Edit.
    • In the dialogue that appears, select New and enter in the path where you placed the unzipped Maven project, making sure to include the "bin" directory at the end (Ex: C:\Maven\apache-maven-3.3.9\bin)
    • Select OK to save all changes.
  • (Optional) Open a new Command Prompt window and enter in “mvn --version” to verify your installation.

Eclipse IDE

Choosing the Java IDE is a matter of preference. This document describes setting up Eclipse IDE for building and debugging the code. Download the latest Eclipse IDE for Java EE developers from the Eclipse project page and follow the instructions to install Eclipse on you machine.

Eclipse Plugins

Once the Eclipse is installed, download the following plugins-

  • EGit Plugin: This plugin allows you to branch, merge, clone and synchronize Git repository from within Eclipse.
  • IvyDE: Apache's IvyDE is an Eclipse plugin that integrates Apache's IvyDE dependency management into Eclipse. Download the plugin by going to Eclipse: Help->Install New Software and enter the Url. It will display two entries -Apache Ivy Library and Apache Ivy Plugins. Choose version 2.2  for both and click Finish.

Instruction to setup platform code in Eclipse

Follow the steps to setup Pentaho-platform code in Eclipse

  • Login to Gitub account and search for pentaho/pentaho-platform repository
  • Click on Fork to create a local copy of pentaho-platform repository.
  • Go to Eclipse and navigate to Git repository view.
  • Enter the Url of forked repository, username and password of GitHub.
  • Click Next and Finish
  • Import the existing project by selecting File->Import menu.
  • Choose "Existing Projects into Workspace" option
  • Specify the root directory in the file system where the pentaho-platform code lives on your machine.
  • Click on Finish.

For windows environment, make sure to choose a short folder name for folder where the pentaho-platform code is stored. This is required to ensure that the build path does not exceed the maximum length.

Building the code in Eclipse

There are two ways to build the code in Eclipse

  • Ant: In this case, the dependencies gets built into the lib folder of the project
  • IvyDE: In this case, the dependencies get built into the cache folder and Eclipse uses the cache folder to build the code. On Windows, the cache folder can be found at C:\Users\<username>\.ivy2\local\pentaho on your machine. The advantage of using IvyDE to build the dependencies is that if there are multiple projects using these jar files, there is only one physical copy of jar file thereby saving space on hard disk.

Using Ant

Following are the steps to build the project using Ant

  • Right click on the build.xml in the project that you like to build and choose Run As-> Ant Build...
  • The Edit Configuration and launch dialog opens. The Targets tab lists the applicable targets.

          

  • Type and check the following targets 
    • clean-all
    • resolve
    • create-dot-classpath
    • publish-local
  • Uncheck the default target
  • Target execution order displays the selected targets
  • Click Apply to save the selection
  • Click on Run to start the build
  • Once the build is completed successfully, right click on the project and select Refresh. The lib folder in the project will list all the jars that are newly built by the build process.

Using IvyDE

Following are the steps to build the project using IvyDE toolto build the project dependencies

  • Right click on the project and choose properties
  • Select Java Build Path
  • In the Libraries tab, select the Ivy and click on Edit button to open the Ivy managed libraries dialog.  Select the Settings Tab.

           

  • To specify IvySettings path, click on project button. Open the project tree and select ivysettings.xml
  • To specify the Properties Files, click on Add button. Choose project and select build.properties from the project tree.
  • Click Apply to save the changes and then click Ok
  • Right click on the build.xml in the project that you like to build and choose Run As-> Ant Build...
  • The Edit Configuration and launch dialog opens. The Targets tab lists the applicable targets.
  • Type and check the following targets 
    • clean-all
    • resolve
    • publish-local
  • Uncheck default target
  • Target execution order displays the selected targets
  • Click Apply to save the selection
  • Click on Run to start the build

Debugging Pentaho platform code in Eclipse

In order to debug the pentaho platform code, we will need to create a local installation of Pentaho server. Following are the steps to create local installation of pentaho server

  • In Eclipse, open pentaho-platform-assembly project. 
  • Right click on assembly.xml in the project and choose Run As-> Ant Build...
  • The Edit Configuration and launch dialog opens. The Targets tab lists the applicable targets.
  • Type and check the following targets 
    • clean-all
    • resolve
    • assemble
    • package
  • Uncheck default target
  • Target execution order displays the selected targets
  • Click Apply to save the selection
  • Click on Run to start the build.
  • When the build completes successfully, it will create a zip file under dist folder named biserver-ce-7.0-SNAPSHOT.zip.
  • Extract the content of zip file to desired location to create a local installation of pentaho biserver-ce.

Setting up Eclipse debugger

Following are the steps to start a debug session 

  • In Eclipse, go to Run->Debug Configuration.
  • In the Debug Configuration dialog, click on Remote Java Application on the left side. Click New to open the new configuration of selected type
  • Specify the name. In connection properties, specify the port as 8044.
  • Click Apply to save the configuration.

           

  • In windows explorer, navigate to the folder where the local pentaho server is installed.
  • Navigate to biserver-ce folder and double click on start-pentaho-debug.bat to start the pentaho server in debug mode.
  • In Eclipse, open the code file which you want to debug and set the break point.
  • Open the debug configuration and click on the new debug configuration that we just created.
  • Click on Debug button to start the debugger.
  • Start a new browser windows and type http://localhost:8080
  • Eclipse will break the code execution at the break point.

IntelliJ IDEA

JetBrains' IntelliJ IDEA is another potential Java IDE choice for development on the Pentaho Platform. Please note that some features of IntelliJ IDEA may require an Ultimate license for development on the Pentaho Platform.

  • Download and run the IntelliJ IDEA installer from the JetBrains website: https://www.jetbrains.com/idea/download/
  • Open IntelliJ IDEA.
  • If you already have the pentaho-platform code cloned from GitHub as described in the Git and GitHub section above, go to File > Open and select the root folder of the pentaho-platform repository. If you do not already have the pentaho-platform code on your local machine, please fork the pentaho-platform repository on GitHub and select File > New > Project from Version Control > GitHub. Then, enter in the repository URL of your pentaho-platform fork (Ex: {_}https://github.com/{username}/pentaho-platform.git_) in the Git Repository URL field. You do not have to change the Parent Directory or Directory Name unless you wish to. When you are done, select Clone.

Checkstyle

At Pentaho, we use the Checkstyle plugin for IntelliJ IDEA to ensure new code meets our coding standards. Below are the instructions for installing and running the Checkstyle plugin within IntelliJ IDEA.

  • Go to File > Settings... and select Plugins from the left-hand menu in the dialog window that appears.
  • Select Browse repositories... and find the Checkstyle-IDEA plugin. Select the plugin and click Install. (Note: you may need to restart IntelliJ IDEA for changes to take affect).

For the next steps, you will need Pentaho's Checkstyle standards which is located in the pentaho-coding-standards repository located on GitHub (https://github.com/pentaho/pentaho-coding-standards). Please fork this repository and clone it on your local machine.

  • Go to File > Settings... and select Checkstyle under Other Settings from the left-hand menu.
  • Under Configuration File, select the + button.
  • Enter "Pentaho Checkstyle" for the Description. Select Browse and navigate to the directory where you cloned the pentaho-coding-standards repository. Select the pentaho_checkStyle.xml file. Select Next.
  • For the samedir Property Name, enter "." under Value, exactly as that appears (for clarification, enter in the period surrounded by two quotation marks) and select Finish.
  • Select Active for the Pentaho Checkstyle configuration file, and select Scan test classes at the top of the dialog window (this will ensure that any test cases added will also be scanned by Checkstyle). When finished, select Apply and then OK.

At this point, Checkstyle should be successfully installed and configured inside of IntelliJ IDEA. To run a Checkstyle audit on a file, follow these instructions.

  • Make sure to have the file you want to audit open inside of IntelliJ IDEA.
  • Open the CheckStyle tool window. If it is not visible inside of IntelliJ IDEA, go to View > Tool Windows > CheckStyle.
  • In the CheckStyle tool window, select Pentaho Checkstyle under the Rules dropdown. Then, select the green triangular Run button to check the current file open in the editor.

Code Style

The pentaho-coding-standards/README.md explains how to set an appropriate project Code Style (this is separate from the check style).

Resolve Dependencies

To resolve your project dependencies, simply right click the pom.xml of your project, and select "Add as maven project"

Setting Up Debugging

  • Go to build.pentaho.com and download the latest QAT build
    • This will be under /Hosted/(most recent version)-QAT.zip
  • Unzip the file to the C: drive
    • You may run into issues if you do not unzip the package close to the root directory
  • Open IntelliJ
  • Open "Run->Edit Configurations" from the toolbar
  • Press the green '+' button to add a new configuration, select Remote, ensure Host is set to localhost and debugger mode is set to Attach
  • Change the port number to 8044
  • Copy the command line argument labeled "Command line arguments for running remote JVM" into your clipboard
  • Navigate to your unzipped pentaho server file, and open /pentaho-server/start-pentaho-debug.bat in your preferred text editor
  • Find the line "-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8044" and replace it with what you copied
    • change "suspend=n" to "suspend=y"!!!!!!!
  • Put in your desired breakpoints and run start-pentaho-debug.bat from windows cmd line
  • Press shift-f9 in IntelliJ to begin debugging