Madeline is currently only distributed as a source-code package. You therefore have to compile it with a modern C++ compiler before you can install it.

For the impatient, just type these commands:

 ~> tar xzvf madeline-0.935.tar.gz
 ~> cd madeline-0.935
 ~> ./configure
 ~> make
 ~> su -c "make install"  
  

If everything goes smoothly, this will install Madeline in /usr/local/bin. Documentation will be located in /usr/local/share/madeline. Note that super-user (admin) rights are required for "make install" into /usr/local -- hence the "su" command shown (for Linux). A "sudo" command can be used in place of "su" on many platforms (MacOSX, OpenBSD, etc.).

If at all possible, be sure to use the GNU version of "tar". GNU "make" may also be required on some platforms.

If you don't have admin rights on the machine, then you can install madeline in a local subdirectory of your home directory. To install Madeline and associated components into a local subdirectory called "statgen", just do this:

 ~> ./configure --prefix=$HOME/statgen
 ~> make
 ~> make install  
  

Madeline will be installed in $HOME/statgen/bin with documentation in $HOME/statgen/share/madeline.

Even though Madeline was historically written in C, we have been compiling the code using only C++ compilers because C++ compilers enforce the tighter type checking rules of the C++ language and this generally results in fewer bugs. Explicit features of the C++ language have also been used in some of the more recent code. You will therefore need to use a modern C++ compiler to compile Madeline. The ./configure script will look for and use the GCC C++ compiler if it is present. You can always manually edit the resulting src/Makefile if you want to use a different compiler.

Development of Madeline is done on Linux machines using the GNU GCC compiler. If you are having trouble compiling Madeline, you may want to try using the GCC compiler first. When using GCC, we recommend version 3 or better. However, you will note from the chart in the main documentation that Madeline compiles successfully using the older 2.95.x series of GCC compilers. On most platforms, the GCC C++ compiler is called using "g++".

The configuration script ("./configure") that you run after unpacking the distribution looks for the presence of several auxiliary programs and tries to pick the best option based on what is available on your system. The two most important auxiliary programs that are sought are (1) an editor for editing files and (2) a web browser for viewing HTML documentation. The names of programs that the configure script picks are then substituted into the "src/config.h" file. These substitutions determine the default value of Madeline's Editor and WebBrowser variables. This configuration script works very well on Linux and similar systems. However, it may not work well on the Macintosh, Cygwin (Windows), or some other platforms. If it does not work well, just edit the "config.h" file directly after the "./configure" script has completed.

Madeline requires the GNU readline library which allows users to edit command lines as they are typed in. The GNU readline library also comes with the GNU history library that Madeline also uses. The readline library will be already installed on most Linux distributions, and some other systems.

If Madeline's ./configure script cannot find an installed copy of these library, the script will ask you whether you want to download and install it. Sometimes this works flawlessly without much user intervention. Often just a "su" or "sudo" is required for the final "make install".

Sometimes it happens that you have installed readline properly, but the ./configure script does not find it. If you installed readline in a local $HOME/statgen/ directory for example, then (assuming a bash shell) try adding the local library path to the linker's search path as follows:

~> export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/statgen/lib
~> cd madeline-0.935
~> ./configure --prefix=$HOME/statgen/
  

Madeline provides support for extended Latin and non-Latin scripts in file names, data files, and in the localized display of dates by using Unicode strings in the UTF-8 format.

In order to display Unicode UTF-8 data properly, you will need to use a Unicode-competent terminal emulator such as mlterm. You will also need a Unicode console font such as GNU Unifont installed on your system. Finally, your system must be set to a UTF-8 locale. See A Quick Primer On Unicode and Software Internationalization Under Linux and UNIX for details.

Modern Linux distributions like SuSE and Redhat now default to UTF-8 locales in most cases. Distributions like SuSE provide both mlterm and GNU Unifont as part of their distribution. Other systems, especially non-Linux systems, do not. In summary, if you need extended Latin or non-Latin script support, install Madeline on a Linux system.

Sun's version of tar often gives a check-sum error on perfectly valid tar files. Use GNU tar instead.

We have compiled 64-bit Madeline executables only using the Sun Workshop compiler (CC -fast -xtarget=ultra -xarch=v9 -xO4) on SPARC architectures. It should be possible to use gcc (g++ -m64 ...) to obtain 64-bit executables on SPARC, AMD, or other 64-bit architectures, but we have not tried it. Note that you will also have to compile 64-bit versions of the GNU readline library in order to link the executable.

For Unicode support, Sun Microsystems provides UTF-8 locales for Solaris, but these are not always installed by system administrators.

Only OS X is supported.

You will need to install the Apple Developer Tools on your OSX machine in order to compile Madeline. These tools should be present on a CD that was supplied when you purchased OSX. It should also be possible to download these tools should you lack the CD.

Although Madeline does not require XWindows to run, some auxillary programs that you might want to use with Madeline, such as the postscript/pdf viewer called gv do require the X windowing system to run. You should therefore seriously think about installing Apple's X11 or XDarwin before you install Madeline. After you have got X11 or XDarwin installed, you can install Fink. Fink is a project to port a large number of Open Source (Linux) software over to the Apple OSX platform. Fink is where you will go to obtain a port of the gv postscript/PDF viewer. Of course it is true that you can run Madeline on OSX without gv, for example, but what OSX will want to do is to convert Madeline's .ps postscript output to PDF format. This works -- but it is very slow compared to just opening the .ps files directly in gv or a similar viewer without having to go through any conversion process. If you take the little bit of extra time required to install XDarwin and Fink, you will probably enjoy using Madeline on OSX a bit more.

Before you can even compile Madeline, you will need to compile and install the GNU readline library. The GNU readline ./configure script fails to detect the host operating system. To get around this problem, type the following when trying to configure readline:

./configure --host=darwin

Readline's ./configure script may still complain about not recognizing this type of host, but it won't matter -- the rest of the tests will be executed and the make files will be created. You can then make and sudo make install to complete installation of readline.

The ./configure script supplied with Madeline v. 0.935 does not know how to find auxiliary programs such as the Safari web browser. In the script/ subdirectory a script called "osx_run_safari" has been provided for starting Safari from the terminal command line or from within Madeline. Edit the config.h file manually to make the WebBrowser variable default to the name of this script.

The ./configure script supplied with Madeline v. 0.936 is a lot smarter and will automatically use OSX's "open" utility for opening files and URLs. OSX's default text editor will be used for editing files, while Safari will be the default for opening HTML pages. If you have Fink's version of gv installed and the Fink /sw/bin directory is part of your $PATH variable, then Madeline's script will choose to use gv as a first choice for viewing Postscript files. The script will fall back to using OSX's open utility if gv cannot be located.

Do not use Internet Explorer for viewing Madeline documentation on a Mac: it will crash while trying to load the document.

Madeline compiles successfully using Cygwin which provides a GNU-based UNIX-like environment on Microsoft Windows. Madeline's ./configure script may not know how to find auxiliary programs on Windows. Madeline's Unicode features are not usable under Cygwin. The Madeline documentation is not formatted correctly when displayed in Internet Explorer: use Mozilla or Opera instead. We don't recommend this configuration. If you have a PC, Linux is a much better platform for statistical genetics work.

Madeline compiles and runs under OpenBSD and FreeBSD but we have not tested these platforms extensively. When I last checked, OpenBSD still lacked modern locale support, so Madeline's Unicode features may be limited on this platform.