Unix Installation Instructions

I keep working on identifying the most streamlined way for other to install Demeter and all of its prerequisites. It's not completely trivial, given the large number of dependencies. The instructions on this page should work on any flavor of linux, any other unix, and probably OSX as well. Much of this will work on a Windows machine with Strawberry perl, but I am not quite ready to begin supporting it.

These instructions are for installation with root privileges. At the end are instructions for installation without root privileges. That's not really any harder, but it does require one more preparatory step.

Demeter is written in perl. You must install perl on your computer. On ubuntu, the package name is simply "perl". (My computers are all ubuntu, hence all of my hints about packages that need installing refer to the ubuntu package names.)

Demeter benefits by having Gnuplot installed. On ubuntu, the package is called "gnuplot".

I promise all of this will become easier once Demeter gets closer to completion.

Step 1: Install Ifeffit and PGPLOT

You will need the gcc and gfortran compilers as well as a few development libraries installed on your computer

1. Download the Ifeffit source code from Downloads

2. Unpack that tarball and cd into the newly created directory

3. Run the PGPLOT_install script. This streamlines the rather unwieldy chore of building PGPLOT. This step will require root or sudo access to the computer.

4. Do ./configure

5. Do make

6. As root or sudo, do make install

On my ubuntu machine, the following development libraries are needed to get Ifeffit and PGPLOT compiled. On other flavors of linux, these packages might be called by different names, but hopefully this list will help you resolve which packages are needed.

1. libx11-dev
2. libncurses5
3. libpng12
4. libgif4

Step 2: Download a copy of Demeter

For now, I am not making tarball packages. The code changes too frequently. For now, you will need to install subversion (ubuntu package name subversion) to grab a copy of the code from the repository.

Find a place on disk where you want to place the folder containing the Demeter source code. cd to that location and, at the command line, type

svn co http://cars9.uchicago.edu/svn/demeter/trunk demeter

It might take a minute or two to download everything.

Step 3: Download and install the dependencies

After checking out a copy of Demeter from svn, cd into the new subdirectory and do

perl ./Build.PL

If this is the first time you are installing Demeter on this computer, you will see a very large number of warnings about missing dependencies. If no warnings are issued, proceed to Step 4.

Working behind a proxy server

The cpanm utility, which I suggest as the most expedient way to accomplish step 3d, may have trouble working behind a proxy server. The same may be true for other parts of this procedure. In that case, one way of dealing is to become the superuser by issuing this command:

sudo -s

and entering the root password.

Once you have become root, configure use of the proxy. At my lab, this would be

export http_proxy=http://192.168.1.130:3128

You will have to enter the information appropriate for your proxy server.

You can then do all of the following steps without explicitly calling sudo. Don't forget to exit once you are finished to return to being a normal user!

Step 3a: Configure cpan

You will use the cpan program to download most of the dependencies from the CPAN repository. You can make this process a little easier by configuring the cpan program. Start cpan:

sudo cpan

At the cpan> prompt, issue the following commands:

o conf build_requires_install_policy yes
o conf prerequisites_policy follow
o conf commit

When on of Demeter's dependencies itself has a dependency, this configuration will tell the cpan program to automatically follow them.

Step 3b: Install Demeter's dependencies

Now that cpan is correctly configured, do the following

sudo ./Build installdeps

This will ask you a few yes/no questions about whether to install optional dependencies. Answering yes to all of these questions is a good idea as these optional dependencies enable some nice features in Demeter. (However, if you do not have Gnuplot on you computer, answer "no" to the question about Graphics::GnuplotIF.)

After that, cpan will begin downloading and installing stuff. Depending on the speed of your Internet connection and the speed of you computer, this could take several minutes or longer. A few modules will ask questions. Mostly "yes" is the right answer. When Term::Twiddle asks if you would like to run its tests, I recommend answering "no". It's tests are quite tedious and unlikely to fail.

Step 3c: Dealing with failed dependencies

For me, the module Regexp::Optimizer always fails its tests and therefore failed to be installed. Despite failing its tests, this module has never misbehaved for me, so I typically do the following for force its installation:

sudo cpan -fi Regexp::Optimizer

The same command can be tried should any other modules fail for you.

Step 3d: Installing the Ifeffit wrapper, my Xray:: modules, and the module for reading CIF files

Issue this command to install a useful tool which extends cpan's functionality

sudo cpan -i App::cpanminus

Once installed, do the following

sudo cpanm http://cars9.uchicago.edu/~ravel/software/packages/Xray-Absorption-v3.0.1.tar.gz
sudo cpanm http://cars9.uchicago.edu/~ravel/software/packages/Chemistry-Formula-v3.0.1.tar.gz
sudo cpanm http://cars9.uchicago.edu/~ravel/software/packages/Ifeffit-3.0.1.tar.gz
sudo cpanm http://pdb.sdsc.edu/STAR/STAR-Parser-0.59.tar.gz

Step 4: Build and install Demeter

Almost done! Just do each of the following:

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

You need to redo the perl Build.PL step to verify that all the dependencies are installed and available. If any failed to install correctly, you will be told at that stage.

This will put all of Demeter, all the executable programs, and all the documentation in in the proper place on your computer. You are now good to go.

If any errors are reported during the ./Build test step, you should report them to Bruce. The best report includes a complete capture of everything written to the screen. The easiest way to capture screen text is to use tee. Here is an example:

./Build test | tee screen_messages.txt

Installing Demeter without root privileges

• In step one, replace the command

  .configure

  with

  .configure --prefix=/path/to/installation/location

  
  Here you need to specify a location in your own diskspace in which to install Ifeffit and all the rest. I'd recommend something like $HOME/local. You will also need to put $HOME/local/bin/ in your execution path.
  
  Even if you are installing Demeter without root, it is probably easier to get Ifeffit and PGPLOT installed system-wide. On a debian-based system, even better would be to install Carlo Segre's pre-built versions of Ifeffit and PGPLOT by following the instructions at http://debian-xray.iit.edu/

• Prior to Step 3a, go to http://search.cpan.org/~getty/local-lib/ and download the latest version of the local::lib module. Unpack it and cd into the newly created directory.

  • Do

    perl Makefile.PL --bootstrap

  • Then do

    make test && make install

  • If you use the bash shell, do

    echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc

    If you use a shell that used C shell syntax, follow this link for instructions.
    This last step adds a line to your login file. The easiest way for this to take effect is to log out and log in again or to open a new terminal window.

• Once local::lib is installed, follow all the instructions in Steps 3a-3d and Step 4, except that you now do not need to run anything through sudo. The whole point of installing local::lib is to be able to install all of this software in your own diskspace without needing root privileges.

Following Demeter's development

At this point you will have a bit over 50 MB of stuff in your $HOME/perl5 directory.

As I continue working on Demeter, you can keep up to date by doing the following in the folder containing the Demeter source code:

svn update
perl Build.PL
./Build
./Build test
./Build install

It is not necessary to redo Steps 1 through 3 when you update Demeter. The svn update command, updates your copy of the Demeter source. Presumably everything else will still be OK. So, the first time you install Demeter, it is rather time consuming. After that, not so much.