# Raptor RDF Syntax 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 raptor. It ensures that a tested and working set of files are used.

The released sources are available from http://download.librdf.org/source/ (master site). Do not use GitHub tagged tarballs, they are not the same thing and are not supported.

## 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/raptor.git
      cd raptor

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 Raptor in this way requires some particular development tools not needed when building from snapshot releases - automake, autoconf, libtool, gtkdocize and their dependencies. The `autogen.sh` script looks for the newest versions of the auto* tools and checks that they meet the minimum versions.

gtkdocize can be found in the `gtk-doc-tools` package on Debian-based systems such as Ubuntu, `gtk-doc`gtk-doc on OSX.

## 2. Configuring and building

Raptor 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.

Raptor has several optional libraries:

- The libxml2 XML library (2.6.8 or newer) for parsing XML syntaxes.
- Libcurl, libxml2 or libfetch for retrieving URIs.
- libxslt (requiring libxml2 also) to provide the XSLT functionality for the GRDDL and microformats parser.
- YAJL to provide JSON parsers if it is available.
- ICU to provide Unicode NFC checking only if enabled with `--with-icu-config`

### 2.1. Create `configure` program

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

If there is no `configure` program, you can 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. The full path to the utility should be given:

>       LIBTOOLIZE=/opt/local/bin/glibtoolize ./autogen.sh

Alternatively you can run them by hand with:

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

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.

Raptor 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`

Raptor's configure supports the following options:

`--disable-nfc-check`

  Disable Unicode Normal Form C (NFC) checking code. The code primarily consists of large tables plus some checking code which can be removed from the library with this option. All NFC checks will succeed when this is disabled.

`--enable-debug`

  Enable debug messages (default not enabled). Maintainer mode automatically enables this.

`--enable-parsers=PARSERS`

  Pick the RDF parsers to build from the list:
  `rdfxml ntriples turtle rss-tag-soup`
  The default when this option is omitted is to enable all parsers. `grddl` requires libxml2 and libxstl so may not always be available. If all parsers are not enabled, parts of the test suite will likely fail.

  The parsers that a built library supports can be found from the API level using functions such as `raptor_parsers_enumerate` and `raptor_syntaxes_enumerate` or from the `rapper` utility in the help message.

`--enable-serializers=SERIALIZERS`

  Pick the RDF serializers to build from the list:
  `rdfxml ntriples rdfxml-abbrev`
  The default when this option is omitted is to enable all serializers. If all serializers are not enabled, parts of the test suite will likely fail.

  The serializers that a built library supports can be found from the API level using functions such as `raptor_serializers_enumerate` or from the `rapper` utility in the help message.

`--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-www=NAME`

  Pick a WWW library to use - either `curl`, `xml` (for libxml), `libwww` for W3C libwww or `none` to disable it.

`--with-xml2-config=NAME`

  Set the path to the libxml xml2-config program. The default is to look for this on the PATH.

`--with-xslt-config=NAME`

  Set the path to the libxslt xslt-config program. The default is to look for this on the PATH.

`--with-curl-config=NAME`

  Set the path to the libcurl curl-config program. The default is to look for this on the PATH.

`--with-icu-config=NAME`

  Set the path to the ICU icu-config program. This will NOT be searched for on the PATH.

`--with-libwww-config=NAME`

  Legacy option that used to support the libwww library.

`--with-yajl=DIR|no`

  Build against YAJL installed into directory DIR or with 'no', disable looking for YAJL. The default is to search a set of common installation directories such /opt/local, /usr/local and /usr.

### 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-parsers=rdfxml

### 2.4 Compiling

Compile the library and the `rapper` 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

Raptor 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 will be some Unicode NFC checking tests that give ignored failures in 1.3.2 or later as NFC checking has been temporarily removed.

### 2.6 Installing

Install the library and the `rapper` 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

Raptor includes a full tutorial and reference manual for the library. These are installed into PREFIX`/share/gtk-doc/html/raptor` and are also available from the Raptor web site.

In addition, the examples in the tutorial as well as some other example programs are available in the `examples` sub-directory. These can be compiled with:

       cd examples

       # Raptor GUI - only if you have the GTK libraries
       make grapper

       # If you have all requirements
       make examples

### 3.2 rapper utility

Raptor provides an RDF syntax utility program called rapper which can do a variety of parsing and serializing operations.

rapper can be run over RDF/XML content like this:

      rapper http://librdf.org/raptor/raptor.rdf

Raptor can also extract RDF content inside general XML when the `-f scanForRDF` feature is enabled. For example if some RDF/XML is embedded inside some SVG, it could be extracted with:

      rapper -f scanForRDF /path/to/test/pic.svg

You can also run it on other syntaxes such as N-Triples files with the `-i` option like this:

      rapper -i ntriples test.nt

The default output is a simple statement dump format, but it can be changed to write N-Triples by using the `-o` option, like this:

      rapper -o ntriples dc.rdf

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

Copyright 2000-2014 Dave Beckett
Copyright 2000-2005 University of Bristol