REBOL/SDK - Encapsulating Programs

Encrypt and embed your program within a single executable file.

How Encap Works

REBOL/Encap functions in a manner similar to that of a compiler. You provide Encap with one or more input scripts, include files, graphics files, sounds, or other resources, and it outputs a single executable binary file. The binary file can stand alone without any other files, which makes it a good way to distribute REBOL applications.

The script and other resources that are provided as input are compressed, encrypted, and embedded within a special, platform-specific REBOL binary. Upon execution, the files are decrypted and decompressed. This technique keeps the executable file small (with compressed sections) and hides scripts from users. (See note on limitations).

Types of Encap

Several versions of the Encap program are provided in this SDK. You will want to pick the one that makes the most sense for the program that you are creating.

EnBase	provides the basic set of low level REBOL natives and functions. You can use this to encap simple utility scripts for file and network operations (such as CGI scripts for example).
EnPro	adds to the /Base the features found in /Pro, including encryption, shell access, and DLL function calls.
EnFace	adds graphics and sound to the Pro features above. For Linux and Unix, do not use this version unless you know that the target systems have X Windows installed and running.

Additional versions of Encap are available for REBOL/Command developers.

Running Encap

There are three ways to run Encap:

Interactive mode
Just run it and it will prompt you for the input and output files.
Command line arguments
You provide the input and output filenames on the command line.
Drag and drop
You can drag and drop the source script onto the appropriate Encap icon (Windows only).

Each of these methods will be described below.

Note the license.key file contains your license key and has to be located in the same directory as the Encap program. If the license file is missing, Encap will display an error message and refuse to start up. The encapped programs do not require the license.key file to run, the license.key file should not be distributed.

Interactive Mode

If you run any one of the Encap programs, it will prompt you for the files it needs.

Here is an example of what you will see:

REBOL/Encap 1.1.0.3.1
Copyright 1997-2002 REBOL Technologies
REBOL is a Trademark of REBOL Technologies
All rights reserved.

Component: "Encryption" 1.3.2.2 (24-Mar-2002/20:13:52)
Component: "Big Numbers" 1.2.2.2 (24-Mar-2002/20:13:52)
Component: "RSA Encryption" 1.3.2.2 (24-Mar-2002/20:13:58)
Component: "System port" 1.1.2.3 (24-Jan-2002/19:54:41)
Component: "Licensing" 1.8.2.3 (24-Mar-2002/20:13:53)
Component: "Encapsulation" 1.2.10.9 (19-Oct-2002/18:40:37)
Licensed to: REBOL.com <luke@rebol.com>
License ID: 4-00000-1

Input file name (REBOL script to encapsulate)?

At this point, type the name of your REBOL input file, such as test.r. The program will then request an output file:

Output file name (test.exe)?

You can just press return to use the default that is suggested, or you can enter a new output file name.

Encap will process the file and provide status information such as:

Processing files:
     Code: test.r

Preprocessing complete. Encapsulating...

Encapsulation complete. No errors.

Input File Summary
------------------
    Input:   test.r
    Title:   "Untitled"
    Version: 0.0.0
    Size:    731 bytes
    Params:  []

Output File Summary
-------------------
    Output:  test.exe
    Blocks:  ~0
    Strings: ~15
    Payload: 367 bytes
    Size:    434702 bytes

Elapsed: 0:00:00.44

Press enter to quit.

The program will wait for you to press the ENTER key before closing the window (in Windows version).

Note that if the output file already exists, it will be overwritten. If the output file is currently running, or if it is write protected, or the name of a directory, an error will be shown.

Encap Arguments

The Encap programs can also be provided with command line arguments to specify the input and output files, as well as a few options.

The general syntax for the command line is:

encap [options] [input-files]

however, options are also allowed anywhere on the line.

One or more input-files can be provided, and they will be appended in the order that they appear.

The Encap options are:

Option	Description
-o file	Specify an output file.
-p	when done, pause until user hits ENTER key
-q	quiet mode. Do not show verbose status information.
-t file	write out the entire encapsulated script and data as a text file. This option lets you view the entire script as it appears within the encapsulated binary.
-?	print usage help information

If an output file is not specified, the default file name will be the name of the first input file (with the .exe suffix added on Windows versions).

On Windows, the output window will close as soon as the process has completed.

Example command lines:

enpro test.r

enpro test.r -o t2.exe

enpro -q test.r file.r gui.r -o t3.exe

enpro -q test.r file.r gui.r -t temp.r

Note that if the output file already exists, it will be overwritten. If the output file is currently running, or if it is write protected, or the name of a directory, an error will occur.

Drag and Drop

A simple and convenient way to Encap scripts from Windows is to drag and drop the input script onto the Encap program icon. The file will be encapsulated and saved to an output file that has the same base name as the input file. For example, providing test.r as input will produce test.exe as a result (on Windows).

Preprocessing

As part of the Encap process, all input files will be scanned for include files and other build-time options. This preprocessing step makes the full power of REBOL available to you during the Encap process, allowing you to dynamically include and construct elements of your script (e.g. version numbers or encryption keys for example).

Complete details can be found in the Preprocessing chapter.

Encap Headers

Although it is not required, you can provide additional Encap options within the REBOL header of the script file that is provided as input. To do so, add an Encap block to the header.

For example:

REBOL [
    Title: "Fringe Area Localizor"
    Date: 1-Dec-2002
    Author: "Luke Lakeswimmer"
    Encap: [quiet secure none]
]

The Encap block has following options:

Option	Description
cgi	Use this option if you intend to run the encapsulated binary within a CGI environment, or within a FastCGI environment in CGI compatibility mode. This is equivalent to the "-c" command line argument in REBOL.
title "name"	This option is used only with graphical versions. It allows you to provide a prefix for all window titles of opened by the encapsulated program. If a title is not provided, the default title prefix is "REBOL - ".
secure level	The word "secure" followed by a word or block with security settings defines the default security settings for the encapsulated script. The "level" follows the same syntax as the argument in the SECURE REBOL native, e.g. "secure none" completely disables security, "secure [???: file quit %documents/ [allow read]]" prohibits access to all files, except read access to files in the "documents" directory. Please see the REBOL User's Guide for more information on the SECURE native.
no-window	Do not open the REBOL console window upon startup. Equivalent to the "-w" command line argument in REBOL/Command.
quiet	Do not display the startup banner and component list upon startup, and do not display a progress indicator (spinning line) during network activity. Equivalent to the "-q" command line argument in REBOL. Default if not specified.
no-quiet	Verbose startup, do not be quiet. This is the opposite of the "quiet" option.

Examples:

REBOL [
    Title: "Program"
    Encap: [title "Program 1.0 "]
]

This example will use the above title prefix for all windows.

REBOL [
    Title: "CGI Script"
    Encap: [cgi secure none]
]

This example will check the CGI environment and run without security.

Network Configuration

Earlier versions of Encap had a network configuration option to control initial network setup. This has been removed from the Encap program and is now provided as a source code module that you can customize for your requirements.

The no-network option is no longer required in the Encap header block.

Errors

Errors During Encapsulation

These errors can occur while using Encap to create a program:

License key is missing.
You must have the license.key file in the same directory (folder) as the Encap programs that you are using.
Output file cannot be created.
If the output file is running, if the output file is write protected, or is the same name as a directory it cannot be written out.
Cannot load file: (filename).
If the file has a syntax error, then this error will occur. For example, if you are missing a quote on a string, you will see this error occur. To see the specific error, load the script with REBOL (by either running REBOL and providing the script as an argument or by loading it within REBOL with a line such as LOAD %filename.r).
File not found: (filename).
The file does not exist.

Run-time (Decap) Errors

Unable to find encapsulated data.
The encapsulated program must be able to locate itself on disk. This error will occur if your program runs in an environment that incorrectly identifies the program name or the path to the program. This may occur on older versions of Windows when the filename is longer than 8 characters, or on Linux and Unix if the program is run from a context other than the shell, and that context does not provide the program with the correct path argument to the program.
No data has been encapsulated into this binary.
You did not include any source code with your program.
Script execution errors.
Any other errors will be shown as normal REBOL errors. If you do not catch the error, the REBOL console window will pop open and display the error message to the user. To avoid this in your products, see the section below.

Trapping Run-time Errors

You can use the REBOL TRY function to trap errors that might occur in your program and display a more pleasant message to the end user.

Using TRY to catch errors is very simple. Here is an example:

REBOL [Title: "Test Program"]

if error? err: try [
    ; Put your code here...
    #include %funcs.r
    #include %gui.r
    include foo bar
][
    err: disarm :err
    print [
        "A program error has occurred:"
        mold err
    ]
    ask "Press ENTER to stop"
]

Now when an error occurs, your code can print the message:

A program error has occurred:
make object! [
    code: 300
    type: 'script
    id: 'no-value
    arg1: 'include
    arg2: none
    arg3: none
    near: [include foo bar
        #include %funcs.r]
    where: 'do-boot
]
Press ENTER to stop

If you included View functions, you can display a popup message by changing the error handling block to use an ALERT or create a custom layout:

][
    err: disarm :err
    alert reform [
        "A program error has occurred!"
        err/id err/where err/arg1
    ]
    quit
]

The error can also be sent to a web site with HTTP and CGI or emailed to a specific address.

To send it via HTTP, use code such as:

err: mold disarm :err
if confirm "A program error has occurred. Send it?" [
    read/custom http://www.example.com/cgi-bin/error.cgi
        reduce ['post err]
]
quit

Run-Time Problems

Under Windows, when dragging and dropping an icon onto an encapped program, the current directory for the program gets reset to . A good solution is to change-dir to the path of the argument (change-dir first split-path file).
Under older versions of Windows, if the encapped program file name is greater than 8 characters (not including suffix) or contains special characters, the encapsulated program may fail to start due to the filename character substitution used by Windows file directories. One solution is to shorten the file name.
On all operating systems, if the encapsulated program is run from another program that does not properly set the path to the executable file (your program), the program may fail to start. Sometimes this problem can be solved by specifying the full executable path for the program.

	Contents
How Encap Works Types of Encap Running Encap Interactive Mode Encap Arguments Drag and Drop Preprocessing Encap Headers Network Configuration Errors Errors During Encapsulation Run-time (Decap) Errors Trapping Run-time Errors Run-Time Problems