Rasqal RDF Query Library - Building and Installing from Source

1. Getting the sources

There are several ways to get the sources. The most stable and tested versions are the sources shipped with each release and these are recommended as the first place to start. If you want to get a newer set, then there are nightly snapshots made of the development sources, which may not yet be committed to GIT. For the latest developent sources, anonymous GIT access is available but this may require some configuring of developer tools that are not needed for the snapshot releases.

The source bundle and package files contain all the HTML files and documentation provided on the web site.

1.1 Getting the sources from releases

This is the recommended source to build and install Rasqal. It ensures that a tested and working set of files are used.

The sources are available from http://download.librdf.org/source/ (master site) and also from the SourceForge site.

1.2 Getting the sources from GIT

This is the recommended source for developers. It provides the latest beta or unstable code. For a stable version, use a release as described above.

  git clone git://github.com/dajobe/rasqal.git
  cd rasqal

At this stage, or after a git pull you will need to create the automake and autoconf derived files, as described below in Create the configure program by using the autogen.sh script.

Building Rasqal in this way requires some particular development tools not needed when building from snapshot releases - automake, autoconf, libtool, gtk-doc and dependencies. The autogen.sh script looks for the newest versions of the auto* tools and checks that they meet the minimum versions.

Building from development sources rather than from a release also requires some additional development tools. Presently this includes the flex scanner generator version 2.5.31 or later and the GNU Bison parser generator. The configure script checks that the minimum versions are present. There are optional dependencies that will be used if present such as MPFR or GMP for decimal arithmetic and PCRE for regex support.

2. Configuring and building

Rasqal uses the GNU automake and autoconf to handle system dependency checking. It is developed and built on x86 Linux and x86 OSX but is also tested on other systems occasionally.

Required (Rasqal will not build without these):

The Raptor RDF Syntax Library version 2.0.4 or later for parsing RDF, retrieving WWW content from URIs and other utility classes.

Recommended (Optional):

PCRE regex library or another implementing the POSIX regex API.
GNU multiple-precision floating-point library (MPFR) or GNU Multiple Precision Arithmetic Library (GMP) libraries for decimal arithmetic.

If some of the recommended libraries are not present some of the tests will fail and the query engine will fail to handle regex matches or decimal arithmetic accurately.

2.1. Create `configure` program

If there is a configure program, skip to the next section.

If there is no configure program, you should create it using the autogen.sh script, as long as you have the automake and autoconf tools. This is done by:

  ./autogen.sh

and you can also pass along arguments intended for configure (see below for what these are):

  ./autogen.sh --prefix=/usr/local/somewhere

On OSX you may have to explicitly set the LIBTOOLIZE variable for the libtoolize utility since on OSX libtoolize is a different program:
  LIBTOOLIZE=glibtoolize ./autogen.sh

autogen.sh also checks out the libmtwist GIT submodule and/or updates it with the latest sources.

Alternatively you can run them by hand (not recommended) with:

  aclocal; autoheader; automake --add-missing; autoconf

however this will not do any of the GIT submodule checkout or updates that are needed for libmtwist.

The automake and autoconf tools have many different versions and at present development is being done with automake 1.11.1 (minimum version 1.11), autoconf 2.65 (minimum version 2.62) and libtool 2.2.10 (minimum version 2.2.0). These are only needed when compiling from GIT sources. autogen.sh enforces the requirements.

Rasqal also requires flex version 2.5.31 or newer (2.5.4 will not work) and GNU Bison to build lexers and parsers. These are only required when building from GIT.

2.2 Options for `configure`

Rasqal's configure supports the following options:

--enable-debug: Enable debugging statements for developing the code. Should NOT be used with any regular build that is installed since it slows the code and generates lots of extra output. This is a maintainer option.
--enable-query-languages=LANGUAGES: Pick the RDF query languages to build from the list:
rdql sparql laqrs
The default when this option is omitted is to enable all query languages except the experimental one, laqrs.
--enable-release: Enable configuration for building a release by not removing -O options for compiler flags. This is a maintainer option.
--with-gmp=PATH: Set the installation path for the GNU Multiple Precision Arithmetic Library (GMP) if it is not in the standard lib/include prefix.
--with-mpfr=PATH: Set the installation path for the GNU multiple-precision floating-point library (MPFR) if it is not in the standard lib/include prefix.
--with-memory-signing: Enable signing of memory allocations so that when memory is allocated with malloc() and released free(), a check is made that the memory was allocated in the same library.
--with-random-approach=ALGO: Pick the random number generator approach to use from the choices of mtwist (the default), gmp (when GMP is available and used for decimals), random_r (glibc initstate_r and random_r), rand_r (POSIX rand_r), random (BSD initstate and random) and rand (POSIX srand and rand).
--with-regex-library=NAME: Pick a regex library to use - either pcre (default) for the PCRE or posix a POSIX regex implementation in the C library
--with-pcre-config=NAME: Set the path to the PCRE pcre-config program

2.3 Configuring

The default configuration will install into /usr/local:

   ./configure

To install into the standard Unix / Linux (and also Cygwin) system directory, use:

   ./configure --prefix=/usr

Append to the line any additional options you need like this:

   ./configure --prefix=/usr --enable-query-languages=sparql

The configure script uses pkg-config(1) to find an installed version of Raptor . If configure reports that it cannot find Raptor, try $ pkg-config raptor2 --modversion on the command line and if there is an error or nothing is shown, then pkg-config is not properly installed and configured. Use 'man pkg-config(1)' to read how to set PKG_CONFIG_PATH which should include a directory where raptor2.pc is installed. When it is correct, the above command will return the Raptor version.

2.4 Compiling

Compile the library and the roqet utility with:

   make

Note: GNU make is probably required which may be called gmake or gnumake if your system has a different make available too.

2.5 Testing

Rasqal has a built-in test suite that can be invoked with:

  make check

which should emit lots of exciting test messages to the screen but conclude with something like:
All n tests passed
if everything works correctly. There might be some regex or decimal tests that fail if no POSIX regex library or multiple precision numeric library was available when Rasqal was compiled.

NOTE: if the system perl program XML:DOM package is not installed, some of the test suite perl scripts will fail. This will be fixed in a future release.

2.6 Installing

Install the library and the roqet utility into the area configure with --prefix (or /usr/local if not given) with:

   make install

Note: This may require root access if the destination area is a system directory such as /usr. In that case you may have to do sudo make install.

3. Using the library

3.1 Documentation

Rasqal includes a reference manual for the library but no tutorial at this time. This is installed into PREFIX/share/gtk-doc/html/rasqal and is also available from the Rasqal web site.

3.2 Examples

At present, to get a good idea of how to use Rasqal in a program, check out the source for roqet in src/roqet.c which uses the library extensively with the recommended APIs.

3.3 roqet utility

Rasqal provides an RDF query utility program called roqet which can do a variety of query operations on local and remote data, local and remote queries and running queries on SPARQL protocol services.

See the roqet manual page for full details using 'man roqet' or read the HTML version in docs/roqet.html or on the Rasqal website.