Building WSO2 Carbon 4.x from Source

Carbon is the middleware platform developed by WSO2 which is a completely open source stack (and also a complete middleware stack, if you are interested... ;-) ) under Apache License v2. However, if you are the kind of person who would like to hack into stuff and make it work the way you want, and you like to play around with the WSO2 platform at source code level...well there is nothing stopping you! I know that you are probably clever enough to figure out most of the things said here, but here are a few tips on building the carbon platform from source, nevertheless.

It is actually pretty straight forward to build from the source. However, let me highlight first that the carbon platform is something that is constantly evolving. So the structure you get in Carbon 4.x might not be there when it comes to Carbon 5. Similarly, the structure in older versions would be somewhat different.

Breaking down the structure.

The structure of Carbon 4 is mainly composed of three parts.

• Orbit - Bundles third party dependencies that are needed for building, but not maintained by WSO2.
• Kernel - This contains the core/kernel of the platform
• Platform - Contains the whole platform with all the products, tests and all.

To build the platform, you've got to build in that order. That's right... orbit, kernel and platform. If you are building for the first time, it is advisable to build from a branch or a tag and not from the trunk. This is mainly because active development takes place on the trunk and you'll find code in a branch to be more stable. You can access the WSO2 SVN repository from here.

Prerequisites

Before building please make sure that you have the following pre-requisites.

1. Java JDK 1.6 or 1.7
2. Maven 3 or above
3. SVN client
4. A working internet connection when building for the first time (Maven will download any required artifacts to your local maven repository the first time you build)

Please ensure that all the path and environment variables are set properly as well.

Also, it is advisable to increase the allocated memory parameters for maven before you start building since the carbon platform is quite large. You can adjust those by specifying Java heap sizes and perm sizes in the MAVEN_OPTS environment variable. You can set it temporarily, put it to a start-up script or whatever way you prefer. It should be similar to following.

MAVEN_OPTS=" -Xms256m -Xmx1024m -XX:MaxPermSize=512m"

If you have enough memory, then don't hold back and increase those Xmx,XX:PermSize parameters. The more the merrier!

Building the source

Now for the actual building from the code. Checkout from the proper SVN location to build. For example, if you want to build the kernel 4.0.0 branch, you can run the following command.

svn co https://svn.wso2.org/repos/wso2/carbon/kernel/branches/4.0.0/ kernel-4.0.0

After, that simply go to the checked out directory and run

mvn install

While simply running the above command is prim and proper, you probably wouldn't want to build the entire platform with all the tests the first time you build. So first build without the tests which will be much faster. Run

mvn install -Dmaven.test.skip=true

As above, make sure you checkout and build corresponding versions of orbit,kernel and platform, in that same order.

Niceties of a carbon build

About Patch Releases

Building carbon as specified is above is all right. But there are certain dependencies if you want to build a patch release version of the platform. You will find that different products were released under different patch release versions. If you want to build a particular a product, you have to build from the relevant carbon patch release version, rather than from the branch itself. You can get more information about the release of each product and their corresponding patch release version from http://wso2.com/products/carbon/release-matrix/. 

If you want to build ESB 4.6.0 from source, you'll see that the corresponding patch-release version is 4.0.6. So go to you checkout of carbon-4.0.0 platform, and go to 'patch-releases/4.0.6/ directory. Run 'mvn install' from there and only that patch-release will be built along with its dependencies. After the build is finished, you can find the packaged product inside the platform checkout in  'products/<product_name>/<product_version>/modules/distribution/target

For example, for ESB 4.6.0, you will find the packaged zip as 'products/esb/4.6.0/modules/distribtuon/target/wso2esb-4.6.0.zip'

Artifacts in WSO2 Maven Repository

After a product is released, the relevant artifacts are pushed to the WSO2 maven repository which is hosted publicly. Because of this, you should be able to download some required artifacts without building it in your local machine. For example, you can build the kernel without building orbit because the relevant orbit bundles are available in the WSO2 maven repository. However, if you are trying to build something on Monday with dependent artifacts that were released last Friday, there is a good chance those artifacts aren't available in the public repository as yet. So it is always a good idea to build from ground up if you are trying to build the latest patch-release for the latest branch.

Kernel Dependencies for Patch Releases

Another fact is, if you are building one of the patch-releases you have to know the kernel patch-release version which it depends on. This particular issue applies to the carbon 4.0.x branch. So if you are building a particular carbon platform patch-release, you've got to build the relevant kernel patch-release as well. Here are the platform patch-release to kernel patch-release mappings.

Platform Patch Release Ver.	Kernel Patch Release Ver.
4.0.1	4.0.1
4.0.2	4.0.2
4.0.3	4.0.3
4.0.4	4.0.4
4.0.5	4.0.5
4.0.6	4.0.5
4.0.7	4.0.6
4.0.8	4.0.7

Have fun hacking into code. If you run in to any issues building, please raise a query at Stackoverflow or drop a mail to dev@ mailing list at wso2.org.