Installing Demeter from source code

The instructions for installing the DEMETER source code 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 a Windows machine with Strawberry perl.

These instructions are for installing system-wide, which requires root privileges. All instructions are given assuming that you use a system which uses sudo. If your machine does not use sudo, then replace sudo with su -s in the instructions that follow.

In a section below instructions are given for installation without root privileges. All the instructions are the same, once you do an additional preparatory step.

Here is another take on installation instructions, written in another person's words.

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. Package names on other systems are likely to be similar.) You must use at least perl 5.10, butpreferably something much newer. Some “enterprise” versions of Linux (notably Red Hat based ones like RHEL, CentOS, and Scientific Linux) may ship with an ancient version of perl. Demeter will not run under perl 5.6 or 5.8. You will have to upgrade perl before using DEMETER.

DEMETER benefits tremendously by having Gnuplot installed. All Linux distributions should have a package for Gnuplot. On Ubuntu, the package is called “gnuplot”. You also likely want to install one of the GUI packages, “gnuplot-x11” or “gnuplot-qt”. Or you can grab the latest source code from http://gnuplot.info and install it from scratch.

DEMETER's build system

DEMETER uses a tool called Module::Build for its build system. For many years, Module::Build was simply a part of the standard Perl installation. As of Perl 5.22, Module::Build is no longer part of the Perl standard distribution. This is a small inconvenience for people who are installing DEMETER for the first time. It means that you must take a step to prepare the build environment before actually beginning to build DEMETER.

If you do not have Module::Build on your system, you will see and error much like this:

$ perl Build.PL
Base class package "Module::Build" is empty.
   (Perhaps you need to 'use' the module which defines that package first,
   or make that module available in @INC (@INC contains: /etc/perl /usr/local/lib/x86_64-linux-gnu/perl/5.22.1 /usr/local/share/perl/5.22.1 /usr/lib/x86_64-linux-gnu/perl5/5.22 /usr/share/perl5 /usr/lib/x86_64-linux-gnu/perl/5.22 /usr/share/perl/5.22 /usr/local/lib/site_perl /usr/lib/x86_64-linux-gnu/perl-base .).
at DemeterBuilder.pm line 6.
BEGIN failed--compilation aborted at DemeterBuilder.pm line 6.
Compilation failed in require at Build.PL line 29.
BEGIN failed--compilation aborted at Build.PL line 29.

You have (at least) three options, any of which should work just fine:

  1. Use your system's package manager to install Module::Build. On Debian and Ubuntu systems, the package is called libmodule-build-perl.
  2. Use one of the standard tools to install Module::Build from source. For example, the command cpanm -S Module::Build will download, test, and install it, prompting you for a sudo password for the installation step. Alternately, you can run the cpan program, then do install Module::Build at the cpan prompt.
  3. Follow the instructions given here to build and install the copy of Module::Build that comes packaged with DEMETER.

Once one of those is done, you should have no problem proceeding with the installation.

Build DEMETER and its dependencies

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. Grab the latest Ifeffit source code from its github site.

  2. cd into the source directory

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

    sudo ./PGPLOT_install

  4. Do ./configure

  5. Do make

  6. Do sudo 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 and libncurses5-dev
  3. libpng3 and libpng3-dev
  4. libgif4
  5. libwxgtk2.8-dev (the version number, here 2.8, might be different in your distribution)

Step 2: Download a copy of Demeter

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

To download a copy of the source code, do one of the following:

  1. Use git to clone a copy. You will need to have git, which is a version control system used to manage the Demeter source code, installed on your computer. On Ubuntu machines, the package is called “git-core”. At the command line, do:

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

    then follow along with developments by doing

    git pull

    to download future modifications to the code.

  2. Grab the most recent archive file containing the DEMETER source code. Go to https://github.com/bruceravel/demeter and click on one of the download buttons near the top of the page to get either the tar.gz or .zip archive file containing the entire source code.

Cloning a copy with git is far more convenient as it allows you to keep up more easily as Demeter evolves.

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 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

Now, 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 your computer, answer “no” to the question about Graphics::GnuplotIF. But, really, use Gnuplot. Your DEMETER experience will be much better.)

In my experience, most dependencies install smoothly on recent Linux installations. They also all install smoothly under Strawberry Perl on Windows. If there are any failures, you will need to track down the problems and fix them in order to proceed.

Step 3c: Dealing with failed dependencies

Demeter has a lot of dependencies on other Perl modules. The ./Build installdeps step downloads each of the approximately 40 modules that Demeter needs. Each of those modules has its own tree of dependencies. All in all, a couple hundred packages get downloaded, built, and installed when do the ./Build installdeps step.

Sometimes, a few of these fail. This is not a disaster. In most cases, the problem can be dispatched easily. See this post to the IFEFFIT Mailing List about some strategies for dealing with failed builds of dependencies.

“PDL::Stats” presents a special challange. There is a known bug in “PDL::Stats” that is not yet fixed (at the time of this writing, Aug. 2015) in the upstream source. If possible, use your system's pre-built package (the Debian package is called “libpdl-stats-perl”).

If you cannot use a package and you are unable to build L<PDL::Stats>, as discussed in this mailing list thread, do the following:

  1. Download PDL::Stats from https://metacpan.org/pod/PDL::Stats

  2. Unpack the tarball and cd into its directory

  3. Copy the file glm.patch from Demeter's tools/ directory into the PDL:Stats top directory

  4. Apply the patch

    patch -p0 < glm.patch

  5. Build and install PDL::Stats

    perl Makefile.PL
make
make test
make install

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 includes components (e.g. “Xray::Absorption” and “STAR::Parser”) that once had 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

Special cases

A Demeter program fails, complaining that Carp::Clan is missing

This may happen after an upgrade. A recent version of one of Demeter's dependencies (MooseX::Types) depends on (Carp::Clan) but may not be installed after an OS upgrade. If this happens, either use CPAN to install Carp::Clan:

sudo cpanm Carp::Clan

or install the debian package libcarp-clan-perl.

Installing Demeter without root privileges

In step 1, replace the command

./configure

with

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

Here you need to specify a location in your own disk space 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, which can be done by adding this to your .bashrc file:

export PATH=$PATH:$HOME/local/bin/

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 https://metacpan.org/pod/local::lib and download the latest version of the “local::lib” module. Unpack it and cd into the newly created directory. (See this mailing list post for an explanation of why you want to use “local::lib”.)

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 the instructions at https://metacpan.org/pod/local::lib#The-bootstrapping-technique.

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 (that is, type the command as given, but without sudo). The whole point of installing “local::lib” is to be able to install all of this software in your own disk space 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.

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

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

  2. To use cpan:, first, fire up C<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

cpan should now work properly through the proxy.

Installing and using source code on Windows

You can easily follow DEMETER's developments or hack on DEMETER's source code on a Windows machine.

  1. Install the most recent Windows installer package from http://bruceravel.github.io/demeter.
  2. Next install L<git|http://git-scm.com/> on your computer.
  3. Proceed with Steps 2 and 4 from the instructions above. This will keep you up to date with the latest developments.

WxPerl GUIs on KDE

WxPerl on linux uses GTK. This means that the GUIs may not match your desktop if you are a KDE user. The solution to this "problem" is to install the tool for configuring GTK applications under KDE. On Ubuntu, this package is called “kde-config-gtk”. You will then want to install the “gtk2-engines” package. There are several GTK2 themes with names like “gtk2-engines-clearlooks” that you can also install. The key to making ATHENA and ARTEMIS look like the rest of your desktop is to synchronize your choice of KDE and GTK2 themes. I use KDE's “cleanlooks” theme with GTK2's “clearlooks” theme. “Oxygen” is another possibility.

Upon upgrading to Ubuntu 12.04 on one of my computers, I observed frequent crashes in ARTEMIS related to drag and drop (e.g. when importing paths from a FEFF calculation). This turned out to be related to a problem with the “oxygen-gtk” GTK2 theme. Changing the GTK2 theme to any other choice made the problem go away.

Miscellany

Building the Ifeffit SWIG wrapper

(The mess that is) Scientific Linux 5

See http://cars9.uchicago.edu/ifeffit/Demeter/ScientificLinux>

Have the problems with perl and gnuplot described on that page been fixed in SL 6?

Building Ifeffit on Windows with MinGW and Strawberry



DEMETER is copyright © 2009-2016 Bruce Ravel – This document is copyright © 2016 Bruce Ravel

This document is licensed under The Creative Commons Attribution-ShareAlike License.

If DEMETER and this document are useful to you, please consider supporting The Creative Commons.