Skip to content

Creating a Build Manually

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

Table of Contents

IMPORTANT NOTE - UNDER CONSTRUCTION

(These instructions are incorrect at the moment. They were accurate when the sources were kept in a Subversion repository and need to be updated to reflect a Git repository, and the automatic build scripts probably need to be updated.)

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. There are also automatic build scripts that run at a regular time each day or multiple regular 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.

Pre-requisites

Your machine needs the following to create builds:

  • 64-bit JVM. To see if you have a 64-bit JVM, open a shell window and type "java -version".
  • Command-line "git" on your PATH. To see if you have command-line "git", open a shell window and type "git".

Instructions for Building from Eclipse

  • Launch Eclipse (version 3.4 or greater)
  • Create temp directory, e.g. /Maqetta/temp/VERSION
  • Update all projects with latest from HEAD
In eclipse: (this step takes ~45 minutes)
  • right click on the davinci.product & davinci.core projects and select "Refresh" (do this for all projects?)
  • right click on davinci.product and select "Export"
  • Under "plugin development" select "Eclipse Product"
  • In the next dialog, use these settings:
    • configuration: /davinci.product/DavinciServer.product
    • root directory: eclipse
    • Synchronization: not checked
    • destination: /Maqetta/temp/VERSION
    • export source: unchecked
    • generate metadata: unchecked
    • allow for binary: checked
The above process launches Dojo build scripts. To verify that the build scripts ran successfully, look inside the davinci.core JAR and look at build.out in a text editor and see if there are any error messages. If successful, this file should have hundreds of lines in it.
In Finder or Explorer:
  • after export copy the following files from the davinci.product plugin and place into /Maqetta/temp/VERSION/eclipse:
    • maqetta.local.mac.command
    • maqetta.local.win.bat
    • maqetta.server.mac.command
    • maqetta.server.win.bat
  • on mac, make sure the these files all have "x" execute permission by going into Terminal and issuing a "chmod a+x maqetta.local.mac.command maqetta.local.win.bat maqetta.server.mac.command maqetta.server.win.bat"
  • For Mac builds, it appears to be necessary to manually update the configuration/config.ini file. Somehow the build process isn't updating that file and a bogus config.ini file is being used.
  • in windows explorer, select all of the files in /Maqetta/temp/VERSION/eclipse, and do "add to zip" (want the contents of /Maqetta/temp/VERSION/eclipse as the root of the archive. (On Mac, in Finder, open the /Maqetta/temp/VERSION folder, select "eclipse" and with context menu issue "compress command to create eclipse.zip.)
  • rename the zip file as appropriate (e.g., to maqetta_preview_N.zip)

Building WAR file

Set up

If you want to do this on your own machine, check out the following 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

  • synchronize all projects with repository
  • 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

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.

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 set 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 SSH 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' file 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

????? 

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

????? 

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

????? 

 #
 # 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
Add a custom footer
Add a custom sidebar

Clone this wiki locally