Welcome to libwin32 version 0.14. WHAT ---- This used to be a bundle of extensions that provided a quick migration path for people wanting to use the core support for win32 in perl 5.004 and later. With the release of Perl version 5.005 (which brings ActiveState's changes to Perl sources into the mainstream), this library of extensions has assumed loftier motives. The long term goal of this project is to provide a coherent collection of modules that allow access to the functionality provided by the Win32 API, while maintaining the style and spirit of Perl. Like Perl, the intention is to make "easy things easy, and hard things possible". Note that we are nowhere close to this goal at the present time, but we are slowly getting there. As the name suggests, all modules in this distribution are Win32-specific. They cannot be used on platforms that do not support the Win32 API. This distribution has been pre-compiled for the x86 architecture. The precompiled binaries can ONLY be used with the perl5.00402-bindist04-bc.zip distribution from CPAN. See the "WHAT TO DO" section for installation instructions. Binaries compatible with "ActivePerl" should be available soon from http://www.activestate.com/. WHAT HAS CHANGED ---------------- The top level "Changes" file contains a version by version overview of the most significant changes. This release has the following changes over the previous one (version 0.13): + Support for building with mingw32/GCC from Nick Ing-Simmons. Building many of the extensions is skipped, since the mingw32 libraries don't yet support all of the Win32 API. + Memory leaks fixed in PerfLib (thanks to Artur Silveira da Cunha). + EventLog now returns 'User' and 'Message' fields (thanks to Martin Pauley). + Other minor bugfixes. Many thanks to all the contributors. WHAT IT HAS ----------- This bundle contains: * The collection of modules originally distributed by the ActiveState folks as part of their "Perl for Win32"(TM) port. These have been modified so that they will build under MakeMaker using perls greater than 5.004. There have been many bugfixes. The complete list of ActiveState extensions is available: Win32/ChangeNotify Win32/EventLog Win32/File Win32/FileSecurity Win32/IPC Win32/Mutex Win32/NetAdmin Win32/NetResource Win32/OLE Win32/Process Win32/Registry Win32/Semaphore Win32/Service Win32/WinError Note this covers all of the Win32 extensions distributed by ActiveState (as of build 316). Win32::OLE is currently most actively maintained by Jan Dubois . These extensions have been re-engineered to use the XS interface language, yet the changes are compatible with the originals. This should minimize any problems for people wanting to migrate their application to 5.004. The design of these modules is subject to change in future. The only deliberately incompatible change is in the Win32::OLE module. While the ActiveState port used the "OLE::" and "Win32::" namespaces for the functionality contained in this module, this port uses "Win32::OLE::" consistently. For a list of other incompatibilities in Win32::OLE, see the embedded documentation in "OLE/OLE.pm". * The following five modules maintained by Aldo Calpini : Win32/Clipboard Win32/Console Win32/Internet Win32/Shortcut Win32/Sound These also have been converted back to XS. I have added bug fixes as I found them during the conversion process. * Two useful modules maintained by Dave Roth . Win32/ODBC Win32/Pipe These have only received just the bare modifications needed to build them under MakeMaker. *.xs are really C/C++ files masquerading as XS. * The Win32::PerfLib module to access performance counters on remote and local Windows NT systems, contributed by Jutta M. Klebe . * The Win32::TieRegistry module for easy access to the registry, layered over the Win32API::Registry module that exposes the Registry API functions. Both modules are maintained by Tye McQueen . * The Win32API::Net module, which is a small step towards comprehensive Net* API functionality, maintained by Bret Giddings . WHAT TO DO ---------- You can either use the binaries that come with this distribution, or choose to recompile them from scratch (recommended if you have a C compiler that is capable of building perl). Once again, the included binaries *cannot* be used with the ActivePerl binaries from ActiveState. ActivePerl compatible binaries are available via the PPM tool included in ActivePerl. See http://www.activestate.com/ for details on using PPM. If you have ActivePerl, but want to build your own binaries, you will need Visual C++, and a good read of some of the caveats below. If you want to use the precompiled binaries: + Download: http://www.perl.com/CPAN/authors/id/GSAR/perl5.00402-bindist04-bc.zip Unzip that, thoroughly read the README file, and install it. Note that the it comes with an older version of libwin32, but you'll be completely replacing that in the next few steps. [Well not completely-- the Win32::AdminMisc module has been dropped since Dave Roth is distributing newer versions compatible with the above binary distribution, so the old AdminMisc will be left alone. See http://www.roth.net/perl/adminmisc for how to get the latest.] + Make sure the newly installed perl is available from the command line. Typing "perl -v" should report version 5.004_02. If not, make sure you've added the installed location of perl.exe to your PATH correctly. + cd to wherever you uncompressed this distribution, and type "install.bat". This should take care of installing everything in the right place. + Many modules come with their own test files. You may want to use them as a source of examples. Many of the test files will only run on Windows NT, others may require Windows NT 4.0, and still others may require Administrator privileges, or a full fledged Windows network. The following applies only if you need to rebuild using your C compiler. (Note that you HAVE to do this if you built Perl yourself.) Otherwise, skip to the next section. This set of modules will build with perl5.004_01 and later on the Windows NT platform. Building on Windows 95 is not supported (it *may* be possible if you use the 4DOS command shell, but your mileage may vary). + First you need to build perl 5.004_01 or later (you will need either Visual C++ 4.x+ or Borland C++ 5.02+), and install it. See README.win32 in the perl distribution for details on how to build perl for the Win32 platform. + Make sure your perl is properly configured. "perl -V:libpth" should report a valid path to your compiler's library files. Some versions of ActivePerl are known to report a bogus value here. To fix the problem, you will have to edit the Config.pm file (found somewhere like c:\perl\5.00502\lib\MSWin32-x86-object\Config.pm) and set the line that begins with "libpth=" to something like: libpth='c:\devstudio\vc\lib' If you built perl yourself and see the problem, it probably means you didn't specify the library location properly in the Makefile used to build perl. If you're one of those people who have fallen (unwittingly or otherwise) for the "spa ces in filenames are co ol" disease, make sure you're using perl 5.00502 or later, and that your libpth entry looks something like: libpth='c:\"Program Files"\DevStudio\vc\lib' i.e. you have to ensure that any space-filled components in the path are quoted. Another common problem is not making perlcrt.lib available at your 'libpth' location. perlcrt.lib may or may not be needed if you have perl 5.005 or later, depending on whether you built perl to use it. ActivePerl needs it. + All that done, you need to extract this distribution into an NTFS partition (the tests in the FileSecurity module and Net* modules will fail otherwise). The testsuite for OLE needs Excel to run. NetAdmin will only work if you have some kind of live network connection, and are in a domain with a properly configured domain controller. NetResource requires that you be part of a domain or workgroup. You may also need Administrator privileges for running some of the tests. If one or more of these conditions will not be met, you may wish to build in the subdirectories one by one. The steps below will work either at the toplevel directory, or in each of the individual extension subdirectories. + You need either MS Visual C++ (OLE needs 4.2b, NetAdmin needs ver. 4.x+, Internet needs ver. 5.0. ver. 2.0 should suffice for the others) or Borland C++ 5.02. Make sure you have the full installation of either of these compilers ("Minimal" installations or CDROM-based installations may have problems finding all the libraries). + If the Internet extension doesn't build due to lack of libraries (the wininet.h header is included), fetch the Platform SDK from "http://www.microsoft.com/msdn/sdk/". You need to look for wininet.h and wininet.dll. If either of those is newer than the ones you already have, replace the older ones, and copy the newer wininet.lib into the Internet/ directory. + Remove the 'blib' directory (it contains the precompiled binaries) + perl Makefile.PL [either at toplevel or in subdirs] + $MAKE [either at toplevel or in subdirs] + $MAKE test [optional, some interactive tests] + $MAKE install [either at toplevel or in subdirs] $MAKE above stands for either "dmake" or "nmake" depending on your available compiler, and perl configuration. WHAT THEN --------- If you find any problems with these modules, kindly report them to both the original author and to me. While I have fixed many problems in these modules, I may also have introduced brand new bugs in the process :) I wish to thank the authors of these modules for their effort in making them useful, and for making them freely available. Suggestions, patches, testsuite additions, and wholesale rewrites welcome. Enjoy! Gurusamy Sarathy gsar@umich.edu 14 Nov 1998 WHATEVER -------- Copyright for many of the modules is held by their respective authors. Look in the module subdirectories for any conditions of use. The following copyright applies to all files that don't have an explicit copyright statement: (c) 1995 Microsoft Corporation. All rights reserved. Developed by ActiveWare Internet Corp., http://www.ActiveWare.com Other modifications (c) 1997, 1998 by Gurusamy Sarathy You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the README file of the Perl distribution.