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 development 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/.
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):
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
Select the RDF query languages to build from the list:
sparql laqrs
The default when this option is omitted is to enable all query languages
except the experimental one, laqrs. LANGUAGES takes a
space-separated value.
--enable-release
Enable configuration for building a release by not removing
-O options for compiler flags. This is a maintainer
option.
--with-digest-library=NAME
Pick the message digest library approach to use from the
choices of mhash (the default when available),
gcrypt (when libgcrypt is available) and internal
(always available, providing only MD5 and SHA1).
--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-libgcrypt-config=PATH
Set the path of the libgcrypt libgcrypt-config
program that provides the compiling and linking flags. Enables
libgcrypt for use as a message digest.
See also --with-digest-library
--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-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-random-approach=ALGO
Pick the random number generator approach to use from the
choices of mtwist (the default - this is bundled with rasqal
and can be used without any additional installs), 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.
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.
