* wxPerl INSTALLATION

****************************************************************************
You need to install wxWidgets before you can compile wxPerl.
For UNIX systems look at the section "INSTALL wxWidgets"; for Win32
systems, detailed build instructions for wxWidgets + wxPerl are included
in the section "COMPILING UNDER WIN32"; for Mac OS X, refer to
"INSTALL wxWidgets", and then to "PREPARING Perl on MAC OS X"
****************************************************************************

* QUICK INSTALLATION

This applies to UN*X systems, and only if wxWidgets is already compiled and
installed.

unpack the wxPerl archive
cd to wxPerl directory
perl Makefile.PL   # (1)
make               # (2)
make test          # (3)
make install       # (4)

1) see below for a way to specify a different installation directory
2) under Windows you may need to use nmake, or another *make
3) you may also want to do
   perl run minimal
   perl run controls
   ...
   against the samples in the 'samples' subdirectory, and
   perl demo/demo.pl

   before installing
4) you may need Administrator/root privileges to install

* ADDITIONAL FLAGS TO Makefile.PL

In addition to ExtUtils::MakeMaker flags wxPerl Makefile.PL accepts

  - --debug
    Currently only under Win32 or GCC
    adds debugging information to the library

  - --extra-libs={extra libraries}
    Adds extra libraries to the link command line

  - --extra-cflags={extra compiler flags}
    Adds extra compiler flags to compiler line

  - --help
    Show the full list of options

* SPECIFYING C++ COMPILER

  wxPerl needs a C++ compiler to build. Under Windows there is no
problem, since there are only 2 supported compilers. Under Unix, if
your Perl was built with GCC all should be fine, otherwise wxPerl does
nothing and warns you at Makefile.PL time; in this case you will almost 
surely need to add some special flags (via --extra-cflags) or to specify 
a different compiler (via perl Makefile.PL CC=c++-compiler)..
 
* INSTALLING wxWidgets (on UNIX systems and Mac OS X)

  For UNIX systems only. If you are using the prepackaged binaries, you
need to install the -dev packages in order to compile wxPerl, otherwise
you just need the main package and the -contrib package.
If you are compiling wxWidgets yourself, the quick way is:

./configure
make
make install
cd contrib/src/stc
make
make install
cd ../xrc
make
make install

  If something goes wrong, please refer to the wxWidgets
installation instructions.

* COMPILING UNDER WIN32

This wxPerl version was tested with MinGW 1.1 and MS Visual C++ 5.
For the remainder of this section I'll assume that your Perl is installed
in C:\Perl

- MS Visual C++ 5 (and probably 4.x)
- MS Visual C++ 6 SP4

  Build wxWidgets as a dll

  set WXDIR=z:\path\to\wx
  set WXWIN=z:\path\to\wx
  cd %WXDIR%\src\msw
  nmake -f makefile.vc FINAL=1 dll
  cd %WXDIR%\contrib\src\stc
  nmake -f makefile.vc FINAL=1 WXUSINGDLL=1
  cd %WXDIR%\contrib\src\xrc
  nmake -f makefile.vc FINAL=1 WXUSINGDLL=1

  # build wxPerl
  perl Makefile.PL
  nmake
  nmake test
  nmake install

  # after wxPerl is installed you need to copy the wxmsw*.dll from
  # z:\path\to\wx\lib to the directoy where Wx.dll is installed.

  If you are using ActivePerl with MSVC != 6.x you may
  experience linking problems (Can't seek to position XXXXXX ...),
  then you need to rebuild the perl56.dll import library.

  Use the make_implib.pl script (included in the ExtUtils::FakeConfig
  distribution): make a backup of C:\Perl\lib\CORE\Perl56.lib, then do

  perl script/make_implib.pl --target=vc C:\Perl\bin\Perl56.dll

  This will create a file Perl56.lib; copy this file to C:\Perl\lib\CORE\ .

- MinGW 1.1 or later

  Get MinGW from http://www.mingw.org/; direct link is
  http://prdownloads.sourceforge.net/mingw/MinGW-1.1.tar.gz

  If you want to compile wxPerl against ActivePerl using MinGW,
  you ned to first download and install ExtUtils::FakeConfig from
  http://wxperl.sourceforge.net/ap_mingw/; then just replace the
  "perl Makefile.PL" with "perl -MConfig_m Makefile.PL". If you built
  Perl from sources, you don't need this additional step.

  Build wxWidgets as a dll (you will need the utilities from
      http://biolpc22.york.ac.uk/pub/ports/mingw32/extra.zip)

  set WXDIR=z:/path/to/wx
  set WXWIN=z:/path/to/wx
  cd z:\path\to\wx\src\msw
  make -f makefile.g95 FINAL=1 WXMAKINGDLL=1
  cd %WXDIR%\contrib\src\stc
  make -f makefile.g95 FINAL=1 WXUSINGDLL=1
  cd %WXDIR%\contrib\src\xrc
  make -f makefile.g95 FINAL=1 WXUSINGDLL=1

  # now build wxPerl
  # get dmake from http://www.cpan.org/authors/id/GSAR/dmake-4.1pl1-win32.zip
  perl Makefile.PL
  dmake
  dmake test
  dmake install

  # when wxPerl is installed you need to copy the wxmsw*.dll from
  # z:\path\to\wx\lib to the directoy where Wx.dll is installed.

* SPECIFYING THE INSTALLATION PATH

If you don't want to install wxPerl as a system module, you must
specify a different installation path. Usually you do this with

perl Makefile.PL PREFIX=path

however, depending on your Perl setup, you may need different options:
in my Win2k system, ActivePerl build 620, I use

perl Makefile.PL LIB=path

In my Debian 2.2 system (Perl 5.005_03 and 5.004_05 shipped with
 Debian), I use

perl Makefile.PL PREFIX=path INSTALLSITELIB=path INSTALLMAN3DIR=manpath

With the Perl 5.004_04 I built from sources (in my Debian system) I use

perl Makefile.PL PREFIX=path

Depending on your setup you may need other options: che complete list
is on the ExtUtils::MakeMaker manpage

perldoc ExtUtils::MakeMaker 

for details.

* PREPARING Perl on MAC OS X

  The 'perl' executable shipped with your OS can't be used to run executables
that interact with the GUI, hence you need to prepare a special 'wxPerl'
executable. Let's assume that your 'perl' is in '/usr/local/bin/perl'.
  First, you need to install wxWidgets, then do the following from the
command prompt:

$ cp /usr/local/bin/perl wxPerl
$ `wx-config --rezflags` wxPerl

Now test your shiny new wxPerl executable:

$ wxPerl -Mblib samples/minimal/minimal.pl

* FAQ

1) Problems compiling XRC and/or STC

Usually they start like this:

STC.c:33:24: wx/stc/stc.h: No such file or directory

and go ahead with many compilation errors.
  This usually means you did not install wxWidgets' 'contrib' libraries;
either install them or disable STC/XRC passing --disable-stc --disable-xrc
to Makefile.PL.
