Contents

1. Introduction
2. Release Notes
3. Requirements
4. Read me before installing the PDK
5. Information for Perl Resource Kit (PRK) owners
6. Tools
   • Perl Debugger
   • PerlCOM
   • PerlCtrl
   • PerlApp
   • Visual Package Manager
   • Network Installer
   • Perl WSAPI
7. What's new?
8. Documentation
9. Known issues
10. Release history
11. Sample code
12. Reporting problems or bugs

Introduction

The Perl Development Kit is a collection of Win32 Perl development tools. As a continued show of support for our existing customer base, Perl Development Kit 1.2 will be a free upgrade for owners of any of the following products:

• O'Reilly Perl Resource Kit -- Win32 Edition 1.0
• ActiveState Perl Debugger 1.0
• Perl Development Kit 1.1

Release Notes

To get the best results and maximum satisfaction out of the PDK, we recommend that you use ActivePerl build 519 or later. See the 'What's New?' section for more information about problems with PDK and ActivePerl builds 518 and earlier.

If you have problems downloading PDK send mail to Webmaster@ActiveState.com

Requirements

1. This version of the PDK requires a computer with:
   • Windows 95 with DCOM 1.3,
   • Windows 98, or
   • Windows NT 4.0 with Service Pack 3 or greater.

2. This version of the PDK requires version 509 or later of ActivePerl to be installed in order to install any components other than Perl Debugger, examples and documentation. However it is strongly recommended that you use ActivePerl build 518 or later since build 518 fixed some bugs that were causing problems when building a freestanding PerlCtrl or PerlApp. The latest version of ActivePerl can be downloaded from our web site or from our ftp site.
   NOTE:Prior to installing ActivePerl, it is recommended that you

   • Uninstall any previous versions of ActivePerl.
   • Reboot your computer.
   • Install the latest version of ActivePerl.

3. Windows NT 4.0 is required to build a PerlCtrl or PerlApp.

Read me before installing the PDK

Before you install the PDK, it is recommended that you uninstall any previous versions of the PDK and any previous versions of the Perl Debugger.

Information for Perl Resource Kit (PRK) owners

Perl Resource Kit 1.0 owners may upgrade to the Perl Development Kit if they have applied PRK Service Pack 1 and/or the latest version of ActivePerl.

PDK Tools

Perl Debugger

Painless, simple debugging for Perl scripts. The ActiveState Perl Debugger makes debugging Perl scripts a breeze with quick views of variables and expression. Its intuitive visual environment gets you up and running fast.

PerlCOM

PerlCOM is an ActiveX Component that allows you to easily embed Perl Interpreters into client applications. You can add Perl subroutines to your applications, use Perl packages and classes, and exchange data freely between the host languages and Perl. Now you can embed Perl in any development environment that supports ActiveX components.

PerlCtrl

Build ActiveX Controls with Perl. These controls are packaged up as DLLs and can be used in any language that supports ActiveX components. You can build a dependent PerlCtrl, which depend on an existent Perl installation on the target computer, or a freestanding PerlCtrl which will run on a target computer that does not have Perl installed.

PerlApp

Convert your Perl programs to executable files. You can build dependent executables, which depend on an existent Perl installation on the target computer, or freestanding executables which will run on a target computer that does not have Perl installed.

Visual Package Manager (VPM)

VPM, the Visual Package Manager allows you to manage your Perl installation locally or remotely. VPM is a browser based application that lets you install, update, delete and get information about the Perl modules and extensions you have on your system.

Network Installer

The Network Installer lets you maintain a Perl installation in a single central point and provide access to that installation to clients across your network.

Perl WSAPI

Perl WSAPI is an embedded Perl interpreter that runs in process with the O'Reilly WebSite web server and presents a standard CGI environment for a Perl programmer. With Perl WSAPI and O'Reilly WebSite you get the benefit of not having to start a new process to handle each request for a Perl script. Scripts written to be run by Perl.exe in a standard CGI environment should run without any modifications.

What's new since PDK 1.2 Release Candidate 1

Installer

• Installer stops the PerlSock service when performing and upgrade installation or uninstall in order to ensure the DLLs are not in use and can be replaced or removed.

PerlCtrl

• Version number is 1.2.2.106.
• Added the '-i[nfo]' option which allows you set the version information of the resulting DLL file. See the documentation for information regarding what values may be set.
• Extension DLL files are extracted to <TEMP>/<PerlCtrlName>/<GUID>

Debugger

• Version number is 1.2.2.106.

PerlCOM

• Version number is 1.2.2.106.

PerlApp

• Version number is 1.2.2.106.
• Added the '-i[nfo]' option which allows you set the version information of the resulting EXE file. See the documentation for information regarding what values may be set.
• Extension DLL files are extracted to <TEMP>/<PerlAppName>/<GUID>
• Additional Tk resources are bound into the EXE if your script or any module used by your script uses any of the Tk* modules.

Visual Package Manager (VPM)

• No change.

Network Installer

• No change.

Perl WSAPI

• Version number is 1.2.2.106.

Known Issues

Known Installer Issues:

• If you did not uninstall an earlier version of PDK or Perl Debugger 1.0 and then install this version of PDK, then uninstall the Perl Debugger 1.0 / old version of PDK, some components of PDK will no longer work properly. To avoid this problem, uninstall any old versions of the PDK or Perl Debugger 1.0.

• If an incorrect directory is selected for the location of your ActivePerl installation the installation script may not be able to determine that you have a valid ActivePerl installation and present you with an error dialog. If this occurs you should return to the directory selection dialog and ensure that the correct directory is selected according to the instructions on the dialog.

Known PerlCOM Issues:

• Although an array can be passed to PerlCOM, a reference to the array can not be passed. Therefore any changes to the array elements must be explicitly returned to the caller.

• When running the \Perl\eg\PDK\Approx\approx.pl example, the String::Approx package can produce a benign error if the requested word in ARGV[0] cannot be approximately matched from the words in words.txt. The error text looks like this:

  Win32::OLE(0.1005) error 0x8002000b: "Invalid index" at approx.pl line 54.

  Approx.vbs will produce a blank message box if an approximate match for the user's text cannot be found.
  

Known PerlCtrl Issues:

• Although controls built with PerlCtrl will operate on Windows 95, Windows 98 and Windows NT 4.0, the PerlCtrl builder will only operate on Windows NT. This is due to a limitation in the Win32 API under Windows 95 and Windows 98.

• Although an array can be passed to a PerlCtrl, a reference to the array can not be passed. Therefore any manipulation of the array elements must be returned to the caller.

• Parameters to PerlCtrl Methods are [IN] only. This also means that method parameters can only be passed by value, and not by reference. If you try to pass an array reference into a PerlCtrl method, a copy of the array is passed - thus, the client's array will be unchanged by any manipulations of the array by the PerlCtrl method.

• Because PerlCtrl builds a binary Type Library, it does not support Case Smashing of methods or properties. This is not a bug and is the expected behavior. Case Smashing, however, is supported on method and properties of PerlCOM objects returned from PerlCtrl methods.

• If at runtime you find that certain modules have not been included in your control properly, you will need explicitly add those modules on the command line. You should use the '-add=SomeModule' command line switch to force the inclusion of the module. The semantics of this are equivalent to doing a 'use SomeModule;' at the beginning of your script.

• If you try to build a freestanding PerlCtrl which relies on an extension which in turn relies on certain DLLs, these DLLs are not included into the freestanding PerlCtrl. Since these DLLs are not part of the freestanding executable, they will have to be present on the target machine and accessible via the PATH environment variable.

• The standard glob operator <*.*> will not work in a freestanding PerlCtrl because it relies on the 'perlglob.exe' file that ships with Perl. If you plan to use the glob operator in your freestanding PerlCtrl, you should import the overridden version from File::DosGlob like so:

  use File::DosGlob 'glob';
  
  From there on out you can use the glob operator as expected.

Known PerlApp Issues:

• Although executables built with PerlApp will operate on Windows 95, Windows 98 and WinNT, the PerlApp builder will only operate on Windows NT. This is due to a limitation in the Win32 API under Windows 95 and Windows 98.

• If at runtime you find that certain modules have not been included in your control properly, you will need explicitly add those modules on the command line. You should use the '-add=SomeModule' command line switch to force the inclusion of the module. The semantics of this are equivalent to doing a 'use SomeModule;' at the beginning of your script.

• For the reason stated above some Perl/Tk applications may not work as freestanding PerlApps. Tk uses 'do' and 'require' statements on variables as opposed to literal strings. A workaround for this problem is to preload modules not picked up by the builder script by adding the appropriate 'use' statements to your script or use -add=Foo;Bar;Baz on the command line.

• If you try to build a freestanding executable which relies on an extension which in turn relies on certain DLLs, these DLLs are not included into the freestanding executable .exe file. Since these DLLs are not part of the freestanding executable, they will have to be present on the target machine and accessible via the PATH environment variable.

• The standard glob operator <*.*> will not work in a freestanding PerlApp because it relies on the 'perlglob.exe' file that ships with Perl. If you plan to use the glob operator in your freestanding PerlApp, you should import the overridden version from File::DosGlob like so:

  use File::DosGlob 'glob';
  
  From there on out you can use the glob operator as expected.

Known VPM Issues:

• On Win9x machines, if launched from the Start menu, will cause the entire Start bar to disappear until the PerlSock task is killed or the system is rebooted.

• VPM will not install any packages if you are using ActivePerl build 518 or earlier.

• VPM may not work correctly on a machine that was configured to be a network Perl server. The cause of this is that the user the PerlSock service is being run as does not have permission to access the Perl share.

Release History 

PDK 1.2 Release Candidate 1 (released 8/14/99) changes from Beta

• Installer
  • No change.
• PerlCtrl
  • Version number is 1.2.1.104.
  • Added the '-c[lean]' option which will delete the freestanding file cache when the PerlCtrl DLL file is unloaded.
  • File cache directory is unique for each version of a PerlCtrl. This eliminates the potential to use out of date DLL files.
  • In addition to encrypting the code for the PerlCtrl itself, all perl modules are encrypted as well.
• Debugger
  • Version number is 1.2.1.104.
• PerlCOM
  • Version number is 1.2.1.104.
• PerlApp
  • Version number is 1.2.1.104.
  • Added the '-c[lean]' option which will delete the freestanding file cache when the PerlApp DLL file is unloaded.
  • File cache directory is unique for each version of a PerlApp. This eliminates the potential to use out of date DLL files.
  • In addition to encrypting the code for the PerlApp itself, all perl modules are encrypted as well.
• Visual Package Manager (VPM)
  • A problem with chdir() in PerlSock was keeping VPM from intalling packages properly, this problem has been fixed.
  • Output from install command is better formatted.
  • zlib in ActivePerl build 519 now uses PerlIO_open() instead of fopen(); this enables proper translation of pathnames, which was another issue keeping VPM from installing packages properly.
• Network Installer
  • No change.
• Perl WSAPI
  • Version number is 1.2.1.104.
  • Fix for new Win32::* functions which among other things will fix File::Copy in PerlScript and Perl for ISAPI.
  • Fixed buffer overrun caused by off by one error.

PDK 1.1 Release (released 2/26/99) changes from Release Candidate 2

• Installer
  • Gives you the option of installing each of the components individually.

• PerlCtrl
  • Version number is 1.2.0.103.
  • Added '-add=<list>' option to force inclusion of a list of modules separated with semicolons.
  • END blocks are called before the PerlCtrl DLL is unloaded.

• Debugger
  • Version number is 1.2.0.103.

• PerlCOM
  • Version number is 1.2.0.103.
  • END blocks are called before the PerlCOM DLL is unloaded.

• PerlApp
  • Version number is 1.2.0.103.
  • END blocks are called before the script exits.
  • Added '-gui' option to create an executable file that has no console window.
  • Added '-add=<list>' option to force inclusion of files specified by list.

• Visual Package Manager (VPM)
  • This is a new addition to PDK that was previously only available in the PRK from O'Reilly and Associates. VPM allows you to easily manage a Perl installation.

• Network Installer
  • This is a new addition to PDK that was previously only available in the PRK from O'Reilly and Associates. The Network Installer allows you to centrally manage a Perl installation that is accessible to clients across the network.

• Perl WSAPI
  • This is a new addition to PDK that was previously only available in the PRK from O'Reilly and Associates. Perl WSAPI enhances the performance of Perl scripts running under O'Reilly's WebSite web server.

PDK 1.1 Release Candidate 2 (released 2/26/99) changes from Release Candidate 1

• Installer:

  • Some Windows 95 users reported a dialog box upon installation:
      Could not load PerlEz.dll in GetPerlDirectories()
    This has been fixed.
  • Some users have complex multi-version Perl installs. The installer now has enhanced logic for ascertaining which versions of ActivePerl you have installed.

• Debugger:

  • DLL version number was 1.1.00021 (build 21).

• PerlCOM:

  • Memory leak fixed.
  • DLL version number was 1.1.3.2

• PerlCtrl:

  • Improved variable scope handling within eval() for free-standing builds.
  • A new example directory eg\TestCtrl\ has been added which demonstrates data type passing to a PerlCtrl.
  • Memory leak fixed.
  • DLL version number was 1.1.3.2

• PerlApp:

  • The PerlApp executable builder utility replaces the PerlEXE utility.
  • Improved variable handling within eval() for free-standing builds.
  • PerlApp no longer leaves behind an empty temporary subdirectory after user runs resultant executable.

  • PerlApp builder no longer puts out 5 blank lines on the console window while building a freestanding executable.

  • Improved variable scope handling within eval() for free-standing builds.

  • Scripts which contain
      qx(net user $username /domain);
        or
      @userinfo = `net user $username /domain`;
    now can be built properly by PerlApp.

  • DLL version number was 1.1.3.2

• Documentation:

  • Improved documentation about data type passing, especially regarding passing parameters or return values by reference.

PDK 1.1 Release Candidate 1 (released 2/11/99) changes from Beta 3

• Debugger:

  • Watch, proximity and special variable panels are now updated properly when not docked.
  • PlDbSync.dll is now registered properly on install. Before this bug was fixed, users would encounter error dialog box:
    SECSplashWnd: PERLDB.EXE Application Error
  • Uninstalling PLDBSync.dll now removes the TypeLib registry entry properly.

• PerlCOM: Minor bug fixes.

• PerlCtrl:

  • -drb
    command line option (for building DCOM registration binaries) has been changed to
    -rb
  • DLL stub fixed - the DLL stub used to create Perl Controls did not work properly in Beta 3.
  • Creation of a hash in VB & access from DLL fixed.
  • ReadOnly property now works properly. e.g.
    Properties => {
        'myProp' => {
            Type => VT_BSTR,
            ReadOnly => 1,
        },
    
  • Improved documentation notes for Windows 95 and Windows 98 users.

• PerlApp:

  • The PerlApp executable builder tool replaces the PerlEXE utility.
  • Builds executables more robustly. Some Perl scripts would fail to build into executables in Beta 3.
  • Commands in backticks will now execute in a free-standing executable. system() commands and commands in backticks would not execute in freestanding .exe files in Beta 3.
  • If a non-existent file name is used as the source script name or if a non-existent module is referenced, the error message is more informative.
  • exit() with non-zero code now exits gracefully in .exe file.
  • There was a problem building freestanding executables with the AdminMisc module - this has been fixed.
  • Improved documentation notes for Windows 95 and Windows 98 users.
  • TestRe.doc example now works properly - if no text is selected, text replacement will occur in the entire document.
  • require "filename.pl";
    will now include the proper module. In previous versions of the PDK, it was assumed that required files ended in .pm.
  • DLL stub fixed - the DLL stub used to create executables did not work properly in Beta 3.

• Installer:

  • You can now install the PDK over the Perl Resource Kit if you have applied PRK Service Pack 1.
  • PDK uninstall no longer deletes the bindir registry key. In previous beta PDK releases, an error dialog box would appear for some users:
      Could not load PerlEz.dll in Get PerlDirectories()

PDK 1.1 Beta 3 changes from Beta 2

• Requires Win32::OLE module version .1005 or higher.

• PerlCOM: Improved error checking and minor bug fixes.

• pl2exe: In the Beta 3 release, the pl2exe utility was replaced with the PerlEXE utility. The final release of PDK 1.1 now contains a utility named PerlApp which replaces pl2exe and PerlEXE.

• PerlCtrl and PerlEXE (now known as PerlApp): It is no longer necessary to have Perl installed in order to use controls or executables which are built using these 2 tools. You now have the option of building freestanding PerlCtrl DLLs and PerlApp executables.

PDK 1.1 Beta 2 changes from Beta 1

• PerlCOM:
  • Backticks now work on Windows 95, Windows 98 and WinNT.
  • system() now works on Windows 95, Windows 98 and WinNT. fixed extra parameter bug. PerlCOM now tries to find the executable if the full path is not specified.
  • File::Find now reports the correct File size.
  • now works correctly over DCOM.

• PerlCtrl: New option introduced for building DCOM Registration Binary. The PerlCtrl Builder now supports a new switch, -DRB, which stands for "DCOM Registration Binary". A DCOM Registration Binary is an executable that contains all the registration information for a PerlCtrl. The executable produced can be used to create the proper PerlCtrl registry entries on a machine where the control is not present.

PDK 1.1 Beta 1 changes from PDK 1.0

• PerlCOM:

  • Type library now included. This allows the Visual Basic programmer to add a reference to the PerlCOM type library. Visual Basic variables can then be dimensioned as type PerlCOM. For example, Dim objPerlCOM As PerlCOM. This also enables code completion on the PerlCOM object itself. In addition, Visual C++ can read the type library and create a C++ wrapper class for use in VC++ projects.
  • PerlCOM now implements a minor form of case smashing on method and property names. This was necessary because Perl is case sensitive, while host languages like Visual Basic are not. PerlCOM will successfully case smash a method or property name if there is only one occurrence of the name defined in the namespace. If there are multiple methods or properties defined with the same name but different case, PerlCOM will return the following error:
      PerlCOM::CaseSmash() Failed: Ambiguous method or property call for ...  
  • Scalar vs. List context:PerlCOM now provides a mechanism to explicitly specify the context of a method call. By default, all PerlCOM method calls are made in scalar context, which also means they can only return one value. If a method call is checking the $wantarray variable or needs to return multiple return values, you need to explicitly specify List context for method call. This can be done by
    $objPerlCOM->List->Method(). Scalar context can also be explicitly set by
    $objPerlCOM->Scalar->Method(). See the Arrays section in the PDK help file for more information regarding this topic.
  • Perl Interpreter stays alive to support SubPerlCOM objects: Perl Objects returned from PerlCOM methods are automatically packaged up as PerlCOM Objects. These are technically known as SubPerlCOM object because they share the same Perl Interpreter as the PerlCOM object that created them. PerlCOM now keeps the Perl Interpreter alive as long as it is needed to support any outstanding SubPerlCOM objects.
  • Returning Win32::OLE Objects: PerlCOM now supports returning OLE Automation objects (Win32::OLE Objects) from PerlCOM methods. These objects are safe to use even after the Main PerlCOM object, which contains the Perl Interpreter, has been destroyed. This should also work over DCOM. For example, Perl can instantiate PerlCOM on a remote machine using DCOM. The remote PerlCOM object can then be used to instantiate an ADSI Object, or any other Automation Object, on the remote machine and have that object returned across machine boundaries to the local machine. The remote PerlCOM object can then be destroyed.
  • Multiple Perl Interpreters: Multiple Perl Interpreters are fully supported in this version of PerlCOM. This means that multiple PerlCOM objects can coexist in the same client process without conflicting. For example, if you create two instances of PerlCOM.Script, each one will contain a separate Perl Interpreter.

• PerlCtrl:

  • Nesting PerlCtrls:This version of PerlCtrl support the nesting of PerlCtrls, i.e., one PerlCtrl can create and use any number of other PerlCtrls.
  • Multiple Perl Interpreters: Multiple Perl Interpreters are fully supported in this version of PerlCtrl. This means that multiple PerlCtrls can coexist in the same client process without conflicting.

Documentation

The PDK comes with two online help files: Perl Development Kit documentation and Debugger documentation. There is a printable file PDKGuide.doc which is a Microsoft Word document version of the PDK help file. The ActiveState Perl Debugger help includes a quick tutorial to get you up and running, and the Perl Development Kit help includes tutorial-based sections on PerlCOM and PerlCtrl. A wealth of examples is included in the example code subdirectory (usually C:\Perl\PDK\eg).

Sample Code

The PDK should be installed in the PDK directory under your Perl installation. This directory is typically C:\Perl\PDK. The example code is included a separate directory (usually C:\Perl\eg\PDK).

This version of the PDK contains sample files written in Perl, VBScript, JScript, Java and C++.

In order to use the samples written in VBScript (.vbs files), you will have to have Windows Scripting Host (WSH) installed.

• Additional Information regarding WSH can be found at: http://msdn.microsoft.com/scripting/
• WSH can be downloaded from: http://msdn.microsoft.com/scripting/windowshost/download/default.htm

All JScript samples are implemented within HTML files.

Reporting Problems or Bugs

There are two methods of reporting bugs or problems:

1. The preferred method for reporting bugs or problems with the PDK is to fill in the Online Bug Report. The PDK-specific bug reporting form is located at:

   http://www.activestate.com/cgibin/tiwi.pl?cmd=ShowMainFrame&project=PerlDevelopmentKit
   
   You can also reach this URL through our general bug reporting interface at http://www.activestate.com/bugs/.

2. Send e-mail to support@ActiveState.com making sure to include a complete, step by step description of the problem, including the machine and operating system type.

We're interested in what you have to say! Do you have something that used to work that just doesn't work any more? Any feature suggestions? Let us know! We can't guarantee that all suggestions will be implemented in future releases, but we'll do our best!

PDK Mailing List

  SUBSCRIBE pdk