=for comment $Id: Readme.pod,v 1.6 2005/12/03 01:56:31 robertemay Exp $

=head1 NAME

Win32::GUI::UserGuide::Readme - Perl-Win32 Graphical User Interface Extension README

=head1 DESCRIPTION

Win32::GUI is a Win32-platform native graphical user interface toolkit for
perl. Basically, it's an XS implementation of most of the functions found in 
user32.dll and gdi32.dll, with an object oriented perl interface and an 
event-based dialog model that mimic the functionality of visual basic. 


=head1 AVAILABILITY

This is the README file for Win32::GUI v__W32G_VERSION__
built on __W32G_DATE__.

Source and ActiveState Perl PPMs are available from
L<__W32G_WEB_FILES__>. 

A cygwin distribution (available through cygwin's setup.exe) is maintained
by Reini Urban (rurban@x-ray.at).

If the Win32::GUI version number contains an underscore, then it is an alpha,
beta or release candidate distribution.  If there is no such underscore, then
it is a stable release.

=head1 INSTALLING

=head2 ActiveState ActivePerl PPMs

It is recommended to uninstall any previous version of Win32::GUI before
installing a new version.  This ensures old documentation is removed correctly.
From a command prompt run:

  ppm uninstall Win32-GUI

If you have any packages that are dependent on Win32::GUI you may need to add
the C<-force> option to the command line.  See your documentation for PPM.

Unzip the PPM distribution into a local directory.  From a command
prompt in that directory run:

  ppm install ./Win32-GUI.ppd

=head2 Cygwin

Runtime requirements:

  cygwin
  perl-5.8.6
  w32api

Use the cygwin setup.exe tool to locate, download and install
the perl-Win32-GUI binary package.

Cygwin port questions to the mailinglist <cygwin@cygwin.com>

=head1 Building from source

Unpack the distribution into a local directory, and from a command
prompt in that directory follow the instructions below.

These instructions assume that you have already set up your build
environment, and can build source distributions.  The following
environments are known to work:

=head2 Microsoft Visual C++ V6

Other versions may work.  There are reported issues with VC++ 7
which links with a different C runtime to VC++ 6, and so you may have
issues running an extension built with VC++ 7 with the ActiveState Perls.

  perl Makefle.PL
  nmake
  nmake test
  nmake install

=head2 MinGW and ExtUtils::FakeConfig

  perl -MConfig_m Makefile.PL
  nmake
  nmake test
  nmake install

Built this way the GUI.dll extension can be very large (~3MB).  There is a
module in the F<build_tools> directory that works with B<Config_m> and
L<Extutils::FakeConfig|ExtUtils::FakeConfig> to set the MinGW compiler
flags more optimally.  If you want to try this, then replace the first
command with:

  perl -Ibuild_tools -MConfig_mO Makefile.PL

=head2 Cygwin

Build requirements (over and above the runtime requirements above):

  cygwin
  cygutils
  gcc
  make
  gzip

Build instructions:

unpack F<perl-Win32-GUI-X.XX-X-src.tar.bz2>. If you use setup to install
this src package, it will be unpacked under F</usr/src> automatically.

  cd /usr/src
  ./perl-Win32-GUI-X.XX-X.sh all

This will create:

  /usr/src/perl-Win32-GUI-X.XX-X.tar.bz2
  /usr/src/perl-Win32-GUI-X.XX-X-src.tar.bz2

Port Notes:

The dll's must probably be rebased. If a remap error occurs run rebaseall from 
the rebase package. The packaged version is already rebased to my personal settings.

For a source build from the official source, the standard build process
should be sufficient:

  Perl Makefile.PL
  make
  make test
  make install

=head1 Documentation

=head2 POD documentation

When building from source the POD documentation is built automatically
by the make process.  It can also be generated by issuing:

  nmake poddocs;

=head2 HTML Documentation

HTML documentation is included with the PPM distributions, and installed
into your ActiveState Perl documentation tree by the install process.

The HTML documentation can also be generated by issuing:

  nmake htmldocs;

=head1 Building your own PPM from source

You will need B<tar>, B<gzip> and B<zip> utilities on your path.  Issue
the following commands.

  perl Makefile.PL (adjust as necessary for your build environment)
  nmake
  nmake test
  nmake ppm

This procedure will generate a PPM for your current perl environment,
including the HTML documentation, ready for installation as above.

__W32G_POSTAMBLE__