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
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).
The chown command must be executed after every make install execution.
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.
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.
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
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
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
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.
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).
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
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.
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.
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.
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.
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).
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.
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.
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:
a MySQL client application invokes XA START
it updates some data in the database
it invokes XA END and XA PREPARE
it crashes and disconnects from the MySQL server
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).
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.
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.
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.
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.
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).
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.
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.
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).
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
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...
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.
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