After all, if it's open source, means we can compile it, right?

I'm sure you've guessed by now this is not an original image from me even though I've been told I'm very good at drawing stuff - and I always believe my daughter!


Sure - but sometimes it's not as easy as it seems. However, we're doing a huge consolidation work to streamline all our build processes. Historically, each project, specially the older ones (kettle, mondrian, prd, ctools) used each own build method, depending on the author's personal stance on them (and boy, there are some heavy opinions in here...)


Personally, I come from the CCLJTMHIWAPMIS school of thought (for the ones not familiar with it, the acronym means Couldn't Care Less Just Tell Me How It Works And Please Make It Simple, very popular specially within lazy Portuguese people).


And we're now doing this, slowly and surely, to all projects, as you can see from browsing through Pentaho's Github.


So let's take a look at an example - building Pentaho Platform from source. Please note that we'll try to make sure the project's README.md contains the correct instructions. Also, this won't work for all versions, as we don't backport this changes; In the case of Pentaho Platform, this works for master and will appear in 7.1. Other will have it's own timeline.


Compiling Pentaho Platform

1. Clone it from source

Ok, so step one, clone it from source:


(or use git:// if you already have a user)
2. Set up your m2 config right

Before compiling it, you need to set some stuff in your maven settings file. In your home directory, under the .m2 folder, place this settings file. If you already one m2 settings files, that means you're probably familiar with maven in the first place and will know how to merge the two. Don't ask me, I have no clue.


If you're wondering why we need a specific settings file... I wonder too, but since my laziness is bigger than my curiosity (CCLJTMHIWAPMIS, remember?) I think I zoned out when they were explaining it to me and now I forgot.
3. Build it

This one is easy :)
$ mvn clean package
or the equivalent without the tests:
$ mvn clean package -Dmaven.test.skip=true
If all goes well, you should see





[INFO]
[INFO] --- maven-site-plugin:3.4:attach-descriptor (attach-site-descriptor) @ pentaho-server-ce ---
[INFO]
[INFO] --- maven-assembly-plugin:3.0.0:single (assembly_package) @ pentaho-server-ce ---
[INFO] Building zip: /Users/pedro/tex/pentaho/pentaho-platform-master/assemblies/pentaho-server/target/pentaho-server-ce-7.1-SNAPSHOT.zip
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] Pentaho BI Platform Community Edition .............. SUCCESS [ 4.461 s]
[INFO] pentaho-platform-api ............................... SUCCESS [ 10.149 s]
[INFO] pentaho-platform-core .............................. SUCCESS [ 19.819 s]
[INFO] pentaho-platform-repository ........................ SUCCESS [ 2.210 s]
[INFO] pentaho-platform-scheduler ......................... SUCCESS [ 0.172 s]
[INFO] pentaho-platform-build-utils ....................... SUCCESS [ 1.695 s]
[INFO] pentaho-platform-extensions ........................ SUCCESS [01:22 min]
[INFO] pentaho-user-console ............................... SUCCESS [ 19.596 s]
[INFO] Platform assemblies ................................ SUCCESS [ 0.059 s]
[INFO] pentaho-user-console-package ....................... SUCCESS [ 16.399 s]
[INFO] pentaho-samples .................................... SUCCESS [ 1.159 s]
[INFO] pentaho-plugin-samples ............................. SUCCESS [ 11.129 s]
[INFO] pentaho-war ........................................ SUCCESS [ 45.434 s]
[INFO] pentaho-style ...................................... SUCCESS [ 0.742 s]
[INFO] pentaho-data ....................................... SUCCESS [ 0.211 s]
[INFO] pentaho-solutions .................................. SUCCESS [31:31 min]
[INFO] pentaho-server-manual-ce ........................... SUCCESS [01:15 min]
[INFO] pentaho-server-ce .................................. SUCCESS [01:51 min]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 38:36 min
[INFO] Finished at: 2017-03-31T15:36:43+01:00
[INFO] Final Memory: 102M/1084M
[INFO] ------------------------------------------------------------------------


There you go! In the end you should see a dist file like assemblies/pentaho-server/target/pentaho-server-ce--SNAPSHOT.zip. Unzip it, run it, done.

Debugging / inspecting the code

So the next thing you'd probably want, would be to be able to inspect and debug the code. This is actually pretty simple and common to all java projects. Goes something like this:


1. Open the project in a Java IDE

Since we use maven, it's pretty straightforward to do this - simply navigate to the folder and open the project as a maven project.


In theory, any java IDE would do, but I had some issues with Netbeans given it uses an outdated version of maven and ended up switching to IntelliJ IDEA.
I actually took this screenshot of IntelliJ myself, so no need to give credits to anyone


2. Define a remote run configuration

Now you need to define a remote debug configuration. It works pretty much the same in all IDEs. Make sure you point to the port of the Java Debug Wire Protocol (JDWP) port you'll be using in the application you're attaching to
Setting up a debug configuration
3. Make sure you start your application with JDWP enabled

This sounds complex, but really isn't. Just make sure your java command includes the following options:
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8044
For pentaho platform is even easier, as you can simply run start-pentaho-debug.sh.


4. Once the server / application is running, simply attach to it

And from this point on, any breakpoints should be intercepted


Inspecting and debugging the code


Submitting your fixes

Now that you know how to compile and debug code, we're a contributor in the works! Let's imagine you add some new functionality or fix a bug, and you want to send it back to us (you do, right???). Here are the steps you need - they may seem extensive but it's really pretty much the normal stuff:

  1. Create a jira
  2. Clone the repository
  3. Implement the improvement / fixes in your repository
  4. Make sure to include a unit test on it (link to how to write a unit test or a sample would be good)
  5. Separate formatting-only commits from actual commits. So if your commit reformats the java class, you need to have a commit with [CHECKSTYLE] as the commit comment. Your main changes including your test case should be in a single commit.
  6. Get the code formatting style template for your IDE and update the year in the copyright header
  7. Issue a pull request against the project
  8. For visibility, add that PR to the jira you created, email me, tweet, whatever it takes. Won't promise it will be fast, but I promise we'll look :)




Hope this is useful!


-pedro



More...