source: plugins/base1/se.lu.thep.wenni/trunk/INSTALL @ 887

$Id: INSTALL 887 2008-12-05 16:45:56Z jari $

----------------------------------------------------------------------
{{{
Copyright (C) 2005, 2006 Jari Häkkinen, Peter Johansson
Copyright (C) 2007 Peter Johansson
Copyright (C) 2008 Jari Häkkinen

This file is part of WeNNI,
http://baseplugins.thep.lu.se/wiki/se.lu.thep.WeNNI

WeNNI is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 3 of the License, or (at your
option) any later version.

WeNNI is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License
along with WeNNI. If not, see <http://www.gnu.org/licenses/>.
}}}
----------------------------------------------------------------------


If you think the instructions are worthless or stupid or maybe both,
please tell me and I'll try to improve them. Even better, tell me how
to improve them. My email address is jari@thep.lu.se

This package can be built in three different modes: base2, base1, and
stand-alone. The base2 mode is default and the mode you should use if
you plan on running WeNNI as plugin to BASE2. The base1 mode is the
old (classic) mode similar to WeNNI 0.6 (or earlier). This is the mode
you should use if you plan on using WeNNI as a plugin to BASE1. The
stand-alone mode is intended for you who want to use the WeNNI
algorithm independently of BASE. The different modes build and require
different things. You choose the mode by giving the `configure` script
the appropriate option. See below for more details on how to compile
the package in the different modes.



= General requirements =

General requirements to build the package are that you work in a
decent computing environment where you have access to tools such as
make and a standards compliant C++ compiler. Since parts of the
algorithms in WeNNI depends on the GNU scientific library it is
required. GSL can be downloaded from http://www.gnu.org/software/gsl/.



= BASE 2 mode =

The core WeNNI algorithms are implemented in C++ and to be useful in
BASE2 a Java wrapper is required. BASE2 only accepts plug-ins written
in the Java programming language hence a Java wrapper is provided with
WeNNI for BASE2. The wrapper will export appropriate data from the
BASE2 server, run the WeNNI binary, and import data back to the
server.

== Short instructions ==

It can be this easy:

 1. Download and unpack WeNNI and `cd` to the root directory of the
    distribution.

 2. If you haven't access to a BASE2 installation or prefer to use the
    standard compilation components, run the configure script with
    {{{
    $ ./configure --with-plugindir=/path/to/base/plugin-directory/wenni
    $ make
    $ make check
    $ make install-plugin
    }}}

If you have problems check the pre-requisites below.

== Pre-requisite ==

 1. Java 1.6.

 2. A working BASE2 installation or Internet connection. Some BASE2
    program libraries are required for the creation of the wrapper
    plug-in. Required libraries will be downloaded automatically, or
    local libraries can be used.

 3. Version 0.1 of !PluginUtilities (http://baseplugins.thep.lu.se)
    package. Needed for creation of the Java wrapper. If the package
    is not available it will automatically be downloaded during the
    compilation process.

 4. BASE 2.9 or later for plug-in use. Earlier versions may work but
    it is not tested.

 5. Optionally, for testing, Perl (http://www.cpan.org/). The test
    programs can be run manually, see README for details.

== Automatic download of required BASE components ==

During the build process and depending on configuration options,
required program libraries will be downloaded from the official BASE
sites, http://base2.thep.lu.se/base and
http://baseplugins.thep.lu.se. If you feel uncomfortable with this
procedure you need to do some manual work.

 1. If you have no working BASE2 installation, download the latest
    BASE2 binary package from http://base.thep.lu.se and unpack
    it. There is no need for further work, use the created directory
    as the path for the `--with-basedir` option given to the configure
    script below.

 2. Download the !PluginUtilities package from
    http://base.thep.lu.se/wiki/net.sf.basedb.pluginutilities and
    place the package file in directory `base/base2`. The install
    process will use this file automatically but beware, a `make
    distclean` will erase the file (but `make clean` will not). This
    WeNNI package is known to work with version 0.1 of the
    !PluginUtilities package (only the latest known version will be
    given here), and the stated version is the one automatically
    downloaded in the build process.

== Building and installing the plug-in (WeNNI and the Java wrapper) ==

 1. Download and unpack WeNNI and `cd` to the root directory of the
    distribution.

 2. If you haven't access to a BASE2 installation or prefer to use the
    standard compilation components, run the configure script with
    {{{
    $ ./configure
    }}}
    This will automatically download required BASE related libraries
    from the official BASE package repositories (see output from the
    configure script on details about the downloads).
    [[br]] [[br]]
    There is a possibility to use the build tools to automatically
    install the package. In this case you may want to change the
    default plug-in installation path.
    {{{
    $ ./configure --with-plugindir=DIR
    }}}
    The default plug-in installation directory is the directory
    plugins/se/lu/thep/wenni rooted in `basedir`. If you prefer to
    install the plug-in manually you must place `nni`, `WeNNI.jar`,
    and `PluginUtilities-0.1pre.jar` in the same installation
    directory.
    [[br]] [[br]]
    If you prefer to compile WeNNI Java wrapper using your local BASE2
    installation. This is only needed if you have made local changes
    affecting plugins and where these modifications are required in
    the WeNNI Java wrapper. You should know if this is required, if
    you do not know simply go for the above option. So, if you know do
    {{{
    $ ./configure --with-basedir=/path/to/base
    }}}
    where `/path/to/base` should point to the directory containing
    directory `www`.
    [[br]] [[br]]
    ''Some notes on configure options:''
    [[br]] [[br]]
    The configure script accepts
    a few options that may be of interest. You can provide
    `./configure` with BASE2 location information with
    `--with-basedir=BASEDIR`. This information is used to find jar
    files such as `BASE2Core.jar` needed for compilation. The plug-in
    installation directory can be changed using `./configure` option
    `--with-plugindir=DIR`. Files will be installed in
    `<DIR>`. Default `DIR` is set to
    `<BASEDIR>/plugins/se/lu/thep/wenni/`.
    [[br]] [[br]]
    You may use `with-gsl=DIR`
    to provide information on GSL location. The option `enable-debug`
    turns on debug options on the compilation of binary `nni`
    (e.g. enables assertions).
    [[br]] [[br]]
    The Java compiler sometimes fails to recognize the character
    encoding of the source files. Use
    `--with-javasourceencoding=coding` to set the encoding of source
    files. You can find available encodings by doing `man javac`.

 3. Now build using
    {{{
    $ make
    }}}
    If all went well `nni` was created in directory `bin/nni` as well
    as `WeNNI.jar` in directory `base/base2/`.

 4. Optionally, run the test programs
    {{{
    $ make check
    }}}

 5. Install files using
    {{{
    $ make install-plugin
    }}}
    If you prefer to install the plug-in manually you must place
    `nni`, `WeNNI.jar`, and `PluginUtilities-0.1pre.jar` in the same
    installation directory.
    [[br]] [[br]]
    Note! `make install` will install in location `${exec_prefix}/bin`
    which may be something else than your BASE plugin directory.

 6. Make BASE2 aware of the plugin, see BASE2 documentation
    http://base.thep.lu.se/chrome/site/doc/html/index.html and use
    the below information with appropriate change of Path
    {{{
    Class: se.lu.thep.wenni.WeNNI
    Path : /path/to/base/pluginsse/lu/thep/wenni-0.7/WeNNI.jar
    }}}
    Path should be the absolute path to the WeNNI.jar file.



= BASE 1 mode =

This section is not well tested. Please report success or failure
following these BASE1 related instructions.

The core WeNNI algorithms are implemented in C++ and to be useful in
BASE1 a Perl wrapper is used. The wrapper will parse the from the
BASE1 server exported data file, run the WeNNI binary, and generate a
data file for import of data back to the server.

== Pre-requisite ==

 1. Perl (http://www.cpan.org/) for testing and plug-in execution in
    the BASE1 server environment. The test programs can be run
    manually, see README for details.

 2. A working BASE1 installation, or download the BASE1 plug-in
    development kit.

== Preparing WeNNI build for BASE1 ==

 1. Download and unpack WeNNI. `cd` to the root directory of the
    distribution.

 2. If you do not have access to a working BASE1 installation do the
    following steps; Download the BASE1 plug-in development kit from
    http://baseplugins.thep.lu.se/wiki/PluginDownload, unpack the
    package in the WeNNI root directory, compile the package, and then
    create a symbolic link to this directory. Basically, after
    download, issue the following sequence of commands in to prepare
    the devkit for WeNNI:
    {{{
    $ tar zxpf BASE-plugindevkit-1.2.17.tar.gz
    $ cd BASE-plugindevkit-1.2.17/bogus_base
    $ ./bootstrap
    $ ./configure
    $ make
    $ cd ../..
    $ ln -s BASE-plugindevkit-1.2.17 BASE-plugindevkit
    }}}

== Building and installing the plug-in (WeNNI with support) ==

 1. You should already have downloaded WeNNI above if not please
    return to the previous section. `cd` to the root directory of the
    distribution.

 2. Run configure script with 
    {{{
    $ ./configure --enable-state=base1 --with-basedir=BASEDIR
    }}}
    where <BASEDIR> is the absolute path to the root directory of your
    working BASE1 installation, or if you are using the developer kit,
    the absolute path to the bogus_base directory created above:
    `/path/to/wenni/BASE-plugindevkit/bogus-base`
    [[br]] [[br]]
    ''Some notes on configure options:''
    [[br]] [[br]]
    The configure script accepts
    a few options that may be of interest. You generally must provide
    `./configure` with BASE1 location information with
    `--with-basedir=BASEDIR`. This information is used to find BASE1
    API (program libraries and header files). Header file `basefile.h`
    is expected to reside in `<BASEDIR>/include/cxx/`. `<BASEDIR>`
    must be an absolute path. The plug-in installation directory can
    be changed using `./configure` option
    `with-plugindir=DIR`. Default `DIR` is set to
    `<BASEDIR>/plugins/bin/wenni/`. You may use `with-gsl=DIR` to
    provide information on GSL location. The option `enable-debug`
    turns on debug options on the compilation of binary `nni`
    (e.g. enables assertions).

 3. Now build using 
    {{{
    $ make
    }}}

 4. Optionally, run the test programs
    {{{
    $ make check
    }}}

 5. Install files using 
    {{{
    $ make install-plugin
    }}}
    Note! `make install` will install in location `${exec_prefix}/bin`
    which maybe something else than the BASE plugin directory.

 6. ''Make BASE1 aware of the plugin.''  Make sure that the settings
    in the plug-in definitions file are set appropriately when
    importing the plug-in definitions file
    (`base/base1/base_plugin_script/plugin_WeNNI.base`) into
    BASE1. More explicitly make sure that the entry in the web GUI:
    'Name of executable' is set according to the wenni.pl install
    location. If you prefer to make the change in the file you should
    manipulate the line starting with `execName`.
    [[br]] [[br]]
    If you want use other than the default fields for intensity1,
    intensity2, BCh1SD, and BCh2SD, you need to indicate this in the
    WeNNIParams section of the plug-in definition file. Change the 5th
    column of parameters 4 through 7 appropriately, i.e., if the
    standard deviation is defined in another column than the default
    change lines 6 and 7:
    ≈ß©{{{
    6 h BCh1SD    30  _xc_BCh1SD    0
    7 h BCh2SD    30  _xc_BCh2SD    0
    }}}



= Stand alone mode =

The core WeNNI algorithms are implemented in C++ whereas the test
script is written in Perl.

== Short instructions ==

It can be this easy:

 1. Download and unpack WeNNI and `cd` to the root directory of the
    distribution.

 2. Do
    {{{
    $ ./configure --enable-state=stand-alone
    $ make
    $ make check
    $ make install
    }}}

== Pre-requisite ==

 Optionally, for testing, Perl (http://www.cpan.org/). The test
 programs can be run manually, see README for details.

== Building and installing WeNNI ==

 1. Download and unpack WeNNI and `cd` to the root directory of the
    distribution.

 2. If you haven't access to a BASE installation or prefer to use the
    standard compilation components, run the configure script with
    {{{
    $ ./configure  --enable-state=stand-alone
    }}}
    ''Some notes on configure options:''
    [[br]] [[br]]
    Do `./configure --help` for
    details in available options. You may use `with-gsl=DIR` to
    provide information on GSL location. The option `enable-debug`
    turns on debug options on the compilation of binary `nni`
    (e.g. enables assertions).

 3. Now build using
    {{{
    $ make
    }}}
    If the package was successfully compiled two binaries are created;
    `NNIFileConverter` and `nni`.

 4. Optionally, run the test programs
    {{{
    $ make check
    }}}

 5. Install with
    {{{
    $ make install
    }}}
    Note! `make install-plugin` will do the same thing as `make install`.


= Test program fails =

The numerical checks are very restrictive, if 'make check' fails this
may be due to rounding errors. You can loosen the error bound in the
tests by changing the default value in test/wenni_test.cc. Search for:
{{{
bool compare(const std::string&, const std::string&, double error_bound=1e-20);
}}}