gtk2-perl-xs on win32

["muppet" <scott asofyet org>]

as much as we may or may not like win32, a lot of us are stuck with it.
a quick search for win32 through the gtk-perl-list archives reveals a lot
of discussion on the topic in the past, usually disappointing.

in may, goran forwarded us a note that carlos reis had gotten gtk2-perl-xs
to work on windows by way of a clever hack.[1]

i spent a fair amount of masochistic time this week making gtk2-perl-xs
build natively on windows with what could be considered "normal" tools.
with any luck, we may have the first version of gtk-perl/gtk2-perl to
support both unix and windows.  ;-)


this will be a bit in-depth, so i'll break it up:

1. requirements
2. procedure & caveats
3. unresolved issues

1. requirements
---------------

i presume that most people will get perl on windows by installing
ActiveState's native win32 perl[2].  ActiveState's perl is the most maintained
win32 build of perl, at any rate (as i discovered last year when trying to
build perl with mingw32).

a drawback to this is the fact that perl's extension system wants to build
extensions with the same set of tools that were used to build perl itself;
with the ActiveState perl, that means microsoft's nmake.exe, cl.exe,
and link.exe.  i used Microsoft Visual Studio 6.0.  i understand that nmake
is (or was) freely available from MS' website, but i don't know about cl.exe,
lib.exe, and link.exe.

also, this build process uses a few tricks that work in cmd.exe (as seen on
NT4, NT5 (win2k), and NT5.1 (winxp), but which fail miserably in win9x/me.

i'm not crazy enough to suggest that we build Gtk+ as well; we'll get that
in binary form[3].

so, the requirements for this procedure are:

 - windows NT4, 2000 (tested), or XP.
 - ActiveState Perl 5.8.0 [2]
 - microsoft's compiler tool chain (tested with Microsoft Visual Studio 6.0)
 - Gtk+ runtime environment [4]
 - Gtk+ development environment [5]

i also got gtk-wimp[6] so that my gtk2-perl programs will look and feel like
native windows applications; it should help avoid scaring the users.  :-)


2. procedure & caveats
----------------------

 - make sure you have all the requisites:
   - install the Gtk+ runtime to the default place
     (usually c:\Program Files\Common Files\GTK\2.0, i'll call it %GTK%)
   - install the Gtk+ devel packages.
     (i put them in c:\gtk, but will refer to this as %GTK_DEVEL%)
   - install ActiveState's Perl, MUST be 5.8.0
     (i installed to c:\Perl, but will refer to it as %PERL% below)
   - install MSVC if you have to.

 - fetch the gtk2-perl-xs source code, and apply the attached patch.  this
   provides some workarounds in the code for symbols missing from the
   dropline GTK dll, and some #ifdefs to avoid symbol clashes between glib,
   perl, and the msvcrt's headers.
   be warned!!! there are hardcoded paths in the patch, and you will have
   to change them!

 - open a new command shell and set up your paths.  this must be cmd.exe,
   *not* a cygwin shell or command.com/command.exe.  (both command and cmd
   are available on XP, be careful.)  i find it easiest to type cmd.exe into
   the Run dialog to avoid searching the menus.[8]
   - make sure that c:\Perl\bin in the path.
   - make sure the microsoft toolchain is in your path.  if you're using
     MSVC, you can run the BAT script that comes with it, usually as
     %MSVC%\VC98\Bin\VCVARS32.BAT.
   - windows looks for libraries in the binary search path.  whatever.  that
     means that all of the lib directories you'd normally put into
     $LD_LIBRARY_PATH need to go into %PATH%
     - %GTK%\bin
     - %GTK%\lib
     - %GTK_DEVEL%\bin
     - %GTK_DEVEL%\lib
   - for reference my path looks like this (lines broken by me for
     readability):
        c:\gtk\bin;c:\gtk\lib;c:\perl\bin;
        c:\Program Files\Common Files\GTK\2.0\bin;
        c:\Program Files\Common Files\GTK\2.0\lib;
        C:\PROGRA~1\MICROS~3\Common\msdev98\BIN;
        C:\PROGRA~1\MICROS~3\VC98\BIN;
        C:\PROGRA~1\MICROS~3\Common\TOOLS\WINNT;
        C:\PROGRA~1\MICROS~3\Common\TOOLS;
        C:\Perl\bin\;C:\WINNT\system32;C:\WINNT
    - we're going to be installing a bunch of alpha perl modules, so i
      STRONGLY urge you to install them to a non-standard place:
        set PERL5LIB=c:/gtk2-perl/lib
      i'll refer to c:/gtk2-perl below as %GTK2PERL%.  if you don't set it
      then you don't have to specify it.

  - build gtk2-perl-xs components with your freshly configured shell.
    - go into ExtUtils-Depends
      - 'perl Makefile.PL PREFIX=%GTK2PERL%'
      - 'nmake test'
      - 'nmake install'
    - go into Glib
      - if you don't have the file Glib.exports, then you didn't apply the
        patch above and this won't work.
      - 'perl Makefile.PL PREFIX=%GTK2PERL%'
      - 'nmake test'
      - 'nmake install'
    - go into Gtk2
      - Gtk2.dll must be linked against the Glib.lib we created a moment ago.
        open up Makefile.PL and look for this line
         $gtk2->set_libs($pkgcfg{libs}." %GTK2PERL%/lib/auto/Glib/Glib.lib");
        replace %GTK2PERL% with the path to the place where your perl modules
        are getting installed.  in mine, it would be
         $gtk2->set_libs($pkgcfg{libs}." c:/gtk2-perl/lib/auto/Glib/Glib.lib");
        yes, i know those are forward slashes --- perl is fine with them.
      - 'perl Makefile.PL PREFIX=%GTK2PERL%'
      - 'nmake'
      - the build should bomb at the link stage, complaining that it can't
        find any object files.  that's because we have the xs files in a
        subdirectory, and cl.exe apparently ignores the /o switch[7].
        do 'move *.obj xs', and then 'nmake' again.  the build should succeed
        this time.  if it fails with unresolved symbols, find them in the
        source, comment them out, and rebuild (don't forget to move the
        new objects into the subdirectory again!).
      - 'nmake test'
      - 'nmake install'
      - cd into gtk-demo and do 'perl main.pl'.  play around a bit, make
        sure that things work.

  - if you installed to a non-standard PREFIX, you'll have to set PERL5LIB
    in your environment (there are tools to do that) or add a 'use lib ...'
    line to each script.


3. unresolved issues
--------------------

- binary packages
  this procedure is a whole lot of not-fun, and requires a non-free compiler.
  additionally, most windows users are accustomed to binary packages.
  i'm not entirely sure what it takes to build binary packages on win32;
  from the PPM manpage it's as simple as tar'ing up the blib, but i'd like
  the advice of someone who's tried this.

- linking
  link.exe won't allow unresolved symbols at compile time, so the patch
  adds the full path to Glib.lib, created by the Glib compile, to the
  list of libraries for Gtk2.  i really despise this.  does anybody know
  how we can get around this nastiness?

- the missing symbols within the Gtk dlls are a bug with either the win32
  port of gtk (for not keeping the defs file up to date) or with the
  packagers for the same (for not ensuring the symbols are there).  the most
  we can do is patch around them, unfortunately.



[1] http://lists.gnome.org/archives/gtk-perl-list/2003-May/msg00097.html
[2] freely available from http://activestate.com
[3] http://www.dropline.net/gtk/download.php
[4]
http://prdownloads.sourceforge.net/gtk-win/GTK-Runtime-Environment-2.2.1.2.exe?download
[5]
http://prdownloads.sourceforge.net/gtk-win/GTK-Development-Environment-2.2.1.2.exe?download
[6] http://gtk-wimp.sourceforge.net/
[7] this is the same bug about which we've gotten lots of questions on the
    list since perl 5.8.0.  the makefile trick doesn't work.  :-(
[8] if you are used to bash or tcsh on linux or even on cygwin, then windows'
    shells will drive you completely batty, and will have you swearing within
    minutes.  here's a quick primer:
       to view your path, just type 'path' (without the quotes) and press
    enter.  to set your path, do 'path=newstuff'; components are separated by
    semicolons (because the colon is part of the volume name!).  to get the
    value of a variable, wrap it in percents; this prepends a path:
      path=c:\tmp;%path%
    for other variables, do something like
      set foo=bar
    quoting doesn't work like you'd expect.  sorry.  i don't understand it,
    either.

-- 
muppet <scott at asofyet dot org>