REBOL
Downloads Products Documents Community

REBOL/SDK - Encapsulating Programs

SDK Documentation

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.

EnBaseprovides 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).
EnProadds to the /Base the features found in /Pro, including encryption, shell access, and DLL function calls.
EnFaceadds 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:

  1. Interactive mode
    Just run it and it will prompt you for the input and output files.
  2. Command line arguments
    You provide the input and output filenames on the command line.
  3. 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:

Run-time (Decap) Errors

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

  1. 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).
  2. 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.
  3. 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.
About | Contact | Support | Privacy | LicenseREBOL Technologies 2013