Install Demeter On Unix Using Git

The instructions for installing Demeter on a Linux machine are not trivial, but also not difficult. If you follow these instructions patiently, everything will work. The main issue is 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. Everything here except for installing Ifeffit and PGPLOT will work on Windows machine with Strawberry perl.

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.) You should have at least perl 5.10. Some "enterprise" versions of Linux (notably Red Hat based ones like RHEL, CentOS, and Scientific Linux) ship with an ancient version of perl. Demeter will not run under perl 5.6 or 5.8. You will have to upgrade perl.

Demeter benefits by having Gnuplot installed. All Linux distributions should have a package for Gnuplot. On ubuntu, the package is called "gnuplot". Or you can grab the latest source code from Gnuplot's SourceForge site and install it from scratch.

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

The source code for Demeter is currently managed on github: https://github.com/bruceravel/demeter

You will need to have git installed on your computer. On ubuntu machines, the package is called git-core.

To download a copy of the source code, either

• Use git to clone a copy:

  git clone git://github.com/bruceravel/demeter.git

  then follow along with developments by doing

  git pull

  to download future modifications to the code.

• Grab the most recent archive file containing the Demeter soruce code, go to https://github.com/bruceravel/demeter/archives/master and download either the tar.gz or zip file.

Cloning a copy with git is far more convenient as it allows you to easily follow developments.

Step 3: Download and install the dependencies

After checking out a copy of Demeter from git (or unpacking the archive), 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.

Step 3a: Configure cpan (optional)

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 one of Demeter's dependencies itself has a dependency, this configuration will tell the cpan program to automatically follow them.

Skipping this step is ok, but it means that you will need to answer "yes" to a lot of questions in Step 3b.

Step 3b: Install Demeter's dependencies (not optional!)

Now that cpan is correctly configured, do the following

sudo ./Build installdeps

Go get a cup of coffee. This takes a while.

Although step 3a configures cpan in such a way that most of the interaction is handled automatically, a few packages will still ask you questions. 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.)

In my experience, all dependencies install smoothly on recent linux installations. If there are any failures, you will need to track down the problems and fix them in order to proceed.

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.

The Demeter package now includes components (e.g. Xray::Absorption and STAR::Parser) that used to be handled separately. Demeter is now one stop shopping!

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

Following Demeter's development

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

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

It is not necessary to redo Step 1 and rarely necessary to redo Step 3 when you update Demeter. The git pull 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.

The very latest version of magit really helps if you are an emacs user: https://github.com/philjackson/magit

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 uses 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, 3b, and 4, except that you now do not need to install using 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.

Working behind a proxy server

Each of the steps that involves going out onto the big, bad internet will require special configuration if you are working from behind a proxy server.

For example, here at Brookhaven National Laboratory, the proxy URL and port number is http://192.168.1.130:3128. In the examples that follow, you will need to replace that with the correct proxy configuration for your institution.

git

To have git talk through the proxy, I had to do this:

git config --global https.proxy http://192.168.1.130:3128

cpan

First, fire up cpan as root

sudo cpan

At the cpan> prompt, issue the following commands:

o conf http_proxy http://192.168.1.130:3128
o conf ftp_proxy http://192.168.1.130:3128
o conf commit

Now cpan will work thorugh the proxy.