You are here: Building and Viewing an Application > Perform a Headless Build

Perform a Headless Build

A headless build is a method of building and publishing an app without launching the Eclipse environment that hosts Quantum Visualizer. Instead, AntAn open-source software tool developed by the Apache Software Foundation that automates software build processes. manages the build and publish process.

Conducting headless builds has a number of advantages.

Running a headless build involves the following tasks: 

  1. Prerequisites for a Headless Build
  2. Configure the HeadlessBuild.properties File
  3. Configure the HeadlessBuild-Global.properties File
  4. Increase Heap Memory
  5. Build the Application

Note: Before using conducting a headless build, ensure you have the files mentioned in Prerequisites

For headless builds, the following two files are required:

Most of the effort in preparing a headless build involves configuring these files. Ant gives you the flexibility to build an app or publish it. The decision of building or publishing is configured using Modes. The modes are: 

Prerequisites

Following are the prerequisites for doing headless build: 

Configure the HeadlessBuild.properties File

The following sections explain where to find the HeadlessBuild.properties file and how to configure it. Depending on what mode you are building (either 0, 1, 2, 3, or 4), you need to set particular values in the HeadlessBuild.properties file. These are detailed in Configure the Mode.

  1. How to Find the HeadlessBuild.properties File
  2. Configure the Mode
How to Find the HeadlessBuild.properties File

The file HeadlessBuild.properties is stored in the project folder of your workspace. For example, if the name of your project is HelloWorld, and the name of your workspace folder is Workspace, the path in Microsoft Windows will be:

C:\Users\<username>\Workspace\HelloWorld

Example of HeadlessBuild.properties file

Following is an example of sections that are present in the HeadlessBuild.properties file and the values that can be used.

Important: If the values for any variables are left blank, then the values set through Quantum Visualizer will be retained while building the application.

#Note: Please escape '\' with '\\' in all file paths#
#This file represents the Application level properties used by headless build.
project.name=app1

#mode 0-Build; 1-Publish; 2-Build & Publish; 3-Combine Web Application+Kony Server Archive; 4-Build & Combine Web Application+Kony Server Archive;
#mode-0: Application will be built for the selected build platforms
#mode-1: Based on publish.web, publish.service properties, app will be published & services will be published
#mode-2: Application will be built for selected build platforms and publish will be performed.
#mode-3: Combines web archive of app & kony server archive and generates combined war/ear file
#mode-4: Application will be built & Generated web archive will be combined with Kony server archive and final war/ear will be generated
mode=0

#build mode [release | debug]
build.mode=release

#Application details
appid=app1
#Please ensure that this is incremented while doing multiple Headless builds involving the modes 0 or 1 or 2
version=1.0.0
map_google_key=
default_locale=
#The android packagename can follow the pattern com.<orgname>.<appid>
android.packagename=com.orgname.app1

#Cloud Mode credentials (Applicable only for cloud)
cloud.username=
cloud.password= 

#Provide Quantum Fabric specific details konyfabric.url=

# Environment.Name used for publishing example using the format LocalDevEnv
# For example, if your Quantum Fabric Environment URL is:
# https://mycompany.konycloud.com
# then the value is as follows: environment.name=mycompany environment.name=
account.id=
mf.appname=

#Specify the platforms for which the headless build needs to run. #Mobile Channel. iphone=false android=false spa.iphone=false spa.android=false #Tablet Channel. ipad=false androidtablet=false #Selecting Windows10 will also trigger builds for X86,X64,ARM architectures. windows10=false spa.ipad=false spa.androidtablet=false spa.windowstablet=false #Desktop Channel. desktop_kiosk=false desktopweb=false #Wearbles channel. iphonewatch=false

#Universal Channel. universal.iphone=false universal.android=false #App Extensions iosappextension=false #Provide iOS deployment target details in the case of iPhone or iPad. #Ex: 8.0, 9.0, 10.0 mac.iosdeploymenttarget= #Ex: 2.0, 3.0, 4.0 mac.watchosdeploymenttarget= #Ex: 4.0, 5.0 mac.swiftversion= #Provide following details to generate IPA file in the case of iPhone or iPad. mac.ipaddress= mac.username= mac.password= keychain.password=
#Possible values for method are "app-store", "ad-hoc", "enterprise", "development" method=
#Examples for development.team are "G9B5P7QDV2", "PM7453S8QE"
development.team=
#Possible values are true/false genipaiphone=false genipaipad=false #middleware server properties middleware_server_ip=192.168.251.1 middleware_http_port=80 middleware_https_port=443 #used in cloud mode cloud.middleware.url= middleware_web_context=middleware mobileweb_web_context=app1 #To build binaries with protected mode enabled.
protectedmodeenabled.ios=true
protectedmodeenabled.android=true
protectedmodeenabled.web=true
#If not specified, by default final binaries will be copied to 'binaries' folder inside project binaries.location= #Combine Web Application+Kony Server Archive. Applicable for mode = 3 or 4 # #Full path of middleware archive (war/ear).If project has Kony session Manager, #provide with-cache archive, for Http session Manager, provide without-cache archive. combinewar.middlewarearchive= combinewar.context= #combinewar.war,combinewar.ear are mutually exclusive(Only one of them should be true) combinewar.war=false combinewar.ear=false #Provide full path of dependant libraries,Separate with semicolon(;) if there are multiple libraries combinewar.dependencylibraries=

# Supported context paths for Quantum Fabric components, if customized.
context.path.identity context.path.workspace context.path.accounts
context.path.console

#Siteminder login URL if your on-premise Quantum Fabric is protected by siteminder.
login.siteminder.url



Important: If you do not want to store your password in the headless build.properties file, you can use mfcli to encrypt your password. You can download the mfcli.jar from https://community.kony.com/downloads.

Ensure that you use the corresponding version of MFCLI as that of the Visualizer. i.e 7.x viz, 7.x mfcli, 8.x viz, 8.x mfcli.

To encrypt the password using mfcli (using default password.encryption.key),
java -jar mfcli.jar encrypt "Kony@1234"
Encrypted password is: en1801f1abee7b9e12426c062509e1b18epd

Configure the Mode

Depending on what mode you are building for (either 0, 1, 2, 3, or 4), you need to set values in the HeadlessBuild.properties file.

Mode 0 Properties

In Mode 0, the application is built, binaries are generated at the location specified in HeadlessBuild.properties, additionally if no location is specified they will also be copied to <drive>/<workspace>/<project>/binaries, apart from the temp folder. To configure build.properties for mode 0, in addition to setting mode=0, simply set the platform you are building for to true.

For example, iphone=true

Mode 1 Properties

In mode 1, the application or services are published, the application or services are published to Quantum Fabric, depending on the Quantum Fabric details in HeadlessBuild.properties file. The properties are in addition to setting mode=1.

Note: In order to publish, initial build has to be done in mode 0 before you execute mode 1 and mode 2.

Mode 2 Properties

Because mode 2 is a combination of modes 0 and 1, you must set the properties described in the Mode 0 properties and Mode 1 properties, and set the property mode=2 in order to build and publish to Quantum Fabric. For example:

#Cloud Mode credentials (Applicable only for cloud)
cloud.username=username@kony.com
cloud.password=Abc@123

#Provide Quantum Fabric specific details 
konyfabric.url=https://mbaastest25.konylabs.net:443

# Environment.Name used for publishing example using the format LocalDevEnv
# For example, if your Quantum Fabric Environment URL is:
# https://mycompany.konycloud.com
# then the value is as follows: environment.name=mycompany environment.name=
Mode 3 Properties

In mode 3, Quantum Visualizer combines the web archive and the Quantum Fabric archive which presumes the web archive is already built and generates a combined war/ear file. If the application is not built or the web archive is not available, then Quantum Visualizer displays an error. To configure HeadlessBuild.properties for mode 3, in addition to setting mode=3, the following properties must be set:

#Full path of middleware archive (war/ear). If project has Kony session Manager, provide with-cache archive, for Http session Manager, provide without-cache

archive.combinewar.middlewarearchive= <Path to middleware archive (war/ear, based on whether combinewar.ear / combinewar.war properties)>
combinewar.context= <Provide context name with which final war/ear will be generated.>

#combinewar.war and combinewar.ear are mutually exclusive(only one of them should be true)
combinewar.war=false
combinewar.ear=false

#Provide full path of dependent libraries, separated by semicolons(;) if there are multiple libraries
combinewar.dependencylibraries= <All MobileWeb dependency jars (full path) separated by semicolons(;) should be provided.>

Mode 4 Properties

Because mode 4 is a combination of modes 0 and 3, you must set the properties described in the headings Mode 0 Properties and Mode 3 Properties, and set the property mode=4.

Configure Quantum Fabric Parameters

To configure Quantum Fabric parameters, follow these steps:

  1. Open HeadlessBuild.properties file.
  2. Provide user-name at cloud.username.
  3. Provide password at cloud.password.
  4. Provide Quantum Fabric URL at konyfabric.url.
  5. Provide Quantum Fabric environment name at environment.name.

    Note: Providing user-name, password, and Quantum Fabric URL are mandatory to build an application from the command line.

    #Cloud Mode credentials (Applicable only for cloud)
    cloud.username=username@kony.com
    cloud.password=Abc@123
    
    #Provide Quantum Fabric specific details 
    konyfabric.url=https://mbaastest25.konylabs.net:443

    # Environment.Name used for publishing example using the format LocalDevEnv
    # For example, if your Quantum Fabric Environment URL is:
    # https://mycompany.konycloud.com
    # then the value is as follows: environment.name=mycompany environment.name=
  6. In order to enable services, you need to publish the app at least once from IDE.

Configure the HeadlessBuild-Global.properties File

The following sections explain where to find the HeadlessBuild-Global.properties file and how to configure it.

How to Find the build.properties File

The file HeadlessBuild-Global.properties is stored in the root folder of your workspace. For example, if the name of your workspace folder is Workspace, the path in Microsoft Windows would be something like this:

C:\Users\<username>\Workspace

Example of HeadlessBuild-Global.properties File

The following illustrates the sections that comprise the global.properties file and the values that can be used.

#The file represents the workspace level properties relevant for Headless Build
#Note: Please escape '\' with '\\' in file paths (Ex: C:\\workspace\\project)

 #Specify the eclipse workspace path where the project exists.
workspace.location=

#Full Path to a jar file whose name starts with 'org.eclipse.equinox.launcher_' in eclipse plugins folder
#Example: D:\\eclipse\\plugins\\org.eclipse.equinox.launcher_1.1.0.v20100507.jar
eclipse.equinox.path=

#Android Home-Please specify the path of Android SDK. This is needed only if Android Builds are being triggered
android.home=

Increase Heap Memory

If required, you can increase the heap memory available to your build by modifying the run file (either run.bat or run.sh). To increase the heap memory, type the following memory options in the run file.

java -Xms40m -Xmx512m -Dinput.file=%1 -Dglobal.file=%4 -cp %3 org.eclipse.core.launcher.Main -data %2 -application com.pat.tool.keditor.konyapplication

Generating IPA

To generate IPA, following fields need to be configured before triggering the build.

  1. Open HeadlessBuild.properties file.
  2. Provide Mac User-name at mac.username.
  3. Provide Mac password at mac.password.
  4. Provide IP address at mac.ipaddress.
    #Provide following details to generate IPA file in the case of iPhone or iPad.
    mac.ipaddress=xx.xx.xx.xx
    mac.username=Username
    mac.password=p@ssword
    
  5. Provide profile key chain password, export method, and Team ID.
    keychain.password=p@ssword
    #Possible values for method are "app-store", "ad-hoc", "enterprise", "development" method="development" #Examples for development.team are "G9B5P7QDV2", "PM7453S8QE"
    development.team="G9B5P7QDV2"
  6. Based on the requirement, user should set genipaiphone or genipaipad value to true.

    #Possible values are true/false
    genipaiphone=true
    genipaipad=false
  7. Value of the respective channel should be set to true.
    #Mobile Channel.
    iphone=True
    android=false
    windowsphone8=false
    windowsphone81s=false
  8. Build the application to generate IPA.

Build the Application

To build the application, follow these steps:

  1. Navigate to your application's workspace.
  2. Make sure the files run.bat, build.xml, HeadlessBuild.properties, and HeadlessBuild-Global.properties are present in the workspace.
  3. Update the HeadlessBuild-Global.properties file with details like workspace location, eclipse.equinox.path, and preference. For example.

    workspace.location = c:\\Myprojects\\Releases
    eclipse.equinox.path = c:\\Eclipse_6.5\\plugins\\org.eclipse.equinox.launcher_1.1.1.R36x_v20101122_1400.jar

  4. Update the HeadlessBuild.properties file with details like project.name, application, and platforms that you are building the application for.
  5. Open the command prompt in the workspace.
  6. Type ant in the command prompt. You can see the status of the build on the command prompt window.

    Note: If you want to write the console statements to a file for later viewing, such as for evaluating errors, use the command ant > <drive:\filename>

  7. If the app is built for Android, you can expect the folder to have the following structure (unless otherwise defined in the binaries section of the HeadlessBuild.properties file).

Copyright © 2020 Temenos. All rights reserved.