README

This software is an implementation of the steering API for the
RealityGrid project.

Research Computing Services, IT Services, University of Manchester.

It uses:
 * A Base64 codec by Bob Withers.
 * gSoap, an implementation of the Simple Object Access Protocol
   from Florida State University.
 * A Win32 port of the POSIX directory browsing functions by
   Kevlin Henney.

----------------------------------------------------------------------

Prerequisites:

Compilers

You will need a C compiler to build the library. If you wish to use
the Steering library from a Fortran code you will also need a Fortran
compiler. The library has been tested with GCC, Intel, SunPro and MSVC
compilers but hopefully should compile using any standards compliant
compiler.

libXML2

The Steering library uses XML to pass messages and uses the libXML2
library from the GNOME project to facilitate this. To build the
library you will need to have the development files available, that is
the header files as well as the runtime libraries themselves. libXML2
can be downloaded from http://www.xmlsoft.org/ if it is not available
as part of your OS. For Windows (MSVC) users there are binaries
available for libXML2 and its prerequisites from
http://www.zlatkovic.com/libxml.en.html

SunRPC XDR

The Steering Library uses SunRPC eXternal Data Representation to
ensure correct transfer of data between different architectures. This
is available by default on most systems, including Cygwin, but is
missing from Windows MSVC. You can get a compatible implementation for
Windows from http://code.google.com/p/bsd-xdr/

OpenSSL

Certain parts of the Steering library require SSL for secure
communications. Again, you will need to have the header files
available on your system as well as the runtime libraries. OpenSSL is
available from http://www.openssl.org/ if it is not provided by your
OS.

Doxygen/LaTeX

If you would like to build a copy of the documentation from the source
code (much like javadoc) then you will need to have Doxygen
available. You can get it from http://www.doxygen.org/

Doxygen creates HTML documentation by default but it can also create
LaTeX output if you wish. LaTeX is available from
http://www.latex-project.org/

CMake

The Steering library is built with an Open Source tool called CMake
available from Kitware, Inc. It is available from here:
http://www.cmake.org/ and is provided in a number of different
flavours including Win32, Mac OS X, IRIX, AIX, Linux and source code.

The Steering Library requires CMake version 2.6 or later.

----------------------------------------------------------------------

How to build and install:

With CMake you build software "out of source", that is you leave the
source code tree clean and build in a different directory. The
advantage of this is that you can produce a few different builds of
the same software in different directories from the same source tree.

CMake has an interactive "wizard" interface to help you configure the
build options that you require. This interface runs as a stand alone
application on Windows and Mac and runs as a curses-based terminal
application on Linux/Unix.

As an example I will describe a build in the /opt directory of a
Linux/Unix system using the curses-based terminal application. Options
that can be supplied while building the Steering library are detailed
in the next section.

Create the directory:

 $ cd /opt
 $ mkdir RealityGrid
 $ cd RealityGrid

As I am keen to keep the sources separate from the built software I
create two directories, 'source' and 'build', in the RealityGrid
directory. This is an especially good setup if you are going to build
any of the other RealityGrid packages.

Create the two directories and move into the 'source' one:

 $ mkdir source build
 $ cd source

Unpack the source here:

 $ tar xzf steer_lib.tgz

Now move into the build directory, create a directory for the Steering
Library to be built in (do this for each RealityGrid package you are
building) and move into it:

 $ cd ../build
 $ mkdir steer_lib
 $ cd steer_lib

Now run CMake pointing it at the source code directory:

 $ ccmake ../../source/steer_lib

NOTE: At this point it is worth pointing out that however you lay out
your directory structure, when running CMake you need to point it at
the root directory of the source code. If you are running CMake in the
source code directory itself (not recommended) you would run:

 $ ccmake .

You will see a largely blank screen with a set of instructions at the
bottom. CMake works by the user making changes to the options it
presents and then reconfiguring the build to check that these options
are consistent. Once the user has selected the options that they
require and the configuration is consistent CMake will generate the
files to perform the actual build and exit.

At the moment, however, we have not started so there are no options,
just a single placeholder saying "EMPTY CACHE".

Press 'c' to configure and CMake will examine your system to determine
which compiler you have and find certain required packages such as
libXML2. Once this has been done you will see a list of options which
you can navigate about using the arrow keys. Some options can be
toggled ON or OFF using the 'enter' key, others can be edited with
text: while the cursor is over the option press 'enter' then input the
text you want and press 'enter' to save it in the option.

There are also "advanced options" that are usually hidden. Press 't'
to toggle the visibility of them.

After you have changed a few options, press 'c' to re-configure. CMake
will check that what you have chosen is consistent and search for any
extra requirements that you may have turned on. Re-configuring may add
further options for you to choose from, some of which may be advanced
and therefore hidden initially.

When CMake is happy that everything is consistent (and that it knows
where everything it needs to build the software is) a new key action
('g') appears in the lower section of the window. You can still change
options and re-configure, but when you are happy you can press 'g' to
generate the build rules and exit CMake.

Finally, to build the Steering library simply use 'make':

 $ make

Or if you're installing the Library somewhere:

 $ make install

There is a lot more information about CMake and how to use it on
different platforms on their wiki:
http://www.cmake.org/Wiki/CMake

----------------------------------------------------------------------

The Steering Library Options.

Some of these options will only be visible in "advanced mode".

CMAKE_INSTALL_PREFIX

Set this to where you want to install the Steering library
to. /usr/local is the default on Linux/Unix but this is not
recommended for general use. When installed the Steering library is
installed in CMAKE_INSTALL_PREFIX/lib and example applications are
installed in CMAKE_INSTALL_PREFIX/bin.

REG_BUILD_DOCUMENTATION - default OFF

Build the Doxygen documentation?

REG_BUILD_EXAMPLES - default ON

Build the example applications?

REG_BUILD_FORTRAN_WRAPPERS - default OFF

Wrap the Steering library for us from Fortran codes?

REG_BUILD_MODULAR_LIBS - default OFF

Build all the modules as separate libraries? If OFF then only build
the chosen modules into a single monolithic library (see
REG_USE_MODULE_Samples and REG_USE_MODULE_Steering below).

Leaving this option OFF produces a library equivalent to that of a
version 2.5.0 build.

REG_BUILD_SHARED_LIBS - default OFF

Build static or shared libraries?

REG_DEBUG - default OFF

Add debug messages to Steering library output for debugging purposes?

REG_USE_MODULE_Samples - default sockets

Choose the transport over which sample data is moved. Current choices
are sockets, files or proxy.

REG_USE_MODULE_Steering - default sockets

Choose the transport which is used to pass steering messages. Current
choices are sockets, wsrf or files.

REG_SCRATCH_DEFAULT - default .

The directory to use for any temporary files that the library needs to
create. If using File-based methods then steering messages and data
are written into this directory. Checkpoints are also written to this
directory.

REG_KEEP_XML_MESSAGES - default OFF
REG_USE_TIMING - default OFF

Some further debugging aids. Leave OFF for general use.

REG_LOG_STEERING - default ON

Keep a log of steering operations performed during a run.

REG_VALIDATE_XML - default OFF

Validate every message passed between the steering client and steered
application in both directions. This is really just a debugging aid
and should not generally be used due to large speed overheads.

----------------------------------------------------------------------

Other software and documentation

All documentation included with the library is also available from
http://code.google.com/p/computational-steering/

The doc directory contains information on the environment variables
used by the steering library (doc/Environment_variables.txt) and its
dependencies on other software (doc/Dependencies.txt).  The library
code has been annotated with comments for use with Doxygen.  The
resulting HTML documentation is available at
http://code.google.com/p/computational-steering/wiki/Documentation

You can generate this documentation locally via the CMake build tool
described above.

Finally, there is some documentation on the protocols used by the
steering library, both for steering itself and for emitting data sets
(doc/ReG_steering_walkthrough_file.doc,
doc/ReG_steering_walkthrough_socket.doc and
ReG_emitdata_walkthrough.doc, respectively).

The XML schema used for all steering messages is in
xml_schema/reg_steer_comm.xsd.

A Qt-based steering client written in C++ and built with the
RealityGrid steering library is also available for Linux and Windows
from the same site as the steering library:
http://code.google.com/p/computational-steering/

The steering library is able to make use of a Web-Services framework
for remote steering and checkpoint control. To use this you will need
the WSRF-Lite package (http://code.google.com/p/wsrflite/) and the
Steering Web Service code, available from
http://code.google.com/p/computational-steering/. The use of this
framework is described in doc/ReG_Steering_Web_Service.tex.

(Versions of the library prior to 2.0 used the OGSI-Lite package
[http://www.rcs.manchester.ac.uk/research/wsrflite].  The use of this
framework is described in doc/ReG_Steering_Grid_Service.doc.)

gSoap

The library distribution includes gSoap, version 2.7.13.  If for any
reason you wish to change the version of gSoap used then the relevant
files are:

src/stdsoap2.c
include/stdsoap2.h

However, PLEASE NOTE that the version of gSoap used by the library
includes an addition to allow the calling code to control which port
the http connection uses on the local machine.  The latter is
necessary to make use of the GLOBUS_TCP_PORT_RANGE holes in firewalls
that restrict outgoing as well as incoming connections.  Search for
/* REG START */ and /* REG END */ in the source and header files.

The following files are generated (using gSoap) tools from header
files that describe the functionality of the various services
that the steering library can interact with:

src/soapC.c
src/soapClient.c
include/soapH.h
include/soapStub.h
include/soapRealityGrid.nsmap

See the src/gsoap_stubs/README file for more details.

----------------------------------------------------------------------

Any comments, enquiries or pleas for explanation should be directed to
the comp-steering mailing list.  Details available from:

http://listserv.manchester.ac.uk/cgi-bin/wa?A0=COMP-STEERING