Fork me on GitHub

n. Slang a rough lawless young Kuali developer.
[perhaps variant of Houlihan, Irish surname]
kualiganism n

Blog of an rSmart Java Developer. Full of code examples, solutions, best practices, et al.

Tuesday, June 14, 2011

Convert Your KFS Distribution to Maven

Overview

I am going to cover the process/steps for converting your KFS distribution to use maven. The two greatest reasons for doing this is for development and building/releasing the software. Using maven will make your distribution more consistent with other Kuali projects, get your transitive dependency management, simplify your build process, and simplify your development process with convention over configuration.

At first, this may seem to be a daunting task to move from ant to maven, but it is actually pretty simple. The properties file conventions in KFS do not make this any more difficult as one would think. We can still use maven.

Steps

Before I begin, I want to point out that this assumes you are working with a fresh checkout of the KFS from http://test.kuali.org/svn/kfs/branches/release-4-0-br. You can use 4.1.1 as well. The important thing to note is that it's KFS 4.x.

1 Create path structure

In the directory where KFS is checked out, I suggest first creating all the necessary directories for maven. On Mac or Linux, this is as simple as the following command(s):
% mkdir -p src/main/java src/main/resources src/main/webapp src/main/config src/test/resources src/test/config

2 Copy build components to necessary project configuration locations

build components are typically located in your build/ directory in you KFS project. To do this, I like to use rsync because then I can exclude .svn and .git metadata.
% rsync -avC distribution/ external/ helper-scripts/ project/ properties/ tomcat/ upgrades/ src/main/config/
I have left out the library directories because maven handles our dependencies for us. There is no longer any reason to include the jars in the project. I am not completely sure if tomcat is necessary either, but I left it until later when I can decide if I really need it or not.

3 Move any other project configuration

I consider workflow doctypes, ddl, and dml to be project configuration metadata. These are typically in work/db and work/workflow respectively. I want them to be in src/main/config with the rest of my project configuration.
% mv work/workflow work/db src/main/config

4 Relocate java sources and project resources

Project resources are really anything that isn't a java source. These are going into src/main/resources. Java sources will go into src/main/java. Currently, the KFS project lumps these up into work/src. I am going to split this up.

First, I want to copy the source.

% rsync -avC work/src src2
Now I can do with it what I want which is to remove all the java source from it.
% find src2/ -name \*.java -exec {} \;

Copy project resources

Now that the java code is gone I copy the resources
% rsync -avC src2/* src/main/resources
% rm -rf src2

Copy java sources

I got all the resources, now I will move all my java source.
% find work/src \! -name \*.java -type f -exec rm {} \
% rsync -avC work/src/* src/main/java

5 Relocate tests

I like the way KFS has separated tests. They're interdependent still, but maven also differentiates between test types. I'll keep this separation and move the tests over to src/test/java
% rm -rf test/lib
% mv test/* src/test/java

6 Clean up a little

Now I get rid of all the unnecessary stuff
% rm -rf test work build *.xml
You should now have something that looks like this
leo@behemoth~/.workspace/kfs/release-4-0-mvn
(15:59:41) [6] ls
cnv-build.properties ptd-build.properties src
dev-build.properties reg-build.properties
leo@behemoth~/.workspace/kfs/release-4-0-mvn
(15:59:42) [7]

Crazy, right?

7 Get the pom.xml

To make things easy. I have a pom already. You can get it like this:
% svn export https://svn.rsmart.com/svn/kuali/contribution/community/travel_module/branches/release-4-0-mvn/pom.xml

I'm not going to paste it in here. It's too long.
For the most part, you will not need to change the pom.xml. The groupId, artifactid, or version may be properties about the project you will want to change. Other than that, everything should be peachy and ready to go (with the pom.xml at least).

8 Fix some properties in KFS

There are a couple things that do not jive with maven's conventions in the old KFS. Some are directory structure related. Mostly is the use of ant.project.name allover the place. This property is specific to ant only and not very generic. Therefore, it cannot be used with maven. Maven had the right idea by going with generic property name like project.name

Fix ant.project.name

First, thing to do is clean this up. I used grep to determine where al it's used
leo@behemoth~/.workspace/kfs/travel_module/build/properties
(16:07:09) [5] grep -l ant.project.name *
build-foundation.properties
directory.properties
email.properties
url.properties
I just went through those files and replaced ant. with nothing.

Fix directory properties

Next, is to fix all the properties that point to non-conventional places.
webroot.directory=src/main/webapp
build.directory=src/main/config

Maven Overlay!

The following are more about setting up an overlay project.

9 Install the war

We install the war in our local repository
% mvn -Dmaven.test.skip=true install

10 Create a jar and install it

We need both jar and war to do the overlay, so let's create one and install it.
% mvn jar:jar
% mvn install:install-file -Dpackaging=jar -DgroupId=org.kuali.kfs -DartifactId=kfs -Dversion=4.0 -DgeneratePom=true -Dfile=target/kfs-dev.jar

11 Setup your overlay

Now you pretty much just repeat steps 1-3. This is mostly to get the build configuration going again. Everything will be overlaid on top of the existing war, so we don't need to add resources our java sources.

12 Copy overlay pom.xml

Just like with the KFS project pom.xml, I have a good overlay pom with the dependencies setup just right!
%  svn export https://svn.rsmart.com/svn/kuali/contribution/community/travel_module/branches/release-4-0-overlay/pom.xml


That's it!!! You now have mavenized KFS and you're using an overlay to boot!

Want to see how I did it? Checkout the Mavenize KFS Screencasts

2 comments:

  1. Hey Leo,

    Looks like your pom.xml requires authentication to access. Can you address this?

    I am really curious how your's compares to ours at Cornell since we have done this since 3.0.1

    -kevin

    ReplyDelete