Obyx can be compiled from code using a small number of supporting libraries. This documentation explains what libraries are necessary and how the code can be compiled to get a working version of Obyx.

System Requirements

Obyx is loosely based on the LAMP architecture. Basic Requirements:
  • OS (e.g. Linux Debian)
  • HTTP Server (e.g. Apache 2)
  • Database (e.g. MySQL or PostgreSQL)
Although it may be installed on a number of configurations, this documentation is based on installation for Linux Debian server. It is assumed that Apache and MySQL are already available, configured and running.

Installation Process

This installation guide consists of the following steps:
  • 1. Preparation of host: Application support installation
  • 2. Preparation of host: Library installations
  • 3. Set up server file structure
  • 4. Setup compile settings
  • 5. Download source code (SVN)
  • 6. Compile obyx.cgi binary
  • 7. Configure HTTP server
  • 8. Test

Preparation of host: Application support installation

It is assumed MySQL/PostgreSQL and Apache are already installed and working. The Obyx source code is C++ and requires gcc/g++ compiler to compile. The source code is stored in a SVN repository, so svn is necessary to get it. Installation of these can be used with aptitude or similar.
g++ Compiler (>= 4.1)
The obyx source code is C++ and requires the g++ or compatible compiler to compile. 
g++ 
sudo aptitude install build-essential
svn
Used for svn access. Not necessary if you prefer to download tarballs. 
subversion 
sudo aptitude install subversion-tools

Preparation of host: Compile-time Library installations

Obyx relies on a number of supporting libraries at compilation time. Installation here is provided using the aptitude tool as an example. In most cases the development version of libraries is required. With the runtime libraries, there is still need for headers. Compile-time
xercesc 3.0.1 or above
http://xerces.apache.org/xerces-c
http://xerces.apache.org/xerces-c/download.cgi
xqilla 2.2.4 or above
http://xqilla.sourceforge.net/HomePage
http://sourceforge.net/projects/xqilla/files
Run-time
libpcre
This library is used to handle regular expressions within obyx. 
libpcre3-dev 
sudo aptitude install libpcre3-dev
libcurl
This library provides network access utilities 
libcurl3-dev 
sudo aptitude install libcurl3-dev
libmysql
This library provides database connectivity with MySQL 
libmysqlclient15-dev 
sudo aptitude install libmysqlclient15-dev

Set up server file structure

The structure and location of files on the host server is flexible and controlled by configuration files. However, the following is suggested and used in this installation:
  • /WWW_ROOT/public - location of publicly accessible .html, .css, .obyx files.
  • /WWW_ROOT/scripts - location of Obyx run script files
  • /WWW_ROOT/cgi - location of Obyx binary and any other cgi scripts
  • /WWW_ROOT/source - location of Obyx source code

Download source code (SVN)

The Obyx source code is currently available in a SVN repository. To checkout the source code do the following from the /WWW_ROOT/source directory: 
$cd /WWW_ROOT/source
$svn co http://svn.obyx.org/obyx/supported/version1 obyx
To update the source files any later time 
$cd /WWW_ROOT/source/obyx
$svn update

Set up compile settings

Before trying to compile the code some settings need to be setup. The file local.cfg contains compile settings specific to your setup. local.cfg should be at /WWW_ROOT/source/local.cfg local.cfg Before trying to compile the code some settings need to be setup. This file contains compile settings specific to your setup. Create this file in the RSapps directory, amending where necessary: These values can be defined elsewhere, but the file should exist.
MYSQL_INC
Should point to the mysql include directory.
CC_INCLUDES
Any additional include directories needed for the compilation.
CC_PATH
The path to gcc or g++
MYSQL_INC
Should point to the mysql include directory.
CC_DB
These are defines used to include or exclude compilation of the mysql or postgresql code. If you do not have postgresql or mysql, remove the -DALLOW flag for the salient item to prevent headers from not being found.
CC_FLAGS
The normal set of additional gcc flags used for this compilation.
RPATH
The full path to the root directory of the www files as mentioned above. Importantly, this only MUST be the parent of the cgi directory to install to.
CGIDIR
The relative path to the cgi directory. It must be underneath RPATH.
/WWW_ROOT/source/local.cfg:
MYSQL_INC   = /usr/include/mysql
CC_INCLUDES = -I$(MYSQL_INC)
CC_PATH     = /usr/bin/
CC_FLAGS    = -x c++ -funsigned-char -fno-asm -Wno-trigraphs -g -O3 -fmessage-length=0
RPATH       = /WWW_ROOT
CGIDIR      = cgi

Compile obyx.cgi binary

$cd /WWW_ROOT/source/obyx
$make /WWW_ROOT/cgi/obyx.cgi
To check that the linking is correct one can do: 
$ldd /WWW_ROOT/cgi/obyx.cgi

Http (Apache2) Configuration

Apache needs to know how to handle .obyx files. The following basic apache server configuration file can be used as a basis: 
<VirtualHost YOUR-IP-ADDRESS:80>
	DocumentRoot  /WWW_ROOT/public
	ServerName    host.yourdomain.com
	RewriteEngine  on
	RewriteRule    ^/$   /index.html [R]

#####  Obyx configuration ########
	<IfModule mime_module>
		AddHandler  cgi-script				.cgi
		AddType		application/obyx+xml	.obyx
		Action      application/obyx+xml	/o/obyx.cgi
	</IfModule>

	ScriptAlias  /o/			  /WWW_ROOT/cgi
	<LocationMatch "^/o/" >
		Order Deny,Allow
		Deny from All
		Allow from env=REDIRECT_STATUS
	</LocationMatch>

#obyx runtime will be able to access any files/directories under the OBYX_ROOT_DIR directory
#eg using filename /foo.html will actually be pointing to /OBYX_ROOT_DIR/foo.html
#the scripts directory, which is used by the 'shell' operation should be outside OBYX_ROOT_DIR.

 SetEnv OBYX_DEVELOPMENT       on
 SetEnv OBYX_ROOT_DIR          /WWW_ROOT/public
 SetEnv OBYX_SCRIPTS_DIR       /WWW_ROOT/scripts
 
 SetEnv OBYX_SQLSERVICE        mysql  (or postgresql)
 SetEnv OBYX_SQLDATABASE       YOUR-DATABASE-NAME
 SetEnv OBYX_SQLHOST           YOUR-DATABASE-HOST
 SetEnv OBYX_SQLPORT           YOUR-DATABASE-PORT
 SetEnv OBYX_SQLUSER           YOUR-DATABASE-USERNAME
 SetEnv OBYX_SQLUSERPW         YOUR-DATABASE-USERPASSWORD

#set the following, if debugging or using breakpoints in obyx files.
 SetEnv OBYX_DEVELOPMENT       true	
	
#There are some settings for using custom paths to dynamic libraries
#For Mac OS X, which has a dylib suffix, they are mandatory. 
#Mac OS X uses dylib suffix
	SetEnv OBYX_LIBCURLSO         /usr/local/lib/libcurl.dylib
	SetEnv OBYX_LIBPCRESO         /usr/local/lib/libpcre.dylib

#MySQL Library location	(if using MySQL)
	SetEnv OBYX_LIBMYSQLCRSO      /usr/local/mysql/lib/libmysqlclient_r.dylib
	SetEnv OBYX_LIBZIPSO          /usr/lib/libz.dylib

#PostgreSQL Library Location (if using PostgreSQL)
	SetEnv OBYX_LIBPQSO           /usr/local/pgsql/lib/libpq.dylib
    
##### End Obyx Configuration #####
</VirtualHost>|

Test

Example Obyx Hello World The two following files may be used to test that Obyx is working. It uses both an SQL connection and a filesystem include to test some basic functionality. The files should go into your public directory (e.g. /WWW_ROOT/public ): Run the hello world example by going to http://www.yourdomain.com/hello_world.obyx You should simply see the words "Hello World" in a valid html page. 
hello_world.obyx
<instruction xmlns="http://www.obyx.org" >
   <input>
       <instruction note="load view">
           <output space="store" value="v" />
           <input space="file" value="hello_world.html" />
       </instruction>
       <iteration operation="sql" note="get model">
           <output space="store" value="v#//*[@id='msg']/text()" />
           <control value="select 'Hello World' as message" />
           <body space="field" value="message" />
       </iteration>
       <instruction note="display view">
           <input space="store" value="v" release="true" />
       </instruction>      
   </input>
</instruction>
hello_world.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8" />
	<title>Hello World View</title>
</head>
<body><div id="msg">Message</div></body>
</html>


Last Modified: Tue, 08 Jun 2010