Marketplace Build Instructions

#DRAFT Build Instructions

##Objectives This document will describe how to build the following projects:

• Marketplace Server--A local copy of the bundled (marketplace.war + Tomcat) ZIP file.

##Requirements This document is targeted to widget developers and assumes a basic familiarity with the target development environment, be it Microsoft Windows or Linux. Before building, there are several tools that must be installed by the developer. The following sections list the tools, the version requirements for recent Marketplace releases and nominal configuration elements. Instructions provided below assume a Microsoft Windows development environment for illustrative purposes only.

##Download and Install Applications Marketplace Development requires the use of the Java Development Kit (JDK), Apache Ant, Apache Ant Contrib, Ruby, RubyGems, Sass and Compass, Node.js, and Grails. The following table lists the versions of each tool required by the last few releases of Marketplace.

The terms Store, Marketplace, OZONE Marketplace, and OMP can be used interchangeably.

####Table: OMP Development Tools and Version Numbers

Application	JDK	ANT	Ant Contrib	Grails	Ruby	Compass	SASS*	Groovy	Node.js
OMP 7.17.0	1.8	1.8.4	-	2.4.2	1.9.2	0.11.7	3.1.3	2.3.3 (included with Grails)	4.2.2
OMP 7.16.0	1.7	1.8.4	1.0b3	2.3.7	1.9.2	0.11.7	3.1.3	2.1.9 (included with Grails)	4.2.2

Obtain installation media and instructions from the primary websites or trusted download source for each tool. The default locations are provided below. Also, install the tools in the order listed below. Once all tools have been installed, the following sections will describe how to configure the environment.

####Table: Tool Provider Websites

Application	Location
JDK	http://www.oracle.com/technetwork/java/javase/downloads/index.html
ANT	http://ant.apache.org/
Grails	http://www.grails.org/
Ruby	https://www.ruby-lang.org/en/downloads/
Node	https://nodejs.org

###Setting Environment Variables The build environment uses Apache Ant for most tasks. For Ant to run properly, it should discover the locations of the other supporting tools. This is accomplished by setting appropriate environment variables describing the install directory of each tool. On Windows 7, the following steps will set the ANT_HOME variable, assuming an install location of C:\Apache_Ant\apache-ant-1.8.3.

1. Go to the Start menu and select Control Panel.
2. Click the System icon and select the Advanced System Settings link in the resulting window.
3. Click on the Advanced tab in the resulting pop-up and then select the Environment Variables button. For the following steps, if Administrator rights are available, use the System Variables section. If not, use the User variables section.
4. Create/Edit a variable named ANT_HOME. Set its value to C:\Apache_Ant\apache-ant-1.8.3. Save the new variable. On your system, the value should be the location where Ant was actually installed.
5. Create/Edit the Path variable. If the Path variable already contains the value %ANT_HOME%/bin, click Cancel. If the Path doesn’t contain the variable, append ;%ANT_HOME%/bin to the end of the Path variable. Click OK until the system properties dialog is closed.

This method should be repeated to set the JAVA_HOME, ANT_HOME, GRAILS_HOME, NODE_HOME, and RUBY_HOME environment variables for each of their installation folders, respectively.

###Configuring Ruby Gems (SASS and Compass) Configuring the required Ruby gems cannot happen until you set the environmental variables (described above).

1. Open a new Command Prompt window and enter: gem install sass --version 3.1.3

2. Your response should be similar to:

    C:\Users\myusername>gem install sass --version 3.1.3
    Fetching: sass-3.1.3.gem (100%)
    Successfully installed sass-3.1.3
    1 gem installed
    Installing ri documentation for sass-3.1.3...
    Installing RDoc documentation for sass-3.1.3...
    C:\Users\myusername>
   

3. Then run gem install compass --version 0.11.3

4. Your response should be similar to:

    C:\Users\myusername>gem install compass --version 0.11.7
    Fetching: chunky_png-1.2.5.gem (100%)
    Fetching: fssm-0.2.9.gem (100%)
    Fetching: compass-0.11.7.gem (100%)
    Successfully installed chunky_png-1.2.5
    Successfully installed fssm-0.2.9
    Successfully installed compass-0.11.7
    3 gems installed
    Installing ri documentation for chunky_png-1.2.5...
    Installing ri documentation for fssm-0.2.9...
    Installing ri documentation for compass-0.11.7...
    Installing RDoc documentation for chunky_png-1.2.5...
    Installing RDoc documentation for fssm-0.2.9...
    Installing RDoc documentation for compass-0.11.7...
    C:\Users\myusername>
   

5. Ensure that you installed the correct Ruby, Sass and Compass versions.

6. From a Command Prompt window, run the following command: sass -v (Your response should say `Sass 3.1.3(Brainy Betty) is in use.)

If a different version is running or a Sass error appears (e.g., "no such file to load"), execute the following steps to correct the Sass install:

1. In the Command Prompt window enter: gem uninstall sass, then choose which version to install.

    C:\Users\myusername>gem uninstall sass
    Select gem to uninstall:
    1. sass-3.1.3
    2. sass-3.1.15
    3. All versions
    > 2
    Remove executables:
    Scss in addition to the gem? [Yn]  y
    Removing scss
    Successfully uninstalled sass-3.1.15
   

2. Run the sass -v again; see the example below:

    C:\Users\myusername>sass -v
    Sass 3.1.3 (Brainy Betty) 
    C:\Users\myusername>
   

###Verify Tool Installation To verify the installation and version of the tools, use the version command for each tool in the Command Prompt Window. Example commands and output follow:

1. Enter java -version

    C:\Users\myusername>java –version
    java version "1.8.0_60"
    Java(TM) SE Runtime Environment (build 1.8.0_60-b27)
    Java HotSpot(TM) 64-Bit Server VM (build 25.60-b23, mixed mode)
   

2. Enter ant -version

    C:\Users\myusername>ant –version
    Apache Ant(TM) version 1.8.4
   

3. Enter grails -version

    C:\Users\myusername>grails -version
    Grails version: 2.4.2
   

4. Enter ruby -v

    C:\Users\myusername>ruby –v
    ruby 1.9.2p290 (2011-07-09) [i386-mingw32]
   

5. Enter gem -v

    C:\Users\myusername>gem –v
    1.8.16
   

Note: RubyGem is provided by the Ruby Installation. The Compass and Sass configuration is described in the previous section Configuring Ruby Gems (SASS and Compass)

7. Enter sass -v

    C:\Users\myusername>sass –v
    Sass 3.1.3 (Brainy Betty)
   

8. Enter compass -v

    C:\Users\myusername>compass -v
    Compass 0.11.7 (Antares)
    Copyright (c) 2008-2012 Chris Eppstein
    Released under the MIT License. Compass is charityware. 
    Please make a tax deductable donation for a worthy cause: http://umdf.org/compass
   

##OWF and Server Builds If changes are being made to the server code, the developer does not normally need to run build tasks to test them. Instead, use the standard grails scripts to run or test the server code. Use the Ant build when there is the need to build a server bundle, i.e. package the WAR files, along with a Tomcat instance into a ZIP file that can then be distributed to an end user. To build a server bundle, open a Command Prompt window and ‘cd’ into the server’s base directory.

C:\owf-server>ant setup-ant

To build the bundle, type the following on the command line and press Enter:

C:\owf-server>ant bundle

The bundle task will do a clean and build of the server code (retrieving any dependencies), run the server tests (both unit and integration) and then build the zipped bundle. The results of the build are written to the staging directory within the server directory. The staging directory of a successful build should contain the zipped bundle, as well as the unzipped contents of the bundle. The latter is provided as a convenience to test the bundle by running the start.bat (or start.sh on Linux systems) in the staging/apache-tomcat directory. This will start the Tomcat server which is initially configured to load the OMP war file.

Additional Build Command Line Options

When running the build, use any (or all) the following command line parameters:

• -logfile build.log – This will redirect the output of the build to the specified log file. This can be useful when there are problems with the build because the output is often too verbose to be completely captured by the Command Prompt window.
• -Dno-test=true – This skip the running of the grails unit and integration tests. Often, they’ve already run. Using this option will speed up the build.

###Building Offline Note: Previous offline build instructions based on downloading an Ivy repository via SVN are deprecated. While those steps may work with older versions of the product, the SVN-based repo is no longer updated and will not contain all of the required libraries for building current Ozone products.

It is possible to build the product without an external network connection by copying the necessary files from a connected build environment. Following these steps:

1. In a connected build environment, follow the steps to build the bundle normally.
2. Create an archive of the source directory. On most Unix-like operating systems this can be accomplished by running the following command from the directory one level above the source directory (called owf in this example): tar –zcf src.tar.gz owf
3. Create an archive of the Ivy dependency cache, located in $HOME/.ivy2. From that directory, run the following command: tar –zcf cache.tar.gz cache
4. Copy both of artifacts created in the preceding steps to the unconnected environment.
5. Extract the cache archive by running the following command: mkdir $HOME/.ivy2; tar -zxf cache.tar.gz -C $HOME/.ivy2 (if $HOME/.ivy2 exists, omit the first part)
6. Run the following command to extract the project source: tar -zxf src.tar.gz -C $HOME (change the location following –C as needed).
7. Build the project, following the normal steps.

###Troubleshooting

####Supporting Multiple Versions of SASS and Compass Ruby Gems Building OMP 7 requires installing an older version of SASS and Compass Ruby Gems. Developers may run into an issue if their systems ever require the latest versions of these programs. For example, systems that have installed an older version of SASS and Compass Ruby Gems can build OMP but cannot run other applications with different environment requirements. Likewise, systems installed with the latest version of SASS and Compass Ruby Gems cannot build OWF 7. Ruby Gems does not support a method for choosing a specific Ruby Gems version to run when multiple versions are installed on a system. Therefore, this section explains how to select a Gem repository using the GEM_HOME and GEM_PATH environment variables. This explanationis written for a Windows environment, but a similar solution could be created for Linux:

1. Create the following command script and name it UseOwf7Gems.cmd:

    REM Script to switch to local Ruby Gems repository for OWF 7 build
   
    REM Keep specific versions of Gems in a local repository
    SET GEM_HOME=%USERPROFILE%\Gems-Owf7
   
    REM Prevent Gem from searching other repositories
    SET GEM_PATH=%GEM_HOME%
   
    MKDIR "%GEM_HOME%"
    
    REM Ensure our specific Gem binaries are preferred in the path
    SET PATH="%GEM_HOME%\bin";%PATH%
   

2. Copy the UseOwf7Gems.cmd script to the system path where it is accessible from the command line.

3. Run the script before:

4. Installing SASS and Compass

5. Running ant for the build

Note: Developers only need to install Gems in their local OWF Gem repository once.

To switch to the default Gems repository, clear the GEM_HOME and GEM_PATH environment variables with the following commands:

SET GEM_HOME=
SET GEM_PATH=