Evolving Software

These are my notes on the integration and streamlining of Horae, Demeter, libperlxray, and the Athena User's Guide. These notes cover installation of all these tools on a linux machine or some other kind of unix. (These instructions should also work on Windows for someone brave and knowledgeable enough to properly set up an adequate development environment. But don't expect me to know much about Windows development.) Eventually Carlo Segre will have debian packages for everything on this page. For people on debian based systems, those will probably prove easier to install that following the instructions on this page. Once this is all working, I intend to tag releases and upload tarballs to my web site and to SourceForge.

I assume that you already have Perl, Subversion, a C compiler (gcc, for instance), and a Fortran compiler (I recommend gfortran on a linux machine) installed on your computer. All these things should be available via your system's package manager.

Note that I am in the process of moving from ExtUtils::MakeMaker to Module::Build as my build system. The semantics are very similar, but the details of the build incantations are somewhat different. This little chart compares the two sets of build commands:

      E::M                         M::B
    -------------------          ------------------
     perl Makefile.PL             perl Build.PL
     make                         ./Build
     sudo make install            ./Build install

Module::Build will be installed when you follow the instructions for installing the many pre-requisites needed by these packages.

The symbol is used to mark parts of this process that are awkward or broken.

Checking the codes out of SVN

Links to SVN repositories:

• libperlxray: Currently Xray::Absorption, Xray::Scattering, Xray::SpaceGroup, Chemistry::Formula, and Ifeffit

• Horae: Athena, Artemis, and Hephaestus

• Demeter: tools for writing Ifeffit applications in perl

• Athena User's Guide: The Athena documentation build system

If you have an SVN client on your computer, issue these commands to check out the sources for all these packages:

  svn co http://cars9.uchicago.edu/svn/libperlxray libperlxray
  svn co http://cars9.uchicago.edu/svn/horae/trunk horae
  svn co http://cars9.uchicago.edu/svn/demeter     demeter
  svn co http://cars9.uchicago.edu/svn/aug         aug

Of course, you can also use a graphical SVN client. I sometimes use KDESvn, which is decent and well integrated into Konqueror. Tortoise SVN is a good Windows client.

Once you have checked out these packages, build and install everything in the order listed here.

Install Ifeffit

Grab the latest Ifeffit from the Ifeffit download page or from SourceForge.

You will need C and fortran compilers for all parts of this. Compiling the pgplot library requires X11 development libraries, development libraries for making png and gif images, and development packages for one of the curses libraries. If compilation crashes out at any step, examine the error messages for hints about which development package is missing and fetch them using your system's package installer.

The first step is to install pgplot. The easiest way by far is to use the PGPLOT_install script that Matt provides. You will need to run this as root or through sudo. After that finishes, configure and make the Ifeffit package.

    sudo ./PGPLOT_install
    ./configure
    make
    sudo make install

Install the libperlxray modules

libperlxray is a collection of perl modules used by both Horae and Demeter. These include:

Ifeffit

• SWIG-based interface to the Ifeffit library

Xray::Absorption

• Class methods for accessing several atomic x-ray absorption databases (Elam, McMaster, Chantler, Cromer-Liberman, Henke, Shaltout, and -- coming soon -- xcom)

Xray::Scattering

• Class methods for accessing two atomic x-ray scattering databases, Crommer-Mann and Waasmaier-Kirfel

Xray::SpaceGroup

• Object oriented interface to a database of symmetries of the space groups

Chemistry::Formula

• Parse strings as chemical formulas

Install the prerequisites for the libperlxray modules. Some of the prerequisites might compiling C code. You will need to have a C compiler installed on your computer. This is done by running the install_prereqs script as root:

   su root   # <--- enter root password
   ./install_prereqs

or as a sudoer:

   sudo ./install_prereqs

Occasionally, the process will stop to ask you a question. Answer yes to all such questions. This step may be a bit time-consuming, but once done it does not need to be re-done when you upgrade any of my software.

The install_prereqs script has several options, including a way of dealing with a proxy server. Here is the documentation.

In all remaining examples, I assume you are on a system which uses sudo rather than requiring you to become root. If you are on a root system (SUSE or Red Hat, for example, then become root and do not type sudo in the following instructions.

You can use the build script in the top-level directory to build and compile each of the parts of libperlxray.

   sudo ./build

This is just a simple shell script that cds into each of the subdirectories and runs the build sequence.

If, for some reason you need to do so, you can cd into each subdirectory, and build each libperlxray component in turn using these commands:

   perl Build.PL
   ./Build
   sudo ./Build install

except for Ifeffit, which is built like this:

   perl Makefile.PL
   make
   sudo make install

To successfully install the Ifeffit module, you need a C compiler.

Ifeffit's Build.PL file is not written yet. Still using Makefile.PL

Once you have installed libperlxray you can begin using the Vulcan server, an XML-RPC based web service exposing the functionality of Xray::Absorption and Chemistry::Formula via the web. This can be found in the server/ subdirectory. The server has thorough documentation embedded in the file.

Install Horae

Demeter should now be completely independent of horae, with all common functionality placed in libperlxray. You can now install Horae and Demeter separately or together, as you wish.

In the directory where you checked out Horae, issue this command to install all the CPAN prerequisites:

  sudo ./install_prereqs

Answer yes to any questions you are asked.

Once that has completed successfully, do the standard perl installation incantation:

  perl Build.PL
  ./Build
  sudo ./Build install

Install Demeter

Demeter should now be completely independent of Horae, with all common functionality placed in libperlxray. You can now install Horae and Demeter separately or together, as you wish.

In the directory where you checked out Demeter, issue this command to install all the CPAN prerequisites:

  sudo ./install_prereqs

Answer yes to any questions you are asked.

Once that has completed successfully, do the standard perl installation incantation:

  perl Build.PL
  ./Build
  sudo ./Build install

Install The Athena User's Guide

Athena's documentation is no longer included in the horae package. The User's Guide must be built and installed if you want to be able to view the document from within Athena. Once everything settles down, there will be a pre-built document package on SourceForge, but for now you need to do the following.

In the directory where you checked out the Athena User's Guide, issue this command to install all the CPAN prerequisites:

  sudo ./install_prereqs

Answer yes to any questions you are asked.

You should consider using your package manager to install the Template Toolkit before running the install_prereqs script. TT is a rather lengthy build -- most linux distributions include TT, so you should just go ahead and use the pre-built package. (In the Ubuntu universe, for example, the package is called libtemplate-perl.)

Once TT and the required perl modules are installed, issue the following commands in the directory where you checked out the user's guide:

  ./configure
  ./bin/build -a
  ./bin/pod -a
  sudo ./install

The last step moves the html and pod versions to the location where Athena can find them. The installation requires that Horae already be installed so that the correct location can be determined.

You can also build the PDF document if you have the latex interpreter installed on your computer:

  ./bin/tex -a
  cd tex
  pdflatex athena.ltx
  pdflatex athena.ltx

You have to run pdflatex twice to get the cross-referencing correct.

The package script makes the zip file containing the html, pod, css, data, and image files which will eventually find its way to SourceForge.

A note on the intall_prereqs script

As you have seen above, installing each package starts by running the install_prereqs script. (Here is it's documentation.) The purpose of this script is to streamline the downloading and installation of modules from CPAN that are used by each package. That is, its purpose is to resolve all the Perl software dependencies of each package.

The install_prereqs scripts is exactly the same for each package. It determines the dependencies by reading a file from the Bundle subdirectory under each package's main directory. For horae, the file read is Bundle\HoraeBundle.pm and so on.

When run, the script uses the CPAN Perl module and a generic set of configuration parameters to search CPAN for each of the dependencies. The current version of each dependency is compared to the version (if any) installed on your computer. If a new installation or an update is needed, the new version is downloaded, built, and installed.

The CPAN Perl module provides methods for determining versioning information for each module. Because there is not a widely accepted and observed versioning standard for Perl modules, these methods will, in some cases, fail to compare correctly the CPAN version with the version on your computer. In each such case, the script makes the decision to re-install the module regardless of the version on your computer.

Some of these are a bit annoying. For example, Math::Spline is needed by three of the four packages, but does not provide any versioning information. As a result, it will be installed repeatedly. There are a few other examples of this behavior. I decided that the conservative approach is best -- module installation is usually speedy, so it seems better to install repeatedly than to run the risk of missing a dependency.

---