Installing PDL Manually

From pdl

(Difference between revisions)
Jump to: navigation, search
(Installing Necessary and Recommended Dependencies)
(Automated Installation: Added a message telling the reader their installation is done, and split off some of the later material into its own section.)
 
(27 intermediate revisions not shown)
Line 1: Line 1:
-
==Overview==
 
-
Whereas [[Installing PDL the quick and easy way]] covers installing PDL using package management tools, here I will assume that you want to install PDL from source.  This page covers the how and why of doing just that.
 
-
 
==Why install PDL Manually?==
==Why install PDL Manually?==
-
That's a good question, and I'm glad you asked.  You might install PDL manually for a number of reasons, some of which probably include:
+
Unless you really need to have a manually installed version of PDL, we highly recommend that you [[Installing PDL the quick and easy way | install PDL the quick and easy way]]. The manual installation process still has a few wrinkles that could be ironed out a bit better, so if you can get away with your OS's distribution of PDL, it would probably make your life better.
-
# you have an operating system or flavor of Linux that does not contain a pre-packaged version of PDL, or which contains an old version of PDL;
+
 
-
# you want to test the new PDL release on some of your scripts before installing it;
+
However, you may want to install PDL manually, despite what I just said.  Some reasons include:
-
# you want to contribute to the development of PDL (thanks!);
+
# you have an operating system or flavor of Linux that does not contain a pre-packaged version of PDL
-
# you're trying to debug problems with an installation or you want your own, customized build of PDL, and the manual installation gives you more diagnostics and control
+
# your OS's pre-packaged version of PDL is rather old and has bugs that newer versions of PDL have fixed,
 +
# it's fun to be on the cutting-edge of development,
 +
# you want to contribute to the development of PDL, or
 +
# you're trying to debug problems with an automated installation or you want your own, customized build of PDL.  (The manual installation gives you more diagnostics and control for these circumstances.)
 +
 
Whatever your reasons, this page should get you through the configuration and installation phase of installing PDL manually.
Whatever your reasons, this page should get you through the configuration and installation phase of installing PDL manually.
-
==Installing Necessary and Recommended Dependencies==
+
==Installing Necessary and Recommended External Dependencies==
PDL can be very tricky to install, and the primary reason it gives such trouble is because it has a number of dependencies.  Although the development team is working towards automating the whole installation process, we're not there yet.  So, this portion of this guide should tell you which dependencies you'll need to install to get a nicely running PDL.
PDL can be very tricky to install, and the primary reason it gives such trouble is because it has a number of dependencies.  Although the development team is working towards automating the whole installation process, we're not there yet.  So, this portion of this guide should tell you which dependencies you'll need to install to get a nicely running PDL.
Line 22: Line 23:
  Ubuntu:
  Ubuntu:
-
  sudo apt-get install freeglut3-dev libgsl0-dev libnetpbm10-dev libplplot-dev pgplot5
+
  sudo apt-get install libxi-dev libxmu-dev freeglut3-dev libgsl0-dev libnetpbm10-dev libplplot-dev \
-
 
+
      pgplot5 libterm-readline-perl-perl
 +
  Ubuntu Dapper:
  Ubuntu Dapper:
-
  sudo apt-get install freeglut3-dev libgsl0-dev libnetpbm10-dev libplplot-dev pgplot5 slatec-dev
+
  sudo apt-get install libxi-dev libxmu-dev freeglut3-dev libgsl0-dev libnetpbm10-dev libplplot-dev \
 +
      pgplot5 slatec-dev libterm-readline-perl-perl
 +
 
 +
===X Development Files===
 +
If you use the X window system on an OS that primarily distributes precompiled libraries, you will likely need to install the X development libraries in order to get OpenGL to work.  (This is arguably the most annoying part of the process for me.)
 +
 
 +
Ubuntu:
 +
#> sudo apt-get install libxi-dev libxmu-dev
===OpenGL, FreeGLUT===
===OpenGL, FreeGLUT===
Line 63: Line 72:
  #> sudo apt-get install slatec-dev
  #> sudo apt-get install slatec-dev
-
==Acquiring and Installing PDL==
+
===Term-Readline===
-
When it comes to acquiring the source code for PDL, you have at least three options: you can install PDL through the CPAN shell, you can manually download the files from Sourceforge, or you can pull the sources from the GIT repositoryBefore running the actual installation, be sure you have installed the dependencies (which are discussed below at the moment).  If you have never installed PDL before, we highly recommend that you install PDL using CPAN because that will automate the installation of a few important Perl dependencies.  Once you have done the CPAN-based installation once, you can use Sourceforge or Git if you want even more up-to-date editions of PDL than you can get through CPAN.
+
You'll want this for a nice perldl command-lineIt will also enable the command-line history of the cpan shell, if that's not working for you.
-
===CPAN===
+
Ubuntu
 +
#> sudo apt-get install libterm-readline-perl-perl
 +
 +
Arch Linux
 +
#> sudo pacman -S perl-term-readline
 +
 
 +
==Installing Necessary Perl Dependencies==
 +
PDL has a few Perl dependencies.  If you plan on installing PDL straight from Sourceforge or GIT without having performed a CPAN or pre-packaged install, you will want to install these first.  In principle, if you install PDL using CPAN, these dependencies are supposed to be resolved and installed for you.  I have run into trouble with some sort of never-ending loop, so I recommend installing the PDL dependencies before installing PDL, even on CPAN.
 +
 
 +
===Firing up CPAN===
Begin by firing up the CPAN shell.  You'll want to do this with root/administrative privileges because it will eventually install files into some of your system folders.  To start CPAN, issue a command like one of these:
Begin by firing up the CPAN shell.  You'll want to do this with root/administrative privileges because it will eventually install files into some of your system folders.  To start CPAN, issue a command like one of these:
-
 
  $> cpan      # as root/administrator
  $> cpan      # as root/administrator
  $> sudo cpan  # if your systems uses sudo, like with Ubuntu
  $> sudo cpan  # if your systems uses sudo, like with Ubuntu
-
====Side Note: Starting CPAN for the first time====
+
===Side Note: Starting CPAN for the first time===
-
 
+
If you have never used CPAN before, it will begin with a rather verbose message, finishing with a question, like this:
If you have never used CPAN before, it will begin with a rather verbose message, finishing with a question, like this:
-
<code>
+
CPAN is the world-wide archive of perl resources. It consists of about
-
CPAN is the world-wide archive of perl resources. It consists of about
+
300 sites that all replicate the same contents around the globe. Many
-
300 sites that all replicate the same contents around the globe. Many
+
countries have at least one CPAN site already. The resources found on
-
countries have at least one CPAN site already. The resources found on
+
CPAN are easily accessible with the CPAN.pm module. If you want to use
-
CPAN are easily accessible with the CPAN.pm module. If you want to use
+
CPAN.pm, lots of things have to be configured. Fortunately, most of
-
CPAN.pm, lots of things have to be configured. Fortunately, most of
+
them can be determined automatically. If you prefer the automatic
-
them can be determined automatically. If you prefer the automatic
+
configuration, answer 'yes' below.
-
configuration, answer 'yes' below.
+
-
 
+
If you prefer to enter a dialog instead, you can answer 'no' to this
-
If you prefer to enter a dialog instead, you can answer 'no' to this
+
question and I'll let you configure in small steps one thing after the
-
question and I'll let you configure in small steps one thing after the
+
other. (Note: you can revisit this dialog anytime later by typing 'o
-
other. (Note: you can revisit this dialog anytime later by typing 'o
+
conf init' at the cpan prompt.)
-
conf init' at the cpan prompt.)
+
Would you like me to configure as much as possible automatically? [yes]
-
Would you like me to configure as much as possible automatically? [yes]
+
-
</code>
+
Just hit ENTER (which makes the default selection of '''yes'''). Don't say '''no''' unless you actually know what you're doing (in which case you wouldn't need to read this section anyway).  If you go for automatic configuration - which we highly recommend - volumes of text will pass by on the screen and you will hopefully be presented with the following prompt:
Just hit ENTER (which makes the default selection of '''yes'''). Don't say '''no''' unless you actually know what you're doing (in which case you wouldn't need to read this section anyway).  If you go for automatic configuration - which we highly recommend - volumes of text will pass by on the screen and you will hopefully be presented with the following prompt:
Line 98: Line 112:
Now we are ready to issue our installation commands.
Now we are ready to issue our installation commands.
-
====Get POGL====
+
===Installing Inline===
-
 
+
Inline is a Perl family of modules that allows you to include code from other languages into your Perl scriptsYou may never use it, but if you ever mess around with PDL::PP, you will probably start by playing around with Inline::PdlppTo install Inline, say:
-
We won't begin immediately with PDL because first we need to get Perl's OpenGL module, aka POGLFor many modules, it is sufficient to tell CPAN to '''install''' the module, but OpenGL can run into some tricky snags and it'll be easier to take it one step at a timeSo issue this command at the cpan prompt:
+
-
  cpan[1]> get OpenGL
+
  cpan> install Inline
-
You will see a few lines of text, ending with this question:
+
If this is the first download you've issued since starting CPAN, you will see a few lines of text, ending with this question:
  Is it OK to try to connect to the Internet? [yes]
  Is it OK to try to connect to the Internet? [yes]
-
CPAN needs to connect to the internet to get the latest repository list.  Hit ENTER (or type 'yes' and ENTER).
+
CPAN needs to get the latest repository list.  Before you hit ENTER, check the preceding text for any notifications about a new CPAN.  It won't change your answer to this question, but you'll want to remember it for the next section.
-
====Side Note: Updating CPAN====
+
So, hit ENTER to allow CPAN to connect to the internet.  After downloading files for Inline, it will ask if you want to install Inline::C.  You don't have to install Inline::C (Inline::Pdlpp will be installed when you install PDL and in principle that's all you will need for PDL stuff).  If you do install Inline::C, you will be asked to install Parse::RecDescent, too.
-
At this point, if you see a message like this:
+
===Side Note: Updating CPAN===
 +
Now that Inline is installed, if you saw a message like this:
  New CPAN.pm version (v1.9402) available.
  New CPAN.pm version (v1.9402) available.
Line 123: Line 137:
And now you should be running the latest CPAN module.
And now you should be running the latest CPAN module.
-
====Make POGL====
+
===Installing Astro::FITS::Header===
 +
Obviously, FITS is a file format used by astronomers.  It's probably not necessary for your work unless you are an astronomer.  It may seem like a strange requirement, but it is helpful for at least some of our users and points back to PDL's roots in astronomy.
 +
 
 +
cpan> install Astro::FITS::Header
 +
 
 +
===Installing POGL===
 +
POGL stands for Perl's OpenGL module.  For many modules, it is sufficient to tell CPAN to '''install''' the module, but OpenGL can run into some tricky snags and it'll be easier to take it one step at a time.  So issue this command at the cpan prompt:
 +
 
 +
cpan> get OpenGL
 +
 
After getting the source code for POGL, we'll want to run the '''make''' command by issuing this:
After getting the source code for POGL, we'll want to run the '''make''' command by issuing this:
  cpan> make OpenGL
  cpan> make OpenGL
-
If all goes well, you will have Perl's OpenGL bindings compiled and you will be ready to move on to the next stage. However, if you get errors, chances are pretty good that you don't have the OpenGL libraries installed on your system.  Go to the section on this page about external dependencies with directions for installing OpenGL.  Leave the CPAN shell open - you'll want to come back to it later.  After you've installed OpenGL on your system, try to reissue the '''make OpenGL''' command again in the CPAN shell.  If you still have trouble, you should email the PDL mailing list (see the bottom of this page for instructions).
+
You will know that everything is working if you see text that looks like this:
 +
 
 +
... (text not shown) ...
 +
Checking if your kit is complete...
 +
Looks good
 +
Writing Makefile for OpenGL
 +
...
 +
cc -c  -I/usr/include -I/usr/local/include -D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fno-strict-aliasing -pipe
 +
-I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -O2 -g  -DVERSION=\"0.61\"
 +
-DXS_VERSION=\"0.61\" -fPIC "-I/usr/lib/perl/5.10/CORE"  -DHAVE_VER -DHAVE_FREEGLUT -DHAVE_GL -DHAVE_GLU
 +
-DHAVE_GLUT -DHAVE_GLX -DHAVE_FREEGLUT -DHAVE_FREEGLUT_H -DGL_GLEXT_LEGACY OpenGL.c
 +
...
 +
 
 +
That cc command is your compiler.  Your computer may appear to hang after one or more of these commands, but don't worry - it's just busy compiling the OpenGL bindings.  It should be done in a couple of minutes.  If all goes well, you will have Perl's OpenGL bindings compiled and you will be ready to move on to the next stage.
 +
 
 +
However, if you get errors (and you get your cpan prompt back in a matter of seconds), chances are pretty good that you don't have the OpenGL libraries or one of their dependencies installed on your system.  [[#Installing Necessary and Recommended Dependencies | Check the external dependencies above]].  If you still have trouble, [[#Send an Email to the PDL Mailing List |  send an email to the PDL mailing list]].
-
====Test POGL====
 
You've compiled POGL, but you haven't tested or installed it (yet).  To test POGL, issue this command:
You've compiled POGL, but you haven't tested or installed it (yet).  To test POGL, issue this command:
  cpan> test OpenGL
  cpan> test OpenGL
-
If tests pass,  
+
At some point, if all goes well, you'll have a graphic of a floating tea-pot.  You'll be able to play around with the graphic using your keyboard, using these commands:
-
====Install POGL====
+
Hold down arrow keys to rotate, 'r' to reverse, 's' to stop.
 +
Page up/down will move cube away from/towards camera.
 +
Use first letter of shown display mode settings to alter.
 +
Press 'g' to toggle fullscreen mode (not supported on all platforms).
 +
Press 'c' to capture/save a RGBA targa file.
 +
'q' or [Esc] to quit; OpenGL window must have focus for input.
 +
 
 +
Be sure to type '''q''' when you're done.  Finally, you should install OpenGL:
  cpan> install OpenGL
  cpan> install OpenGL
-
More instructions to follow...
+
Again, if you have any trouble with this, [[#Send an Email to the PDL Mailing List | send an email to the PDL mailing list]].
 +
 
 +
==Acquiring and Installing PDL==
 +
When it comes to acquiring the source code for PDL, you have at least three options: you can install PDL through the CPAN shell, you can manually download the files from Sourceforge, or you can pull the sources from the GIT repository.
 +
 
 +
===CPAN===
 +
Start CPAN as discussed in [[#Firing up CPAN]].  Your next step depends on how much work you want CPAN to do for you.
 +
 
 +
====Automated Installation====
 +
You can ask CPAN to simply install PDL.  If you have all of the dependencies as discussed above, this should run smoothly:
 +
cpan> install PDL
 +
 
 +
This should take many minutes (about 10 minutes for a 1.9 GHz, 1 GB RAM) and a huge volume of text will pass by.  If you watch closely, you'll see various warnings during the compilation phase.  While warnings mean that our code could be cleaned up, they are OK from the standpoint of installation.  You will know that everything went well if the tail of the text looks something like this (possibly without the YAML warning):
 +
 
 +
Making HTML docs...
 +
 +
  CHM/PDL-2.4.5.tar.gz
 +
  /usr/bin/make install  -- OK
 +
Warning (usually harmless): 'YAML' not installed, will not store persistent state
 +
 +
cpan[##]>
 +
 
 +
If you see this then you're good to go!  If you simply want to install PDL then you're done.  However, if you want more details, you run into trouble, or you want to tweak your PDL install, continue reading.
 +
 
 +
===Automated Installation Explained===
 +
CPAN's install command will try to do these four steps:
 +
# download PDL's tarball from the CPAN repository
 +
# set up and compile PDL
 +
# test PDL against the test suite
 +
# install PDL
 +
 
 +
If it gets stuck at any point, it will not perform any of the other steps unless you explicitly force it to do so.  I sometimes run into trouble with the simple '''install''' command.  If you run into trouble, you can always start over by issuing the '''clean''' command:
 +
cpan> clean PDL
 +
 
 +
If PDL does not install because one or two tests did not pass, chances are pretty good that PDL will still work for most of your purposes.  As such, you can force PDL to be installed if you think it will be OK by issuing this command:
 +
cpan> force install PDL
 +
 
 +
If the '''install PDL''' command above does not work and you don't want to force the installation, jump into the current state of the installation (as discussed in the next section) and continue below in the section, [[#Finishing a source-code installation]]
 +
 
 +
====Manipulating the State of the Installation====
 +
CPAN's '''look''' command is very helpful.  When you call it, you will be put into the temporary directory that holds the current state of the installation.  This way, if you run into trouble, you can drop into the current installation state and poke around to figure out what might be giving you trouble.  This also allows you to tweak perldl.conf before moving forward with the installation process.
 +
 
 +
The command you want is this:
 +
cpan> look PDL
 +
 
 +
Upon issuing that command, your screen will give you output that looks similar to this:
 +
Running look for module 'PDL'
 +
 +
Trying to open a subshell in the build directory...
 +
Working directory is /home/david/.cpan/build/PDL-2.4.5-8UIzOx
 +
root@arch:~/.cpan/build/PDL-2.4.5-8UIzOx#
 +
 
 +
The particular folder (in this case PDL-2.4.5-8UIzOx) may be different for you, but the point is that this command will put you into the current state of the installation.  When you are all done, type '''exit''' and you will return to the CPAN shell.
 +
 
 +
====Tweaked CPAN Installation====
 +
If you intend to tweak your PDL installation, issue these commands
 +
 +
cpan> get PDL
 +
cpan> look PDL      # this will put you in a shell, at which point you should tweak perldl.conf
 +
cpan> install PDL
 +
For instructions on tweaking the configuration file, see [[#Tweaking the perldl.conf file]] below.
===Sourceforge===
===Sourceforge===
Line 149: Line 253:
  tar -xzf PDL-2.4.5.tar.gz
  tar -xzf PDL-2.4.5.tar.gz
-
This will create a folder called PDL-2.4.5 in your current directory.  Change into the directory and continue below with [[GIT and Sourceforge concluding steps]].
+
This will create a folder called PDL-2.4.5 in your current directory.  Change into the directory and continue below with [[#Tweaking the perldl.conf file]] if you care to do that, or [[#Finishing a source-code installation]].
===GIT===
===GIT===
Line 155: Line 259:
# Install GIT on your system, if you don't already have it.
# Install GIT on your system, if you don't already have it.
# Open a prompt and cd into whatever directory you would use for these sorts of projects.  For example, on my machine I keep code bases that I want to hold onto in the folder /home/david/packages/
# Open a prompt and cd into whatever directory you would use for these sorts of projects.  For example, on my machine I keep code bases that I want to hold onto in the folder /home/david/packages/
-
# Run the command: <code>git clone git://pdl.git.sourceforge.net/gitroot/pdl/pdl PDL</code>
+
# Run this command
-
Then continue with the next section
+
git clone git://pdl.git.sourceforge.net/gitroot/pdl/pdl PDL
 +
Continue below with [[#Tweaking the perldl.conf file]] if you care to do that, or [[#Finishing a source-code installation]].
-
===GIT and Sourceforge Concluding Steps===
+
===Tweaking the perldl.conf file===
-
At this point, I will proceed with a basic installation processYou can get much more detailed installation options by looking at the INSTALL file in the source code that you have just downloaded.  If you want to tweak the compilation process, have a look at perldl.conf.
+
This should be documented hereHowever, the file itself is fairly well self-documented, so give it a read and see if anything stands out.  If in doubt, [[# Send an Email to the PDL Mailing List]].
-
<code>perl Makefile.PL</code>
+
===Finishing a source-code installation===
 +
At this point, I will proceed with a basic installation process. You can get much more detailed installation options by looking at the INSTALL file in the source code that you have just downloaded.  If you want to tweak the compilation process, have a look at perldl.conf (discussed in the previous section).
-
This command will spit out lots of lines saying, <code>writing Makefile for ...</code>.  The most important part of this step is to check for anything that says, "Not building..." or "Will skip...", which indicate either that you've told perldl.conf to skip that part or you don't have a dependency installed.  For example, the first time I ran this I was told my PDL wouldn't have GSL support or FFTW.  Skip down to the Dependencies section for details on how to fix that.  Install whatever dependencies you think you need, tweak the perldl.conf file, and run it again.  Once everything seems to be working the way you want run the makefile:
+
perl Makefile.PL
-
<code>make</code>
+
This command will spit out lots of lines saying, <code>writing Makefile for ...</code>.  The most important part of this step is to check for anything that says, "Not building..." or "Will skip...", which indicate either that you've told perldl.conf to skip that part or you don't have a dependency installed.  For example, the first time I ran this I was told my PDL wouldn't have GSL support or FFTW.  If you want one of these skipped capabilities, go back up to the [[#Installing Necessary and Recommended External Dependencies | dependencies]] section for information on how to fix that.  Install whatever dependencies you think you need, tweak the perldl.conf file, and run it again.  Once everything seems to be working the way you want run the makefile:
 +
 
 +
make
This step will probably take a while.  You may get many warnings, but as long as you get no errors, you can continue.  When it's finished, assuming all went well, run
This step will probably take a while.  You may get many warnings, but as long as you get no errors, you can continue.  When it's finished, assuming all went well, run
-
<code>make test</code>
+
make test
This will also take some time.  The program should present a summary when it's done, and if any particular test files gave trouble, you can run them separately with  
This will also take some time.  The program should present a summary when it's done, and if any particular test files gave trouble, you can run them separately with  
-
<code>prove -vb t/test_file.t</code>
+
prove -vb t/test_file.t
Doing so will give you more precise info to send to the mailing list when you run into trouble.  Once all the tests pass, or you've convinced yourself it's OK that some have not passed, build the help documentation database by issuing:
Doing so will give you more precise info to send to the mailing list when you run into trouble.  Once all the tests pass, or you've convinced yourself it's OK that some have not passed, build the help documentation database by issuing:
-
<code>make doctest</code>
+
make doctest
Once that's finished, test the shell with this command:
Once that's finished, test the shell with this command:
-
<code>perl -Mblib perldl</code>
+
perl -Mblib perldl
-
While in the shell, you can check any documentation by typing <code>help readfraw</code>, or similarly for the function or item you want to know more about.  Finally, once you've convinced yourself it's all working, run as root (or using sudo):
+
While in the shell, you can check any documentation by typing
 +
help readfraw
 +
or similarly for the function or item you want to know more about.  Finally, once you've convinced yourself it's all working, run as root (or using sudo):
-
<code>make install</code>
+
make install
And you should be all set!
And you should be all set!
-
 
-
==Dependencies==
 
-
PDL has a number of dependencies that you should be aware of.  Some are required for PDL to compile and install; others are simply useful parts to have working.  Either way, the most accurate and up-to-date listing of the dependencies can be found in the DEPENDENCIES file, which is in the root of the GIT repository or the source tarball.
 
-
 
-
The easiest way to ensure that your Perl dependencies work is to issue this command (as root or using sudo) at your prompt:
 
-
 
-
<code>cpan install PDL</code>
 
-
 
-
If <code>cpan</code> is not an executable on your system, try this instead (again with root privileges):
 
-
 
-
<code>perl -MCPAN -e shell
 
-
cpan&gt; install PDL</code>
 
-
 
-
So... at some point I should discuss all the dependencies of the project, but for now, just check the DEPENDENCIES file.  If in doubt, you can find it online at [http://pdl.git.sourceforge.net/git/gitweb.cgi?p=pdl/pdl;a=tree PDL's GIT repository browser]; click on the DEPENDENCIES file to see what it says.
 
==Running into Trouble==
==Running into Trouble==
Line 211: Line 307:
First, make sure that what you see with this command are in fact errors.  You will often get output saying something like, <code>Not building...</code> or <code>Will skip build of...</code>.  These are not errors: you should be able to get PDL to build and install despite these warnings.
First, make sure that what you see with this command are in fact errors.  You will often get output saying something like, <code>Not building...</code> or <code>Will skip build of...</code>.  These are not errors: you should be able to get PDL to build and install despite these warnings.
-
If you do run into an error, or if you get a warning about a module that you want, then your problem is almost surely a dependency problem, or there's a bug in the makefile.  Check the [[#Dependencies]] section (above). If everything looks right but you're still having trouble, [[#Send an Email to the PDL Mailing List]].
+
If you do run into an error, or if you get a warning about a module that you want, then your problem is almost surely a dependency problem, or there's a bug in the makefile.  Check the [[#Installing Necessary and Recommended External Dependencies | dependencies]] section (above). If everything looks right but you're still having trouble, [[#Send an Email to the PDL Mailing List]].
===Problems with make===
===Problems with make===
Line 231: Line 327:
==Send an Email to the PDL Mailing List==
==Send an Email to the PDL Mailing List==
 +
If you run into trouble and can't find a solution here, try sending an email to the PDL mailing list.  I will give a somewhat cryptic form in order to prevent spam - read it and figure out how to spell the addres:
 +
 +
perldl at something.hawaii.edu
 +
replace 'something' with 'jach' (not jack)

Current revision as of 14:40, 3 December 2009

Contents

Why install PDL Manually?

Unless you really need to have a manually installed version of PDL, we highly recommend that you install PDL the quick and easy way. The manual installation process still has a few wrinkles that could be ironed out a bit better, so if you can get away with your OS's distribution of PDL, it would probably make your life better.

However, you may want to install PDL manually, despite what I just said. Some reasons include:

  1. you have an operating system or flavor of Linux that does not contain a pre-packaged version of PDL
  2. your OS's pre-packaged version of PDL is rather old and has bugs that newer versions of PDL have fixed,
  3. it's fun to be on the cutting-edge of development,
  4. you want to contribute to the development of PDL, or
  5. you're trying to debug problems with an automated installation or you want your own, customized build of PDL. (The manual installation gives you more diagnostics and control for these circumstances.)

Whatever your reasons, this page should get you through the configuration and installation phase of installing PDL manually.

Installing Necessary and Recommended External Dependencies

PDL can be very tricky to install, and the primary reason it gives such trouble is because it has a number of dependencies. Although the development team is working towards automating the whole installation process, we're not there yet. So, this portion of this guide should tell you which dependencies you'll need to install to get a nicely running PDL.

You can find the full list of dependencies in the DEPENDENCIES file in the root of the PDL tarball. To see this file without downloading and unwrapping that tarball, take a look at the DEPENDENCIES file in PDL's GIT repository.

At the moment, only OpenGL is required, but many are recommended. In what follows, we try to give instructions for installing the necessary libraries on your OS. If yours is not listed, we would love to add it. Please send a list of installation instructions to the PDL mailing list. Thanks!

All Dependencies

Each dependency is discussed below, but here's a single command (or set of commands) to get them all installed:

Ubuntu:
sudo apt-get install libxi-dev libxmu-dev freeglut3-dev libgsl0-dev libnetpbm10-dev libplplot-dev \
      pgplot5 libterm-readline-perl-perl

Ubuntu Dapper:
sudo apt-get install libxi-dev libxmu-dev freeglut3-dev libgsl0-dev libnetpbm10-dev libplplot-dev \
      pgplot5 slatec-dev libterm-readline-perl-perl

X Development Files

If you use the X window system on an OS that primarily distributes precompiled libraries, you will likely need to install the X development libraries in order to get OpenGL to work. (This is arguably the most annoying part of the process for me.)

Ubuntu:
#> sudo apt-get install libxi-dev libxmu-dev

OpenGL, FreeGLUT

PDL can perform 3D visualization with the TriD package, which requires OpenGL. Technically, PDL doesn't explicitly require OpenGL, but it does depend on POGL (Perl's OpenGL), which does depend on OpenGL.

Ubuntu:
#> sudo apt-get install freeglut3-dev

GSL

GSL provides a complete scientific numerical library. PDL does not currently implement wrappers for all of GSL's functionality, but it's a goal of ours, and the stuff that is implemented is handy and highly recommended. Here's how to install GSL for various operating systems.

Ubuntu:
#> sudo apt-get install libgsl0-dev

Netpbm

Netpbm is useful for converting between image formats. If you can't find installation instructions for you OS here, you can hopefully find them at their Sourceforge project page: http://netpbm.sourceforge.net/

Ubuntu:
#> sudo apt-get install libnetpbm10-dev

PLplot

PDL has two (three if you include OpenGL, four if you consider SDL, five if you count Karma) different libraries for visualizing your data. PLplot is a well written and currently supported library written in C.

Ubuntu:
#> sudo apt-get install libplplot-dev

PGPLOT

PGPLOT is a fortran-based plotting library that has gotten a lot of use with PDL. It has a well-developed interface for PDL, so if you have a fortran compiler or can get your hands on a pre-compiled copy, it is a great way to graph your data.

Ubuntu
#> sudo apt-get install pgplot5

Slatec

Slatec is an ancient (circa '95) fortran library for matrix operations and general math. However, it is well tested and fast.

Ubuntu Dapper
#> sudo apt-get install slatec-dev

Term-Readline

You'll want this for a nice perldl command-line. It will also enable the command-line history of the cpan shell, if that's not working for you.

Ubuntu
#> sudo apt-get install libterm-readline-perl-perl

Arch Linux
#> sudo pacman -S perl-term-readline

Installing Necessary Perl Dependencies

PDL has a few Perl dependencies. If you plan on installing PDL straight from Sourceforge or GIT without having performed a CPAN or pre-packaged install, you will want to install these first. In principle, if you install PDL using CPAN, these dependencies are supposed to be resolved and installed for you. I have run into trouble with some sort of never-ending loop, so I recommend installing the PDL dependencies before installing PDL, even on CPAN.

Firing up CPAN

Begin by firing up the CPAN shell. You'll want to do this with root/administrative privileges because it will eventually install files into some of your system folders. To start CPAN, issue a command like one of these:

$> cpan       # as root/administrator
$> sudo cpan  # if your systems uses sudo, like with Ubuntu

Side Note: Starting CPAN for the first time

If you have never used CPAN before, it will begin with a rather verbose message, finishing with a question, like this:

CPAN is the world-wide archive of perl resources. It consists of about
300 sites that all replicate the same contents around the globe. Many
countries have at least one CPAN site already. The resources found on
CPAN are easily accessible with the CPAN.pm module. If you want to use
CPAN.pm, lots of things have to be configured. Fortunately, most of
them can be determined automatically. If you prefer the automatic
configuration, answer 'yes' below.

If you prefer to enter a dialog instead, you can answer 'no' to this
question and I'll let you configure in small steps one thing after the
other. (Note: you can revisit this dialog anytime later by typing 'o
conf init' at the cpan prompt.)
Would you like me to configure as much as possible automatically? [yes]

Just hit ENTER (which makes the default selection of yes). Don't say no unless you actually know what you're doing (in which case you wouldn't need to read this section anyway). If you go for automatic configuration - which we highly recommend - volumes of text will pass by on the screen and you will hopefully be presented with the following prompt:

cpan[1]> 

Now we are ready to issue our installation commands.

Installing Inline

Inline is a Perl family of modules that allows you to include code from other languages into your Perl scripts. You may never use it, but if you ever mess around with PDL::PP, you will probably start by playing around with Inline::Pdlpp. To install Inline, say:

cpan> install Inline

If this is the first download you've issued since starting CPAN, you will see a few lines of text, ending with this question:

Is it OK to try to connect to the Internet? [yes]

CPAN needs to get the latest repository list. Before you hit ENTER, check the preceding text for any notifications about a new CPAN. It won't change your answer to this question, but you'll want to remember it for the next section.

So, hit ENTER to allow CPAN to connect to the internet. After downloading files for Inline, it will ask if you want to install Inline::C. You don't have to install Inline::C (Inline::Pdlpp will be installed when you install PDL and in principle that's all you will need for PDL stuff). If you do install Inline::C, you will be asked to install Parse::RecDescent, too.

Side Note: Updating CPAN

Now that Inline is installed, if you saw a message like this:

New CPAN.pm version (v1.9402) available.

go ahead and install the new CPAN. It says you'll want to issue two commands, but I find that the first one spits out so much text that I can't find the second command because it's pushed out of my screen's buffer. So I'll list them both for you here:

cpan> install CPAN    # tons of text will follow this command
cpan> reload cpan     # Notice the difference in capitalization!

And now you should be running the latest CPAN module.

Installing Astro::FITS::Header

Obviously, FITS is a file format used by astronomers. It's probably not necessary for your work unless you are an astronomer. It may seem like a strange requirement, but it is helpful for at least some of our users and points back to PDL's roots in astronomy.

cpan> install Astro::FITS::Header

Installing POGL

POGL stands for Perl's OpenGL module. For many modules, it is sufficient to tell CPAN to install the module, but OpenGL can run into some tricky snags and it'll be easier to take it one step at a time. So issue this command at the cpan prompt:

cpan> get OpenGL

After getting the source code for POGL, we'll want to run the make command by issuing this:

cpan> make OpenGL

You will know that everything is working if you see text that looks like this:

... (text not shown) ...
Checking if your kit is complete...
Looks good
Writing Makefile for OpenGL
...
cc -c  -I/usr/include -I/usr/local/include -D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fno-strict-aliasing -pipe
-I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -O2 -g   -DVERSION=\"0.61\" 
-DXS_VERSION=\"0.61\" -fPIC "-I/usr/lib/perl/5.10/CORE"  -DHAVE_VER -DHAVE_FREEGLUT -DHAVE_GL -DHAVE_GLU 
-DHAVE_GLUT -DHAVE_GLX -DHAVE_FREEGLUT -DHAVE_FREEGLUT_H -DGL_GLEXT_LEGACY OpenGL.c
...

That cc command is your compiler. Your computer may appear to hang after one or more of these commands, but don't worry - it's just busy compiling the OpenGL bindings. It should be done in a couple of minutes. If all goes well, you will have Perl's OpenGL bindings compiled and you will be ready to move on to the next stage.

However, if you get errors (and you get your cpan prompt back in a matter of seconds), chances are pretty good that you don't have the OpenGL libraries or one of their dependencies installed on your system. Check the external dependencies above. If you still have trouble, send an email to the PDL mailing list.

You've compiled POGL, but you haven't tested or installed it (yet). To test POGL, issue this command:

cpan> test OpenGL

At some point, if all goes well, you'll have a graphic of a floating tea-pot. You'll be able to play around with the graphic using your keyboard, using these commands:

Hold down arrow keys to rotate, 'r' to reverse, 's' to stop.
Page up/down will move cube away from/towards camera.
Use first letter of shown display mode settings to alter.
Press 'g' to toggle fullscreen mode (not supported on all platforms).
Press 'c' to capture/save a RGBA targa file.
'q' or [Esc] to quit; OpenGL window must have focus for input.

Be sure to type q when you're done. Finally, you should install OpenGL:

cpan> install OpenGL

Again, if you have any trouble with this, send an email to the PDL mailing list.

Acquiring and Installing PDL

When it comes to acquiring the source code for PDL, you have at least three options: you can install PDL through the CPAN shell, you can manually download the files from Sourceforge, or you can pull the sources from the GIT repository.

CPAN

Start CPAN as discussed in #Firing up CPAN. Your next step depends on how much work you want CPAN to do for you.

Automated Installation

You can ask CPAN to simply install PDL. If you have all of the dependencies as discussed above, this should run smoothly:

cpan> install PDL

This should take many minutes (about 10 minutes for a 1.9 GHz, 1 GB RAM) and a huge volume of text will pass by. If you watch closely, you'll see various warnings during the compilation phase. While warnings mean that our code could be cleaned up, they are OK from the standpoint of installation. You will know that everything went well if the tail of the text looks something like this (possibly without the YAML warning):

Making HTML docs...

  CHM/PDL-2.4.5.tar.gz
  /usr/bin/make install  -- OK
Warning (usually harmless): 'YAML' not installed, will not store persistent state

cpan[##]> 

If you see this then you're good to go! If you simply want to install PDL then you're done. However, if you want more details, you run into trouble, or you want to tweak your PDL install, continue reading.

Automated Installation Explained

CPAN's install command will try to do these four steps:

  1. download PDL's tarball from the CPAN repository
  2. set up and compile PDL
  3. test PDL against the test suite
  4. install PDL

If it gets stuck at any point, it will not perform any of the other steps unless you explicitly force it to do so. I sometimes run into trouble with the simple install command. If you run into trouble, you can always start over by issuing the clean command:

cpan> clean PDL

If PDL does not install because one or two tests did not pass, chances are pretty good that PDL will still work for most of your purposes. As such, you can force PDL to be installed if you think it will be OK by issuing this command:

cpan> force install PDL

If the install PDL command above does not work and you don't want to force the installation, jump into the current state of the installation (as discussed in the next section) and continue below in the section, #Finishing a source-code installation

Manipulating the State of the Installation

CPAN's look command is very helpful. When you call it, you will be put into the temporary directory that holds the current state of the installation. This way, if you run into trouble, you can drop into the current installation state and poke around to figure out what might be giving you trouble. This also allows you to tweak perldl.conf before moving forward with the installation process.

The command you want is this:

cpan> look PDL

Upon issuing that command, your screen will give you output that looks similar to this:

Running look for module 'PDL'

Trying to open a subshell in the build directory...
Working directory is /home/david/.cpan/build/PDL-2.4.5-8UIzOx
root@arch:~/.cpan/build/PDL-2.4.5-8UIzOx# 

The particular folder (in this case PDL-2.4.5-8UIzOx) may be different for you, but the point is that this command will put you into the current state of the installation. When you are all done, type exit and you will return to the CPAN shell.

Tweaked CPAN Installation

If you intend to tweak your PDL installation, issue these commands

cpan> get PDL
cpan> look PDL      # this will put you in a shell, at which point you should tweak perldl.conf
cpan> install PDL

For instructions on tweaking the configuration file, see #Tweaking the perldl.conf file below.

Sourceforge

You can find the latest official releases on sourceforge at [1]. The files are distributed as a gzipped tarball. To extract them, use your archive manager software, or (if you've got a Unix-like system) at the prompt type go to the directory where you saved the downloaded archive and issue this command:

tar -xzf PDL-2.4.5.tar.gz

This will create a folder called PDL-2.4.5 in your current directory. Change into the directory and continue below with #Tweaking the perldl.conf file if you care to do that, or #Finishing a source-code installation.

GIT

If you download PDL from the GIT repository, you will have the bleeding-edge edition of PDL. Obviously, you'll need to have GIT installed on your machine before proceeding.

  1. Install GIT on your system, if you don't already have it.
  2. Open a prompt and cd into whatever directory you would use for these sorts of projects. For example, on my machine I keep code bases that I want to hold onto in the folder /home/david/packages/
  3. Run this command
git clone git://pdl.git.sourceforge.net/gitroot/pdl/pdl PDL

Continue below with #Tweaking the perldl.conf file if you care to do that, or #Finishing a source-code installation.

Tweaking the perldl.conf file

This should be documented here. However, the file itself is fairly well self-documented, so give it a read and see if anything stands out. If in doubt, # Send an Email to the PDL Mailing List.

Finishing a source-code installation

At this point, I will proceed with a basic installation process. You can get much more detailed installation options by looking at the INSTALL file in the source code that you have just downloaded. If you want to tweak the compilation process, have a look at perldl.conf (discussed in the previous section).

perl Makefile.PL

This command will spit out lots of lines saying, writing Makefile for .... The most important part of this step is to check for anything that says, "Not building..." or "Will skip...", which indicate either that you've told perldl.conf to skip that part or you don't have a dependency installed. For example, the first time I ran this I was told my PDL wouldn't have GSL support or FFTW. If you want one of these skipped capabilities, go back up to the dependencies section for information on how to fix that. Install whatever dependencies you think you need, tweak the perldl.conf file, and run it again. Once everything seems to be working the way you want run the makefile:

make

This step will probably take a while. You may get many warnings, but as long as you get no errors, you can continue. When it's finished, assuming all went well, run

make test

This will also take some time. The program should present a summary when it's done, and if any particular test files gave trouble, you can run them separately with

prove -vb t/test_file.t

Doing so will give you more precise info to send to the mailing list when you run into trouble. Once all the tests pass, or you've convinced yourself it's OK that some have not passed, build the help documentation database by issuing:

make doctest

Once that's finished, test the shell with this command:

perl -Mblib perldl

While in the shell, you can check any documentation by typing

help readfraw

or similarly for the function or item you want to know more about. Finally, once you've convinced yourself it's all working, run as root (or using sudo):

make install

And you should be all set!

Running into Trouble

Based loosely on BUGS.

Most of the steps discussed in the installation give voluminous output, which can make it hard to track down precisely what is giving you trouble. However, if you run into trouble while trying to do a manual installation, the best place to start is by examining the output of the command that gave you trouble.

Problems with perl Makefile.PL

First, make sure that what you see with this command are in fact errors. You will often get output saying something like, Not building... or Will skip build of.... These are not errors: you should be able to get PDL to build and install despite these warnings.

If you do run into an error, or if you get a warning about a module that you want, then your problem is almost surely a dependency problem, or there's a bug in the makefile. Check the dependencies section (above). If everything looks right but you're still having trouble, #Send an Email to the PDL Mailing List.

Problems with make

When you run make, you will get lots of output. Although it's not obvious that make succeeded (Unfortunately, make doesn't say "Everything's all done!"), it's usually abundantly clear when make failed. First, the compilation step that failed will usually be filled with many lines indicated 'error', and second, the last line of make should say something like, "make: *** [test.o] Error 1" with test.o replaced by whatever file make was attempting to create, but could not because of trouble. (Note - make will not give you the name of the file it choked on: that's the compiler's job, because it's really the compiler that choked.)

You really shouldn't run into these sorts of errors, so if you do, you should file a bug report, discussed below.

Problems with make test

Although make test, like all the other steps, will give lots of output, it will give a summary at the end of which tests failed. If you like, you can get lots of details on what worked and what didn't by running the individual tests with prove, like this:

prove -vb t/fastraw.t

This is not strictly necessary, but it might tell you exactly what you need to know. If you're as ambitious as you are good looking, you will dig into the source code and try to fix the problem. If you do that, be sure that you work with the most recent GIT version (see #GIT, above), and when you've fixed the problem, be sure to submit a patch.

If you're not so ambitious, you should file a bug report.

Problems with make install

If you ran into trouble at this point, you probably didn't perform the install with root permissions.

Send an Email to the PDL Mailing List

If you run into trouble and can't find a solution here, try sending an email to the PDL mailing list. I will give a somewhat cryptic form in order to prevent spam - read it and figure out how to spell the addres:

perldl at something.hawaii.edu
replace 'something' with 'jach' (not jack)
Personal tools