Creating a Build Manually

== 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 exists as '''Eclipse Projects'''. You can find empty versions of these projects checked into GitHub in the 'davinci.releng' project as 'javax_project_templates.zip'.

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

• javax.activation URL - [http://www.oracle.com/technetwork/java/javase/index-jsp-136939.html]
• javax.mail URL - [http://www.oracle.com/technetwork/java/javamail/index.html] 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.

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"

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 for and pull down the latest code from GitHub

if [ ! -d ${buildDirectory}/repository ] then echo "Making repository directory" mkdir -p ${buildDirectory}/repository fi

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

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