David Hughes' guide to Demeter Installation on Ubuntu

These instructions cover a non-root manual build of Bruce Ravel's Demeter package under Ubuntu 12.04. The instructions are deliberately written with a non-technical audience in mind and hence might read as somewhat patronizing for the technical reader. The main 12.04 repositories include fairly recent versions of most of the pre-requisites, allowing us to simplify the installation process somewhat.

First time build

Firstly, start a Terminal. In the sections below I'll represent the terminal prompt with $ -- don't type this when entering commands, it's simply to give you an indication of what your command line should look like. To save you typing, you can fairly easily copy and paste examples (excluding the prompt) by selecting text with your mouse and then middle clicking (the mouse-wheel on most modern mice) in the terminal where you wish to paste the selected text.

Preparing your machine

The first step is to install all the build and runtime dependencies that are available in the standard Ubuntu repositories, along with Perl's excellent local::lib system which will allow us to play around with the development version of Demeter without affecting the system Perl install:

$ sudo apt-get install build-essential git gfortran gnuplot ifeffit liblocal-lib-perl libx11-dev libncurses5-dev libpng3 libpng3-dev libgif4 libwxgtk2.8-dev

Next, make sure you're in your home directory and use local::lib to set up a local copy of Perl to play around with in  /perl5 (note that these steps will alter your  /.bashrc file to ensure that whenever you start a shell in future, it will be using the local copy of Perl in  /perl5):

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

Now we configure the Perl environment for building Demeter's dependencies. Start the CPAN tool:

$ cpan

Then, at the CPAN prompt (which looks like cpan[1]>) enter the following commands:

cpan[1]> o conf build_requires_install_policy yes
cpan[2]> o conf prerequisites_policy follow
cpan[3]> o conf commit

These simply tell the Perl build environment that we don't want to be endlessly prompted during the build of all the Demeter pre-requisites. Press Ctrl+D to quit CPAN and return to the normal terminal prompt. Next, we'll take a clone of Demeter's git repository:

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

Demeter's build environment

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.

Demeter's many dependencies

Now we attempt to build Demeter's dependencies. Firstly, change into the cloned directory and generate the script to install the dependencies:

$ cd demeter
$ perl ./Build.PL

This will probably produce a screen or two of output which on my system looked like this:

WARNING: the following files are missing in your kit:
    lib/Demeter/UI/Hephaestus/data/hephaestus.htm
Please inform the author.

Checking prerequisites...
  requires:
    !  Archive::Zip is not installed
    !  Chemistry::Elements is not installed
    !  Config::INI is not installed
    !  Const::Fast is not installed
    !  DateTime is not installed
    !  Encoding::FixLatin is not installed
    !  File::CountLines is not installed
    !  Graph is not installed
    !  Heap is not installed
    !  Math::Combinatorics is not installed
    !  Math::Derivative is not installed
    !  Math::Round is not installed
    !  Math::Spline is not installed
    !  Moose is not installed
    !  MooseX::Aliases is not installed
    !  MooseX::Singleton is not installed
    !  MooseX::StrictConstructor is not installed
    !  MooseX::Types is not installed
    !  PDL is not installed
    !  PDL::Stats is not installed
    !  Pod::POM is not installed
    !  Spreadsheet::WriteExcel is not installed
    !  Statistics::Descriptive is not installed
    !  String::Random is not installed
    !  Tree::Simple is not installed
    !  Want is not installed
  build_requires:
    !  File::Touch is not installed
    !  Image::Size is not installed
    !  PPI is not installed
    !  PPI::HTML is not installed
    !  Pod::ProjectDocs is not installed
    !  Template is not installed
  recommends:
    *  File::Monitor::Lite is not installed
    *  Graphics::GnuplotIF is not installed
    *  Term::Sk is not installed
    *  Term::Twiddle is not installed
    *  Wx is not installed

ERRORS/WARNINGS FOUND IN PREREQUISITES.  You may wish to install the versions
of the modules indicated above before proceeding with this installation

Run 'Build installdeps' to install missing prerequisites.

Created MYMETA.yml and MYMETA.json
Creating new 'Build' script for 'Demeter' version 'v0.9.13'

The list of the all the not installed items is the list of dependencies we need to install. We use the generated Build script to handle installing all these for us:

$ ./Build installdeps

Be aware that this process will produce a very large amount of terminal output. This is normal and nothing to be alarmed about (most of the output is simply the build process giving exhaustive detail of what it's running or testing or installing at that moment). However, at times the process will prompt you to ask whether you want to install something. Simply hit Enter to accept the default (which is always "yes") in such instances. The prompts will look like the following:

Install Wx? [y ]
y
Install Graphics::GnuplotIF? [y ]
y
Install File::Monitor::Lite? [y ]
y
Install Term::Twiddle? [y ]
y
Install Term::Sk? [y ]
y

These questions may pop up at the start, or after 10 minutes and several thousand lines of output in the terminal, or both! Basically, just have patience and occasionally check your terminal to see if it needs your confirmation.

During the Wx build you may find small windows appearing randomly on your desktop. This is part of the test process for the build and perfectly normal. Try and avoid doing anything with the windows - they should disappear on their own. Also, if possible, try and avoid using your desktop while this is going on. The windows may grab keyboard focus, causing you to inadvertently interfere with the test process if you're typing at the time.

Eventually, the dependencies build should complete. To make sure that all the dependencies have been installed correctly, re-run the generator script:

$ perl ./Build.PL

Dealing with failed dependencies

This time you should get output which doesn't include any not installed items. However, in my particular case for some reason Wx failed to install the first go round so I got this:

WARNING: the following files are missing in your kit:
    lib/Demeter/UI/Hephaestus/data/hephaestus.htm
Please inform the author.

Checking prerequisites...
  recommends:
    *  Wx is not installed

ERRORS/WARNINGS FOUND IN PREREQUISITES.  You may wish to install the versions
of the modules indicated above before proceeding with this installation

Run 'Build installdeps' to install missing prerequisites.

Created MYMETA.yml and MYMETA.json
Creating new 'Build' script for 'Demeter' version 'v0.9.13'

Simply re-running the installdeps process fixed this for me (skip this step if you don't see any not installed items above):

$ ./Build installdeps

Depending on the state of your machine or the distribution you are using, you might still fail to successfully build wxperl or some other package, as discussed here. If you use a distribution with a robust package manager and an extensive library of packages, it should be fine to satisfy the dependency using the system's package manager. For example, on a debian-based distribution, you could meet the requirement for wxperl by doing

~> sudo apt-get install libwx-perl

Eventually you should get the following when running Build.PL:

$ perl ./Build.PL
WARNING: the following files are missing in your kit:
    lib/Demeter/UI/Hephaestus/data/hephaestus.htm
Please inform the author.

Created MYMETA.yml and MYMETA.json
Creating new 'Build' script for 'Demeter' version 'v0.9.13'

The type of warning about files missing in the kit is not serious. It usually just means that Bruce forgot to update the MANIFEST file.

Ready to build Demeter!

At this point you're finally ready to build and install Demeter itself which is done as follows:

$ ./Build
$ ./Build test
$ ./Build install

Don't worry if a few errors crop up during the "Build test" phase; you are building a development copy of the software and inevitably these are somewhat less stable than "proper" releases. However, if you do happen to notice something new has failed since the last time you tested Demeter, you may want to inform the author. You can generate a copy of the test output simply by copying and pasting (as described at the beginning) or with the following command line which will place the output in test_errors.txt in your home directory:

$ ./Build test | tee ~/test_errors.txt

Please ensure when informing the author of any test issues that you include a copy of the test output, and preferably other details such as the date on which you last updated your clone of the Demeter repository (which may help identify the change that caused the failure) and the version of the OS you're running.

Once "Build install" has completed you should be able to run applications within the Demeter package as follows:

$ dathena
$ dartemis
$ dhephaestus
$ denergy

... and so on

Updating your installation

At some point you may learn that some new feature or existing bug has been fixed, and wish to update your installation from the latest development copy. To do so (you will be relieved to hear!) is considerably simpler than the initial install.

Firstly, start up a terminal and update your copy of the Demeter repository:

$ cd demeter
$ git pull

Next, ensure that your pre-requisites are still fine (it's possible that new features may pull in additional pre-requisites):

$ perl Build.PL

If your output includes any not installed lines you will need to run the installdeps command line below, but otherwise skip this step:

$ ./Build installdeps

Now rebuild, re-test, and re-install Demeter:

$ ./Build
$ ./Build test
$ ./Build install

Removing your installation

Should you ever wish to start from scratch you can completely remove your Demeter installation (and the local Perl copy) by starting a terminal and entering the following commands (be aware these will not prompt to make sure you really want to delete your installation - they will simply delete it - hook, line, and sinker):

$ rm -fr ~/demeter/
$ rm -fr ~/perl5/

Using Gnuplot with Demeter

At build time, Demeter tries to figure out which gnuplot terminal to use by default. It will query a gnuplot session to see if either the wxt or qt terminal types is available. If not, it will fall back to the X11 terminal.

That said, the X11 terminal is rather ugly. Because Debian/Ubuntu support for the wxt terminal may be spotty, you might want to recompile gnuplot from source. User Patrick Browne offers this recipe:

~> sudo apt-get install libwxgtk2.8-dev libgtk2.0-dev
~> wget "http://downloads.sourceforge.net/project/gnuplot/gnuplot/5.0.4/gnuplot-5.0.4.tar.gz"
~> tar xzf gnuplot-5.0.4.tar.gz  ## or whatever version number is current
~> cd gnuplot-5.0.4
~> env TERMLIBS="-lX11" ./configure
~> make
~> sudo make install

After that, use the wxt terminal by setting it in either ATHENA or ARTEMIS.

In ATHENA: select Preferences from the main menu, then click open gnuplot and click on terminal. Replace "x11" by "wxt", click "Apply and Save".

In ARTEMIS: File ‣ Edit preferences, then click open gnuplot and click on terminal. Replace "x11" by "wxt", click "Apply and Save".

---

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.