source: trunk/se/lu/thep/affymetrix/INSTALL @ 189

$Id: INSTALL 189 2006-10-27 08:53:18Z jari $

======================================================================
Copyright (C) 2006 Jari Häkkinen

This file is part of RMAExpress plug-in for BASE,
http://baseplugins.thep.lu.se/wiki/thep.lu.se.RMAExpress

RMAExpress plug-in for BASE 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 2 of the
License, or (at your option) any later version.

RMAExpress plug-in for BASE 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 this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
USA.
======================================================================


If you think these 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


0. Introduction

There are two supported ways to install the RMAExpress plug-in, you
either download a pre-compiled package or you checkout the latest
source from the subversion repository. The below instructions covers
both installation options since major parts of the installation is the
same for the different cases. There is also a source package available
for download but installation from that package is currently not
supported, it is supplied for reference only.

Note, the underlying RMAExpress algorithm itself is not a part of this
package. This packages contains the plug-in code needed for hooking up
RMAExpress to BASE as a plug-in. RMAExpress must be installed for this
plug-in to work, see more in item 1.ii) below.

Users who prefer the install from pre-compiled packages must go
through all items below except 1.iii) and 2.iv).

Users who prefer the live on bleeding edge software and compiles the
source from the subversion repository must go through all items except
3.v).

If you are upgrading a previously installed RMAExpress plug-in for
BASE you can safely skip to item 7) below.


1. Pre-requisites

i) Pre-requisite for both all install options:
This plug-in will only work with BASE 2.0 (revision 2512) or later,
i.e. BASE 1.2.x is not (and will never be) supported.

ii) Pre-requisite for both binary package and subversion tree
installs: Installation of RMAExpressConsole.

RMAExpressConsole available in the RMAExpress package written by Ben
Bolstad, and the official RMAExpress web site is
http://rmaexpress.bmbolstad.com/

You must download and compile RMAExpressConsole. This requires that
wxWidgets (a.k.a. wxWindows) is installed on your system. wxWidgets is
found at http://www.wxwidgets.org. The compilation of
RMAExpressConsole is not completely trivial, but after some tweaking
it has been successfully compiled on Mac OS X (v10.4.7) running on a
G4, and SuSE Linux (v10).

You should install the RMAExpressConsole binary such that it is
readable for the user running your BASE application server. The name
of the binary MUST be 'RMAExpressConsole' and copied into the same
directory as the plug-in (see item 3.v below). These two conditions
are hard coded in the plug-in.

Install of the plug-in will succeed even if this requisite is not
fulfilled, but execution of the plug-in will fail.

iii) Pre-requisite for subversion tree compilation:
Compile time access to BASE core jar file.

The BASE2Core.jar (must be later than subversion revision 2512) file
in use by the server running the BASE web application.


2. Compilation and installation from a subversion tree

You should skip this section if you downloaded a pre-compiled package.

iv) When installing from a subversion working copy you must compile
the plug-in, do

  make

This assumes that BASE is installed in /usr/local/base. If this is not
the case do

  make BASEROOT=<base-dir>

where <base-dir> is to be replaced with the path to BASE. When the
compilation finishes you install the plug-in into the BASE application
server file system with

  make install    or    make BASEROOT=<base-dir> install

The plug-in will install in the recommended directory
<base-dir>/www/plugins/se/lu/thep/affymetrix, i.e. if you prefer
another location please refer to the Makefile (which supports further
options).

For advanced users only: <base-dir> can really be any directory
readable for the user running your tomcat server. This may be handy if
you run several servers on one machine but only want one common
directory hierarchy for the plug-ins. Or, if you update the BASE
application frequently and in the process create new directories for
the newer application. More information about this is available in the
Makefile.

Remember the plug-in location for configuration of BASE below.


3. Installation from a pre-compiled package

You should skip this section if you use the subversion repository.

v) Install the plug-in in the BASE application server file system. If
BASE is installed in /usr/local/base simply do

  make install-precompiled

If BASE is installed elsewhere, do

  make BASEROOT=<base-dir> install-precompiled

where <base-dir> is to be replaced by the path to BASE. The plug-in
will install in the recommended directory
<base-dir>/www/plugins/se/lu/thep/affymetrix, i.e. if you prefer
another location please refer to the Makefile (which supports further
options).

For advanced users only: <base-dir> can really be any directory
readable for the user running your tomcat server. This may be handy if
you run several servers on one machine but only want one common
directory hierarchy for the plug-ins. Or, if you update the BASE
application frequently and in the process create new directories for
the newer application. More information about this is available in the
Makefile.

Remember the plug-in location for configuration of BASE below.


4. BASE configuration

vi) Make BASE aware of the new plug-in:

 - Login to BASE with plug-in administrative privileges.

 - Choose 'Administrate' -> 'Plugins' -> 'Definitions'.

 - Click on 'New...'. This will open up the 'Create plugin' pop-up
   window. Type "se.lu.thep.affymetrix.RMAExpress" in the 'Class'
   field and
   "<base-dir>/www/plugins/se/lu/thep/affymetrix/RMAExpress.jar" in
   the 'Path' field. Replace <base-dir> with whatever you used in item
   3.v) above. Click on the 'Save' button.

 - Share the plug-in to all users/roles/groups that should have
   access to it (sharing it to group Everyone should be sufficient in
   most cases).


5. Remember to install RMAExpressConsole according to the conditions
   stated in item 1.ii) above.


6. That's it, now you need to BASE skills to actually make use of the
   RMAExpress plug-in. Read the README file for some pointers on what
   to do now.


7. Updating RMAExpressConsole or RMAExpress plug-in for BASE.

   a) RMAExpressConsole

   Installing a new RMAExpressConsole binary is trivial, just replace
   the old binary with the new binary.

   b) RMAExpress plug-in for BASE.

   This is straighforward:

   - Replace the old jar-file and

   - Login to BASE with plug-in administrative privileges.

   - Choose 'Administrate' -> 'Plugins' -> 'Definitions'.

   - Locate the RMAExpress plug-in in the list and click on it.

   - Click on the 'Unload' button if it is available. This will
     remove the old plug-in from the application.

   - Click on 'Edit...'. This will open up the 'Edit plugin'
     pop-up window. No parameter changes are need, just click on
     the 'Save' button.

   - Done.