SSP Sencha Build Tool Usage

Currently, Sencha is part of the maven build process for SSP 2.0. Eventually, the same configuration will be added to the rel-1-2-patches and rel-1-1-patches branches.

Sencha Installation

Sencha SDK Tools can be downloaded from here: http://www.sencha.com/products/sdk-tools/download/

These steps are relevant for both the automated process as well as the manual process:

1) Install sencha tools. Especially if installing in a Windows environment, it has proven problematic if there is a space in the path name (if installed in Program Files.) It is best to install Sencha tools to a directory in which there are no embedded spaces.

2) Add the installation directory to your PATH. Will look something like:

for OSX:
export PATH="/Applications/SenchaSDKTools-2.0.0-beta3:$PATH"

for Windows (easiest to add environment variable; or set from cmd prompt):

set path=%path%;<Sencha SDK Tools Installation Dir>

You can validate your Sencha installation by typing the following command (should get usage information back):
%> sencha --help

3) On a 64-bit Linux OS, you may need to install additional packages:

Ubuntu x64: 

  $ sudo apt-get install lib32stdc++6

Amazon AMI

  $ sudo yum install libstdc++47.i686

CentOS

  $ sudo yum install libstdc++.i686

4) Windows x64 users will also need to install a 32-bit Java SDK/JRE for the sencha build command to work properly (one of the jars in sencha looks for the 32-bit runtime and won't play nicely with the 64-bit SDK/JRE.)

GENERAL DEVELOPMENT PROCESS

Developers should note that when adding new Ext classes, it is important to edit the ssp.jsb3 file so that the new classes will be included in the minification process. This isn't currently automated.

If a developer is working on a JavaScript-heavy part of the application, he would typically modify ssp-main.jsp to include app.js rather than app-all.js, hack away on the .js files in the the source tree, and copy them to the running Tomcat instance in order to see the effects of the change. This process is still proper if development is happening on the 1.1 or 1.2 branch. The 2.0 branch handles much of this due to some additional maven profiles and an additional configuration setting that properly adjusts the ssp-main.jsp file accordingly.

AUTOMATED PROCESS (SSP 2.0)

Critical parts of the Sencha build to process automatically are:

1) An additional environment variable was added to ssp-config.properties called ssp_main_use_minified_js.

When set to true, ssp-main.jsp will include the reference to the minified js called app-all.js

When set to false, ssp-main.jsp will include the reference to the non-minified app.js

2) Three additional profiles added to SSP's pom.xml

profile for calling Sencha from Windows (called WINS)

provile for calling Sencha from *inux (called LINUX)

profile for skipping the sencha build (called SKIP_SENCHA)

The default behavior is to generate the aggregated files (app-all.js and all-classes.js). To build without the aggregated files, one can call:

%> mvn -PSKIP_SENCHA clean install

If this is done, it is also advisable to set ssp_main_use_minifed_js=false in ssp-config.properties so that ssp-main.jsp will look for and utilize app.js.

MANUAL PROCESS (SSP 1.1.x and SSP 1.2.x)

Eventually, the same automated configuration will be added to the 1.2.x and 1.1.x. Until then, the manual process for just building these versions is:

1) cd over to the directory with your ssp.jsb3 file:
%> cd {src_root}/src/main/webapp

2) Run the sencha tool (note the dot at the end):
%> sencha build -p ssp.jsb3 -d .

3) Add the resulting files to git:
%> git add app-all.js all-classes.js

MANUAL PROCESS FROM PERSPECTIVE OF INSTALLATION

There are a couple of instances where the manual process plus some additional steps would need to be employed:

A) In the process of applying an upstream SSP patch or upgrade that contains Javascript code changes

B) When the overlay in ssp-platform includes customized Javascript code (currently, since Configuration.js is still the mechanism through which much of this site-specific customization happens, this will be very common until all of the configuration settings are pushed to the SSP config table.)

%> cd {ssp-src}

# Builds and installs the ssp.war file in the local maven repository

%> mvn -Dmaven.test.skip=true clean install

%> cd {platform-src}/uportal-portlets-overlay/ssp

# Builds the ssp.war file for the overlay project in ssp-platform

%> mvn clean package

%> cd /target/ssp

# Builds the minified versions of app-all.js and all-classes.js

%> sencha build -p ssp.jsb3 -d .

# Copy the minified versions to the src/main/webapp directory for ssp in the overlay

%> cp app-all.js ../../src/main/webapp/

%> cp all-classes.js ../../src/main/webapp/

%> cd ../../

# Make sure it looks like all-classes.js and app-all.js have been modified

%> git status

# Add, commit, and push those changes

%> git add src/main/webapp/app-all.js src/main/webapp/all-classes.js

%> git commit -m "NOJIRA Update aggregated/minified js to include overlay code"

%> git push <remote-name> <branch-name>

%> cd {platform-src}

# Then build and deploy platform as usual