INSTALLING VIECRF
=================

The VieCRF distribution consists of two packages:

1) libviecrf-0.1.2.tar.gz

   This tarball contains the core library, which is implemented in
   C++ (header-only).

2) VieCRF-0.1.2.tar.gz

   This tarball contains the Perl bindings and the command line tools
   of VieCRF, which are implemented in Perl.

VieCRF has been successfully compiled and used on a number of
UNIX-like platforms:

- Linux/x86
- Linux/em64t
- Mac OS X/PPC
- Cygwin/x86

If you need packages for ActiveState's Perl port to Win32, see
http://www.ofai.at/~jeremy.jancsary/ for binary packages. Creating
these on your own is a major nightmare, and I cannot provide support.


Installing libviecrf
--------------------

Extract the tarball and change into libviecrf's toplevel directory:

$ tar xfvz libviecrf-0.1.2.tar.gz
$ cd viecrf-0.1.2

In the next step, configure the library:

$ ./configure

The library depends on boost (http://www.boost.org) >= 1.33. If boost
is installed in a non-default location, you will have to tell the
configure script where boost resides:

$ ./configure --with-boost=/opt/boost

VieCRF can leverage IPP (Intel Integrated Performance Primitives) to
speed up certain operations. If you want to use IPP, tell the
configure script where the library resides, e.g.:

$ ./configure --with-ipp=/opt/intel/ipp/5.2/em64t/

VieCRF can use OpenMP to parallelize CRF training. Currently, only the
Intel C++ compiler (preferably version >= 10.0) can be used for OpenMP
support out of the box. GCC >= 4.2 supports OpenMP, but not in shared
objects that are dlopen'ed.  See
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=28482 for details. GCC can
be used, but you need to compile your own GCC and patch libgomp (I
have done this, and VieCRF works perfectly). There is hope that this
"bug" will be resolved in later versions of GCC.

If you want to use OpenMP, you need to tell the configure script:

$ CXX=icpc ./configure --with-openmp

After the library is configured, you have the choice of installing it;
this step is optional if you only want to use the Perl bindings or the
command line tools of VieCRF:

$ make install

In case you do not install libviecrf, make sure to set the
PKG_CONFIG_PATH variable to point to the libviecrf source directory;
this is needed in order for the Perl bindings to find the headers of
libviecrf:

$ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/path/to/viecrf-0.1.2/


Installing VieCRF
-----------------

Now that libviecrf is prepared, you can install the Perl bindings and
the command line tools.

Extract VieCRF-0.1.2 and change into the source directory:

$ tar xfvz VieCRF-0.1.2.tar.gz
$ cd VieCRF-0.1.2

Generate a makefile:

$ CXX=icpc perl Makefile.PL OPTIMIZE="-O3 ..." 

Specify your favorite compiler flags in the OPTIMIZE parameter. One
VieCRF-specific flag that can be specified here is
"-DUSE_LINSPACE". This flag specifies that factor operations shall not
be carried out in logarithmic space; it greatly speeds up CRF
training, but decreases numerical stability. For most applications, it
should be safe to use this option, but your mileage may vary.

Compile the bindings:

$ make

Check if everything seems to work (unit tests are rather crude at this
point, sorry folks):

$ make test

Install the Perl bindings and the command line tools:

$ make install

See "man viecrf" for an entry point to the command line tools and "man
VieCRF" for an entry point to the Perl bindings.

That's it, have fun.