If you read this file _as_is_, just ignore the funny characters you see.
It is written in the POD format (see pod/perlpod.pod) which is specially
designed to be readable as is.
=head1 NAME
Install - Build and install wxPerl
=head1 wxPerl installation
************************************************************************
You need to install wxWidgets 2.5.3 or later 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 "USING wxPerl on MAC OS X"
************************************************************************
=head1 Quick installation
This applies to UN*X systems, and only if wxWidgets 2.5.3 or later is already
compiled and installed.
# unpack the wxPerl archive
tar xzvf Wx-0.xx.tar.gz
cd Wx-0.xx
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
=head1 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
=head1 Installing wxWidgets (on UNIX systems and Mac OS X)
wxWidgets 2.5.3 or later is required for wxPerl to work.
For UNIX systems only. If you are using prepackaged wxWidgets binaries you
need to install the -dev and -contrib-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
If something goes wrong, please refer to the wxWidgets
installation instructions.
=head1 Installing under Win32
This wxPerl version was tested with MinGW 3.0 and MS Visual C++ 5.
Older MinGW versions (from 1.1 onwards) and newer versions will likely work.
For the remainder of this section I'll assume that your Perl is installed
in C:\Perl
=head2 MS Visual C++ 5 (wxWidgets 2.5.x), MS Visual C++ 6 SP4 (wxWidgets 2.5.x)
wxWidgets 2.5.3 or later is required for wxPerl to work.
Build wxWidgets as a dll
cd z:\path\to\wx\build\msw
nmake -f makefile.vc SHARED=1 BUILD=release
cd ..\..\contrib\build\stc
nmake -f makefile.vc SHARED=1 BUILD=release
# build wxPerl
set WXDIR=z:\path\to\wx
set WXWIN=z:\path\to\wx
perl Makefile.PL
nmake
nmake test
nmake install
To build a debugging wxPerl, follow the instructions above passing
BUILD=debug DEBUG_RUNTIME_LIBS=0 to wxWidgets makefile and --debug
to Makefile.PL.
=head2 MinGW 1.1 or later (wxWidgets 2.5.x)
wxWidgets 2.5.3 or later is required for wxPerl to work.
Get MinGW from http://www.mingw.org/ ; choose the all-in-one
package (downloading the individual packages will work but requires
you knowing how to install them). MSYS is not required.
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
cd z:\path\to\wx\build\msw
make -f makefile.gcc SHARED=1 BUILD=release
cd ..\..\contrib\src\stc
make -f makefile.gcc SHARED=1 BUILD=release
# now build wxPerl
# get dmake from http://www.cpan.org/authors/id/GSAR/dmake-4.1pl1-win32.zip
set WXDIR=z:\path\to\wx
set WXWIN=z:\path\to\wx
perl Makefile.PL
dmake
dmake test
dmake install
To build a debugging wxPerl, follow the instructions above passing
BUILD=debug to wxWidgets makefile and --debug to Makefile.PL.
=head1 Specifying the installation path
If you don't want to install wxPerl as a system module, you must
specify a different installation path. With recent ExtUtils::MakeMaker
you can do this by using
perl Makefile.PL PREFIX=path
On older ExtUtils::MakeMaker version the correct incantation
might be different.
=head1 Using wxPerl 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 use the special 'wxPerl'
executable created by wxPerl.
=head1 FAQ
=head2 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.
=head2 C++ compiler
wxPerl needs a C++ compiler to build. By default it will use
the C++ compiler that was used to compile wxWidgets; this can cause
problems if Perl was compiled with a C compiler of a different brand.
For example if you compile Perl with GCC and wxWidgets with ICC or
Perl with Sun C compiler and wxWidgets with G++ you will most likely
not be able to compile wxPerl. Exceptions are: under Windows you can
use ActivePerl (compiled with MS Visual Studio) and wxWidgets compiled
with MinGW by using ExtUtils::FakeConfig, under Solaris a similar
tool exists for Sun C Compiler -> GCC/G++ compilation.