INSTALL ======= -- 2001.11.30.ET: Prerequisites ============= Required Libraries ================== Madeline v. 0.933 requires the GNU readline library version 4.1. Older versions of the readline library may also work, but have not been tested. We have previously had trouble compiling some newer versions of the library. We now provide a script to retrieve and install GNU readline v. 4.1 for you in the event that your system does not yet have it installed. If you have problems or don't care to use our script, download the readline version 4.1 library from the GNU ftp site, ftp.gnu.org, in the /gnu/readline/ directory, or from the link on the eyegene.ophthy.med.umich.edu web site. Optional Companion Utilities ============================ The optional "gt" utility provides a convenient way to watch Madeline's error and log messages in separate windows under X. You can obtain "gt" from the eyegene.ophthy.med.umich.edu web site. Unfortunately, "gt" is now out of sync with newer versions of the GTK libraries and needs some work. Note that "gt" requires gtk+ v. 1.2. (http://www.gtk.org). Since the utility is really optional, you can live without it quite well. "gt" is currently *not* recommended. Compilers and Platforms ======================= UNIX and Linux Platforms ======================== Madeline now uses GNU Autoconf to insure portability to the widest possible variety of systems. This version of Madeline has been successfully compiled using the following compiler, kernel, and hardware combinations: * GNU gcc 2.95.3 on: * RedHat v. 6.2 Linux (2.2 i386 kernel) * SuSE v. 7.2 Linux (2.4 i386 kernel) * SuSE v. 7.3 Linux (2.4 i386 kernel) * OpenBSD v. 2.9 on i386 * FreeBSD v. 4.4 on i386 * Solaris 8 (SunOS 5.8) on i386 * SunOS 5.6 on Sparc Ultra-1 * Solaris 8 (SunOS 5.8) on Sparc UltraSPARC-IIi * Sun Forte Workshop C/C++ Compiler: * SunOS 5.6 on Sparc Ultra-1 32-bit executable * Solaris 8 (SunOS 5.8) on Sparc UltraSPARC-IIi 32-bit executable * Solaris 8 (SunOS 5.8) on Sparc UltraSPARC-IIi 64-bit executable (64 bit executable not thoroughly tested) In light of this, we expect that the program can be built successfully on almost any modern UNIX platform. Note that AUTOCONF seems to want to choose GNU gcc in preference to any other compiler on your system. You can change the environment variables related to the compiler, or just manually edit the src/Makefile after letting configure do its thing. For example, on Solaris 8, you could do something like this if you wanted to use Sun's native Workshop (a.k.a. Forte) compiler: CC=/opt/SUNWspro/bin/CC -xtarget=ultra -xarch=v9 Madeline's Make file has only been tested with GNU make. Cygwin on Win32 =============== Madeline also compiles successfully with gcc on Cygwin (http://sources.redhat.com/cygwin/) on Win32 platforms. This is not really recommended, but it does work. Win32 Platforms =============== Direct support for Win32 platforms has been discontinued. The code base contains most of the support needed to compile Madeline as a Win32 console application (in processm.c), except for the GNU readline library (Cygwin provides readline, so this is not an issue on Cygwin). One would have to provide a reasonable replacement for the GNU readline library on Win32. But, why bother? On Intel hardware, GNU/Linux and the various free BSDs are cheaper, faster, and better for the kind of scientific computing that you are probably going to do with Madeline. Installation Procedure ======================== Obtaining TAR Packages ====================== Madeline is distributed in tarred gzip and bzip2 packages available for download from http://eyegene.ophthy.med.umich.edu. Untarring the Packages ====================== Be sure to first untar and install the GNU readline 4.1 library if it is not already installed on your machine. If you have any trouble compiling Madeline with the version of readline installed on your machine, just download and install readline 4.1 in an appropriate location like /usr/local and you shouldn't have any trouble. Follow the directions provided with GNU readline. Should you forget to download GNU readline, Madeline now includes a script to do it for you. For a gzipped madeline package using GNU tar, type: tar xzvf madeline-x.xxx.tar.gz For a bzip2 madeline package using GNU tar, type: tar xIvf madeline-x.xxx.tar.bz2 For a gzipped madeline package using a non-GNU tar, type: gzip -cd madeline-x.xxx.tar.gz | tar xvf - This will create a subdirectory called madeline-x.xxx where x.xxx is the version number. The subdirectory will contain all documentation, source files, and sample data. Compiling and Installing the Package ==================================== From the top level "madeline-x.xxx" subdirectory, just type the following sequence of commands: ./configure <-- You must type the "./" before "configure" make su root <-- You only need su to root if installing in /usr/local or a similar location requiring root permissions. make install By default, Madeline will be installed in /usr/local. You can change this by typing configure with "--prefix=" to specify an alternative directory. For example, if your home directory was "/home/cat" and you wanted to install Madeline in your home "bin" subdirectory ("/home/cat/bin"), you would type: ./configure --prefix=/home/cat make make install Type "./configure --help" to see what other options are available. If you get an error message, first check to make sure that you have the required readline libraries installed correctly. The GNU readline library and Madeline require that at least one of the following libraries is present on your system: * termcap * curses * ncurses So, if the configure script was unable to locate one of these libraries and the src/Makefile doesn't contain a line that looks like this: TERMCAP_LIB = -ltermcap or this: TERMCAP_LIB = -lcurses or this: TERMCAP_LIB = -lncurses ... then you might need to define the LD_LIBRARY_PATH variable or otherwise inform your compiler where to find these libraries. Final Installation ================== By default, Madeline assumes that it can locate the Madeline system directory at /usr/local/madeline-x.xxx/system. If you unpacked Madeline someplace other than /usr/local, you will need to create a MADELINESYSTEM environment variable that points to a directory which contains the default "startup.script" file and a "docs" subdirectory that contains the HTML help documentation. For example, using csh shell: % setenv MADELINESYSTEM /someplace_different/madeline-x.xxx/system Or using bash shell: $ export MADELINESYSTEM=/someplace-different/madeline-x.xxx/system Listing this directory should look like this: % ls -l /someplace_different/madeline-x.xxx/system -rw-r--r-- 1 root root 482 Feb 24 14:13 startup.script drwxr-xr-x 2 root root 4096 Nov 4 16:16 docs NOTE: You DO NOT have to set MADELINESYSTEM if you unpacked the distribution tar file in /usr/local. Madeline first checks the current working directory for a locally customized version of the "startup.script" file. If not found, Madeline checks for a global version of "startup.script" in either the default system directory, or else in the system directory specified by the MADELINESYSTEM environment variable. If not found, or if MADELINESYSTEM does not exist, then Madeline issues a warning message and continues normally. When a user issues the "help" command, Madeline first looks in the default system/docs subdirectory or in the $MADELINESYSTEM/docs subdirectory for the HTML documentation. If Madeline can't find the documentation on the local machine, Madeline will call the web browser (defined in the "WebViewer" variable) using the URL provided in the "WebAddress" variable (http://eyegene.ophthy.med.umich.edu/madeline/). SETTING UP THE GLOBAL startup.script FILE ========================================= The global startup.script file allows you to tell Madeline what helper applications to use, default database field names, and many other parameters that affect the way Madeline behaves. Any commands that you can enter when using Madeline interactively can be placed into a script file, including the global startup.script file. The following provides a sample of assignments that are commonly present in a global startup.script file: // // startup.script for Madeline v. 0.933 // // // Postscript viewer called after the "draw pedigrees" command // has been issued: // // PostscriptViewer="gv" <-- Appropriate for most Linux distributions // PostscriptViewer="ghostview" <-- More likely choice in other 'NIX environments // PostscriptViewer="ghostview" // // File editor used when the "edit" command is issued: // FileEditor ="emacs" // // Watch the error log in a 'gt' window: // system "tail -f madeline.err | gt -1mt 'Madeline Error Log' &" The last line only works on a Unix or Linux system in which you have installed the optional "gt" utility. It says, "call the tail command to continuously monitor the 'madeline.err' file and pipe it to the 'gt' utility which displays the messages in an X-Window. For the FUSION study, you should also include the following three lines in your autorun.bat file(s): PositionField="KOSAMBICM" OrdinalField ="POSITION" set FusionSupport ON In Madeline 0.933, another option now available is to directly edit the config.h file before you compile the executable to reflect the defaults that you would like to use for your environment.