How to Build WebRatio Mobile Projects in a Continuous Integration Environment

by Lucio Bordonaro
5,152 views Published on Jun 10, 2015
Applies to: 8.0 or higher
Table of contents

Introduction

WebRatio Mobile Platform gives you the possibility of making continuous builds of your Mobile Projects. This can be very useful to schedule builds on a dedicated server and for instance get a new build every night.

This process requires to create an Ant file that describes the result of the build of the mobile project and sets some related parameters.

Prerequisites

  • Install and activate WebRatio Mobile Platform 8.3 or higher
  • Setup Ant environment variables

Install and activate WebRatio Mobile Platform 8.3 or higher

Install WebRatio Mobile Platform 8.3 and activate using a dedicated serial. For informations on how to get a serial for continuous build integration please contact your WebRatio sales manager or ask sales@webratio.com.

Setup Ant environment variables

The steps described in this tutorial require you to run an Ant build from the command line or from a script. In order to prevent issues running the Ant commands, you need to configure some environment variables, since your Operating System must understand the keyword Ant when it’s typed on the command line.

Below you find the instructions for your operating system; read only what’s strictly necessary for you.

These two new environment variables are  the ANT_HOME environment variable and update the Path environment variable.

ANT_HOME locates the Ant installation folder, while Path is a variable used by the OS that lists all the executable programs through their installation folder.

You can choose whether to use the Ant installed within WebRatio or install one on your own.

If you wish to use the one installed within WebRatio its location is:

<webratio-installation-path>/WebRatio/plugins/org.apache.ant_<ant_version>

Windows

In Windows environmental variables can be set either from Command Line or from GUI.

This guide reports both, choose the option you prefer.

Command Line (any version)

  1. Run cmd.exe
  2. type:

set ANT_HOME = “<ant-installation-folder>”
e.g. set ANT_HOME = “C:\WebRatio\Mobile Nightly 8\WebRatio\plugins\org.apache.ant_1.9.2.v201404171502”
  1. type:
set PATH = %PATH%;%ANT_HOME%\bin

Warnings:

  • to set permanently the new value for both the environment variables use the command setx in place of set
  • if there are already other cmd.exe processes started you may need to restart your pc

GUI (XP and newer)

  1. Open Windows Control Panel
  2. Click on System section; a new page is displayed with a menu on the left
  3. From the left side menu choose the Advanced System settings option
  4. In the opening dialog you can see several choices. Click on the “Environment Variables” button. Then press OK to confirm.

  1. From the list of user variables pick Path and press the Edit button to update it. Append to its value the string ;%ANT_HOME%\bin; 
    Then press OK to confirm.

Warnings:

  • the first “;” reported at step 6 is needed only if the current value of Path does not already end with “;”
  • if there are already other cmd.exe processes started you may need to restart your pc

Linux/Mac

In Linux or Mac environment variables can only be set from command line.

  1. Open the terminal
  2. type:
export ANT_HOME=”<ant-installation-folder>"
  1. type:
PATH=$PATH:$ANT_HOME\bin

?Warnings:

  • to set permanently the new value for both the environment variables you must update the ~/.profile or ~/.bashrc files

How to Continuously Generate a Mobile Project

The Generate Task

To continuously generate a Mobile Project an Ant task must be created. This task defines all the properties required by the process.

and it can be executed directly from command line. You can create your own task starting from the sample “generation.xml” available in the WebRatio installation directory.

The path should be something like:

C:\WebRatio\<WebRatio-Installed-Version>\WebRatio\build\scripts\generate.xml

This is the content of the sample file::

<?xml version="1.0" ?>
<project name="WebRatio Generation Script" default="main">
     <fail unless="webratioDir" message="Missing script parameter 'webratioDir'" />
     <fail unless="projectDir" message="Missing script parameter 'projectDir'" />
     <fail unless="outputDir" message="Missing script parameter 'outputDir'" />
     <import file="${webratioDir}/WebRatio/build/config/init.xml" />
     <target name="project.generate">
           <webratio.generate webratioDir="${webratioDir}" projectDir="${projectDir}" outputDir="${outputDir}" backendURL="${backendURL}"/>
     </target>
</project>

There are four parameters that can be configured:

  • webratioDir : defines the absolute system path to reach the WebRatio installation folder (mandatory)
  • projectDir : defines the absolute system path to reach the folder containing the Mobile Project to be generated (mandatory)
  • outputDir : defines the absolute system path at which the mobile application will be available (mandatory)
  • backendURL : defines the URL at which is available the Data Service Project or the backend used by the Mobile application. Its required only when the Mobile Project refers a backend (optional)

How to create and run a generate Ant task

To create a new and dedicated Ant file create a new *.xml file and place it in a directory of your file system. A suggested location can be:

C:\WebRatio\<WebRatio-Installed-Version>\WebRatio\build\scripts

This is the structure that your Ant file should have:

<project name="HelloWorldGenerate" default="main">
      <import file="C:\WebRatio\Mobile Nightly 8\WebRatio\build\config\init.xml"/>
      <target name="project.generate">
            <webratio.generate webratioDir="C:\WebRatio\Mobile Nightly 8" projectDir="C:\WebRatio\Mobile Nightly 8\workspace\HelloWorld" outputDir="C:\WebRatio\Mobile Nightly 8\WebRatio\build\output\HelloWorldBuild.apk"/>
      </target>
</project>

The project node describes the general properties of the Ant task defining its name.

The import node its mandatory to link all the required resources; in this example it imports the init.xml file which is a file that comes together with WebRatio installation and describes the build and generation process. This file is located here: <webratio-installation-folder>\WebRatio\build\config\init.xml.

The target node describes the target of the process which is identified by its name.

The webratio.generate node defines a task of type Generate for a WebRatio project. It contains all the definitions and evaluation of the parameters.

This is an Ant file example:

<project name="HelloWorldGenerate" default="main">
      <import file="C:\WebRatio\Mobile Nightly 8\WebRatio\build\config\init.xml"/>
      <target name="project.generate">
            <webratio.generate webratioDir="C:\WebRatio\Mobile Nightly 8" projectDir="C:\WebRatio\Mobile Nightly 8\workspace\HelloWorld" outputDir="C:\WebRatio\Mobile Nightly 8\WebRatio\build\output\HelloWorldBuild.apk"/>
      </target>
</project>

Once the file is ready it’s time to execute the build on your machine.

To run the dedicated Ant file from command line type the following:

ant -buildfile <the-absolute-path-of-your-ant-file>

This is an example of command:

ant -buildfile C:/Users/builds/scripts/HelloWorldBuild.xml

How to Continuously Build a Mobile Project

Prerequisites

  • Install and activate WebRatio Mobile Platform 8.3 or higher
  • Have a build configuration for a Mobile Project

Install and activate WebRatio Mobile Platform 8.3 or higher

If you are not already registered on WebRatio website please register on WebRatio website registration; remember the username and the password as you will need both later.

Install WebRatio Mobile Platform 8.3 and activate using a dedicated serial. For informations on how to get a serial for continuous build integration please contact your WebRatio sales manager or ask sales@webratio.com.

Have a Build Configuration for a Mobile Project

In order to execute the Build operation a Build Configuration is required.

You can either create one from WebRatio GUI or prepare the XML *.launch configuration file.

To know how to create a Build Configuration from WebRatio Mobile Platform please refer to the following articles according your needs:

  • Android - Debug
  • Android - Release
  • iOS - Debug
  • iOS - Release

The Build Task

To continuously build a Mobile Project let’s start taking a look at the build task described in build.xml available in your WebRatio installation directory. The path should be something like:

C:\WebRatio\<WebRatio-Installed-Version>\WebRatio\build\scripts\build.xml

This task is defined as follows:

<?xml version="1.0" ?>
<project name="WebRatio Build Script" default="main">
     <fail unless="webratioDir" message="Missing script parameter 'webratioDir'" />
     <fail unless="projectDir" message="Missing script parameter 'projectDir'" />
     <fail unless="outputFile" message="Missing script parameter 'outputFile'" />
     <fail unless="configuration" message="Missing script parameter 'configuration'" />
     <fail unless="username" message="Missing script parameter 'username'" />
     <fail unless="password" message="Missing script parameter 'password'" />
     <fail unless="serial" message="Missing script parameter 'serial'" />
     <import file="${webratioDir}/WebRatio/build/config/init.xml" />
     <target name="project.build">
          <webratio.build webratioDir="${webratioDir}" projectDir="${projectDir}" outputFile="${outputFile}" configuration="${configuration}" username="${username}" password="${password}" serial="${serial}"/>
     </target>
</project>

There are seven available parameters:

  • webratioDir : defines the absolute system path to reach the installation folder of WebRatio (mandatory)
  • projectDir : defines the absolute system path to reach the folder in which is available the Mobile Project to be generated (mandatory)
  • outputDir : defines the absolute system path at which the generation result will be available (mandatory)
  • configuration : defines the absolute system path to reach the folder in which is available the launch file describing the build configuration to be used. It accepts also only the name of the configuration to be used (mandatory)
  • username : corresponds to the username associated with the WebRatio Mobile Platform activation (mandatory)
  • password : corresponds to the password associated with the WebRatio Mobile Platform activation (mandatory)
  • serial : corresponds to the serial associated with the WebRatio Mobile Platform activation (mandatory)

How to create and run a build Ant task

To create a dedicated Ant file create a new *.xml file and place it in a directory of your file system. A suggested location can be: C:\WebRatio\<WebRatio-Installed-Version>\WebRatio\build\scripts

This is the structure that your Ant file should have:

<project name="<BuildName>" default="main" basedir=".">
      <import file="C:\WebRatio\Mobile Nightly 8\WebRatio\build\config\init.xml"/>
      <target name="project.build">
            <webratio.build webratioDir="<webratio-installation-path>" projectDir="<mobile-project-path>" outputDir="<output-path>" configuration="<build-launch-configuration-path>" username="<activation-username>" password="<activation-password>" serial="<activation-serial>"/>
      </target>
</project>

The project node describes the general properties of the Ant task defining its name.

The import node its mandatory to link all the required resources; in this example it imports the init.xml file which is a file that comes together with WebRatio installation and describes the build and generation process. This file is located here: <webratio-installation-folder>\WebRatio\build\config\init.xml.

The target node describes the target of the process which is identified by its name.

The webratio.build node defines a task of type Build for a WebRatio project. It contains all the definitions and evaluation of the parameters.

This is Ant file example:

<project name="MyAppBuild" default="main" basedir=".">
      <import file="C:\WebRatio\Mobile Nightly 8\WebRatio\build\config\init.xml"/>
      <target name="project.build">
            <webratio.build webratioDir="C:\WebRatio\WebRatio Platform Mobile" projectDir="C:\workspace\MyApp" outputDir="C:\builds\MyApp\MyApp.apk" configuration="C:\workspace\MyApp\build\MyApp - Android" username="johndoe" password="johndoepassword" serial="AAAAA-00000-11111-22222-33333"/>
      </target>
</project>

Once the file is ready it’s time to execute the build on your machine.

To run the dedicated Ant file from command line type the following:

ant -buildfile <the-absolute-path-of-your-ant-file>

This is an example of command:

ant -buildfile C:/Users/builds/scripts/HelloWorldBuild.xml

How to run an Ant task from a script

The predefined Ant tasks available together with WebRatio installation can be also executed from a script file passing the required parameters.

Let’s consider Windows as operating system: you can create a batch *.bat file which prepares the required environmental variables and then calls the Ant command passing all the required parameters.

An example of structure is reported below:

set JAVA_HOME=C:\Program Files\Java\jdk1.7.0_71
set WEBRATIO_DIR="C:\WebRatio\Mobile”
set OUTPUT_FILE=%WEBRATIO_DIR%\WebRatio\build\output\HelloWorld.apk

call %WEBRATIO_DIR%/WebRatio/plugins/org.apache.ant_1.9.2.v201404171502/bin/ant ^
 -buildfile %WEBRATIO_DIR%/WebRatio/build/scripts/build.xml ^
 -logfile %WEBRATIO_DIR%/build.log ^
 -DwebratioDir=%WEBRATIO_DIR% ^
 -DprojectDir=%WEBRATIO_DIR%/workspace/HelloWorld ^
 -DoutputFile=%OUTPUT_FILE% ^
 -Dconfiguration="HelloWorld - Android" ^
 -Dusername=johndoe ^
 -Dpassword=johndoepassword ^
 -Dserial=AAAAA-00000-11111-22222

This applies for all the predefined tasks available. So consider carefully the right paths and set of parameters according to your need (generate or build).

This is also an option available on Linux or Mac. In these other options you should create *.sh files.