waveform80/demeter_nonroot_1204.rst

## demeter_nonroot_1204.rst

      
    Raw
  

              demeter_nonroot_1204.rst
            
          
    Demeter Installation

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

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

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

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'

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/