Changeset 823


Ignore:
Timestamp:
Nov 26, 2008, 4:23:37 PM (13 years ago)
Author:
Jari Häkkinen
Message:

Addresses #53 and fixes #60.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • plugins/base1/se.lu.thep.wenni/trunk/INSTALL

    r665 r823  
    4040algorithm independently of BASE. The different modes build and require
    4141different things. You choose the mode by giving the `configure` script
    42 the appropriate option. See below for more details on the different modes
     42the appropriate option. See below for more details on how to compile
     43the package in the different modes.
     44
     45
     46
     47= General requirements =
     48
     49General requirements to build the package are that you work in a
     50decent computing environment where you have access to tools such as
     51make and a standards comliant C++ compiler. Since parts of the
     52algorthms in WeNNI depends on the GNU scientific library it is
     53required. GSL can be downloaded from http://www.gnu.org/software/gsl/.
     54
     55
    4356
    4457= BASE 2 mode =
    4558
     59The core WeNNI algorithms are implemented in C++ and to be useful in
     60BASE2 a Java wrapper is required. BASE2 only accepts plug-ins written
     61in the Java programming language hence a Java wrapper is provided with
     62WeNNI for BASE2. The wrapper will export appropriate data from the
     63BASE2 server, run the WeNNI binary, and import data back to the
     64server.
     65
    4666== Pre-requisite ==
    4767
    48  1. Download and install GSL, http://www.gnu.org/software/gsl/.
    49  2. A working Base2 installation.
    50 
    51 == WeNNI install ==
    52 
    53  1. Download and unpack WeNNI. `cd` to the root directory of the distribution.
     68 1. Java 1.6.
     69
     70 2. A working BASE2 installation or Internet connection. The BASE
     71    program libraries are required for the creation of the wrapper
     72    plug-in. If no local BASE installation is available the required
     73    packages will be downloaded automatically.
     74
     75 3. Version x of net.sf.basedb. .... package. Needed for creation of
     76    the Java wrapper. The package is downloaded during the compilation
     77    process.
     78
     79 4. BASE 2.9 or later for plug-in use. Earlier versions may work but
     80    it is not tested.
     81
     82 5. Optionally, for tetsing, Perl (http://www.cpan.org/). The test
     83    programs can be run manually, see README for details.
     84
     85== Building and installing the plug-in (WeNNI and the Java wrapper) ==
     86
     87 1. Download and unpack WeNNI and `cd` to the root directory of the
     88    distribution.
     89
     90 2. If you haven't access to a BASE2 installation or prefer to use the
     91    standard compilation components, run the configure script with
     92
     93    $ `./configure`
     94
     95    There is a possiblity to use the build tools to automatically
     96    install the package. In this case you may want to change the
     97    default plug-in installation path.
     98
     99    $ `./configure --with-plugindir=DIR`
     100
     101    The default plug-in installation directory is in the directory
     102    plugins/se/lu/thep/wenni rooted in `basedir`.
     103
     104    If you prefer to compile WeNNI Java wrapper using your local BASE2
     105    installation. This is only needed if you have made local changes
     106    affecting plugins and where these modifications are required in
     107    the WeNNI Java wrapper. You should know if this is required, if
     108    you do not know simply go for the above option. So, if you know do
     109
     110    $ `./configure --with-basedir=/path/to/base`
     111
     112    Some notes on configure options:
     113
     114    The configure script accepts a few options that may be of
     115    interest. You can provide `./configure` with BASE2 location
     116    information with `--with-basedir=BASEDIR`. This information is
     117    used to find jar files such as `BASE2Core.jar` needed for
     118    compilation. The plug-in installation directory can be changed
     119    using `./configure` option `--with-plugindir=DIR`. Files will be
     120    installed in `<DIR>`. Default `DIR` is set to
     121    `<BASEDIR>/plugins/se/lu/thep/wenni/`. You may use `with-gsl=DIR`
     122    to provide information on GSL location. The option `enable-debug`
     123    turns on debug options on the compilation of binary `nni`
     124    (e.g. enables assertions).
     125
     126 3. Now build using
     127
     128    $ `make`
     129
     130    If all went well `nni` was created in directory `bin/nni` as well
     131    as `WeNNI.jar` in directory `base/base2/`.
     132
     133 4. Optionally, run the test programs
     134
     135    $ `make check`
     136
     137 5. Install files using
     138
     139    $ `make install`
     140
     141 6. Make BASE2 aware of the plugin, see BASE2 documentation
     142    http://base.thep.lu.se/chrome/site/doc/html/index.html
     143
     144
     145
     146= BASE 1 mode =
     147
     148This section is not well tested. Please report success or failure
     149following these BASE1 related instructions.
     150
     151The core WeNNI algorithms are implemented in C++ and to be useful in
     152BASE1 a Perl wrapper is used. The wrapper will parse the from the
     153BASE1 server exported data file, run the WeNNI binary, and generate a
     154data file for import of data back to the server.
     155
     156== Pre-requisite ==
     157
     158 1. Perl (http://www.cpan.org/) for testing and plug-in execution in
     159    the BASE1 server environment. The test programs can be run
     160    manually, see README for details.
     161
     162 2. A working BASE1 installation, or download the BASE1 plug-in
     163    development kit.
     164
     165== Preparing WeNNI build for BASE1 ==
     166
     167 1. Download and unpack WeNNI. `cd` to the root directory of the
     168    distribution.
     169
     170 2. If you do not have access to a working BASE1 installation do the
     171    following steps; Download the BASE1 plug-in development kit from
     172    http://baseplugins.thep.lu.se/wiki/PluginDownload, unpack the
     173    package in the WeNNI root directory, compile the package, and then
     174    create a symbolic link to this directory. Basically, after
     175    download, issue the following sequence of commands in to prepare
     176    the devkit for WeNNI:
     177
     178    $ tar zxpf BASE-plugindevkit-1.2.17.tar.gz
     179    $ cd BASE-plugindevkit-1.2.17/bogus_base
     180    $ ./bootstrap
     181    $ ./configure
     182    $ make
     183    $ cd ../..
     184    $ ln -s BASE-plugindevkit-1.2.17 BASE-plugindevkit
     185
     186== Building and installing the plug-in (WeNNI with suport) ==
     187
     188 1. You should already have downloaded WeNNI above if not please
     189    return to the previous section. `cd` to the root directory of the
     190    distribution.
    54191
    55192 2. Run configure script with
    56     $ `./configure`
    57 
    58 The configure script accepts a few options that may be of
    59 interest. You can provide `./configure` with BASE location information
    60 with `--with-basedir=BASEDIR`. This information is used to find jar
    61 files such as `BASE2Core.jar`. Files `WeNNI.jar` and `nni` will be
    62 installed in `<BASEDIR>/www/plugins/se/lu/thep/wenni/`. Installation
    63 directory can be changed by using `./configure` option
    64 `with-plugindir=DIR`.
    65 
    66 
    67 You can configure where files `WeNNI.jar` and
    68 the `nni` will be installed using `with-plugindir=DIR`. Files will be
    69 installed in `<DIR>/se/lu/thep/wenni/`. Default `DIR` is set to
    70 `path/to/base/www/plugins/`. You may use `with-gsl=DIR` to provide
    71 information on GSL location. The option `enable-debug` turns on debug
    72 options on the compilation of binary `nni` (e.g. enables assertions).
     193
     194    $ `./configure --enable-state=base1 --with-basedir=BASEDIR`
     195
     196    where <BASEDIR> is the absolute path to the root direcotry of your
     197    working BASE1 installation, or if you are using the developer kit,
     198    the absolute path to the bogus_base direcotry created above:
     199    `/path/to/wenni/BASE-plugindevkit/bogus-base`
     200
     201    Some notes on configure options:
     202
     203    The configure script accepts a few options that may be of
     204    interest. You generally must provide `./configure` with BASE1
     205    location information with `--with-basedir=BASEDIR`. This
     206    information is used to find BASE1 API (program libraries and
     207    header files). Header file `basefile.h` is expected to reside in
     208    `<BASEDIR>/include/cxx/`. `<BASEDIR>` must be an absolute
     209    path. The plug-in installation directory can be changed using
     210    `./configure` option `with-plugindir=DIR`. Default `DIR` is set to
     211    `<BASEDIR>/plugins/bin/wenni/`. You may use `with-gsl=DIR` to
     212    provide information on GSL location. The option `enable-debug`
     213    turns on debug options on the compilation of binary `nni`
     214    (e.g. enables assertions).
    73215
    74216 3. Now build using
     217
    75218    $ `make`
    76219
    77 If all went well `nni` created in directory `bin/nni` as well as
    78 `WeNNI.jar` in directory `base/base2/`.
    79 
    80  4. Optionally, run the test program
     220 4. Optionally, run the test programs
     221
    81222    $ `make check`
    82223
    83224 5. Install files using
     225
    84226    $ `make install`
    85227
    86  6. Make BASE aware of the plugin, see BASE documentation
    87  http://base.thep.lu.se/chrome/site/doc/html/index.html
    88 
    89 
    90 = BASE 1 mode =
    91 
    92 == Pre-requisite ==
    93 
    94  1. Download and install GSL, http://www.gnu.org/software/gsl/.
    95  2. Perl, http://www.cpan.org/.
    96  3. A working BASE1 installation.
    97 
    98 == WeNNI install ==
    99 
    100  1. Download and unpack WeNNI. `cd` to the root directory of the distribution.
    101 
    102  2. Run configure script with
    103     $ `./configure --enable-state=base1`
    104 
    105 The configure script accepts a few options that may be of
    106 interest. You can provide `./configure` with BASE location information
    107 with `--with-basedir=BASEDIR`. This information is used to find base
    108 library and header file. Header file `basefile.h` is expected to be
    109 found in
    110 `<BASEDIR>/BASE-plugindevkit/bogus_base/include/cxx/`. `<BASEDIR>`
    111 must be an absolute path.
    112 
    113 
    114 This information is used to find jar files
    115 such as `BASE2Core.jar`. You can configure where files `WeNNI.jar` and
    116 the `nni` will be installed using `with-plugindir=DIR`. Files will be
    117 installed in `<DIR>/se/lu/thep/wenni/`. Default `DIR` is set to
    118 `path/to/base/www/plugins/`. You may use `with-gsl=DIR` to provide
    119 •information on GSL location. The option `enable-debug` turns on debug
    120 options on the compilation of binary `nni` (e.g. enables assertions).
    121 
    122  3. Now build using
    123     $ `make`
    124 
    125 If all went well `nni` created in directory `bin/nni` as well as
    126 `WeNNI.jar` in directory `base/base2/`.
    127 
    128  4. Optionally, run the test program
    129     $ `make check`
    130 
    131  5. Install files using
    132     $ `make install`
    133 
    134  6. Make BASE aware of the plugin, see BASE documentation
    135  http://base.thep.lu.se/chrome/site/doc/html/index.html
    136 
    137 
    138 pre-requisite:
    139 
    140 Mandatory:
    141 
    142 a) Download and install GSL, http://www.gnu.org/software/gsl/.
    143 
    144 Optional:
    145 
    146 b) If you plan to run WeNNI as a plug-in you need a running BASE
    147    installation. If you have to set up a BASE server, please go to
    148    http://base.thep.lu.se for information on how to download and
    149    install BASE.
    150 
    151 c) You need Perl, http://www.cpan.org/, to run the tests or
    152    examples. You must install Perl on the BASE server if you plan to
    153    run WeNNI as a plug-in. You do not need Perl if you plan to run
    154    WeNNI as a stand alone package (skip 'make check' below and perform
    155    tests manually according to the README file).
    156 
    157 
    158 
    159 WeNNI install
    160 
    161 i) Download and unpack WeNNI. 'cd' to the root directory of the
    162    distribution.
    163 
    164 
    165 ii) If you are going to run WeNNI as a plug-in to BASE, do the
    166    following steps starting in the WeNNI distribution root directory
    167 
    168      $ mkdir BASE-plugindevkit
    169      $ cd BASE-plugindevkit
    170      $ ln -s /path/to/base bogus_base
    171      $ cd ..
    172 
    173 
    174 iii) If you have a BASE installation available and intend to use WeNNI
    175    as a BASE plug-in you can safely skip this item. Others must
    176    download the BASE plug-in development kit
    177    (http://lev.thep.lu.se/trac/baseplugins/wiki/PluginDownload),
    178    unpack the package in the WeNNI root directory, compile the
    179    package, and then create a symbolic link to this
    180    directory. Basically, after download, issue the following sequence
    181    of commands in to prepare the devkit for WeNNI:
    182 
    183      $ tar zxpf BASE-plugindevkit-1.2.17.tar.gz
    184      $ cd BASE-plugindevkit-1.2.17/bogus_base
    185      $ ./bootstrap
    186      $ ./configure
    187      $ make
    188      $ cd ../..
    189      $ ln -s BASE-plugindevkit-1.2.17 BASE-plugindevkit
    190 
    191 
    192 iv) Very brief WeNNI compilation instructions:
    193 
    194    a) If you are compiling in a BASE server environment do:
    195 
    196      $ ./configure --prefix=/path/to/base
    197 
    198    b) If not do
    199 
    200      $ ./configure --bindir=/path/where/to/install/binaries
    201 
    202    The --bindir is optional, if you do not set it programs will be
    203    installed in /usr/local/bin. The install is performed only if you
    204    choose to do it with an explicit command ('make install').
    205 
    206    Now, irrespective if you choose a) or b) above do
    207 
    208      $ make
    209 
    210    If all went well a few binaries where created.
    211 
    212 
    213 v) Optionally, run the test program
    214 
    215      $ make check
    216 
    217    The numerical checks are very resitrictive, if 'make check' fails
    218    this may due to this. You can loosen the error bound in the tests
    219    by changing the default in test/wenni_test.cc line 17:
    220 
    221      bool compare(const std::string&, const std::string&,
    222                   double error_bound=1e-20);
    223 
    224 If you are installing a BASE plug-in read beyond this point, others
    225 may want to do 'make install' to install the binaries in the directory
    226 set in step iv) above, and then return to the README file.
    227 
    228 
    229 vi) BASErs need to copy the binaries to their plug-in directory on the
    230    BASE server. Do this (5 one-liners):
    231 
    232      $ mkdirhier /path/to/base/plugins/bin/thep.lu.se/wenni
    233      $ cp -p bin/BaseFileConverter/BaseFileConverter \
    234                             /path/to/base/plugins/bin/thep.lu.se/wenni
    235      $ cp -p bin/base_plugin_script/wenni.pl \
    236                             /path/to/base/plugins/bin/thep.lu.se/wenni
    237      $ cp -p bin/nni/nni /path/to/base/plugins/bin/thep.lu.se/wenni
    238      $ cp -p bin/NNIFileConverter/NNIFileConverter \
    239                             /path/to/base/plugins/bin/thep.lu.se/wenni
    240 
    241 
    242 vii) BASErs make sure that the settings in the plug-in definitions
    243    file are set appropriately when importing the plug-in definitions
    244    file (bin/base_plugin_script/plugin_WeNNI.base) into BASE. More
     228 6. Make BASE1 aware of the plugin.
     229
     230   Make sure that the settings in the plug-in definitions file are set
     231   appropriately when importing the plug-in definitions file
     232   (base/base1/base_plugin_script/plugin_WeNNI.base) into BASE1. More
    245233   explicitly make sure that the entry in the web GUI: 'Name of
    246    executable' is set according to the wenni.pl copying in step vi)
    247    above. If you prefer to make the change in the file you should
    248    manipulate the line looking like
    249 
    250          'execName        thep.lu.se/jari/wenni/wenni.pl'
     234   executable' is set according to the wenni.pl install location. If
     235   you prefer to make the change in the file you should manipulate the
     236   line starting with `execName`.
    251237
    252238   If you want use other than the default fields for intensity1,
     
    261247
    262248
    263 viii) Now you should go to the README file.
     249
     250= Stand alone mode =
     251
     252The core WeNNI algorithms are implemented in C++ whereas the test
     253script is written in Perl.
     254
     255== Pre-requisite ==
     256
     257 Optionally, for testing, Perl (http://www.cpan.org/). The test
     258 programs can be run manually, see README for details.
     259
     260== Building and installing WeNNI ==
     261
     262 1. Download and unpack WeNNI and `cd` to the root directory of the
     263    distribution.
     264
     265 2. If you haven't access to a BASE installation or prefer to use the
     266    standard compilation components, run the configure script with
     267
     268    $ `./configure  --enable-state=stand-alone`
     269
     270    Some notes on configure options:
     271
     272    Do `./configure --help` for details in available options. You may
     273    use `with-gsl=DIR` to provide information on GSL location. The
     274    option `enable-debug` turns on debug options on the compilation of
     275    binary `nni` (e.g. enables assertions).
     276
     277 3. Now build using
     278
     279    $ `make`
     280
     281    If the package was successfully compiled two binaries are created;
     282    `NNIFileConverter` and `nni`.
     283
     284 4. Optionally, run the test programs
     285
     286    $ `make check`
     287
     288 5. Install with
     289
     290    $ `make install`
     291
     292
     293
     294= Test programs fail =
     295
     296The numerical checks are very resitrictive, if 'make check' fails this
     297may be due to rounding errors. You can loosen the error bound in the
     298tests by changing the default value in test/wenni_test.cc. Search for:
     299{{{
     300bool compare(const std::string&, const std::string&, double error_bound=1e-20);
     301}}}
Note: See TracChangeset for help on using the changeset viewer.