Product Documentation

PDK 8.1 Documentation

Table of Contents

perltray - Convert Perl program into a Windows tray application

NAME

perltray - Convert Perl program into a Windows tray application

SYNOPSIS

perltray [options] perlscript

perltray [options] project

perltray

perltray --help

perltray --version

The PerlTray utility converts a Perl program into a Windows tray application. This utility combines a Perl program, all of the required Perl modules and a modified Perl interpreter into one binary unit. When the resulting application is run, it searches for modules within itself before searching the filesystem.

Most commonly, PerlTray is invoked with the name of the Perl program that you want converted as an argument. This produces a working application. Some of the options described below make it possible to control which modules are included and how the generated application behaves.

If PerlTray is invoked without arguments, the graphical interface is displayed. If invoked with the --version or --help option, it will print the corresponding message and exit.

OPTIONS

The following command-line options are supported. Options can be abbreviated for uniqueness (shortened only to the point that they are still distinct from other options).

@file

If the command line contains arguments that start with @, then PerlTray replaces each one of these with the arguments parsed from the corresponding file.

--add modules

List additional modules to include in the application. PerlTray also attempts to include modules that the listed modules depend on. Multiple modules can be separated by whitespace or a semicolon. This option can be repeated. For example:

    perltray myscript.pl --add IO::Socket --add XML::Parser::Expat

...would include IO::Socket and XML::Parser in your application.

The --add option supports the following wildcard notations: --add Module::* includes Module::Foo, but neither Module itself nor Module::Foo::Bar. --add Module::** includes Module::Foo and Module::Foo::Bar, but not Module. --add Module:: works the same as --add Module;Module::**, including all of Module, Module::Foo and Module::Foo::Bar. Note that you may have to quote the * character to prevent wildcard expansion by your command shell.

--bind file

List an additional file to include in the application. The application can access this file at runtime through the PerlTray::get_bound_file() and PerlTray::extract_bound_file() functions. Separate multiple filenames with semicolons. This option can be repeated.

Additional options can be specified after the filename, within brackets and separated by commas:

   name[option1,option2,...]

Valid options are:

file=filename: Specifies the filesystem name of the file to be bound. Cannot be specified together with data. If neither file nor data is specified, then the bound name is used as the filesystem name as well.
data=text: File contents specified as literal text. Cannot be specified together with file.
text: The file will be read in text mode on Windows.
extract: The bound file is extracted into the TEMP directory upon application start. It is deleted when the application terminates. The extraction directory is added to the PATH environment variable. It is also added to the front of @INC.
mode=file permissions: Specifies the access mode for the file when extracted either by the extract option or the PerlTray::extract_bound_file() function. File permissions must be specified as an octal number (0555 by default); PerlTray implicitly calls chmod() after extracting the file to make sure it ends up with the right permission bits. The mode= prefix is optional.

Examples:

    --bind PerlEz.dll[file=\perl\bin\PerlEz.dll,extract]
    --bind data.txt[text,0777]

Note: Files bound using the extract suboption of --bind or extracted via PerlTray::extract_bound_file() are written to a a per-process temporary directory and are automatically deleted when the process ends. This occurs regardless of whether the --clean option is used.

--blib libpath

Similar to --lib, but it searches for a MakeMaker-like blib directory structure starting in libpath and working back up to five levels of '..'. If found, it adds both the lib and the arch part of the blib structure to the module search path.

--clean

Clean up object files that were extracted from the application at runtime. By default, these files are cached in the temporary directory to allow the next invocation of the application to start more quickly.

--debug host:port

Create a debugging application. It connects to a remote debugger at startup. The default host is '127.0.0.1' and the default port is ':2000'. Using a single dash '-' selects the standard Perl command-line debugger from the local Perl installation.

The special port name ':komodo' provides support for remote debugging with the ActiveState Komodo IDE (version 1.2 and later, http://www.ActiveState.com/Komodo). Komodo uses a custom version of perl5db.pl. The path to this file must be made available to the application either via the PERL5LIB environment variable (for dependent applications) or via the --lib PerlTray command-line option (for freestanding applications). For example:

    perltray --lib /path-to/komodo-1.2/perl/site/lib ...

Refer to the Komodo Remote Debugging documentation for additional information.

--dependent

Build a Windows tray application that loads modules installed with Perl on the target system. This option makes the application smaller, but it might not run correctly if Perl and/or the required modules are not installed on the target system.

Modules loaded from the directories specified with a --lib or --blib option are still included. This allows you to selectively include only some non-standard modules in your PerlTray generated application.

--dyndll

Use the 'dynamic DLL loader'. By default, PerlTray writes bundled DLLs to disk in the tmp directory and then uses the operating system to load them into the process. The default setting is --nodyndll.

The dynamic DLL loader bypasses some operating system mechanisms and loads the libraries directly from memory without ever writing them to disk. However it may not be fully compatible with all types of DLLs. It is also not compatible with Windows 9x. Executables generated using the --dyndll option will still write DLLs to disk when running on Windows 95/98/Me.

--exe filename

This option allows you to specify the filename to which the generated application will be written. By default, a name derived from the script name will be chosen.

If the argument for --exe ends with .app (i.e. is a Mac OS X application), the --gui option is implied.

--explain modules

For each module, explain why the module will be included in the application and then exit. No executable will be produced.

Multiple modules can be separated by whitespace or semi-colons. The special value all will make PerlTray explain all files it includes.

--force

Normally PerlTray asks for permission to overwrite an existing application. This option tells it to proceed without prompting for confirmation.

--freestanding

Build an executable that includes all modules required to run the program on the target system. This option is the default. Use the --dependent option to built a non-freestanding application.

--help topic

Print this manpage and exit. If an optional topic is specified, only sections whose headings include the topic word are printed. Option names as topics must be specified without the leading dashes. Examples:

    perltray --help FUNCTIONS
    perltray --help bind

--icon filename

Associate icons with the application.

The filename given must be an .ico, .dll or .exe filename. For .dll and .exe files, the name can be followed by a comma and the icon number. The first icon in the file is ,0, the second ,1, etc. If the icon number is not provided, then ,0 is assumed. Separated multiple filenames with semicolons. This option can be repeated. The first icon is used as the default icon. The others can be used at runtime using the SetAnimation() and SetIcon() APIs.

--info name = val ; ...

The arguments to this option is a sequence of name/value pairs that is used to initialize the version information of the generated application. Name/value pairs are separated by an equals sign, with each pair separated by a semicolon. Valid names are as follows, and are case-insensitive:

Comments: Comments or other information to be displayed for diagnostic purposes.
CompanyName: The name of the company that produced the file.
FileDescription: The file description presented to users (e.g. in a list box) when the user is choosing files to install.
FileVersion: The version number of the file in the form 'W.X.Y.Z' where W, X, Y, and Z are numbers in the range 0-65535. X, Y, and Z are optional and default to 0.
InternalName: The internal name of the file (e.g. a module name if the file is a dynamic-link library). If the file has no internal name, this string should be the same as the original filename, without an extension.
LegalCopyright: Copyright notices that apply to the file, including all notices, legal symbols, and copyright dates.
LegalTrademarks: Trademarks and registered trademarks that apply to the file, including the full text of all notices, legal symbols, and trademark numbers.
OriginalFilename: The original name of the file, not including a path. An application uses this information to determine whether a file has been renamed by a user. The format of the name depends on the filesystem for which the file was created.
ProductName: The name of the product.
ProductVersion: The version of the product with which the file is distributed in the form 'W.X.Y.Z' where W, X, Y, and Z are numbers in the range 0-65535. X, Y, and Z are optional and default to 0. Typically, the first number represents the major version number, the second represents the minor version number, the third represents the build number, and the last represents the private part number.

All values are taken as strings except FileVersion and ProductVersion, which must be in the form 'W.X.Y.Z' (where W, X, Y, and Z are numbers in the range 0-65535. X, Y, and Z are optional and default to 0).

--lib libpath

Add to the path where PerlTray looks for modules to include in the application. The libpath can contain multiple directories that are separated in the same way as the PATH environment variable. This option can be repeated.

PerlTray will automatically add architecture and version specific subdirectories the same way the Perl -I option and the Perl lib pragma do.

The content of the PERL5LIB environment variable is automatically added via an implicit --lib option.

--nocompress

Do not try to compress embedded modules and libraries. Compression produces a smaller application, but might slow down execution because the script and modules must be decompressed before they can be parsed.

--nogui

Mark the executable as a console application. This is useful for debugging because the output to STDOUT and STDERR will be visible in the console window.

--nologo

Suppress display of version and license information. This option has no effect when used with an evaluation license.

--norunlib

Specifies that the generated application does not use a runtime library directory. This is different from not specifying the --runlib option because the default runlib location is the directory where the application is stored.

--perl perlpath

Use the given Perl executable with PerlTray. The perlpath should be the path to the perl program.

--runlib dirname

Specifies the location of the runtime library directory. This directory is added to @INC and the PATH environment variable at runtime. The runlib directory should normally be a relative path. It is resolved at runtime relative to the location of the executable and not relative to the current working directory. The default value for this option is "." (current directory). The --gui option on OS X changes this to <Application>.app/Contents/MacOS/.

The --norunlib option can be used to specify that no runlib directory should be used.

The runlib directory is also used to locate shared library files specified using the --use option.

The fully qualified path to the runlib directory is stored in the $PerlTray::RUNLIB variable.

--scan scriptname

Tells PerlTray to scan scriptname for additional module dependencies. scriptname itself is not included in the generated executable. Separate multiple scriptnames with a semicolon. The option can be repeated.

This option is being used to create a shared library that can be referenced by other applications with the --use option.

The --shared option must be used to grant other programs access to modules bundled in the current executable.

--script scriptname

Name of the Perl script to be converted into an executable.

If no --script option is specified, the argument to PerlTray is assumed to be the input script filename. Thus

    perltray myscript.pl

...is equivalent to:

    perltray --script myscript.pl

--shared mode

Specifies the sharing mode for the generated executable. Valid values for mode are "none", "private" or "public". The default, "none", prevents other applications from accessing modules bundled in this executable.

The "private" mode allows applications built with the same PDK license to access any bundled modules. This means that part of the license serial number is encoded in the generated executable. The accessing application must then also be built using the "private" sharing mode to enable serial number matching.

Shared libraries built with the "public" sharing mode can be accessed by all executables built by the PDK without restriction.

--singleton application_name

Specifies that only a single instance of the application should be running at any one time. If the application is started and recognizes that another instance is already running, then the new process sends the command-line parameters to the instance that is already running (via the Singleton() callback) and terminates immediately. The default singleton name is the application name itself.

--tmpdir path

Specify an alternate location for the /tmp directory. This can be used in scenarios where /tmp is not writeable (e.g. for some virtual web servers hosted by ISPs). This option should only be used with an absolute pathname.

Note: PerlTray does not automatically create this directory; it must exist before the application is run.

--trim modules

Prevents modules from being included in the executable. Prerequisites for these modules are excluded unless they are also referenced in other parts of the application.

Multiple modules can be separated by whitespace or a semicolon. This option can be repeated.

The --trim option supports the following wildcard notations: --trim Module::* excludes Module::Foo, but neither Module itself nor Module::Foo::Bar. --trim Module::** excludes Module::Foo and Module::Foo::Bar, but not Module. --trim Module:: works the same as --trim Module;Module::**, excluding all of Module, Module::Foo and Module::Foo::Bar. Note that you may have to quote the * character to prevent wildcard expansion by your command shell.

If a command explicitly adds and removes modules at the same time, modules added with --add will not be removed by --trim. The one exception to this rule is that modules added by the wildcard form of --add can be individually removed by using the non-wildcard form of --trim. For example --add Module::* --trim Module::Bar will bundle Module::Foo but not Module::Bar.

--trim-implicit

This prevents including core modules that are loaded implicitly by Perl on certain syntactic constructs. The following modules belong to this category and are always included unless this option is used:

    attributes
    Errno
    File::Glob
    PerlIO
    PerlIO::scalar
    Tie::Hash::NamedCapture

You can also use the --trim option to exclude these modules on a one-by-one basis.

--use libname

Specifies shared library file containing additional modules. Modules found in a shared library will are not included in the generated executable, reducing its size.

The libname argument can be specified using a full path name. At runtime, the library is located in the runtime library directory specified by the --runlib option. If the library cannot be found, the executable will not run.

If the shared library has been built as a "private" shared library, the application that is using it must be built with the "private" --shared option too.

Separte multiple libnames with semicolons. The option can be repeated.

--verbose

This option causes PerlTray to produce more diagnostic ouput when it runs. It reports which modules were included in the application and where the application was written.

Output lines prefixed with +++ are modules that were included. Lines prefixed with --- are dependent modules that were not included.

--warnings

Display all optional warnings in addition to error messages, which are always displayed. Most warnings will be about optional modules which may be required by other modules, but which are not installed on the machine.

The --verbose option automatically enables --warnings as well.

--version

Print the PerlTray version number and exit. Information about the current license is also printed.

--xclude

Don't include the perl dynamic library (perl56.dll, perl58.dll, or perl510.dll on Windows, libperl.so on most other systems) in the generated application. This option makes the application smaller, but it will not run correctly unless the perl dynamic library corresponding to your ActivePerl version is present on the target system. The PDK license allows you to redistribute the perl dynamic library together with your application. It should be installed on the target system in the same directory as your application and not be put into a system directory on the PATH.

FUNCTIONS

The following functions are made available to the application created by PerlTray. They are available via the PerlApp:: namespace in addition to PerlTray::, to simplify sharing modules between PerlApp applications and PerlTray applications.

PerlTray::exe()

Returns the full path (including filename) to the running application.

PerlTray::extract_bound_file(FILENAME)

Writes the content of a bound file to the filesystem. The file is created in a temporary directory and is automatically deleted when the application terminates. The function returns the full filename of the temporary file created:

    my $datafile = "data.txt";
    my $filename = PerlTray::extract_bound_file($datafile);
    die "$datafile not bound to application\n" unless defined $filename;
    open(my $fh, $filename) or die "Can't open $datafile($filename)\n";

If the file is not bound, no file is created and extract_bound_file() returns undef.

extract_bound_file() always writes files in binmode. Therefore files bound with the [text] option are extracted with \n and not \r\n line endings.

PerlTray::get_bound_file(FILENAME)

Returns the content of files included in the executable with the --bind command-line option. Returns the whole file as a single string in scalar context or separate lines in list context, in which case lines are always split on newline (i.e. $/ is not considered).

    foreach my $line (PerlTray::get_bound_file("data.txt")) {
        # ... process $line ...
    }

If the file is not bound, get_bound_file() returns undef in scalar context or the empty list in list context.

The following functions are automatically exported by the PerlTray module:

    use PerlTray;

Balloon(INFO, TITLE, ICON, TIMEOUT)

The Balloon() function displays a balloon tooltip for TIMEOUT seconds. The balloon displays the INFO text and TITLE title. In addition, one of these icons can be specified: "info", "warning", "error".

Windows limits the range of the timeout value to between 10 and 30 seconds. For example, if you specify a value of '2', Windows displays the balloon for 10 seconds. Only one tooltip can display on the taskbar at any one time. If an application attempts to display a tooltip while another is already displayed, the tooltip will not display until the already-displayed tooltip has been visible for its miminum TIMEOUT value (10 seconds). For example, if a tooltip with a TIMEOUT value of 20 seconds is displayed, and another application attempts to display a tooltip 5 seconds later, the initial tooltip will continue to display for another 5 seconds before it is replaced by the second tooltip.

DisplayMenu()

The DisplayMenu() function displays the popup menu at the current cursor position. This function is typically invoked via a hotkey callback.

Download(URL, CALLBACK)

The Download() function asynchronously downloads a file from a (ftp or http) URL. CALLBACK must be either a string or a code reference. It is evaluated or called when the download is complete. At that time $_ is set to the file content, or undefined if the download was not successful.

Execute(APPLICATION)

The Execute() function starts an APPLICATION. This can be a program name, an document filename, or a URL. An "http:" URL opens the browser and a "mailto:" URL opens the email client. The Execute() function works similar to the shell "start" command.

MessageBox(TEXT, CAPTION, FLAGS)

The MessageBox() function displays a modal dialog box with the message TEXT. While the dialog is displayed, the tray menu is disabled. Clicking on the tray icon brings the message box to the foreground and gives it the input focus.

CAPTION specifies the message box title. The default is "PerlTray".

The FLAGS parameter specifies the type of message box. The default is a box with a single OK button without an icon. Choose the number and types of buttons from the following table:

MB_OK: The message box contains one push button: OK. This is the default.
MB_OKCANCEL: The message box contains two push buttons: OK and Cancel.
MB_YESNOCANCEL: The message box contains three push buttons: Yes, No, and Cancel.
MB_YESNO: The message box contains two push buttons: Yes and No.
MB_RETRYCANCEL: The message box contains two push buttons: Retry and Cancel. The Retry button returns the IDTRYAGAIN value.
MB_CANCELTRYCONTINUE: The message box contains three push buttons: Cancel, Try Again, and Continue. On systems prior to Windows 2000, this option displays Abort, Retry, and Ignore buttons instead. The return code is still IDCANCEL, IDTRYAGAIN or IDCONTINUE.

One of the following four icons can be added to the message box:

MB_ICONERROR: A stop sign icon appears in the message box.
MB_ICONQUESTION: A question mark icon appears in the message box.
MB_ICONINFORMATION: An icon consisting of a lowercase letter i in a circle appears in the message box.
MB_ICONWARNING: An exclamation point icon appears in the message box.

Normally, the first button in the message box is the default button. Use one of the following flags to make the second or third button the default:

MB_DEFBUTTON2: The second button is the default button.
MB_DEFBUTTON3: The third button is the default button.

The function returns the id of the selected push button:

IDOK
IDCANCEL
IDYES
IDNO
IDTRYAGAIN
IDCONTINUE

Sample code:

  my $flags = MB_YESNO | MB_ICONQUESTION | MB_DEFBUTTON2;
  my $ans = MessageBox("Shutdown?", "MyApp", $state);
  if ($ans == IDYES) {
      # ...
  }

RegisterHotKey(HOTKEY, CALLBACK)

This function registers a global Windows hotkey and invokes the CALLBACK whenever the HOTKEY is pressed. Hotkeys cannot be undefined, and should not be redefined once they are registered.

The HOTKEY definition is a string of modifiers followed by a key code. Valid modifiers are "ALT", "CTRL", "SHIFT", and "WIN". Modifiers and key code are separated with a "+" sign, e.g. 'Alt'+'Ctrl'+'F8'.

Valid keycodes are letters and digits, "F" followed by a function key number (1-24), "N" followed by a numeric keypad number (0-9) or one of the following strings:

  back         backspace  tab
  clear        return     enter
  pause        capital    capslock
  esc          escape     space
  spacebar     blank      prior
  pageup       pgup       next
  pagedown     pgdn       end
  home         left       up
  right        down       select
  print        execute    snapshot
  printscreen  prtscn     insert
  delete       help       sleep
  numlock      scroll     scrolllock

It is also possible to specify a VK_* constant as a "hex string", e.g. 'Alt'+'0x1b'. Please see the Microsoft documentation for a list of virtual key codes.

The CALLBACK can be either a string to be evaluated or a CODE reference to be called.

Sample code:

  RegisterHotKey("alt+0x1b", \&show_balloon);
  RegisterHotKey("alt+home", "MessageBox('Foo')");
  RegisterHotKey("alt+F2", "DisplayMenu()");
  RegisterHotKey("win+2", \&DisplayMenu);

SetAnimation(DURATION, FREQUENCY, ICONS)

The SetAnimation() function animates the tray icon by cycling through all icons in the ICONS list for DURATION milliseconds. The icon is changed every FREQUENCY milliseconds. After DURATION milliseconds the previous tray icon is restored.

Please check the documentation of SetTimer() for additional ways to specify the DURATION and FREQUENCY times.

SetIcon(ICON)

The SetIcon() function changes the tray icon to ICON. ICON must be the name of one of the icons bundled with the PerlTray application with the --icon option, but without the ".ico" extension. SetIcon() terminates any icon animation that may be in progress.

SetTimer(ELAPSE, CALLBACK)

The SetTimer() function starts an asynchronous timer, which invokes the CALLBACK every time ELAPSE milliseconds have expired. Calling SetTimer() with ELAPSE set to 0 stops the timer for this specific CALLBACK. If CALLBACK is omitted, it will default to Timer().

The ELAPSE parameter can also be specified in "hh:mm:ss.xxxx" format. Examples are:

  :15       => 15 seconds
  1:30      => 1 hour, 30 minutes
  4:30:15   => 4 hours, 30 minutes, 15 seconds
  2.500     => 2 seconds, 500 milliseconds

Note that timers may not trigger if the system time is changed before the ELAPSE time has elapsed. The TimeChange() callback can be used to catch this situation and restart the timers.

CALLBACKS

The following callback functions are automatically invoked by PerlTray if they are defined:

Click()

The Click() callback is invoked when the user clicks on the tray icon. PerlTray will not call the Click() callback when the click is part of a double-click. The default action for the Click() callback is to display the popup menu. The return value of the Click() callback is ignored.

DoubleClick()

The DoubleClick() callback is invoked when the user double-clicks on the tray icon. The default action for the DoubleClick() callback is to execute the default action defined by the popup menu. The return value of the DoubleClick() callback is ignored.

PopupMenu()

The PopupMenu() callback is invoked whenever the user clicks on the tray icon to invoke the context menu. It must return a reference to an array of menu item definitions.

Each menu item definition is a reference to an array of up to three elements: the LABEL, the ACTION and, sometimes, a CONDITION. For example:

  ["*Active&State", "Execute 'http://www.ActiveState.com'"],

The LABEL contains the menu text. The menu item can be marked as the default item by prefixing the LABEL with an asterisk. It is then displayed in bold automatically executed when the user double-clicks on the menu. An ampersand in the LABEL indicates that the next character is the keyboard shortcut. A tab character can be used to divide the menu into a left and right column (the right is typically used to display keyboard shortcuts).

The ACTION entry may contain a variety of types. A code reference is called when this menu item is selected. A string is evaluted as Perl code. Note that any variables referenced in string actions should be package variables. Lexicals will not be visible. An empty string or undefined value as the ACTION disables the menu item and grays out the LABEL. If the ACTION field is missing altogether, the ACTION of the previous menu item is inherited.

The variable $_ is set to the LABEL before executing the ACTION. This makes it easy to share a single action among multiple menu items. If th menu LABEL contains a colon, the part of the LABEL after the colon is assigned to $_ instead.

A LABEL containing only dashes indicates a separator line. To create a submenu, set the ACTION field to a reference to an array of menu item definitions.

Menu items can also act as radiobuttons. Prefix the LABEL with "o " or "x " for unselected and selected radiobuttons and use a scalar variable reference as the ACTION. For example:

  ["o Fast   :50",  \$freq],
  ["x Medium :100"],
  ["o Slow   :200"],

PerlTray sets the ACTION variable to the LABEL value of the "x" clause if the variable is not yet defined. Every time the menu is displayed, PerlTray compares the value of the ACTION variable to each LABEL to determine which button is currently selected. Alternatively, the optional CONDITION element can be used to specify which element is selected:

  ["o Fast",   '$freq =  50', $freq==50],
  ["o Medium", '$freq = 100', $freq==100],
  ["o Slow",   '$freq = 200', $freq==200],

PerlTray also supports checkmarked menu items. Prefix the label with "_ " or "v " for unchecked and checked items. Actions as scalar references work slightly differently from radiobuttons: the variable is set to the LABEL text if it is undefined. If it is already defined (any value), it is set to undefined. This way it toggles between undefined and the LABEL text. A defined value means that the menu gets a checkmark.

  ["v Checked", \$check],

The third CONDITION argument can once again be used in more complex situations to specify the checked state.

Shutdown(LOGOFF)

The Shutdown() function is called immediately before the application is terminated. It is not possible to abort the termination at this point. The LOGOFF argument is true if the session ends because the user is logging off. It is false during system shutdown.

Singleton(ARGV)

If the PerlTray application has been built using the --singleton option, only a single instance is allowed to run. Each additional instance forwards the command-line parameters to the Singleton() callback of the instance that is already running and then terminates immediately.

TimeChange()

The Timer() callback is called whenever the system time is changed. The return value of this callback is ignored.

Timer()

The Timer() callback is the default callback for the SetTimer() function. The return value is ignored.

ToolTip()

The Tooltip() function is called whenever the mouse cursor hovers over the tray icon. It must return a string value, which will be displayed as a tooltip. The default implementation returns "PerlTray"

VARIABLES

The following predefined variables are available to the application created by PerlTray.

All PerlTray:: variables documented here are also available via the PerlApp:: namespace

$PerlTray::BUILD: The $PerlTray::BUILD variable contains the PerlTray build number.
$PerlTray::PERL5LIB: The $PerlTray::PERL5LIB variable contains the value of the PERL5LIB environment variable. If that does not exist, it contains the value of the PERLLIB environment variable. If that one does not exists either, $PerlTray::PERL5LIB is undef.
$PerlTray::RUNLIB: The $PerlTray::RUNLIB variable contains the fully qualified path name to the runtime library directory specified by the --runlib option. If the --norunlib option is used, this variable is undef.
$PerlTray::TOOL: The $PerlTray::TOOL variable contains the string: "PerlTray", indicating that the currently running executable has been produced by the PerlTray tool.
$PerlTray::VERSION: The $PerlTray::VERSION variable contains the PerlTray version number: "major.minor.release", but not including the build number.

FILES

When the application built with PerlTray runs, it extracts its dynamic object files in the pdk-username subdirectory of the temporary directory. The temporary directory is located using the TEMP environment variable. It is also possible to hardcode the location with the --tmpdir command-line option.

If the application was built using the --clean option, PerlTray also appends the process id to the username when creating the temporary directory (e.g., pdk-username-1234). This avoids race conditions during cleanup. Unless the --clean option is used, extracted files are left behind when the application terminates. They are reused by later incarnations of the same application (or by other PDK-created executables).

ENVIRONMENT

Build Time

PerlTray uses the PERLTRAY_OPT environment variable to set default command-line options. PerlTray treats these options as if they were specified at the beginning of every PerlTray command line. Note: Perl must be in your PATH if you want to use PERLTRAY_OPT.

All directories specified in the PERL5LIB environment variable are treated as if they had been specified with the --lib command-line option. Therefore modules located in PERL5LIB directories will be included even in dependent applications. If PERL5LIB is not set, PerlTray will use the value of PERLLIB instead (just like regular Perl).

PerlTray will pipe the output of perltray --help through the program specified in the PAGER environment variable if STDOUT is a terminal.

Run time

The following environment variables are not visible to the application built with PerlTray: PERL5LIB, PERLLIB, PERL5OPT, PERL5DB and PERL5SHELL.

The temporary extraction directory is automatically added to the PATH environment variable when a file is bound using the [extract] option.

DIAGNOSTICS

Error: Can't locate module.pm

When PerlTray can't locate a module that seems to be used or required by the application, it produces an error message:

    VMS\Stdio.pm:
        warn: Can't locate VMS\Stdio.pm
        refby: C:\perl\lib\File\Temp.pm

In general, PerlTray cannot determine whether a module is absolutely needed at runtime. For the error message above, looking at the source code of the File::Temp module reveals that the VMS::Stdio module is only used on the VMS platform:

    require VMS::Stdio if $^O eq 'VMS';

It is therefore safe to ignore the error. PerlTray includes a number of platform-specific rules telling it that certain dependencies are likely not required. In those cases, the error messages are downgraded to a warning. In all other cases it is the responsibility of the user to verify if the module is needed or not. PerlTray still generates a valid executable, even while this error message is displayed.

It is possible to suppress the error/warning message by explicitly excluding the missing module with the --trim option:

    --trim VMS::Stdio

Error: Case mismatch between module and file name

Windows uses case-insensitive filesystems. It is often possible to misspell a module name and still have Perl load the correct file. For example:

    use Win32::Eventlog;

...loads the Win32::EventLog module, but it does not import any symbols from it: Perl tries to call the Win32::Eventlog->import() method, which doesn't exist, and gives up. PerlTray on Windows generates an error when the file name and the module name cases don't match:

    Win32\Eventlog.pm:
        error: Case mismatch between module and file name
        file: C:\perl\site\lib\Win32\EventLog.pm
    auto\Win32\Eventlog\Eventlog.dll:
        error: Case mismatch between module and file name
        file: C:\perl\site\lib\auto\Win32\EventLog\EventLog.dll

It is important to either correct the wrong spelling in the program or rename the file on disk to the correct name as PerlTray internally uses a case-sensitive file name lookup and otherwise does not load the file at runtime.

Error: Skipping duplicate file file name

PerlTray sometimes needs to include additional module-specific data files. When the module is installed both into the standard Perl library tree and into an additional location added either via the --lib option or PERL5LIB environment variable, the data file will be found twice (but only included once). The same problem can happen when the standard Perl library directories are specified again using --lib or PERL5LIB. The error message should display both the original and the duplicate filenames:

    Tk\srcfile.xpm:
        error: Skipping duplicate file D:\perl\site\lib\Tk\srcfile.xpm
        file: C:\perl\site\lib\Tk\srcfile.xpm

Please make sure that you don't include modules from a library created for a different version of Perl unless you are sure that it is binary compatible.

FAQ

This section answers some frequently asked questions about PerlTray.

How does PerlTray work?

The first thing PerlTray needs to do is to determine which modules and external files the converted script depends upon. The PerlTray program starts out by scanning the source code of the script. When it finds occurrences of use, do or require, it tries to locate the corresponding module and then parse the source of that module. This continues as long as PerlTray finds new modules to examine.

PerlTray does not try to run the script. It will not automatically determine which modules might be loaded by a statement such as:

  require $module;

In cases like this, try listing additional modules to traverse with the --add option.

The PerlTray program has some built-in heuristics for major Perl modules that determine additional modules at runtime, like DBI, LWP, Tk. PerlTray anticipates which additional modules are required so that they are available in freestanding executables.

PerlTray then decides which modules to include in the generated application. Normally, all located modules are included. This also includes the dynamic object files (.so/.dll) and AutoLoader files (.al) that go with the located modules. If the --dependent option is used, only modules located under the directories given by the --lib option are included.

Finally, the application is built with all the modules compressed (unless the --nocompress option is used) and included. When the application runs it arranges for any use, do and require statements to look for and extract the corresponding modules in itself.

Product Documentation

PDK 8.1 Documentation

perltray - Convert Perl program into a Windows tray application

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

FUNCTIONS

CALLBACKS

VARIABLES

FILES

ENVIRONMENT

Build Time

Run time

DIAGNOSTICS

Error: Can't locate module.pm

Error: Case mismatch between module and file name

Error: Skipping duplicate file file name

FAQ

How does PerlTray work?

How can a script determine if it runs under PerlTray?

What is $^X when running under PerlTray?

Will PerlTray work for programs using source filters?

Where can I obtain license for PerlTray?

Does the evaluation license give me fully working applications?

SEE ALSO

VERSION

COPYRIGHT