$Id: INSTALL 838 2008-11-29 01:28:23Z peter $

---

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 comliant C++ compiler. Since parts of the algorthms 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.

Pre-requisite

1. Java 1.6.

2. A working BASE2 installation or Internet connection. The BASE program libraries are required for the creation of the wrapper plug-in. If no local BASE installation is available the required packages will be downloaded automatically.

3. Version x of net.sf.basedb. .... package. Needed for creation of the Java wrapper. The package is 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 tetsing, Perl (​http://www.cpan.org/). The test programs can be run manually, see README for details.

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

There is a possiblity 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 in the directory plugins/se/lu/thep/wenni rooted in basedir.

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

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

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 direcotry of your working BASE1 installation, or if you are using the developer kit, the absolute path to the bogus_base direcotry 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

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.

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

Test programs fail

The numerical checks are very resitrictive, 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);