firstworks Building and Installing SQL Relay

Building and Installing SQL Relay

- Supported Platforms
- Prerequisites
- Installation on Linux, Unix or Unix-like Platforms

- Downloading SQL Relay
- Extracting SQL Relay
- Building SQL Relay
- Installing SQL Relay

- Installation on Windows

- Downloading SQL Relay
- Extracting SQL Relay
- Building SQL Relay
- Installing SQL Relay

Supported Platforms

All SQL Relay components should build and run on relatively modern versions of Linux, Unix or Unix-like systems including Solaris, FreeBSD, NetBSD, OpenBSD, Mac OS X, Haiku and Cygwin, though there are currently some performance and compatibility issues under Cygwin.

x86 and x86_64 platforms are supported, as are non-x86 architectures such as ARM, Sparc, Mips, PPC and others.

uClib/Linux-based systems are also supported.

The command line clients and C, C++ and .NET API's should build and run natively on Windows using Visual Studio but the server components do not yet build and run natively on Windows.

Prerequisites

Before you can compile SQL Relay, you will need to install some pre-requisites.

To build any part of SQL Relay, you need to install the Rudiments library. The library is available at rudiments.sourceforge.net and instructions for building and installing it are available at Installing Rudiments.

To build the non-C/C++ API's, you need to install one or more of Perl, PHP, Python, Ruby, TCL, Java (see note) or Erlang.

Note that the Ruby, TCL and Erlang API's are not supported on Windows, though they may work under Cygwin.

To build the API's natively on Windows, you need to install Microsoft Visual Studio or Microsoft Visual Studio Express.

To build the database connection daemons, you need to install one or more of Oracle, MySQL, PostgreSQL, SQLite, unixODBC, iODBC, DB2, Firebird, Sybase or FreeTDS (for accessing either Sybase or MS SQL Server), MDB Tools for accessing MS Access Databases.

Note that the database connection components are not supported natively under Windows though some do work under Cygwin.

Installation on Linux, Unix or Unix-like Platforms
Downloading SQL Relay

You can download the most current source distribution of SQL Relay from sqlrelay.sourceforge.net.

For Linux, Unix or Cygwin installations, download the tar.gz file.

Extracting SQL Relay

To extract the source distribution, move the file to a location on your machine that you have read/write access and execute the following commands:

> gunzip sqlrelay-X.XX.tar.gz
> tar xf sqlrelay-X.XX.tar

(Where X.XX is replaced with the version of SQL Relay that you downloaded.)

This will create a sqlrelay-X.XX directory.

Building SQL Relay

To build SQL Relay, navigate to the directory that was created by the extraction, make sure your ORACLE_HOME environment variable is set if you want to include support for Oracle, and run:

> configure
> make

The configure script takes lots of command line options, most of which tell it where to find prerequisite software in case any of it is installed in non-standard locations. It also takes the --prefix option in case you want to install it somewhere other than /usr/local/firstworks. For example:

> configure --prefix=/usr/local

This invocation would cause the libraries to be installed in /usr/local/lib, the header files in /usr/local/include, the binaries and scripts to be installed in /usr/local/bin, etc.

There are also options for using cross-compilers and enabling debug and profiling. To see the full list of available options, run:

> configure --help

There are several things to note when using Cygwin.

- You must use the Cygwin shell to build SQL Relay, rather than the Windows Command Line or DOS prompt.
- The file command must be present. If it is not, the build will fail and you will get a very cryptic error.
- SQL Relay cannot be built against non-Cygwin dll's. You can't, for instance, build against the Oracle, Sybase, the native Windows version of MySQL or the native Windows versions of Perl, Python, PHP, etc. Many languages and a few databases come with Cygwin though and others can be compiled from source under Cygwin.

Installing SQL Relay

By default, on Unix or Linux, everything is installed under /usr/local/firstworks by default. You should either create that directory and give yourself full access permissions or install as root.

To install SQL Relay run:

> make install

Libraries are installed in /usr/local/firstworks/lib. Include files are installed in /usr/local/firstworks/include. Binaries and scripts are installed in /usr/local/firstworks/bin. An example config file is installed in /usr/local/firstworks/etc. Java libraries are installed in /usr/local/firstworks/java. Files for other programming languages are installed in the appropriate language-specific directories.

If you install SQL Relay as root, init scripts and files will be installed in the appropriate places under /etc for your system. If you install SQL Relay as a non-root user, the init scripts and files will be installed in similar places under /usr/local/firstworks/etc.

To uninstall SQL Relay run:

> make uninstall

Installation on Windows
Downloading SQL Relay

You can download the most current source distribution of SQL Relay from sqlrelay.sourceforge.net.

For a native Windows installation, download the .zip file.

Extracting SQL Relay

To extract the source distribution, move the file to your desktop or a location on your machine that you have read/write access, right-click on the file and select "Extract All".

This will create a sqlrelay-X.XX directory.

Building SQL Relay

To build SQL Relay natively on Windows, open the Visual Studio Command Prompt and navigate to the directory that was created when SQL Relay was extracted.

There should be a file named make.batch in that directory. Rename this file to make.bat. It is named with the .batch extension because various mail services don't allow .bat files to be emailed around, even if they are inside of an archive. To get around this, the file must manually be renamed.

Unfortunately, building SQL Relay on Windows is currently rather difficult.

The build scripts assume that correct versions of Perl, PHP, Python and Java are all available and intalled in the correct places. If they are absent then build errors occur.

Perl is expected to be installed under C:\Perl (or C:\Perl64 for 64-bit builds).

Python is expected to be installed under C:\Python27

PHP is expected to be installed under C:\PHP

Java is expected to be installed under C:\Program Files\Java\jdk1.8.0_20 (or C:\Program Files (x86)\Java\jdk1.8.0_20 for 64-bit builds).

Though inconvenient, it is possible to modify the make.bat file manually to exclude certain API's.

There are 4 build options. SQL Relay can be built as 32-bit or 64-bit binaries, and with or without Common Language Runtime (CLR) support. There are advantages and disadvantages to building each way but you must build SQL Relay with the same option that you built Rudiments with.

To build 32-bit without CLR support, run:

> make

To build 32-bit with CLR support, run:

> make clr

To build 64-bit without CLR support, run:

> make 64

To build 64-bit with CLR support, run:

> make clr64

Installing SQL Relay

By default, on Windows, most components are installed under C:\Program Files\Firstworks for 64-bit builds or C:\Program Files (x86)\Firstworks for 32-bit builds. You should either create the appropriate directory and give yourself full access permissions or install as Administrator.

To install 32-bit SQL Relay run:

> make install

To install 64-bit SQL Relay run:

> make install64

To uninstall SQL Relay run:

> make uninstall

To run the command line programs, it is helpful to add C:\Program Files\Firstworks\bin or C:\Program Files (x86)\Firstworks\bin to your PATH, as approriate, but not strictly necessary. Alternatively, you could just navigate to C:\Program Files\Firstworks\bin or C:\Program Files (x86)\Firstworks\bin and run them from there.