$Id: INSTALL 856 2008-12-02 07:55:41Z 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@…

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).
   
   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.
   
   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.
   
   Some notes on configure options: 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/. 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 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
   

   Note! make install will install in location ${exec_prefix}/bin which maybe something else than the BASE plugin directory.

6. Make BASE2 aware of the plugin, see BASE2 documentation ​http://base.thep.lu.se/chrome/site/doc/html/index.html

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
   
   Some notes on configure options: 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.
   
   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: 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);