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:

2. Installing Candle Runtime

Installing Candle is quite straightforward. You just need to:

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,
>> 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.
>> /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.  Candle web server is capable of serving Candle script and some static files:
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:
# 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
# add one line at the end of the file to include additional Candle conf
Include candle.conf
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
You can refer to Apache mod_proxy's documentation for details.