.. Athena document is copyright 2016 Bruce Ravel and released under The Creative Commons Attribution-ShareAlike License http://creativecommons.org/licenses/by-sa/3.0/ Installing Demeter from source code =================================== The instructions for installing the :demeter:`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 :demeter:`ifeffit` and :program:`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 :command:`sudo`, then replace :command:`sudo` with :command:`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:`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 :quoted:`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`. :demeter:`demeter` benefits *tremendously* by having `Gnuplot `_ installed. All Linux distributions should have a package for Gnuplot. On Ubuntu, the package is called :quoted:`gnuplot`. You also likely want to install one of the GUI packages, :quoted:`gnuplot-x11` or :quoted:`gnuplot-qt`. Or you can grab the latest source code from http://gnuplot.info and install it from scratch. DEMETER's build system ---------------------- :demeter:`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:`demeter` for the first time. It means that you must take a step to prepare the build environment before actually beginning to build :demeter:`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: #. Use your system's package manager to install Module::Build. On Debian and Ubuntu systems, the package is called ``libmodule-build-perl``. #. 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. #. Follow the instructions `given here `_ to build and install the copy of Module::Build that comes packaged with :demeter:`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 :program:`gcc` and :program:`gfortran` compilers as well as a few development libraries installed on your computer #. Grab the latest Ifeffit source code from `its github site `_. #. cd into the source directory #. Run the :command:`PGPLOT_install` script. This streamlines the rather unwieldy chore of building :program:`PGPLOT`. This step will require root access to the computer. :: sudo ./PGPLOT_install #. Do :command:`./configure` #. Do :command:`make` #. Do :command:`sudo make install` On my Ubuntu machine, the following development libraries are needed to get :demeter:`ifeffit` and :program:`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. #. :file:`libx11-dev` #. :file:`libncurses5` and :file:`libncurses5-dev` #. :file:`libpng3` and :file:`libpng3-dev` #. :file:`libgif4` #. :file:`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: #. 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 :quoted:`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. #. Grab the most recent archive file containing the :demeter:`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 :file:`tar.gz` or :file:`.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:`demeter` from git (or unpacking the archive), :command:`cd` into the new subdirectory and do :: perl ./Build.PL If this is the first time you are installing :demeter:`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:`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 :quoted:`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:`demeter`. (However, if you do not have :program:`Gnuplot` on your computer, answer :quoted:`no` to the question about ``Graphics::GnuplotIF``. But, really, use :program:`Gnuplot`. Your :demeter:`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 :command:`./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 :command:`./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 :demeter:`ifeffit` Mailing List about some strategies for dealing with failed builds of dependencies. :quoted:`PDL::Stats` presents a special challange. There is a `known bug `_ in :quoted:`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 :quoted:`libpdl-stats-perl`). If you cannot use a package and you are unable to build L, as `discussed in this mailing list thread `_, do the following: #. Download PDL::Stats from https://metacpan.org/pod/PDL::Stats #. Unpack the tarball and cd into its directory #. Copy the file :file:`glm.patch` from Demeter's :file:`tools/` directory into the PDL:Stats top directory #. Apply the patch :: patch -p0 < glm.patch #. 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 :command:`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:`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:`demeter` package includes components (e.g. :quoted:`Xray::Absorption` and :quoted:`STAR::Parser`) that once had to be handled separately. :demeter:`demeter` is now one stop shopping! If any errors are reported during the :command:`./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 :file:`$HOME/local`. You will also need to put :file:`$HOME/local/bin/` in your execution path, which can be done by adding this to your :file:`.bashrc` file: :: export PATH=$PATH:$HOME/local/bin/ Even if you are installing :demeter:`demeter` without root, it is probably easier to get :demeter:`ifeffit` and :program:`PGPLOT` installed system-wide. On a Debian-based system, even better would be to install Carlo Segre's pre-built versions of :demeter:`ifeffit` and :program:`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 :quoted:`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 :quoted:`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 :quoted:`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 :quoted:`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. #. To have :program:`git` talk through the proxy, I had to do this: :: git config --global https.proxy http://192.168.1.130:3128 #. To use :program:`cpan:`, first, fire up C 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 :program:`cpan` should now work properly through the proxy. Installing and using source code on Windows ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can easily follow :demeter:`demeter`'s developments or hack on :demeter:`demeter`'s source code on a Windows machine. #. Install the most recent Windows installer package from http://bruceravel.github.io/demeter. #. Next install L on your computer. #. 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 :quoted:`kde-config-gtk`. You will then want to install the :quoted:`gtk2-engines` package. There are several GTK2 themes with names like :quoted:`gtk2-engines-clearlooks` that you can also install. The key to making :demeter:`athena` and :demeter:`artemis` look like the rest of your desktop is to synchronize your choice of KDE and GTK2 themes. I use KDE's :quoted:`cleanlooks` theme with GTK2's :quoted:`clearlooks` theme. :quoted:`Oxygen` is another possibility. Upon upgrading to Ubuntu 12.04 on one of my computers, I observed frequent crashes in :demeter:`artemis` related to drag and drop (e.g. when importing paths from a :demeter:`feff` calculation). This turned out to be related to a problem with the :quoted:`oxygen-gtk` GTK2 theme. Changing the GTK2 theme to any other choice made the problem go away. Miscellany ---------- **Building the Ifeffit SWIG wrapper** See http://cars9.uchicago.edu/ifeffit/Demeter/SwigModuleBuild **(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** I recorded my notes at https://github.com/bruceravel/demeter/blob/master/win/notes.org.