 |
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.
|
|
|
|
