Candle Runtime Reference

Version	: Candle 0.12
Published date	: Nov 4, 2012

1. Introduction

Candle Runtime refers to the runtime environment that is needed to process a Candle script. Because Candle is an interpreted scripting language instead of a compiled language, such runtime is always required.

Candle itself is an platform independent scripting language. In current beta release, Candle Runtime runs on Windows (Win 2000 and above) and Linux (Ubuntu and Fedora), 32bit and 64bit.

As Candle is an scripting language, a program in Candle is distributed with the source script directly. There's no extra compiling step, like Java or .Net.

Candle scripts are normally stored in 3 file extension:

*.cmk is for Candle markup document containing static markup data;
*.csp is for Candle script document containing Candle routines;
*.run is for Candle script that contains a main method, which is the entry point of Candle execution;

2. Installing Candle Runtime

Installing Candle is quite straightforward. You just need to:

Download the corresponding package for your platform:

Windows 2000 and above: candle-0.10-beta-win.zip
Ubuntu: candle-0.10-beta-lin.tar.gz

Unpack the package to a folder;

On Windows, you'll see 3 executables in the unpakced folder:

candle.exe is the binary executable to run Candle scripts as desktop program;
candle.com is the binary executable to run Candle scripts as command line program;
candle-server.exe is binary executable to run Candle as a simple web server;
The binary files are directly executable.

On Linux, you'll see 2 executables in the unpakced folder:

candle is the binary executable to run Candle scripts as desktop program;
candle-server is binary executable to run Candle as a simple web server;
After you extract the files, you should also change the file permission on the above two files to ensure they are executable;
You also need to check the libraries (librt, libodbc) that Candle depends on are installed in your system;
Then you need to add Candle libraries to the system. On Ubuntu, the commands can be:
sudo gedit /etc/ld.so.conf.d/candle.conf
# add the following line to the newly opened file, then save it
/candle-installed-folder/
#reload ld cache
sudo ldconfig
Candle is currently a 32-bit program, so for it to run on 64-bit Linux, you'll need to install the necessary 32-bit packages. For 64-bit Ubuntu, the command is:

sudo apt-get install ia32-libs

3. Running Candle Scripts

After you have installed Candle. There are 3 ways to run it: as command line program, as desktop GUI program (on Windows only in current beta release), and as a simple web application server.

3.1 Candle as Command Line Program

Candle command line currently only takes one argument or option, that's the path to the script to be executed. For example,

on Windows, you'll type something like (assuming you installed Candle on C: drive):

>>
c:/candle-installed-folder/candle
  path/some-candle-script.run

Note: you don't need to specify the Candle executable extension ".com", Windows is able to auto detect that.

on Linux, you'll type something like:

>>
/candle-installed-folder/candle
 
path/some-candle-script.run

The path to the script can be in absolute path or relative path. If the path is relative, then it is resolved based on the current directory of the command line environment.
For convenience, it is recommended you add Candle to your PATH environment variable.

3.2 Candle as Desktop Program

This section is more for Windows platform, because on Linux there's no difference between command line and desktop program. Thus you'll see only candle executable on Linux.

On Windows, candle.com is a command line program, whereas candle.exe is a desktop program. The only difference you'll notice is that when running as desktop program, you'll not have access to standard input (stdin) and standard output (stdout).

For convenience, you can create Windows shortcut to run certain Candle *.run script. The target of the shortcut would look like the following:

c:/candle-installed-folder

/candle.exe
path/some-candle-script.run

Note: You might want to associate *.run and *.csp file extension with some text editor, instead of candle.exe, so that Candle scripts are not executed unintentionally when you double clicked on any of them.

3.3 Candle as Web Application Server

Candle comes with a simple HTTP web server. The purpose of this web server is not to replace any of your heavy duty web servers, like Apache. It is developed to allow Candle to be used for server-side scripting.

To run Candle web server, you just need to run candle-installed-folder/candle-server.exe.

You can then open your browser and go to 'http://127.0.0.1:7077/'. You can see the entire Candle website content now servered on your local machine, including the online query editor 'http://127.0.0.1:7077/demo/editor.csp'.

Candle web server has been configured to server Candle documentation pages out-of-box. To use it for your own purpose, you'll need to configure it. The configuration file is stored in /candle-installed-folder/conf/server-conf.cmk. Below is one sample configuration file.

<?cmk1.0?>
<server port=7077 log="logdir" mode="production" max-content-length=33554432>
    !! MIME mapping settings omitted
    <domain name="127.0.0.1:7077" root='go:candle:doc/web' default-page="index.csp" />
    <domain name="candlescript.org" root='file:///var/candle/www' default-page="index.csp" />
</server>

Field highlighted in red are the ones you may need to change to the corresponding values on your machine.

Candle is capable of serving multiple domains. "127.0.0.1:7077" is for local testing. "candlescript.org" is an example of an actual domain name.

port=8080

this is the IP port number that the server listens to;

max-content-length=33554432

the maximum content-length for a request that is accepted by the server; for a multipart request, this limit is imposed on individual parts of the request;

name="127.0.0.1:7077"

IP in the name:

this is the domain name or IP address that Candle web server shall handle;
if you just want to test it on your local machine, "127.0.0.1" is the right setting;
if you want to test in a LAN environment, you can also set it to the (static or dynamic) IP of your computer;

if you are accessing Candle web server directly, not proxied behind any web server, then you should also put the port number in the name;

root="file:///var/candle/www"

this field should be the file URL to the document root of the web site.

default-page="index.csp"

this is the default page for Candle web server to serve when the requested URL points to a directory instead of a file;

Candle web server is capable of serving Candle script and some static files:

*.csp: treat as Candle script;

the main() function in the script is executed, and it return value is serialized and served to the client;

*.run: treat as Candle script;

the main() method in the script is executed, and it return value is serialized and served to the client;

*.htm, *.html: treat as text/html;
*.css: treat as text/css;
*.js: treat as text/javascript;
*.jpg, *.jpeg: treat as image/jpeg;
*.gif: treat as image/gif;
*.png: treat as image/png;
*.ico: treat as image/x-icon;
*.txt treat as text/plain;
others file extensions are reported as error;

If your web site has other types of static files to be served, you can open the configuration file /candle-installed-folder/conf/server-conf.cmk, and add the MIME mappings to the file as:

<mime
type="mime-type"
extension="file-extension"
/>

!! e.g. <mime type="text/plain" extension="txt" />

You can refer to our tutorial for details on using Candle for server-side scripting.

Integrate Candle Web App Server with other Web Server

In production environment, it is more likely to run Candle as a light-weight application server behind some heavy-duty web server, rather than as a standalone web server by itself. Since Candle server is a standard web server by itself, you can easily setup the integration by configuring the reverse-proxy in your web server to point to Candle app server.

Based on last testing, only Apache's reverse-proxy module works properly with Candle server, because Candle uses HTTP chunked transfer encoding in its response, and currently only Apache's mod_proxy supports that. The built-in proxy modules of nginx and lighttpd have been tested, but neither seems to work.

Below is the detailed steps to configure Apache's mod_proxy to work with Candle:

On Windows:

Open and edit Apache conf file /apache-installed-folder/conf/httpd.conf:

# enable mod_proxy
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
# add one line at the end of the file to include additional Candle conf
Include conf/candle.conf

On Ubuntu:

sudo a2enmod proxy
sudo a2enmod proxy_http

Then open and edit the Apache conf file /etc/apache2/sites-available/default:

# add one line at the end of the file to include additional Candle conf
Include candle.conf

Create a new file with name candle.conf under Apache conf folder with the following content:

ProxyRequests Off
# map a directory to Candle web app server
ProxyPass /dir http://127.0.0.1:8080/dir
# map a particular script to Candle web app server
ProxyPass /dir2/some-script.csp http://127.0.0.1:8080/dir2/some-script.csp

Restart Apache;

You can refer to Apache mod_proxy's documentation for details.