Riverwatcher Active Content Environment

RACE Documentation:


RACE Installation Guide

RACE can be compiled as an Apache Module or as a stand alone shell. It has been tested as both under Mac OS X, a variety of recent Linux distributions, Solaris 8, and FreeBSD, but should compile with little or no modifications under most Unix platforms that support Apache 1.3.x.

If you do have problems compiling for your platform, please check the Forums at http://www.racekit.net. If you do determine that additional changes or modifications are required to work on your platform, please post the details so that we may incorporate your changes and modifications into future releases to make the installation process easier for everyone.

As an Apache Module, RACE requires Apache 1.3.22 or newer on the 1.3.xx path. Plans are being made for Apache 2.x compatibility.

While not required, it is recommended that you also install a database server for use with RACE. RACE is a powerful yet simple language, but it is the ease with which remote data sources can be accessed that makes RACE really shine.

Currently, RACE supports MySQL, Postgresql, Msql, and ODBC compliant data sources through the iODBC API. Testing is performed for all database types supported, but MySQL is by far the most popular so far.

The RACE Shell provides a mechanism for writing scripts to perform data manipulation for day to day use, as opposed to for the web. The easy access to databases and the template driven architecture make many tasks quick and easy to develop. The shell may also be able to interface with web servers other than Apache on your platform, much like Perl, allowing RACE to act as a CGI extension.


Procedures for Installation:


RACE can be compiled with the Apache source, or as a dynamically-loaded module using the "apxs" tool. While it is possible to compile race as a shared module when compiling against the Apache source, doing so with "apxs" is easier, doesn't' require the Apache source on your server, and also provides a simpler path for future updates.


Installation via apxs:


The procedure for installing RACE with apxs is as follows:
  • Unpack the RACE source
  • type 'cd race-[version]'
  • type './configure --with-apxs[=/path/to/apxs]' (additional options may also be included; see below for more)
  • type 'make'
  • type 'make install'
  • Add the following MIME type to the httpd.conf file:
    AddType     application/x-httpd-race race ace
  • Restart your Apache web server and start coding in RACE!

The Makefile will add the necessary information to your httpd.conf file to automatically include RACE when you restart your web server.

If you run into problems installing or running RACE when installed via this method, please review the notes at the end of this file.


Installation via the Apache source:


While the procedure for compileing RACE with the Apache source is similar, it does require that you download and upack the Apache source first. The time to compile is longer, and it also requires making more changes to your httpd.conf file.
  • Unpack the Apache source
  • Unpack the RACE source
  • type 'cd race-[version]'
  • type './configure --with-apache=/path/to/apache' (additional options may also be included; see below for more)
  • type 'make'
  • type 'make install'
  • Now, change to the root of the Apache source directory.
  • If this is your first time compiling Apache on this server, you will need to determine what configuration options you require for Apache and it's default set of modules. To include RACE, do the following:

    ./configure --activate-module=src/modules/race/librace.a [append any additional directives you require]

    If you have compiled Apache before, then you can do the following:

    ./config.status --activate-module=src/modules/race/librace.a

    In both cases, you can also append '--enable-shared=race' to cause RACE to be compiled as a dynamic module while compiling Apache.
  • type 'make'
  • type 'make install'
  • Add the following MIME type to the httpd.conf file:
    AddType     application/x-httpd-race race ace
  • Start (or restart) your Apache web server and start coding in RACE!

  • Configuration Options:


    The following options are provided to dermine what database servers RACE should support:
    --with-mysql Add MySQL support
    --with-msql Add Msql support
    --with-pgsql Add Postgresql support
    --with-iodbc Add ODBC support through iODBC


    The configure script will attempt to locate the necessary include files for the database server types you select. You can also specify the prefix used when you installed the database server by appending =/path to the end of the above argument. For example:

        --with-mysql=/sw

    This would locate MySQL installed on a Macintosh OS X system in which MySQL was installed via the Fink package management system.

    At least one of the following options must also be supplied when you run configure:

        --with-apxs

        --with-apache=/path/to/apache

        --with-shell

    If the appropriate apxs is in your path, then you don't need to specify a path to apxs when using --with-apxs. If, however, it is not in your path, then specify the correct apxs to use with: --with-apxs=/path/to/apxs

    The path specified with --with-apache should be the top directory where you unpacked the Apache source.

    You may also append a path to --with-shell to specify where it should be installed when you type 'make install'. By default, the shell is installed to /usr/local/bin.

    Currently, if you do specify --with-shell, you cannot also specify --with-apxs. Both methods require incompatible changes to the Makefile, so in order to install both the shell and the apxs module, you will have to do the following:

    ./configure --with-apxs
    make
    make install
    ./configure --with-shell
    make
    make install


    Examples:


    An example configure line, which would prepare RACE for both the Apache source and the shell, might look like:

    ./configure --with-apache=/usr/local/src/apache_1.3.27 --with-shell --with-mysql=/usr/local

    After typing 'make', you will see instructions for compiling RACE with Apache. Generally, you should then change to the Apache source directory and execute the Apache configure script with the options you generally use. Generally, I try to use the following for Apache, because it offers the most flexibility:

    ./configure --enable-modules=all --activate-module=src/modules/race/librace.a --enable-shared=max

    After making and installing Apache, add the MimeType specified above and RACE is ready to go!

    You can verify that RACE is working by creating a small test file containing the following line:

    <%system>

    Save the file in your web directory with the .race extension and load the page into your web browser. You should see a list of statistics including the version of RACE installed and some information about your client browser.



    Apxs Notes:


    On a variety of systems, especially when Apache is preinstalled with the operating system, it appears that apxs is broken, or that the compilation environment of the original Apache server is different from the end-user environment. We have encountered this problem with Mac OS X 10.2.6 and with some Red Hat Linux distributions.

    Research has indicated that this is not limited to RACE -- many of these same systems have problems with php or mod_perl when installed via apxs as well.

    If you are unable to compile RACE when configured with --with-apxs or if it compiles, but the web server gives odd errors when restarted after installing RACE, then you will have to compile RACE with the Apache source. In each instance where we have encountered this problem, compiling and installing a fresh version of Apache has allowed RACE to work.

    If you have information on how to work around this problem on your platform, please post your discovery in the forums at http://www.racekit.net, so we can include the fix in future releases.


    Other Notes


    If you find that you need special compilation options to get either RACE or the RACE Shell to work, you can set the following environment variables before running ./configure in the Race directory:

    CFLAGS compiler flags, usually optimization or debugging flags
    LDFLAGS linker flags, usually -L/library/path/to/search
    INCLUDES usually -I/include/path/to/search
    LIBS usually additional libraries to include (-llibrary)


    In the Bourne Shell (/bin/sh), you can do something like the following:

    CFLAGS="-g" ./configure --with-shell

    This will prepare the Makefile for compiling the RACE Shell with debugging information included (assuming you're using gcc).

    If you are using a C based shell (csh, tcsh), then use the setenv command before calling configure. The same example would look like this in csh:

    setenv CFLAGS "-g"
    ./configure --with-shell



    Please check out http://www.racekit.net for additional help and documentation. The latest version will always be available at this site, and you can find out the latest news and tips by visiting the forums.


    RACE Documentation



     
    Copyright 2009 Riverwatcher, Inc. Hosting by Riverwatcher Studios