Configure, build and install

LIXA project tries to adhere to the GNU de facto standard. Supposing you downloaded the package lixa-X.Y.Z.tar.gz, the basic sequence is:

tar xvzf lixa-X.Y.Z.tar.gz
cd lixa-X.Y.Z
./configure
make
      

Note

Sometimes, especially if you clone the git repository, you can get an error like the following one:

WARNING: 'aclocal-1.14' is missing on your system.
         You should only need it if you modified 'acinclude.m4' or
         'configure.ac' or m4 files included by 'configure.ac'.
         The 'aclocal' program is part of the GNU Automake package:
         <http://www.gnu.org/software/automake>
         It also requires GNU Autoconf, GNU m4 and Perl in order to run:
         <http://www.gnu.org/software/autoconf>
         <http://www.gnu.org/software/m4/>
         <http://www.perl.org/>
Makefile:457: recipe for target 'aclocal.m4' failed
make: *** [aclocal.m4] Error 127
	

You can try the following command to solve the issue:

	  touch configure.ac aclocal.m4 configure Makefile.am Makefile.in
	

or, in the event that the previous one failed, the following one:

          autoreconf -v -f -i
        

To install the software you need root access. With some distributions, like Ubuntu, root access is available with the sudo command and your own password:

sudo make install
      

If the previous command does not work, root access is available with the su command and the root password:

su -c "make install"
      

If nothing goes wrong, the above commands install the LIXA software artifacts in /opt/lixa default directory. After the installation you should change the authorization assigned to some directories. Use sudo su -c (Ubuntu) or su -c (CentOS) to gain root privileges and execute chown:

tiian@ubuntu:~$ sudo su -c "chown -R lixa:lixa /opt/lixa/etc/ /opt/lixa/var/"
tiian@ubuntu:~$ ls -la /opt/lixa/etc/ /opt/lixa/var/
/opt/lixa/etc/:
total 16
drwxr-xr-x 2 lixa lixa 4096 2011-03-30 23:13 .
drwxr-xr-x 9 lixa root 4096 2011-03-30 23:14 ..
-rw-r--r-- 1 lixa lixa 3542 2011-03-30 23:13 lixac_conf.xml
-rw-r--r-- 1 lixa lixa  447 2011-03-30 23:13 lixad_conf.xml

/opt/lixa/var/:
total 12
drwxr-xr-x 2 lixa lixa 4096 2011-03-30 23:14 .
drwxr-xr-x 9 lixa root 4096 2011-03-30 23:14 ..
-rw-r--r-- 1 lixa lixa  178 2011-03-30 23:14 README
      

The succesful execution of the above commands guarantees that the configuration and the state files can be managed using the LIXA administrative account ( user=lixa, group=lixa).

Note

The chown command must be executed after every make install execution.

Advanced configuration

There are many options you can pass to the configure command to meet your needs (see below). Skip this section and jump directly to the section called “Linking third party resource managers” if you are not expert in LIXA configuration.

Important

It is strongly suggested you issue the make clean command every time you re-configure the package. If you didn't clean the previous build, you might catch some strange undebuggable errors related to not aligned libraries.

Choosing a different installation PATH

Note

The commands explained in the previous section should be adapted to different paths, if you choosed a non standard installation path.

to perform the very first installation /tmp could be a good destination:

./configure --prefix=/tmp/lixa
	  

After some testing, you might prefer your home directory:

./configure --prefix=$HOME/lixa
	  

and you will get a layout like this:

$HOME/lixa/bin
$HOME/lixa/etc
$HOME/lixa/include
$HOME/lixa/lib
$HOME/lixa/sbin
$HOME/lixa/var
	  

You can split code and data with something like this:

./configure --prefix=/ --exec-prefix=/usr/local
	  

Producing this manual too

To produce LIXA manual in HTML format you need xsltproc installed in your current search path and chunk.xsl docbook.xsl stylesheet files. Use

./configure --with-docbook
	  

to enable manual build and search for stylesheets in a subdir of /usr/share. You may specify a different path using:

./configure --with-docbook=/path/to/father/of/xhtml/dir
	  

Locating pre-requisites libraries

If any of the pre-requisite library include files are not in the standard search PATH, you can export CPPFLAGS before the configure process to add your custom path:

export CPPFLAGS=-I/path/to/libuuid
./configure
make
	  

to see the list of environment variables that can affect the build process use the command

./configure --help
	  

Optional features

The supplied defaults are generally good enought to start working with LIXA, but if you want to perform some hacking you might be interested in activating/deactivating some optional features.

Tracing

The tracing feature is enabled by default: the binary objects produced by the build procedure contains a lot of messages that can be displayed turning on tracing at run time.

Removing the tracing feature can save RAM (smaller binary objects) and CPU (every trace message is tested against run time configuration).

Important

Disabling tracing seems a good way to increase the performance of the software, but unfortunately without a trace it is quite impossible to debug some issues. Only rock stable software can be compiled without tracing, and this is not the case of LIXA.

To disable tracing, use --disable-trace on ./configure command line:

./configure --disable-trace
	    

Extra debug code

To enable extra debug code, that's basically some redundant check code use --enable-debug on ./configure command line:

./configure --enable-debug
	    

This feature could be interesting when porting the LIXA project software to a different platform; for normal use, the extra debugging code is useless.

Crash simulation

This feature is useful when testing the software: with crash simulation the software can be tested against simulated software crashes and, on some extents, power outages. To enable crash simulation use --enable-crash on ./configure command line:

./configure --enable-crash
	    

Linking third party resource managers

To link an already tested third party resource manager you can use a specific option on ./configure command; to link a new resource manager, you have to hack the Makefiles and put all you need in place or you can perform a manual link.

IBM DB2 Express-C 9.7, 11.1[8]

This step is useful if you want to use IBM DB2 as a Resource Manager coordinated by LIXA; only versions Express-C 9.7 and 11.1 have been tested, but there should not be relevant differences with a different version. Use something like this:

./configure --with-ibmdb2=/opt/ibm/db2/V9.7
	  

Or the following for V11.1

        ./configure --with-ibmdb2=/opt/ibm/db2/V11.1
      

to create a loadable module containing the switch structure.

MySQL 5.0, 5.1, 5.5, 5.6[9]

This step is useful if you want to use MySQL [10] as a Resource Manager coordinated by LIXA; only versions 5.0, 5.1, 5.5 and 5.6 have been tested, but there should not be relevant differences with a different version. Use something like this:

./configure --with-mysql
	  

or something like this if you need to point a specific installation:

./configure --with-mysql=/path/to/mysql_config
	  

to create a loadable module containing the switch structure. It's not necessary to specify the MySQL installation directory because the mysql_config utility command is used.

XTA for Python

If you want to use XTA for Python (see Table 8.1, “Resouce Managers and Programming Languages for XTA”), you need the mysqlclient-python driver with function _get_native_connection enabled: at the time of this writing, it's not yet available in a stable version, but it's ready to use in the git master branch. These commands should help you to install it from the source code:

git clone https://github.com/PyMySQL/mysqlclient-python.git

cd mysqlclient-python

python setup.py build

sudo python setup.py install
	    

The required feature should be available in next mysqlclient-python version (1.4.0).

XTA for Java

If you want to use XTA for Java (see Table 8.1, “Resouce Managers and Programming Languages for XTA”), you need a JDBC driver that supports MySQL and JTA standard. Specify the JAR file that contains the JDBC driver during config phase with something like this:

./configure --with-mysql --with-mysql-jdbc=/usr/share/java/mysql.jar
	    

As a general warning, don't stick to the version provided by your Linux distribution: sometimes a better one is available in the vendor's portal.

Note

MySQL does not supply an XA standard switch structure, but only some SQL non standard statements ( XA START, XA END, XA PREPARE, XA COMMIT, XA ROLLBACK, XA RECOVER ) that can be used to implement some XA features. This is good enough to build a loadable module that can be used by the LIXA transaction manager, but some XA standard features - like dynamic registration - can not be implemented.

Warning

Some old versions of the software are affected by a serious documented bug (# 12161) related to the XA implementation of MySQL. The symptoms perceived while developing LIXA are described below:

  1. a MySQL client application invokes XA START

  2. it updates some data in the database

  3. it invokes XA END and XA PREPARE

  4. it crashes and disconnects from the MySQL server

  5. MySQL server rollbacks the transaction and there's no way to see it again using XA RECOVER

This behavior violates the XA specification: below there is an excerpt for xa_prepare from man page ( [XAspec], page 44) Once this function successfully returns, the resource manager must guarantee that the transaction branch may be either committed or rolled back regardless of failures. A resource manager cannot erase its knowledge of a branch until the transaction manager calls either xa_commit() or xa_rollback () to complete the branch .

The impact of this bug is quite severe and seriously compromises the ACID properties of the resulting system (application program + MySQL resource manager + LIXA transaction manager).

MariaDB

Even if MariaDB is different from MySQL, it can be used with LIXA in the same way of MySQL: most of the times it's just a matter of changing some file or directory name. LIXA does not provide specific options for MariaDB, just use the options provided for MySQL.

Oracle XE 10.2/11.2 (server)[11]

This step is useful if you want to use Oracle Database as a Resource Manager coordinated by LIXA; only version XE 10.2/11.2 has been tested, but there should not be relevant differences with a different version. Use something like this for Oracle 10.2 (32 bit architecture):

./configure --with-oracle=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server
	  

and something like this for Oracle 11.2 (64 bit architecture):

./configure --with-oracle=/u01/app/oracle/product/11.2.0/xe
	  

to create a loadable module containing the switch structure.

Extra configuration is needed in order to use Oracle DBMS; the necessary steps are documented in the configuration chapter.

Oracle SE 12.1 (Instant Client)[12]

This step is useful if you want to use Oracle Database Instant Client as a Resource Manager coordinated by LIXA; only version Standard Edition 12.1 has been tested, but there should not be relevant differences with a different version. Use something like this for Oracle 12.1 Instant Client (64 bit architecture):

./configure --with-oracle-include=/opt/oracle/instantclient_12_1/sdk/include/ \
            --with-oracle-lib=/opt/oracle/instantclient_12_1/
	  

to create a loadable module containing the switch structure.

Extra configuration is needed in order to use Oracle DBMS; the necessary steps are documented in the configuration chapter.

PostgreSQL 8.3, 8.4, 9.2, 9.3, 9.5, 10[13]

This step is useful if you want to use PostgreSQL as a Resource Manager coordinated by LIXA; only versions 8.3, 8.4 and 9.3 have been tested, but there should not be relevant differences with a different version. Use something like this (Ubuntu):

./configure --with-postgresql-include=/usr/include/postgresql --with-postgresql-lib=/usr/lib
	  

or something like this (CentOS) [14]:

./configure --with-postgresql-include=/usr/include --with-postgresql-lib=/usr/lib
	  

to create a loadable module containing the switch structure.

XTA for Python

If you want to use XTA for Python (see Table 8.1, “Resouce Managers and Programming Languages for XTA”), you need the psycopg2 driver with function get_native_connection enabled: at the time of this writing, it's not yet available in a stable version, but it's ready to use in the git master branch. These commands should help you to install it from the source code:

git clone https://github.com/psycopg/psycopg2.git

cd psycopg2

python setup.py build

sudo python setup.py install
	    

The required feature should be available in next psycopg2 version (2.8).

XTA for Java

If you want to use XTA for Java (see Table 8.1, “Resouce Managers and Programming Languages for XTA”), you need a JDBC driver that supports PostgreSQL and JTA standard. Specify the JAR file that contains the JDBC driver during config phase with something like this:

./configure --with-postgresql --with-postgresql-jdbc=/opt/postgresql/postgresql.jar
	    

As a general warning, don't stick to the version provided by your Linux distribution: sometimes a better one is available in the project's portal. For instance, version 9.2-1002-1 distributed with Ubuntu 14.04 does not pass all case tests due a bug related to XA protocol implementation.

Note

PostgreSQL does not supply an XA standard switch structure, but only some SQL non standard statements ( PREPARE TRANSACTION, COMMIT PREPARED, ROLLBACK PREPARED ) that can be used to implement some XA features. This is good enough to build a loadable module that can be used by the LIXA transaction manager, but some XA standard features - like dynamic registration - can not be implemented.

WebSphere MQ 7.1[15]

If you want to use WebSphere MQ with server/bind mode, you have to use something like this when configuring LIXA:

./configure --enable-wsmq --with-wsmq=/opt/mqm71
	  

If you want to use WebSphere MQ with Extended Transactional Client mode, you have to use something like this when configuring LIXA:

./configure --enable-wsmq=ETC --with-wsmq=/opt/mqm71
	  

There should be no reason you want both on the same host: if you could use the server/bind mode, you should use it because it would give you the best performance. If you don't have the queue manager inside the host, you will have to use the Extended Transactional Client mode (ETC).

Two or more resource managers

If you want to use two or more resource managers, and this is a typical condition for the XA usage, you must concatenate two or more --with- parameters. This command, for instance, can be used to build IBM DB2, Oracle and PostgreSQL loadable modules:

./configure --with-ibmdb2=/opt/ibm/db2/V9.7 \
> --with-oracle=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server \
> --with-postgresql-include=/usr/include/postgresql --with-postgresql-lib=/usr/lib \
> --with-mysql
	  

Configuring Resource Managers for XTA Java

To build the XTA for Java component, it's not strictly necessary to specify at configure time the classpath of all the Resource Managers that will be linked by the Application Programs. Anyway, if you want to check you build, you have to specify all the jar files related to the Resource Managers used by the tests. The following configure command, for example, configure 3 Java Resource Managers: MySQL, PostgreSQL and Oracle Database server:

./configure --with-mysql --with-mysql-jdbc=/usr/share/java/mysql.jar \
> --with-postgresql --with-postgresql-jdbc=/opt/postgresql/postgresql.jar \
> --with-oracle-include=/opt/oracle/instantclient_12_1/sdk/include/ --with-oracle-lib=/opt/oracle/instantclient_12_1/ --with-oracle-jdbc=/opt/oracle/OJDBC-Full/ojdbc7.jar
	

Notice the parameters related to JDBC drivers: --with-mysql-jdbc=/usr/share/java/mysql.jar, --with-postgresql-jdbc=/opt/postgresql/postgresql.jar, --with-oracle-jdbc=/opt/oracle/OJDBC-Full/ojdbc7.jar. Other parameters like --with-mysql refer to the C driver used by other languages: C, C++, Python...

Note

JDBC drivers available inside Linux distributions are sometimes old in comparison with the drivers that can be downloaded directly from the project or product site: if possible, try to use the latest available JDBC driver that's compatible with your (database) server and with your Java Runtime Environment.

Summary

The options illustrated above can be combined to obtain a specific configuration. This is an example of a IBM DB2 + Oracle enabled installation using an alternate installation path:

tar xvzf lixa-X.Y.Z.tar.gz
cd lixa-X.Y.Z
./configure --prefix=$HOME/lixa --with-ibmdb2=/opt/ibm/db2/V9.7 --with-oracle=/usr/lib/oracle/xe/app/oracle/product/10.2.0/server
make
sudo make install
	



[8] IBM and DB2 are trademarks of IBM™ corporation

[9] MySQL is a trademark of Oracle™ corporation; details are available at this link: http://www.mysql.com/about/legal/

[10] These are the necessary packages on CentOS: mysql.i686 mysql-devel.i686 mysql-server.i686

[11] Oracle is a trademark of Oracle™ corporation

[12] Oracle is a trademark of Oracle™ corporation

[13] The Trademark Policy of PostgreSQL is available at this link: http://wiki.postgresql.org/wiki/Trademark_Policy

[14] These are the necessary packages on CentOS: postgresql-server.i686 postgresql.i686 postgresql-devel.i686

[15] WebSphere and WebSphere MQ are trademarks of IBM™ corporation