
INSTALLATION
------------

To install PerlDL on your machine, first check that you have
a high enough version of Perl. 5.004 should be enough for now.

The file DEPENDENCIES summarizes the dependencies of various
PDL modules on libraries/other packages. To specify location
of some of these libs or disable certain modules see also below.

Edit file perldl.conf in the current directory, this specifies
configuration options for building PDL and is self-documenting.

Then, just say

	perl Makefile.PL

in the directory this file is in. (See 'perldoc ExtUtils::MakeMaker
for info on how to configure the defaults for install location, etc.)
and if that goes ok, say:

	make

If there are any strange error messages, please contact the developers
with a full bug report; response is often rapid (we really like to have
PDL work right out of the box on as many platforms as possible).

If make worked correctly, try

	make test

to run the regression tests. Again, if there are errors, please contact
the developers (via the pdl-porters mailing list, see Basic/Pod/FAQ.pod).

If everything works and you wish to install PDL type

   make install

If you are happy with your perldl.conf you can keep the file
handy for future reference. Place it in ~/.perldl.conf where
it will be picked up automatically or use 'perl Makefile.PL PDLCONF=file'
next time.

There is also another make item:

   make doctest

creates the documentation database for use in the perldl shell.


COMMON PROBLEMS
---------------

There are some more common error messages and problems, which 
are included here for your convenience

Q: "Can't find include file GL.h" or somesuch.

A: If you dont' have either OpenGL or Mesa installed, you need to 
edit perldl.conf (see above) and set WITH_3D to 0. Then, start the
build process again as described above (from the toplevel):

   perl Makefile.PL

etc...

Q: I want TriD, but include files are not found.

A: You need to add -I/usr/openwin/include etc. (or whatever is appropriate
on your platform) to the relevant entry in perldl.conf (see above),
i.e. something like

      OPENGL_INC => '-I/usr/openwin/include',

Additionally, you might have to specify name and location of the appropriate
library on your platform, e.g.

      OPENGL_LIBS =>
	   '-L/usr/openwin/lib -L/usr/X11R6/lib -L/usr/lib/mesa -lGL'.
	 ' -lGLU -lXext -lX11',

Then, start the build process again as described above (from the toplevel):

   perl Makefile.PL

etc...

Q: Compilation of TriD complains about undefined functions or somesuch.

A: The TriD files are autogenerated and your platform doesn't have
some of the extensions or whatever. We are waiting for the Perl
OpenGL module to be upgraded so that we could just rely on that,
so bear with us. There is a script 'generate.pl' in Graphics/TriD/OpenGL
which you can try running and then recompiling.

Please report this problem to pdl-porters@jach.hawaii.edu.

Q: When running tests, complaints about pthread_* symbols not
being defined

A: This shouldn't happen any more. If it does, please inform the mailing
list. However, on certain platforms (notably Digital and IRIX), you will
not get pthread support in PDL unless your perl executable was linked
with -lpthread. 


Q: Make fails at some point with "can't find pdl.h" or somesuch or
alternatively everything compiles fine and then, when trying to do 
something, PDL complains about finding a "PDL/Primitive/assgn.al"
for autoloading.

A: Please try recompiling, turning off all make options that parallelize
the compilations - sometimes something is not correctly done in sequence
and that bothers other parts. We're working on a fix. Also, please report
this condition.

Also, it might be worth a try to get a different 'make' - gmake seems
to work well.


Q: What does 
> Converting input file
> Doc/mkhtmldoc.pl: /usr/lib/perl5/site_perl/PDL/PP.pod: cannot resolve
> L<PDL::Indexing> in paragraph 8: no such page 'PDL/Indexing'
> Doc/mkhtmldoc.pl: /usr/lib/perl5/site_perl/PDL/PP.pod: cannot resolve
> L<perlxs> in paragraph 9: no such page 'perlxs'
> Doc/mkhtmldoc.pl: /usr/lib/perl5/site_perl/PDL/PP.pod: cannot resolve
> L<PDL::Indexing> in paragraph 11: no such page 'PDL/Indexing'
>
> [....]
>
> loading directory cache
> Converting input file
> Doc/mkhtmldoc.pl: /usr/lib/perl5/site_perl/PDL/Indexing.pod: cannot
> resolve L<PDL> in paragraph 4: no such page 'PDL'
> Doc/mkhtmldoc.pl: /usr/lib/perl5/site_perl/PDL/Indexing.pod: cannot
> resolve L<PDL::FAQ> in paragraph 6: no such page 'PDL/FAQ'
> Doc/mkhtmldoc.pl: /usr/lib/perl5/site_perl/PDL/Indexing.pod: cannot
> resolve L<PDL::Internals> in paragraph 35: no such page 'PDL/Internals'
mean?

A: the html documentation is experimental - nothing is wrong
with your system. 

