= How to Build & Install PerlMapScript =

Once you compile !MapServer itself and can successfully run './mapserv' and get back:
{{{
    "This script can only be used to decode form results and should be initiated as a CGI process via a httpd server." 
}}}
    Then
{{{
        cd mapscript/perl 
        perl Makefile.PL 
        make 
        make install 
}}}
== Changing the Perl Module Name ==

The default module name is "mapscript". However, you may want to use something version specific, especially if you have multiple versions installed. To do this:
{{{
    1) edit mapscript.i and change the line "%module mapscript" to "%module yourname", ie. "mapscript563".
    2) in plmodule.i. Look for lines of the form: "mapscript::RFC24_ADD_PARENT_REF(..." and change mapscript to "mapscript563::...".
    3) remove mapscript.pm if it's present. SWIG will create yourname.pm and the presence of mapscript.pm will confuse the install. 
    4) re-SWIG it (install SWIG and the type swig -shadow -perl5 mapscript.i) 
    5) edit Makefile.PL and change the line "'NAME' => 'mapscript'," to "'NAME' => 'yourname'," 
    6) build as normal 
}}}
You should now be able to do "use yourname" in your perl scripts.

== What to Check When Encountering Build Issues ==
{{{
/sbin/ldconfig -v
}}}
    will give information concerning the shared libraries present 
    on your system. 
{{{
ldd mapserv
}}}
    Look for the path that is listed. 
    Then make sure this path is part of your runtime library path, 
    for this you have two options, assuming you're running Linux: 

    1- add the path to /etc/ld.so.conf and run 'ldconfig' as root 

    or 

    2- Use !SetEnv LD_LIBRARY_PATH to specify this path in your 
    apache httpd.conf 
{{{
echo $LD_LIBRARY_PATH
}}}
    Will give information on the library path traversed when 
    linking. 
{{{
locate <library_name_ie._gd.h>
}}}
    Will give location(s) of the specified filename. 

Does the above information show a mixture of include files (different revisions of the same library).

If when running ./mapserv you receive the error message:
{{{
    mapserv:error while loading libraries:libproj.so.0 cannot open shared object file : No such file or directory. 
}}}
    Run '/sbin/ldconfig -v | grep libproj'.

        Which should return something similar to "libproj.so.0" 
        If not try reinstalling proj.4 

If when running ./mapserv you recieve the error message:
{{{
    error while loading shared libraries :/usr/libwwwappp.so.0 undefined symbol: HTZlib_inflate 
}}}
    Check /usr/lib and /usr/local/lib for a copy of w3c-libwww. 
    If both have a copy then remove the copy in /usr/lib. 
    The cleanest way to remove, is to 'rpm -q -a | grep w3c-libwww' & do 'rpm -e w3c-libwww-<version_number>'. 

If when compiling you get an error:
{{{
    mapscript_wrap.c: In function `SWIG_GetPtr?': 
    mapscript_wrap.c:292: `sv_undef' undeclared (first use in this function) 
}}}
    (followed by many more errors)

        Find the DEFINE line in Makefile and add -DPERL_POLLUTE at the end. 

== Instead of compiling ==
(or at least as a starting point) install ftp://ftp.intevation.de/freegis/gnu-linux-i586/updates .

== To Compile w/ Perl 5.8 ==

    (submitted by Joe Bussell) 
    you must make a hand hack to the generated SWIG code in mapscript_wrap.c 
    Specifically, the macro XS(boot_mapscript) must be declared if the PERL object is not declared. 
    In my world line 431 which reads SWIGEXPORT(void) boot_mapscript(CV* cv); should be replaced with XS(boot_mapscript); 

== 3.6.4 Compiles but Does NOT Run ==
Bails with Can't load '/usr/local/lib/perl5/site_perl/5.6.1/sun4-solaris-64int/auto/mapscript/mapscript.so' ...

    (submitted by unknown user) 
    Apparently, the flag "-lgd" isn't being placed in ../../perlvars and this is causing the problem. A rather simple, though barbaric, solution is to add this line: 
{{{
    $libs .= " -lgd"; 
}}}
    right before this in Makefile.PL: 
{{{
    print $inc."\n"; 
    print $libs."\n"; 
}}}
== Building Private !MapScript (Shared ISP Machine) ==

When you are installing a private version of mapscript, there is a perl Makefile bug (at least on perl 5.6.1 and maybe later versions) that must be manually fixed to avoid conflict with installed version of libraries on the machine (in /usr/lib or /usr/local/lib)

In the the mapserver/mapscript/perl directory,
{{{
perl Makefile.PL PREFIX=/usr/home/myhomedir LIB=/usr/home/myhomedir/usr/local/lib
}}}
    * note: the PREFIX and LIB are needed to create your private version 

and where /usr/home/myhomedir is my homedir and my privatedir are is built in /usr/home/myhomedir/usr/local

perl !MakeMaker will create a canned Makefile template... and if you inspect the file, you will see:
{{{
    LDDLFLAGS = -shared -L/usr/local/lib 
    LDFLAGS = -Wl,-E -L/usr/local/lib 
}}}
and when change to:
{{{
    LDDLFLAGS = -shared -L/usr/home/myhomedir/usr/local/lib 
    LDFLAGS = -Wl,-E -L/usr/home/myhomedir/usr/local/lib 
}}}
and then
{{{
make make install
}}}
Mapscript *should* find your private copy of libgd (and other packages) and link to them. I learn this lesson the hard way, and I thought I'd better stick it in the wiki.

Private Perl Module Usage: When you try to "use mapserver;" in perl, you will have to add a "use lib ..." preceding that line.
{{{
    use lib("/usr/home/myhomedir/lib/site_perl"); 
    use mapscript; 
}}}
-mapsurfer 06/04/2003

== Ways to Change the Perl @INC Path ==

As usual there are many ways to do it. You need to alter the default @INC array. You can use on first line of your script:

   1. !/usr/bin/perl -I/installs # puts /installs at front of @INC. 

or: push @INC, '/installs'; # puts it at the end of @INC.

or: use lib '/installs/'; # not sure where this puts it.

But the order is important, if the two modules have identical names.

You might also try: require '/installs/gd-2.0.15';

Of course, to get mapserver to use the new GD you'll need to recompile it.

Eric