Continuous Integration for MAF using OEPE and Hudson
By Cameron Bateman
Audience
This article is intended for senior development or release engineers
who want to put their MAF development effort into a standard
“continuous integration build cycle. This article will focus on
using Git and Hudson to achieve this, although the basic concepts are
applicable to other systems.
Helpful Things to Know
The OEPE MAF build system is based on Ant. We will provide all of the
ant script fragments you need to accomplish the goals of this article,
but for debugging purpose it will useful if you already understand know
the basics.
This article also makes use of OEPE (Eclipse), Hudson, Git and a
system shell prompt. Having a basic understanding of how to install and
use these systems is required and not all steps will be given in these
areas because instructions can be found elsewhere.
Things to Install First
To start, download and install the following:
Apache Ant – make sure this is on your path.
Git (http://git-scm.com/downloads) – you will only need the command
line client; we will use the GUI client that comes with OEPE.
Hudson (http://hudson-ci.org/) – for this article it is sufficient to
download the hudson.war and use it in standalone mode.
Android SDK (http://developer.android.com/sdk/index.html) – scroll to
the bottom to "Other Download Options" and you just download the basic
SDK without an IDE. Follow Android instruction as to how to update the
SDK and create and AVD you wish to deploy to the Android emulator;
having an Android device is recommended but not required because your
application will generally deploy faster.
Oracle Enterprise Pack for Eclipse
Create an Android SDK Configuration in OEPE
Before creating a MAF application, it will be helpful to define an
SDK configuration in OEPE. An SDK configuration is used to tell OEPE
what version of a mobile SDK you want to use and where all its
platform-specific tools reside.
To create a new SDK configuration got to Preferences (from the the
Eclipse menu on Mac, from the Windows menu on other platforms) type
"Android"
Click Add... to open the new SDK dialog. Use the file selector (...)
to navigate to the directory with your sdk in it. This is the
directory that contains (among others things) the "platforms" and
"platform-tools" folders.
Click OK. The preference page should now populate with information about the SDK. Click OK on the dialog to save the changes.
Create the App and Test It From OEPE
For this article, we will use the sample application
HelloWorld. To create a new instance of the application, select
File->New->Examples...
In the wizard, select the MAF Examples wizard.
Click "Next >". In the selection page, pick "Hello World" and leave the runtime version as the default (MAF 2.1).
Click "Next >". A default deployment target should be created based on the SDK configuration you created above. Hit Finish.
The application will now be created as three Eclipse projects. You
may be prompted to switch perspectives. Answer "Yes". At the end of
the creation process your OEPE workbench should look like something like
this:
We now have a pre-created, working application in our workspace. We
can test it out by deploying it to an Android device or emulator.
Before proceeding, ensure that your emulator is running or that your
device is correctly connected to your PC by USB. Refer to Android SDK
documentation for more details.
Now lets test the application from OEPE to make sure it works.
Testing the Application From OEPE
Once you have your Android device or emulator running, you can
proceed to deploy your application by clicking on the "Debug" toolbar
dropdown.
Select the "Debug Configurations..." item to open the launch dialog.
Find the "MAF Application" item in the configuration list and
double-click it (or click the "New launch configuration" menu item near
the top-left) to create a new configuration.
Click on "Debug" at the bottom right of the dialog. After the initial
launch sequence dialog completes, your console should open with the
output from the build's progress. Depending on your system and the
speed of your device, this may take a few minutes.
When it finishes you should see the application launched in your device/emulator.
Modifying Your App For CLI Use
To make your project ready for command-line building, you will need
to modify the build scripts a little bit. The target generates some
defaults that we need to update.
First, you need to change the workspace filtering in the explorer so that you can see the files.
The targets are created in directories with names starting with a
".", which makes them hidden by default. To disable the filtering,
click on the Project Explorer preferences menu.
Uncheck the checkbox for ".* resource" and click OK.
You should now be able to see the folder in your "HelloWorld"
project. It will be called something like ".main.android". Expand this
folder and the "profile" folder below it. Each sub-folder of the profile
folder acts as a named configuration for the MAF build. For non-ide
builds, the application wizard creates a template profile called
"headless". To create your own profile, copy and paste this folder
under profile to a new one called "releng" (the name is arbitrary but we
will use releng here).
Now we need to modify the copy of "configure-fars-override.xml" under
the new releng directory so that the build will know where the
application artifacts are when running outside Eclipse.
Open "releng/configure-fars-override.xml" and find the target named "configure-override-projects".
The top of the target will look something like this:
We need to update those three properties to make them independent of
the Eclipse workspace. First, we add two lines of ant script that allow
us to pass in the absolute path of the application in from the
command-line.
Then update the paths in the original properties.
The first lines of the target should now look like this:
Save the file and close.
The last thing to do is to add an entry in releng/build.properties.
To make it easier to test the command-line build, we will tell it to
automatically generate a debug self-sign keystore for Android. Add this
key-value pair:
Creating A Local Repo and Committing Your App
In order to test your application in a "pure" CLI context, it's a
good idea to test a different copy of the application than the one in
the IDE. To do this, we will create a local GIT repository to simulate a
real CI scenario where a developer has written an application and
checked it in for use by Hudson or other build containers.
To add your application to a new local repository, click on one of
the projects in the Project Explorer and hit Ctrl-A (Cmd-A on Mac) to
select all. Right-click and select Team->Share Project...
In the Share Project dialog page, click on "Git" and hit Next. In
the Git configuration dialog, click "Create..." and enter a local path
on your disk.
Click Finish. Click Finish again to complete the wizard. When the
wizard completes, you will see that all your project artifacts have been
marked with "?" decorations and ">" characters in the Project
Explorer to indicate that they need to be committed to Git.
To commit the changes, switch to the Git perspective (hit Ctrl-3 or
Cmd-3 and in the search box type "Perspectives Git" then click on the
selection). In the left-hand "Git Repositories" view, click on the
repository you just created. At the bottom of the perspective, switch
to the "Git Staging" view. Now, click one of the files in the "Unstaged
Changes" list and hit Ctrl-A (Cmd-A on Mac) to select all. Right-click
on the selection and click on "Add to Index" in the menu. All of the
files listed under "Unstaged Changes" should move to the list below
titled "Staged Changes".
Now, type a comment in the "Commit Message" box and press "Commit".
If you switch back to the Oracle MAF perspective, you should now see
little orange decorations on your projects showing that they are checked
into your repo.
Building and Deploying Your App From the Command Line
To run the application from the command line, we're going to clone a
new local copy of the repo on the command-line and then run the build.
This means opening a Command Prompt (cmd.exe) on Windows or a Terminal
(bash shell) window on Mac and Linux.
First, go to some directory that is different than where you created the Git repo above.
Say "C:\temp\my-test-repo" (Windows) or "/tmp/my-test-repo"
(Mac/Linux). Now clone the repository you created in the previous
section. Go back to the Git perspective, right-click on the repository
in the "Git Repositories" perspective and select "Copy Path To
Clipboard". Now type this command in your command prompt, replacing
"/Users/cbateman/blog-git/.git" with you the contents of your clipboard:
When this command completes, change into the sub-folder that got
created. The folder should have the same name as the second to last
segment of the path you pasted from the clipboard. In the case of the
above command, the folder will be called "blog-git". Once in the
directory, list the contents using "dir" on Windows or "ls" on
Mac/Linux.
You should see the three folders for you application (HelloWorld,
HelloWorldApplication and HelloWorldView). Now change into the bin
folder for your target.
You are now ready to execute a build from the command-line. We do
this by running ant with the "build" target. You need to specify two
"-D" parameters to make sure it builds what you want. The first,
parameter is "oepe.user.config.override.profile=releng". This tells the
build to use the releng profile folder that you created above. The
second parameter is "env.WORKSPACE". We configured this above so it
would pick up from the environment. We did this for convenience since
that is how we will get it on Hudson in the section below. For this
step though, we'll just override it from the command-line to make life
simpler (you could also set it in the shell environment if you prefer).
The command to build will look like this. You will need to adjust the
env.WORKSPACE value to be the absolute path the folder that contains
your three projects.
Once the build has completed, you can look at the output in
../build/debug. This contains all of the staged artifacts ready for
packaging and deploying. At this point, you can call one of two
targets, "dist" and "deploy". This first target, "dist" will take the
build results and assemble them into an APK file that is signed with the
default development certificate (release signing is covered below):
When this completes, you will find both an unsigned and signed copy
of the apk file under /tmp/my-test-repo/blog-git/build/debug.
The second target, "deploy" will allow you to deploy the APK to your
device or emulator. To do this, you will need to execute the android
adb command to find your device's id. You will find adb (adb.exe on
Windows) in the "platform-tools" folder of you Android SDK installation.
Execute this command:
You should see output like this:
The big hex value is the device id. We need to copy and paste that into the last command parameter, maf.deploy.device.id:
Note that after calling "build" and "dist" you could alternatively
just call "adb install" on the signed APK file. This will install the
APK but unlike using the "deploy" target, it won't launch the
application automatically. Refer to Android SDK documentation for more
information on using the adb tool.
Create a release keystore for testing
We are now ready to create a Hudson job to create internal release
builds. First, we need to create a self-sign certificate so we can sign
our application with something more "real".
IMPORTANT: The information provided here for signing your application
is for development and testing purposes only. If you are planning to
release an application to customers or enterprise users, it is important
that you take great care in the way you obtain and manage your signing
certificates. If applicable, be sure to consult your company’s
policies and procedures around using application signing certificates.
You can create a keystore with a certificate in it by using the Java keytool command:
The tool will prompt you for information to create the keystore.
Make note of the path to the keystore (I used /tmp/my.keystore), the
alias name (I used 'myalias') and the passwords that you use. I used
'foobar' for both the keystore and the key alias password.
Add a Job to Hudson
Now we're ready to configure and run our Hudson job. Start your
hudson instance (java -jar hudson.war) and go to the administration web
page (http://localhost:8080).
From the main page, select the New Job link near the top-left. Enter
"HelloWorld" for the name and leave the type defaulted to "Build a
free-style software job". Click Ok.
In the configuration page we need to modify two sections: "Source Code Management" and "Build".
Under "Source Code Management", select Git and under "URL of
repository" enter the same repository that you put in the "git clone"
command above.
Under "Build", click on "Add Build Step" and select "Invoke Ant" from the drop down. In the "Targets" text box, enter build dist. Click "Advanced..." to expand the additional configuration options. Under "Build File", enter $WORKSPACE/HelloWorld/.main.android/bin/build.xml.
Under properties, enter the values as shown below, taking care to
modify the values for key.store, key.alias, key.store.password,
key.alias.password to match those for your keystore.
Click Save at the bottom of the page.
Running Your Job and Finding the Results
Click the "Build Now" link for the job. After the build finishes you
will find the signed and unsigned APK files under build/release in the
job workspace.
The signed APK may be deployed directly to a device. The unsigned
copy is useful if you want to distribute the application to a different
group for resigning.
Additional Information
Oracle Enterprise Pack for Eclipse OTN Page
Oracle MAF OTN Page
Oracle MAF on YouTube