Manually Install and Configure OKWS

At present, OKWS services are built on top of the SFS libraries. To build OKWS services on your machine, you'll first need a reasonable installation of SFS, an installation of the OKWS core services and libraries, and finally, a development directory that allows you to build and link against the OKWS libraries. This document will step through the key points of this installation process, and will also detail some common configuration options.

Eventually, OKWS should not have any requirements aside from the SFS libraries. However, you will find that it works best if you first install the following libraries:

• Pth. OKWS is designed to work with kernel threads, or the standard POSIX pthreads package. However, these features are not currently operational. In the mean time, it's best to use GNU Pth, which is a portable user-level cooperative threading library. It's crucial to compile Pth with –enable-syscall-hard. Soft system calls will (a) not work and (b) break the SFS libraries.
• MySQL. Eventually, you'll probably want to use a database back-end for your web services, and we've built convenient wrapper libraries for the MySQL database libraries. OKWS should be compatible with versions 3.X and 4.X, although the latter is probably better tested. On Linux FC3 (and probably other Linux platforms too), you'll need both the mysql and the mysql-devel packages.
• Dmalloc. You'll most likely run into memory leaks or memory corruptions with your software. SFS and OKWS have good support for Dmalloc.

All packages in the OKWS chain support out-of-directory builds. This means that the source code, and the resulting object files can live in two different locations, even across two different filesystems. On a typical setup, one's source directories might be on an NFS mount, while the build directories will be on local disk (it's slow and a bad idea to be writing object files over NFS). Thus, we recommend making two directories: srcdir and builddir.

If you already have SFS installed on your machine, you can probably skip this step. However, it might be useful to build SFS without optimization, and with use of the Dmalloc library, to assist in the debugging of your OKWS scripts. We offer a way to install a globally accessible SFS build on your machine without disrupting your current installation.

We're currently maintaining a version of the SFS libraries that can be built independent of the higher-level SFS applications. On some machines, building the full SFS distribution might take a while, so our sfslite distribution can be safely substituted for the full build.

You can currently access these libraries from an anonymous subversion repository. You'll first need to install subversion if you don't have it already. Then just issue:

% svn checkout svn://svn2.okws.org/ok/sfslite2/devel/1.2 sfslite-1.2

This checks out a copy of the sfslite sources and places them in the sfslite2 directory on your machine.

To update a previously checked out source tree, change into the sfslite directory and run this command:

% cd <srcdir>
% svn update

Now you're ready to build SFS. Change into your source directory and generate the appropriate configuration scripts.

% cd sfslite-1.2
% sh setup.gnu -f -i -s

Now you can build sfslite. To do this, first make a build directory to build the SFS object files. This might be a temporary directory, but it also might be useful to have the SFS objects around for future reference. Then, you're ready to configure and build:

% cd <builddir>
% mkdir sfslite-1.2
% cd sfslite-1.2
% <srcdir>/sfslite-1.2/cfg --with-mode=shdbg
% gmake

In this example, we're building sfslite in “shdbg” mode (shared debug mode). Shared debug mode will automatically link against the Dmalloc library, will use shared linking, and will not optimize. It will also set the build-tag equal to shdbg. This tag determines installation directories as follows:

We could have also given the configure script (cfg) the mode lite, which has optimization -O2, no Dmalloc linking, and sets the build-tag to lite.

Update (Dec. 27, 2005): for Linux FC3 building (and possibly others as well), you may want to use –with-mode=shdbg or –with-mode=shared or –with-mode=shopt. The reason is that these three modes (which use dynamic linking) will work when it is time to build OKWS (see below for more detail).

Finally, install sfslite:

% su root
# gmake install

Source code is now available via anonymous subversion access. First install subversion (if it's not installed already) and then run:

% svn co svn://svn2.okws.org/ok/okws2/devel/2.0 okws

Now, build a configuration script as usual:

% cd okws
% sh setup.gnu -f -i -s

Next, switch to your build directory, to configure and build OKWS:

% cd <builddir>
% mkdir okws
% cd okws
% <srcdir>/okws/cfg --with-mode=shdbg
% gmake

Again, we're building with debug mode, which sets the same debugging option as above, looks for the SFS build with the same shdbg tag, and finally sets the build tag for OKWS to be shdbg. You can specify custom build tags with the –with-tag=<tag> option. You can link against specific installed builds of SFS with the –with-sfstag=<tag> option. There's a host of build options available, which you can access with ./configure –help. Also note that setting the DEBUG, CC, and CXX environment variables prior to running configure will set compiler debug flags, the C compiler, and the C++ compiler, respectively. Also note that cfg is a lite script that writes your configure options to a file in your build directory, and then calls configure as normal. This way, if you ever need to reconfigure, just run ./cfg from your OKWS build directory.

Update (Dec. 27, 2005): On Linux FC3, OKWS struggles when using static linking. Thus, you may be better off using dynamic linking (shared libraries). That means using one of the configure flags –with-mode=shdbg, –with-mode=shared, or –with-mode=shopt. For any of these to work, you need to have built a corresponding version of sfslite1 (as mentioned above).

Finally, you can install your OKWS libraries, headers and executables:

% su root
# gmake install

As before, this will yield the following install configuration:

We've provided some toy examples of web services and database interfaces to show the different steps involved. They are available in the examples directory of the OKWS distribution. Note that when you build web services with OKWS, you need not put your source in OKWS's source directory; any directory will work.

% cd <srcdir>/okws1/examples
% ./setup

Sets of OKWS web services and database interfaces are known as modules.

% cd <builddir>
% mkdir examples
% cd examples
% <srcdir>/okws1/examples/cfg --with-mode=shdbg
% gmake
% su
# gmake install

As usual, we provide the cfg script with a build tag; it will use this tag to (1) turn on debugging compile options (2) turn off optimization (3) link against dmalloc (4) find SFS with tag debug (5) find OKWS with tag debug and (6) set the tag for this build as debug. It's possible, as usual, to build custom tags with –with-tag=<tag>, to link against certain SFS builds with –with-sfstag=<tag> and to link against certain builds of OKWS with –with-okwstag=<tag>.

By default, the executables and libraries compiled will be installed into:

/var/okws/modules/<name>/<version>/<tag>

The name and the version are specified in the configure.in file for the given module. Of course, when you build your own modules, you should specify these values to your specifications. You can tweak the install prefix by adjusting –with-module-prefix, and you override the module name with –with-name as arguments to the configure script.

You are now nearly ready to run OKWS. First, you'll need to install OKWS configuration files. We provide some for you in our samples directory:

% cd <srcdir>/okws1
% su 
# cp etc/okws_config.dist /usr/local/etc/okws/okws_config
# cp etc/pub_config.dist /usr/local/etc/okws/pub_config

Also, you'll need to setup your log directories so that your logger can write there. This of course depends on where your log files are, and what permissions your logger runs with. See okws_config for more details. For our setup, we would do:

% mkdir /var/okws/log
% chown www /var/okws/log
% chmod 744 /var/okws/log