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

Last change on this file since 887 was 887, checked in by Jari Häkkinen, 14 years ago

Fixes #154. configure now supports setting of java source files encoding.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
  • Property svn:mime-type set to text/x-trac-wiki
File size: 14.1 KB
RevLine 
[69]1$Id: INSTALL 887 2008-12-05 16:45:56Z jari $
2
[317]3----------------------------------------------------------------------
4{{{
[409]5Copyright (C) 2005, 2006 Jari Häkkinen, Peter Johansson
[317]6Copyright (C) 2007 Peter Johansson
[665]7Copyright (C) 2008 Jari Häkkinen
[95]8
9This file is part of WeNNI,
[825]10http://baseplugins.thep.lu.se/wiki/se.lu.thep.WeNNI
[95]11
12WeNNI is free software; you can redistribute it and/or modify it under
13the terms of the GNU General Public License as published by the Free
[824]14Software Foundation; either version 3 of the License, or (at your
[95]15option) any later version.
16
17WeNNI is distributed in the hope that it will be useful, but WITHOUT
18ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
20for more details.
21
22You should have received a copy of the GNU General Public License
[824]23along with WeNNI. If not, see <http://www.gnu.org/licenses/>.
[317]24}}}
25----------------------------------------------------------------------
[95]26
27
[69]28If you think the instructions are worthless or stupid or maybe both,
29please tell me and I'll try to improve them. Even better, tell me how
[70]30to improve them. My email address is jari@thep.lu.se
[69]31
[389]32This package can be built in three different modes: base2, base1, and
33stand-alone. The base2 mode is default and the mode you should use if
34you plan on running WeNNI as plugin to BASE2. The base1 mode is the
[665]35old (classic) mode similar to WeNNI 0.6 (or earlier). This is the mode
[389]36you should use if you plan on using WeNNI as a plugin to BASE1. The
37stand-alone mode is intended for you who want to use the WeNNI
38algorithm independently of BASE. The different modes build and require
39different things. You choose the mode by giving the `configure` script
[823]40the appropriate option. See below for more details on how to compile
41the package in the different modes.
[71]42
[69]43
[389]44
[823]45= General requirements =
[389]46
[823]47General requirements to build the package are that you work in a
48decent computing environment where you have access to tools such as
[854]49make and a standards compliant C++ compiler. Since parts of the
50algorithms in WeNNI depends on the GNU scientific library it is
[823]51required. GSL can be downloaded from http://www.gnu.org/software/gsl/.
[389]52
53
54
[823]55= BASE 2 mode =
[413]56
[823]57The core WeNNI algorithms are implemented in C++ and to be useful in
58BASE2 a Java wrapper is required. BASE2 only accepts plug-ins written
59in the Java programming language hence a Java wrapper is provided with
60WeNNI for BASE2. The wrapper will export appropriate data from the
61BASE2 server, run the WeNNI binary, and import data back to the
62server.
[413]63
[844]64== Short instructions ==
65
66It can be this easy:
67
68 1. Download and unpack WeNNI and `cd` to the root directory of the
69    distribution.
70
71 2. If you haven't access to a BASE2 installation or prefer to use the
72    standard compilation components, run the configure script with
[854]73    {{{
74    $ ./configure --with-plugindir=/path/to/base/plugin-directory/wenni
75    $ make
76    $ make check
77    $ make install-plugin
78    }}}
[844]79
[854]80If you have problems check the pre-requisites below.
[844]81
[823]82== Pre-requisite ==
[389]83
[823]84 1. Java 1.6.
[389]85
[844]86 2. A working BASE2 installation or Internet connection. Some BASE2
[823]87    program libraries are required for the creation of the wrapper
[844]88    plug-in. Required libraries will be downloaded automatically, or
89    local libraries can be used.
[389]90
[854]91 3. Version 0.1 of !PluginUtilities (http://baseplugins.thep.lu.se)
92    package. Needed for creation of the Java wrapper. If the package
93    is not available it will automatically be downloaded during the
94    compilation process.
[389]95
[823]96 4. BASE 2.9 or later for plug-in use. Earlier versions may work but
97    it is not tested.
[389]98
[854]99 5. Optionally, for testing, Perl (http://www.cpan.org/). The test
[823]100    programs can be run manually, see README for details.
[389]101
[844]102== Automatic download of required BASE components ==
103
104During the build process and depending on configuration options,
[854]105required program libraries will be downloaded from the official BASE
106sites, http://base2.thep.lu.se/base and
107http://baseplugins.thep.lu.se. If you feel uncomfortable with this
108procedure you need to do some manual work.
[844]109
110 1. If you have no working BASE2 installation, download the latest
111    BASE2 binary package from http://base.thep.lu.se and unpack
112    it. There is no need for further work, use the created directory
113    as the path for the `--with-basedir` option given to the configure
114    script below.
115
[854]116 2. Download the !PluginUtilities package from
117    http://base.thep.lu.se/wiki/net.sf.basedb.pluginutilities and
118    place the package file in directory `base/base2`. The install
119    process will use this file automatically but beware, a `make
120    distclean` will erase the file (but `make clean` will not). This
121    WeNNI package is known to work with version 0.1 of the
122    !PluginUtilities package (only the latest known version will be
123    given here), and the stated version is the one automatically
124    downloaded in the build process.
[844]125
[823]126== Building and installing the plug-in (WeNNI and the Java wrapper) ==
[389]127
[823]128 1. Download and unpack WeNNI and `cd` to the root directory of the
129    distribution.
[389]130
[823]131 2. If you haven't access to a BASE2 installation or prefer to use the
132    standard compilation components, run the configure script with
[854]133    {{{
134    $ ./configure
135    }}}
[844]136    This will automatically download required BASE related libraries
137    from the official BASE package repositories (see output from the
[854]138    configure script on details about the downloads).
139    [[br]] [[br]]
140    There is a possibility to use the build tools to automatically
[823]141    install the package. In this case you may want to change the
142    default plug-in installation path.
[854]143    {{{
144    $ ./configure --with-plugindir=DIR
145    }}}
[844]146    The default plug-in installation directory is the directory
[856]147    plugins/se/lu/thep/wenni rooted in `basedir`. If you prefer to
148    install the plug-in manually you must place `nni`, `WeNNI.jar`,
149    and `PluginUtilities-0.1pre.jar` in the same installation
150    directory.
[854]151    [[br]] [[br]]
[823]152    If you prefer to compile WeNNI Java wrapper using your local BASE2
153    installation. This is only needed if you have made local changes
154    affecting plugins and where these modifications are required in
155    the WeNNI Java wrapper. You should know if this is required, if
156    you do not know simply go for the above option. So, if you know do
[854]157    {{{
158    $ ./configure --with-basedir=/path/to/base
159    }}}
[844]160    where `/path/to/base` should point to the directory containing
161    directory `www`.
[854]162    [[br]] [[br]]
[887]163    ''Some notes on configure options:''
164    [[br]] [[br]]
165    The configure script accepts
[854]166    a few options that may be of interest. You can provide
167    `./configure` with BASE2 location information with
168    `--with-basedir=BASEDIR`. This information is used to find jar
169    files such as `BASE2Core.jar` needed for compilation. The plug-in
170    installation directory can be changed using `./configure` option
171    `--with-plugindir=DIR`. Files will be installed in
172    `<DIR>`. Default `DIR` is set to
[887]173    `<BASEDIR>/plugins/se/lu/thep/wenni/`.
174    [[br]] [[br]]
175    You may use `with-gsl=DIR`
[823]176    to provide information on GSL location. The option `enable-debug`
177    turns on debug options on the compilation of binary `nni`
178    (e.g. enables assertions).
[887]179    [[br]] [[br]]
180    The Java compiler sometimes fails to recognize the character
181    encoding of the source files. Use
182    `--with-javasourceencoding=coding` to set the encoding of source
183    files. You can find available encodings by doing `man javac`.
[823]184
185 3. Now build using
[854]186    {{{
187    $ make
188    }}}
[823]189    If all went well `nni` was created in directory `bin/nni` as well
190    as `WeNNI.jar` in directory `base/base2/`.
[413]191
[823]192 4. Optionally, run the test programs
[854]193    {{{
194    $ make check
195    }}}
[823]196
197 5. Install files using
[854]198    {{{
199    $ make install-plugin
200    }}}
[858]201    If you prefer to install the plug-in manually you must place
202    `nni`, `WeNNI.jar`, and `PluginUtilities-0.1pre.jar` in the same
203    installation directory.
204    [[br]] [[br]]
[853]205    Note! `make install` will install in location `${exec_prefix}/bin`
[858]206    which may be something else than your BASE plugin directory.
[853]207
[823]208 6. Make BASE2 aware of the plugin, see BASE2 documentation
[858]209    http://base.thep.lu.se/chrome/site/doc/html/index.html and use
210    the below information with appropriate change of Path
211    {{{
212    Class: se.lu.thep.wenni.WeNNI
213    Path : /path/to/base/pluginsse/lu/thep/wenni-0.7/WeNNI.jar
214    }}}
215    Path should be the absolute path to the WeNNI.jar file.
[413]216
217
[389]218
[823]219= BASE 1 mode =
[69]220
[823]221This section is not well tested. Please report success or failure
222following these BASE1 related instructions.
[71]223
[823]224The core WeNNI algorithms are implemented in C++ and to be useful in
225BASE1 a Perl wrapper is used. The wrapper will parse the from the
226BASE1 server exported data file, run the WeNNI binary, and generate a
227data file for import of data back to the server.
[71]228
[823]229== Pre-requisite ==
[69]230
[823]231 1. Perl (http://www.cpan.org/) for testing and plug-in execution in
232    the BASE1 server environment. The test programs can be run
233    manually, see README for details.
[70]234
[823]235 2. A working BASE1 installation, or download the BASE1 plug-in
236    development kit.
[71]237
[823]238== Preparing WeNNI build for BASE1 ==
[71]239
[823]240 1. Download and unpack WeNNI. `cd` to the root directory of the
[854]241    distribution.
[69]242
[823]243 2. If you do not have access to a working BASE1 installation do the
244    following steps; Download the BASE1 plug-in development kit from
245    http://baseplugins.thep.lu.se/wiki/PluginDownload, unpack the
246    package in the WeNNI root directory, compile the package, and then
247    create a symbolic link to this directory. Basically, after
248    download, issue the following sequence of commands in to prepare
249    the devkit for WeNNI:
[854]250    {{{
[823]251    $ tar zxpf BASE-plugindevkit-1.2.17.tar.gz
252    $ cd BASE-plugindevkit-1.2.17/bogus_base
253    $ ./bootstrap
254    $ ./configure
255    $ make
256    $ cd ../..
257    $ ln -s BASE-plugindevkit-1.2.17 BASE-plugindevkit
[854]258    }}}
[86]259
[838]260== Building and installing the plug-in (WeNNI with support) ==
[69]261
[823]262 1. You should already have downloaded WeNNI above if not please
[854]263    return to the previous section. `cd` to the root directory of the
264    distribution.
[69]265
[823]266 2. Run configure script with
[854]267    {{{
268    $ ./configure --enable-state=base1 --with-basedir=BASEDIR
269    }}}
270    where <BASEDIR> is the absolute path to the root directory of your
271    working BASE1 installation, or if you are using the developer kit,
272    the absolute path to the bogus_base directory created above:
273    `/path/to/wenni/BASE-plugindevkit/bogus-base`
274    [[br]] [[br]]
[887]275    ''Some notes on configure options:''
276    [[br]] [[br]]
277    The configure script accepts
[854]278    a few options that may be of interest. You generally must provide
279    `./configure` with BASE1 location information with
280    `--with-basedir=BASEDIR`. This information is used to find BASE1
281    API (program libraries and header files). Header file `basefile.h`
282    is expected to reside in `<BASEDIR>/include/cxx/`. `<BASEDIR>`
283    must be an absolute path. The plug-in installation directory can
284    be changed using `./configure` option
285    `with-plugindir=DIR`. Default `DIR` is set to
[823]286    `<BASEDIR>/plugins/bin/wenni/`. You may use `with-gsl=DIR` to
287    provide information on GSL location. The option `enable-debug`
288    turns on debug options on the compilation of binary `nni`
289    (e.g. enables assertions).
[69]290
[823]291 3. Now build using
[854]292    {{{
293    $ make
294    }}}
[69]295
[823]296 4. Optionally, run the test programs
[854]297    {{{
298    $ make check
299    }}}
[69]300
[823]301 5. Install files using
[854]302    {{{
303    $ make install-plugin
304    }}}
[853]305    Note! `make install` will install in location `${exec_prefix}/bin`
306    which maybe something else than the BASE plugin directory.
307
[854]308 6. ''Make BASE1 aware of the plugin.''  Make sure that the settings
309    in the plug-in definitions file are set appropriately when
310    importing the plug-in definitions file
311    (`base/base1/base_plugin_script/plugin_WeNNI.base`) into
312    BASE1. More explicitly make sure that the entry in the web GUI:
313    'Name of executable' is set according to the wenni.pl install
314    location. If you prefer to make the change in the file you should
315    manipulate the line starting with `execName`.
316    [[br]] [[br]]
317    If you want use other than the default fields for intensity1,
318    intensity2, BCh1SD, and BCh2SD, you need to indicate this in the
319    WeNNIParams section of the plug-in definition file. Change the 5th
320    column of parameters 4 through 7 appropriately, i.e., if the
321    standard deviation is defined in another column than the default
322    change lines 6 and 7:
323    ≈ß©{{{
324    6 h BCh1SD    30  _xc_BCh1SD    0
325    7 h BCh2SD    30  _xc_BCh2SD    0
326    }}}
[69]327
328
[86]329
[823]330= Stand alone mode =
[86]331
[823]332The core WeNNI algorithms are implemented in C++ whereas the test
333script is written in Perl.
[86]334
[844]335== Short instructions ==
336
337It can be this easy:
338
339 1. Download and unpack WeNNI and `cd` to the root directory of the
340    distribution.
341
342 2. Do
[854]343    {{{
344    $ ./configure --enable-state=stand-alone
345    $ make
346    $ make check
347    $ make install
348    }}}
[844]349
[823]350== Pre-requisite ==
[89]351
[823]352 Optionally, for testing, Perl (http://www.cpan.org/). The test
353 programs can be run manually, see README for details.
[69]354
[823]355== Building and installing WeNNI ==
[69]356
[823]357 1. Download and unpack WeNNI and `cd` to the root directory of the
358    distribution.
[89]359
[823]360 2. If you haven't access to a BASE installation or prefer to use the
361    standard compilation components, run the configure script with
[854]362    {{{
363    $ ./configure  --enable-state=stand-alone
364    }}}
[887]365    ''Some notes on configure options:''
366    [[br]] [[br]]
367    Do `./configure --help` for
[854]368    details in available options. You may use `with-gsl=DIR` to
369    provide information on GSL location. The option `enable-debug`
370    turns on debug options on the compilation of binary `nni`
371    (e.g. enables assertions).
[665]372
[823]373 3. Now build using
[854]374    {{{
375    $ make
376    }}}
[823]377    If the package was successfully compiled two binaries are created;
378    `NNIFileConverter` and `nni`.
379
380 4. Optionally, run the test programs
[854]381    {{{
382    $ make check
383    }}}
[823]384
385 5. Install with
[854]386    {{{
387    $ make install
388    }}}
389    Note! `make install-plugin` will do the same thing as `make install`.
[823]390
391
[854]392= Test program fails =
[823]393
[854]394The numerical checks are very restrictive, if 'make check' fails this
[823]395may be due to rounding errors. You can loosen the error bound in the
396tests by changing the default value in test/wenni_test.cc. Search for:
397{{{
398bool compare(const std::string&, const std::string&, double error_bound=1e-20);
399}}}
Note: See TracBrowser for help on using the repository browser.