REBOL/SDK - Encapsulating Programs
Return to Contents
Contents:
1. How Encap Works
2. Types of Encap
3. Running Encap
4. Interactive Mode
5. Encap Arguments
6. Drag and Drop
7. Preprocessing
8. Encap Headers
9. Network Configuration
10. Errors
10.1 Errors During Encapsulation
10.2 Run-time (Decap) Errors
10.3 Trapping Run-time Errors
11. Run-Time Problems
1. 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).
2. 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.
3. 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.
| License.key Required | |
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.
|
4. 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.
5. 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:
| | -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.
6. 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).
7. 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.
8. 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:
| | 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.
9. 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.
10. Errors
10.1 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.
10.2 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.
10.3 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
|
11. Run-Time Problems
- Under Windows, when dragging and dropping an icon onto an encapped
program, the current directory for the program gets reset to C:.
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.
| | REBOL/MakeDoc 2.0 | REBOL is a registered trademark of REBOL Technologies Copyright 2003 REBOL Technologies | 5-Aug-2003 |
|