Skip to content

Creating a Build Manually

Jump to bottom Edit New page
waynevicknair edited this page May 23, 2011 · 23 revisions

Table of Contents

About this page

This page describes how to run the Maqetta build scripts manually. Developers sometimes need to do manual builds for one-off development/debugging reasons or because they can't wait until the next automatic build. The are automatic builds run at a regular time each day or multiple times per day.

The manual build scripts prepare a release build, doing things such as combining zillions of separate JS and CSS files into a much smaller number of consolidated (but bigger) files and minifying the files. The build scripts also are necessary in leverage HTML5 application cache. The build scripts also do some preparatory work such as automatically injecting the build number into the "About Maqetta" dialog.

As a developer, it is assumed that you have cloned the Maqetta repository and imported all the projects from the repository into Eclipse. You may need to install the EGit Eclipse plugin if you haven't done so already.

Prerequisites

Your machine needs the following to create builds:

  • Java 1.5 or greater 64-bit JVM
  • Eclipse version 3.6 or greater
  • git version 1.7.*

Instructions for Building from Command Line

Below are instructions for building Maqetta from the command line. We will discuss build setup and execution by deconstructing the build script build.sh found in the davinci.releng project. All the environment variables exported from this script are imported into the top level Ant script which drives the build process.

Note: Windows users follow along in build.bat which performs the exact same steps as build.sh only in more familiar syntax for your environment.

The Base Application Directory

This bit of shell script sets the base path to the application directory where Eclipse is installed. It is used to build several other paths. Please set it carefully. 

 #
 # Path to parent directory of the eclipse application directory. 
 # That is, if eclipse is installed in '/usr/local/eclipse', this property 
 # would be set as 'base="/usr/local"'. No trailing slash.
 #
 export base="/path/to/eclipse/parent/directory"

The Eclipse Directory

Here you specify the Eclipse directory name. For example, it's eclipse-3.6 on my machine. 

 #
 # Path to eclipse directory inclusive. The application directory is 
 # usually, but not always, named 'eclipse'. It has sub-directories
 # /configuration, /features, /plugins, etc. No trailing slash.
 #
 export baseLocation="${base}/eclipse"

The Launcher Specification

You'll only need to set this once per installation of Eclipse. Carefully capture the numbers and letters following the underscore ('_') character at the end of the word "launcher" up to the dot ('.') character before the "jar" suffix. By now you may have guessed that Maqetta runs as an OSGI Bundle. The launcher is what gets included to kick everything off at runtime. 

 #
 # Version number of the launcher jar file. See ${baseLocation}/plugins/org.eclipse.equinox.launcher_*.jar. 
 # The launcher version is the set of alphanumeric characters between 'launcher_' and the '.' character 
 # before the 'jar' file name suffix.
 #
 launcherVersion="1.1.1.R36x_v20101122_1400"

The Build Directory

This sets a variable to the path to your build directory. The build directory is a scratch space where the build process gets its input and puts its output. 

 #
 # Directory in which to do the build. No trailing slash.
 #
 export buildDirectory="/path/to/your/build/directory"

The Ant Build XML File Directory

This sets a variable to the path to directory holding the top level Ant build XML script. It should not change as long as the Maqetta project keeps its current directory structure. 

 #
 # Directory containing build.xml (this should not have to be changed in most cases).
 # No trailing slash.
 #
 export relEngDir="${buildDirectory}/repository/maqetta/releng/davinci.releng"

The Local Build Switch

Setting this variable will cause the Ant build to attempt to copy the requisite Maqetta Eclipse projects from your Eclipse workspace versus from the Git repository. You should never create a production build with this option. 

 #
 # If 'maqettaCode' is set, copy files from your local workspace instead of GitHub repository
 #
 # Note: This build feature is in incubation and *cannot* be used for production builds.
 #
 #export maqettaCode="/path/to/your/local/eclipse/workspace"

The GitHub URL

This sets a variable to the read-only flavor of the GitHub URL for the Maqetta repository. This setting should not change. 

 #
 # GitHub URL for Maqetta repository. This should not change.
 #
 export gitRepository="git://github.com/maqetta/maqetta.git"

Prerequisite javax.activation and javax.mail Eclipse Projects

This section of the build setup is very important. The build requires the javax.activation and javax.mail packages to exist as Eclipse Projects. You can find empty versions of these projects checked into GitHub in the 'davinci.releng' project as 'javax_project_templates.zip'. We cannot ship the contents of the JARs due to licensing restrictions.

Unzip those projects into your workspace. Then download the javax.activation and javax.mail JAR files:

Once you've downloaded the JAR files, you need to unzip the .class files into the top level directory of their respective Eclipse projects. That is, in the Eclipse package view you should the original project files plus package folders for all the activation and mail packages. (See screen shot of project view here http://www.flickr.com/photos/85081687@N00/5726398423/lightbox/.) 
 #
 # Path to javax.activation and javax.mail Eclipse projects directory
 #
 # Note: Users outside of IBM need to create these projects for
 #       themselves as they are *not* checked-in to GitHub for
 #       licensing reasons. Empty template projects with proper settings
 #       are checked-in to GitHub in 'davinci.releng/javax_project_templates.zip'.
 #
 export javaxPath="/path/to/directory/containing/javax/eclipse/projects"

Launcher Type Settings

Each Eclipse installation has platform specific launcher information required for the build. Here we set the variables for windowing system, operating system and processor architecture. You can find the values for these settings as dot separated components of the 'org.eclipse.equinox.launcher' plugin directory. I build on a Mac hence the settings below. 

 #
 # Windowing System, Operating System and processor Architecture settings
 #
 # Note: See ${baseLocation}/plugins/org.eclipse.equinox.launcher.xxx.yyy.xxx/  
 #       to determine your settings, they should be similar to 'cocoa.macosx.x86_64' 
 #
 export myWS="cocoa"
 export myOS="macosx"
 export myArch="x86_64"

Set Up the 'repository' Subdirectory

The Maqetta project repository will be cloned or pulled into this directory resulting in a '${buildDirectory}/repository/maqetta' directory. Here we make sure the 'repository' directory exists. 

 # 
 # Set up for and pull down the latest code from GitHub
 #
 if [ ! -d ${buildDirectory}/repository ]
 then
    echo "Making repository directory"
    mkdir -p ${buildDirectory}/repository
 fi

Sniff for Valid Git Repository

Check to see if a '.git' directory exists in the 'repository/maqetta' directory which means we need only do a pull operation to get the latest changes. Otherwise, we must clone the repository. 

 #
 # If '.git' directory exists we need only pull
 #
 if [ -d ${buildDirectory}/repository/maqetta/.git ]
 then
    echo "Doing 'git pull'..."
    cd ${buildDirectory}/repository/maqetta
    git pull
 else
    echo "Cloning repository. This may take a few moments..."
    cd ${buildDirectory}/repository
    git clone ${gitRepository}
 fi

Sniff for Valid Internal Git Repository

Due to licensing issues mentioned above, we have an internal Git repository for the javax.activation and javax.mail projects. You may need to modify this script to copy the Eclipse projects for these packages from wherever you chose to place them (e.g. your Eclipse workspace). 

 #
 # If '.git' directory exists we need to pull
 #
 if [ -d ${javaxPath}/.git ]
 then
    echo "Fetching javax.activation and javax.mail projects..."
    cd ${javaxPath}
    git pull
 fi

Copy Activation and Mail Project into Build Repository

Here we copy the activation and mail projects into the Maqetta repository directory. This consolidates all the prerequisite Eclipse projects into one directory from which the Ant build scripts can copy files. 

 echo "Copying javax.activation and javax.mail projects..."
 cd ${buildDirectory}/repository/maqetta
 cp -Rp ${javaxPath}/javax.activation .
 cp -Rp ${javaxPath}/javax.mail .

Change to Build Directory

The build MUST be run from the build directory. 

 #
 # Change directory to the build directory.
 #
 # Note: Many scripts use relative directory references making
 #       running the build from this directory *imperative*.
 #
 cd ${buildDirectory}

Launch the Ant Script

The top level Ant script compiles and packages the build as an OSGI Bundle. The build automatically creates two output files in the result directory:

  1. maqetta-<build designator>.zip which is a standalone version of Maqetta which implements a crude, XML file-based user management facility;
  2. joomla-maqetta-<build designator>.zip which is a version of Maqetta which, through a plug-in, integrates with the Joomla CMS program's user management facility;
      where <build designator> is typically a date and time stamp formatted as "yyyyddmmHHMM".

The build also has targets for building a WAR and EAR file for Maqetta. The WAR file version wraps the Maqetta OSGI Bundle in a bridge servlet. The EAR file is created strictly to capture the EAR specific settings required by some Web Application servers. The WAR target must, currently be invoked manually as a separate build. 

 #
 # Run the Ant buildAll script from the davinci.releng project.
 #
 java -jar ${baseLocation}/plugins/org.eclipse.equinox.launcher_${launcherVersion}.jar -application org.eclipse.ant.core.antRunner -buildfile ${relEngDir}/buildAll.xml

Building a WAR File 

 '''''(WEV: Brad, can you provide information here on how to build a WAR?)'''''

Getting Ready for a WAR Build

If you want to do this on your own machine, check out the following projects: (JON: What's the repository for these projects?)

  • davinci.war
  • org.eclipse.equinox.http.servletbridge
  • org.eclipse.equinox.server.core
  • org.eclipse.equinox.server.servletbridge
  • org.eclipse.equinox.servletbridge
  • org.eclipse.equinox.servletbridge.extensionbundle

Building the WAR File

(JON: Do we need to tell people to create a destination folder with VERSION in its name? Or will this step be included within a VERSION folder due to previous steps?)

  • 'git pull' Maqetta repository and press F5 to refresh
  • right click on davinci.war and select "Export"
  • Under "plugin development" select "Eclipse Product"
  • In the next dialog, use these settings:
    • configuration: /davinci.war/DavinciWar.product
    • root directory: WEB-INF
    • Synchronization: not checked
    • destination should be "Archive file"
    • export source: unchecked
    • generate metadata: unchecked
    • allow for binary: checked
  • after export, rename the resulting .zip to .war
Add a custom footer
Add a custom sidebar

Clone this wiki locally