Introduction

This short tutorial teaches you how to use the QX build automation scripts in making application project development faster and more efficient. At the end of this tutorial, you should be familiar in using QX build automation scripts and should be able to make your own build automation scripts for testing and release.

Prerequisites

To follow this tutorial, you must have the following in place:

Eqela Runtime

Create a Sling project

First let's create a very simple hello world app. Create a new empty directory for it, and name it helloworld. Inside this folder, create a main class source file and name it HelloWorldApp.sling. Also create a Sling project file and name it this.pling. Please see below for their contents:

HelloWorldApp.sling

class:

main
{
	PRINT "Hello world!"
}

this.pling

title = "Hello World App"

Creating a QX build script

A QX build script is a text file (with a qx extension) that describes the actions that will be executed when you execute the script using the eqela command. The file can be named anything as long as the filename extension is "qx". However, customarily the file is named build.qx.

Create the following build script and name it build.qx. Save the build.qx file in the same directory as the helloworld directory (not inside the helloworld directory). Place the following contents inside the file:

use eqela:slingbuild:r19
use eqela:jsh:r4
use eqela:dotnet:2.1.301
set version v1.0.0

build : src {
	requireValue src
	set id ${=getIdNameForPath(${src})}
	eqela:jsh delete build/${id}
	eqela:slingbuild buildNetCoreStatic src=${src}
}

run : id {
	requireValue id
	eqela:dotnet build/${id}/netcore/${id}.dll
}

The line use eqela:slingbuild:r19 configures the slingbuild version to use. Note the r19, this means we will be using the r19 version of slingbuild.

The line use eqela:jsh:r4 configures the version of the Eqela JSH command line tools to use. Note the r4, this means we will be using the r4 version of the Eqela JSH command line tools.

The line use eqela:dotnet:2.1.301 configures the Eqela Dotnet commandline tools version to use. Note the 2.1.301, this means we will be using the 2.1.301 version of the Eqela Dotnet commandline tools.

The line set version v1.0.0 is how we set a variable with its value. In this line, the version here is the variable name and the v1.0.0 is its value. And to use it, simply indicate the variable name by encapsulating it with the characters: ${ and }. For instance:

${version}

Functions

A function defines a command or a set of commands that will be executed in sequence. It has two parts, like in the function below:

build : src {
	requireValue src
	set id ${=getIdNameForPath(${src})}
	eqela:jsh delete build/${id}
	eqela:slingbuild buildNetCoreStatic src=${src}
}

The first part is the function name, which in this example is build followed by the parameter src, notice the : that separates the two. You can have several paramaters, just separate them by spaces. The second part is the code block that includes the actual functionality, enclosed inside characters: { and }.

Comments

Comments are useful and you can make comments in your QX build script by prepending a line with the # character. For example:

# This is a comment. This will be ignored by the eqela command.
# This too is a comment.

Executing the QX build script

Now that we have our QX build script, the last thing we need to do is execute it. To execute the build script, simply run the eqela command with the complete path to build.qx file and the build script name as parameters like this:

eqela <complete-path-to-build.qx> <script-name> <parameter-name>=<parameter-value> ...

For example, to build our hello world app:

eqela build.qx build src=helloworld

After building the project successfully, it will create a build folder (if such folder doesn't exist yet) and will place the actual executable file of the program inside. To then execute the compiled program, execute the eqela command with the build script and the run function like this:

eqela build.qx run id=helloworld

Tips and tricks

This is where the fun starts (if the above is not yet fun). The sample QX build script above is just simple. It would just delete the build folder (if it exists) and then execute the compiled command. You can always make your own build script in a creative and fun way (your imagination is the limit). Below are tips and tricks you can try.

Customizing the versions to use

You can always customize the versions or libraries or tools that you want to use. Say you have a custom or edited version of the Jkop framework saved on your system. You can use it by specifying its complete path to override the version when executing the QX build script, like this:

eqela -Peqela:jkop=/Users/yourhomedirectory/Desktop/my-custom-libs/jkop build.qx build src=helloworld

Now your local Jkop version would be used instead of whatever version would be otherwise configured through the QX files.

Use other Eqela JSH commandline tools

There are also other Eqela JSH commandline tools that you can use aside from the delete command. Consider the following function:

release : src {
	set id ${=getIdNameForPath(${src})}
	call build src=${src}
	set app_name ${id}_${version}

	# Packaging Beta Release

	eqela:jsh delete beta/${app_name}
	eqela:jsh cpto beta/${app_name} \
		build/${id}/netcore/*
	eqela:jsh delete beta/${app_name}.zip
	eqela:jsh zipdir beta/${app_name}

	# Packaging Production Release

	eqela:jsh delete production/${app_name}
	eqela:jsh cpto production/${app_name} \
		build/${id}/netcore/*
	eqela:jsh delete production/${app_name}.zip
	eqela:jsh zipdir production/${app_name}
}

This is a sample release function. At first it will call the build function to build the specified project. After building the project, it will delete the output folder (beta and production), then copy the files from the build folder and put them to the output folder using the cpto command, then compress it as a zip file using the zipdir command and you now have the release packages for beta and production ready to be delivered.