REBOL/View Setup and Installation

    REBOL/View Version 1.0
    Updated 5-April-2001
    REBOL Technologies WWW.REBOL.COM
    Send corrections to docs@rebol.com

Contents:

1. Overview
2. Unpacking REBOL
3. Installation
4. Network Setup
5. Proxy Setup
6. System Specific Issues
7. Running REBOL
8. REBOL Scripts
9. Security

1. Overview

REBOL/View is easy to install and use. It requires only minimal installation.

1.1. Where's the Documentation?

Check the REBOL Web site for the latest REBOL/View documentation. It is available from our developers page.

The REBOL/Core User's Guide is also helpful for using View, and is available as a book from our REBOL/Press web site.

1.2. What Has Changed?

If you used the beta test version of REBOL/View, much has changed. Refer to the documentation on our web site.

1.3. What's in this Distribution?

The following files included as part of this distribution:

rebol	The REBOL/View executable program. On Windows this is called rebol.exe.
setup.html	This document about getting started with REBOL/View.
feedback.r	A script for submitting user feedback or questions to us at REBOL Technologies.
license.html	A copy of the REBOL/View end user license agreement.

1.4. Need Help?

There are several sources of help about REBOL:

• Mailing lists - There are a few mailing lists that discuss a variety of REBOL subjects. They are listed on the REBOL developers page.

• Feedback - For bug reports, type: do %feedback.r at the REBOL prompt. Alternately, you can send us email at feedback@rebol.com.

• Online Help - From the console, a built-in help function provides the description, arguments, and refinements for all functions. Type "help" at the REBOL prompt for more information. Several help options are available.

• Script Library - The script library on the REBOL web site provides many simple and useful examples to help you better understand REBOL.

• Source Function - You can obtain the source to many REBOL functions by using the "source" function from the console. For example, "source join" would show you the source code for the join function.

• REBOL.org - An independent REBOL web site that includes a large library of contributed scripts, chat rooms, archives of mailing lists, and other information about REBOL.

1.5. License Agreement

The license agreement can be viewed at any time by typing:

    license

at the REBOL prompt.

2. Unpacking REBOL

REBOL can be unpacked to any directory on your disk. If you experience a problem while unpacking REBOL or any of its distribution files, we would like to know about it. Please contact us at feedback@rebol.com with details about the problem, including the version number or file name of the distribution.

3. Installation

The first time you run REBOL/View, it will display the license agreement. If you agree, you will be shown the installation options menu. It provides options for:

• Installation Directory: where you want to install REBOL/View and its primary files. If you change the default, use REBOL file path notation: /main-dir/sub-dir/sub-subdir/etc. This installation directory will also be used for the public directory which is a file cache for reading files from the web.

• Create the above directory. This checkbox should be on if you want to create the above directory. If the directory already exists, this option is ignored.

• Overwrite user preferences. If this checkbox is on, your user.r file will be overwritten. The default is not to overwrite user.r, because you may have modified it to include other code or data.

Microsoft Windows systems will also include options for:

• Create a REBOL program group. If this box is set, then a REBOL program group will be created in your Windows start menu.

• Put the REBOL icon on your desktop. When set, this option will create a REBOL/View shortcut icon on your desktop.

• Make .r file association. If this option is set, all files that have a .r suffix will be associated with REBOL. This is useful because it allows you to double click on any .r file to execute its script. Of course this is optional. You can associate REBOL with any suffix from the folder view options in Windows.

All other non Windows systems will include options for:

• Enable graphics dithering. When set, the graphics display will be dithered to simulate greater color range.

• Display graphics in monochrome. If this is set, graphics will be displayed without color.

• Allocate exclusive color map. If set, allows REBOL to create its own exclusive color map, instead of sharing the desktop color map. This increases the number of colors REBOL can use. In AmigaOS this requires opening a separate screen.

When you click the INSTALL button, REBOL will copy itself to your installation directory. It will also create a couple other files:

rebol.r	A file that contains additional changes or patches to REBOL. It also contains the code that will help you set up your network configuration. Do not edit this file as it will be overwritten with each new release.
user.r	A file that holds user preferences. On multi-user systems, there can be a different user.r for every user. The user.r file is not part of the distribution, but it will be built the first time you run REBOL. The file can be edited and extended in whatever way you desire.
prefs.r	A file that holds your REBOL/View preference settings. You can edit this file to change your preference settings the next time you boot REBOL/View.

4. Network Setup

When you install, you have the option of setting your network preferences. REBOL will attempt to automatically determine your settings, but the result may vary depending on your operating system and its installed applications.

You can edit your network settings for Email and Proxy from the preferences panel.

Your email address should appear as it would normally; for example, name@domain.com.

Your email server is required if you want to send email from REBOL. If you don't know the name of the server, check the settings or options menu of your current email program. Hint: if your email address is bob@example.com, your email server may be mail.example.com. Otherwise, contact the network service provider for the name of the email SMTP server.

If you make a mistake or later decide to change any of these network settings, you can bring up the preference panel again by typing at the console:

    set-user

Network settings are stored in the %user.r file, and can be modified with any text editor. The network setting appear in a line the begins with set-net. For example:

    set-net [luke@rebol.com mail none none]

The line can be modify to provide your startup network configuration. See the REBOL/View User's Guide for more information.

5. Proxy Setup

Some organizations use a firewall system or proxy server to access the Internet. To operate with these systems, you will need to provide additional network information.

To change proxy settings click on proxy setup in the preference panel. You will then be prompted for the name of your proxy host. This is the computer or firewall that operates as a proxy. You will also need to supply the port number used by that system for proxy requests. Typically, this is port 1080 for SOCKS proxy servers, but it can vary depending on the setup. If you don't know, look at the Web browser settings or ask your network administrator.

The following proxy protocols are supported:

    socks   - use the latest SOCKS version (5)
    socks4  - use socks4 proxy
    generic - use generic CERN proxy
    none    - use no proxy

See the REBOL/View User's Guide for more information.

6. System Specific Issues

REBOL is system independent. A script produced on a Windows NT system can be run without modification on a Macintosh, Amiga, Solaris SPARC, Linux, Windows CE, and other supported platforms. However, REBOL does integrate with operating systems in different ways. They are described below.

6.1. Amiga

Use Amiga's Tool Types to set the REBOL icon to the REBOL executable file. The REBOL console interface now maps shift-left to the home key and shift-right to the end key.

6.2. BeOS

REBOL for BeOS is run from a terminal window rather than a console. To open a terminal, click on the Be menu, then choose the Applications sub-menu, and select Terminal. Type the path to the REBOL executable program and press ENTER.

Default permissions include read and write permissions for the user and for the user's group, and read permissions for all others.

6.3. UNIX/Linux

REBOL uses the TERMCAP entry provided by UNIX-based systems. If some of your function keys are not operating properly, you will need to setup your computer's TERMCAP entry.

Default permissions include read and write permissions for the user and for the user's group, and read permissions for all others.

7. Running REBOL

REBOL can be run from Icons or from a shell command line.

7.1. Running from Icons

In Windows REBOL can be started by clicking on the REBOL program icon, an associated .r file icon, or a shortcut icon. In AmigaOS REBOL can be started by double-clicking on the REBOL tool icon or the project icon of a REBOL script.

7.2. Running from a Shell

REBOL can be started from the command line with a variety of arguments. To view the options available for any REBOL version, type

    usage

at the REBOL prompt.

The format of argument fields on the command line is:

    REBOL options script args

All of the arguments are optional and any combination is permitted.

    Options -- one or more of the program options as listed below. 
    Script -- a script file to evaluate. 
    Args -- arguments passed to the script. 

Typically, you will provide REBOL with the name of the script file that you want to evaluate. For instance:

    REBOL script.r

To run this script with an option, such as with security turned off:

    REBOL -s script.r

The dash (-) is used for a single-character option (shorthand). A double dash is used for a full-word options. This is standard practice on many operating systems.

For instance, to obtain usage information about REBOL, type:

    REBOL -?
    REBOL --help

To run the program without opening a separate window:

    REBOL -w
    REBOL --nowindow

To use REBOL scripts with CGI, you can write a command line that changes multiple options at the same time:

    REBOL -cs cgi-script.r

This will run in CGI mode with security turned off. This is required for various web servers that restrict the number of arguments allowed on the command line (such as the Apache server on Linux).

You may use "--" to signal the end of command line switches. All remaining items on the command line will be passed to REBOL as an argument.

    REBOL -- this is an argument

In this case it is assumed that you have a default script specified in your user.r file.

7.3. Quitting REBOL

You can quit REBOL at any time by typing:

    quit

This can be done within any part of a script:

    if now/time > 12:00 [quit]

8. REBOL Scripts

REBOL scripts are written as text files, allowing you to create and modify them with any text editor. The normal suffix for REBOL scripts is .r, but any suffix is permitted.

Every script begins with the word REBOL followed by a header that provides information about the script. The header has many uses, including identification, documentation, archiving, revision tracking, and script requirements.

Here is an example script with a typical header:

    REBOL [
        Title:   "Example Script"
        Date:    24-mar-2001
        File:    %include.r
        Version: 1.2.3
        Author:  "Luke Lakeswimmer"
        Purpose: {
            Just show the folks how it's done.
        }
    ]

    print read http://www.rebol.com

See the REBOL/View User's Guide for complete details.

9. Security

By default, security is set to only allow scripts to modify or deleting files or directories in your installation sandbox (all the directories at and below your installation directory).

For scripts that you trust, you can run REBOL with a variety of security settings that control file and network security, including file and directory sandboxes.

Security Warning

Only you, the user, can approve changes to security. When running REBOL, if you receive a security warning, do not approve a change of security or allow file operations if you do not trust the script. Inspect the script first before running it or obtain the script from a well trusted source.

To disable security for your own scripts, you can run REBOL with security disabled. For instance, if you use an editor or development environment to interactively develop scripts, run REBOL with a command line such as:

    REBOL -s script.r

When working this way, take caution to only run scripts that you have written or scripts that you trust completely.

See the REBOL/View User's Guide for complete details.